new repository

1 files changed, 46 insertions, 0 deletions

diff --git a/devdocs/elisp/reading-one-event.html b/devdocs/elisp/reading-one-event.html
new file mode 100644
index 00000000..118d64ad
--- /dev/null
+++ b/devdocs/elisp/reading-one-event.html
@@ -0,0 +1,46 @@
+ <h4 class="subsection">Reading One Event</h4>   <p>The lowest level functions for command input are <code>read-event</code>, <code>read-char</code>, and <code>read-char-exclusive</code>. </p> <p>If you need a function to read a character using the minibuffer, use <code>read-char-from-minibuffer</code> (see <a href="multiple-queries">Multiple Queries</a>). </p> <dl> <dt id="read-event">Function: <strong>read-event</strong> <em>&amp;optional prompt inherit-input-method seconds</em>
+</dt> <dd>
+<p>This function reads and returns the next event of command input, waiting if necessary until an event is available. </p> <p>The returned event may come directly from the user, or from a keyboard macro. It is not decoded by the keyboard’s input coding system (see <a href="terminal-i_002fo-encoding">Terminal I/O Encoding</a>). </p> <p>If the optional argument <var>prompt</var> is non-<code>nil</code>, it should be a string to display in the echo area as a prompt. If <var>prompt</var> is <code>nil</code> or the string ‘<samp>""</samp>’, <code>read-event</code> does not display any message to indicate it is waiting for input; instead, it prompts by echoing: it displays descriptions of the events that led to or were read by the current command. See <a href="the-echo-area">The Echo Area</a>. </p> <p>If <var>inherit-input-method</var> is non-<code>nil</code>, then the current input method (if any) is employed to make it possible to enter a non-<acronym>ASCII</acronym> character. Otherwise, input method handling is disabled for reading this event. </p> <p>If <code>cursor-in-echo-area</code> is non-<code>nil</code>, then <code>read-event</code> moves the cursor temporarily to the echo area, to the end of any message displayed there. Otherwise <code>read-event</code> does not move the cursor. </p> <p>If <var>seconds</var> is non-<code>nil</code>, it should be a number specifying the maximum time to wait for input, in seconds. If no input arrives within that time, <code>read-event</code> stops waiting and returns <code>nil</code>. A floating point <var>seconds</var> means to wait for a fractional number of seconds. Some systems support only a whole number of seconds; on these systems, <var>seconds</var> is rounded down. If <var>seconds</var> is <code>nil</code>, <code>read-event</code> waits as long as necessary for input to arrive. </p> <p>If <var>seconds</var> is <code>nil</code>, Emacs is considered idle while waiting for user input to arrive. Idle timers—those created with <code>run-with-idle-timer</code> (see <a href="idle-timers">Idle Timers</a>)—can run during this period. However, if <var>seconds</var> is non-<code>nil</code>, the state of idleness remains unchanged. If Emacs is non-idle when <code>read-event</code> is called, it remains non-idle throughout the operation of <code>read-event</code>; if Emacs is idle (which can happen if the call happens inside an idle timer), it remains idle. </p> <p>If <code>read-event</code> gets an event that is defined as a help character, then in some cases <code>read-event</code> processes the event directly without returning. See <a href="help-functions">Help Functions</a>. Certain other events, called <em>special events</em>, are also processed directly within <code>read-event</code> (see <a href="special-events">Special Events</a>). </p> <p>Here is what happens if you call <code>read-event</code> and then press the right-arrow function key: </p> <div class="example"> <pre class="example">(read-event)
+     ⇒ right
+</pre>
+</div> </dd>
+</dl> <dl> <dt id="read-char">Function: <strong>read-char</strong> <em>&amp;optional prompt inherit-input-method seconds</em>
+</dt> <dd>
+<p>This function reads and returns a character input event. If the user generates an event which is not a character (i.e., a mouse click or function key event), <code>read-char</code> signals an error. The arguments work as in <code>read-event</code>. </p> <p>If the event has modifiers, Emacs attempts to resolve them and return the code of the corresponding character. For example, if the user types <kbd>C-a</kbd>, the function returns 1, which is the <acronym>ASCII</acronym> code of the ‘<samp>C-a</samp>’ character. If some of the modifiers cannot be reflected in the character code, <code>read-char</code> leaves the unresolved modifier bits set in the returned event. For example, if the user types <kbd>C-M-a</kbd>, the function returns 134217729, 8000001 in hex, i.e. ‘<samp>C-a</samp>’ with the Meta modifier bit set. This value is not a valid character code: it fails the <code>characterp</code> test (see <a href="character-codes">Character Codes</a>). Use <code>event-basic-type</code> (see <a href="classifying-events">Classifying Events</a>) to recover the character code with the modifier bits removed; use <code>event-modifiers</code> to test for modifiers in the character event returned by <code>read-char</code>. </p> <p>In the first example below, the user types the character <kbd>1</kbd> (<acronym>ASCII</acronym> code 49). The second example shows a keyboard macro definition that calls <code>read-char</code> from the minibuffer using <code>eval-expression</code>. <code>read-char</code> reads the keyboard macro’s very next character, which is <kbd>1</kbd>. Then <code>eval-expression</code> displays its return value in the echo area. </p> <div class="example"> <pre class="example">(read-char)
+     ⇒ 49
+</pre>
+
+<pre class="example">;; <span class="roman">We assume here you use <kbd>M-:</kbd> to evaluate this.</span>
+(symbol-function 'foo)
+     ⇒ "^[:(read-char)^M1"
+</pre>
+<pre class="example">(execute-kbd-macro 'foo)
+     -| 49
+     ⇒ nil
+</pre>
+</div> </dd>
+</dl> <dl> <dt id="read-char-exclusive">Function: <strong>read-char-exclusive</strong> <em>&amp;optional prompt inherit-input-method seconds</em>
+</dt> <dd><p>This function reads and returns a character input event. If the user generates an event which is not a character event, <code>read-char-exclusive</code> ignores it and reads another event, until it gets a character. The arguments work as in <code>read-event</code>. The returned value may include modifier bits, as with <code>read-char</code>. </p></dd>
+</dl> <p>None of the above functions suppress quitting. </p> <dl> <dt id="num-nonmacro-input-events">Variable: <strong>num-nonmacro-input-events</strong>
+</dt> <dd><p>This variable holds the total number of input events received so far from the terminal—not counting those generated by keyboard macros. </p></dd>
+</dl> <p>We emphasize that, unlike <code>read-key-sequence</code>, the functions <code>read-event</code>, <code>read-char</code>, and <code>read-char-exclusive</code> do not perform the translations described in <a href="translation-keymaps">Translation Keymaps</a>. If you wish to read a single key taking these translations into account (for example, to read <a href="function-keys">Function Keys</a> in a terminal or <a href="mouse-events">Mouse Events</a> from <code>xterm-mouse-mode</code>), use the function <code>read-key</code>: </p> <dl> <dt id="read-key">Function: <strong>read-key</strong> <em>&amp;optional prompt disable-fallbacks</em>
+</dt> <dd>
+<p>This function reads a single key. It is intermediate between <code>read-key-sequence</code> and <code>read-event</code>. Unlike the former, it reads a single key, not a key sequence. Unlike the latter, it does not return a raw event, but decodes and translates the user input according to <code>input-decode-map</code>, <code>local-function-key-map</code>, and <code>key-translation-map</code> (see <a href="translation-keymaps">Translation Keymaps</a>). </p> <p>The argument <var>prompt</var> is either a string to be displayed in the echo area as a prompt, or <code>nil</code>, meaning not to display a prompt. </p> <p>If argument <var>disable-fallbacks</var> is non-<code>nil</code> then the usual fallback logic for unbound keys in <code>read-key-sequence</code> is not applied. This means that mouse button-down and multi-click events will not be discarded and <code>local-function-key-map</code> and <code>key-translation-map</code> will not get applied. If <code>nil</code> or unspecified, the only fallback disabled is downcasing of the last event. </p>
+</dd>
+</dl> <dl> <dt id="read-char-choice">Function: <strong>read-char-choice</strong> <em>prompt chars &amp;optional inhibit-quit</em>
+</dt> <dd><p>This function uses <code>read-key</code> to read and return a single character. It ignores any input that is not a member of <var>chars</var>, a list of accepted characters. Optionally, it will also ignore keyboard-quit events while it is waiting for valid input. If you bind <code>help-form</code> (see <a href="help-functions">Help Functions</a>) to a non-<code>nil</code> value while calling <code>read-char-choice</code>, then pressing <code>help-char</code> causes it to evaluate <code>help-form</code> and display the result. It then continues to wait for a valid input character, or keyboard-quit. </p></dd>
+</dl> <dl> <dt id="read-multiple-choice">Function: <strong>read-multiple-choice</strong> <em>prompt choices &amp;optional help-string</em>
+</dt> <dd>
+<p>Ask user a multiple choice question. <var>prompt</var> should be a string that will be displayed as the prompt. </p> <p><var>choices</var> is an alist where the first element in each entry is a character to be entered, the second element is a short name for the entry to be displayed while prompting (if there’s room, it might be shortened), and the third, optional entry is a longer explanation that will be displayed in a help buffer if the user requests more help. </p> <p>If optional argument <var>help-string</var> is non-<code>nil</code>, it should be a string with a more detailed description of all choices. It will be displayed in a help buffer instead of the default auto-generated description when the user types <kbd>?</kbd>. </p> <p>The return value is the matching value from <var>choices</var>. </p> <div class="lisp"> <pre class="lisp">(read-multiple-choice
+ "Continue connecting?"
+ '((?a "always" "Accept certificate for this and future sessions.")
+   (?s "session only" "Accept certificate this session only.")
+   (?n "no" "Refuse to use certificate, close connection.")))
+</pre>
+</div> <p>The <code>read-multiple-choice-face</code> face is used to highlight the matching characters in the name string on graphical terminals. </p> </dd>
+</dl><div class="_attribution">
+  <p class="_attribution-p">
+    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
+    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Reading-One-Event.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Reading-One-Event.html</a>
+  </p>
+</div>