diff options
Diffstat (limited to 'devdocs/elisp/event-input-misc.html')
| -rw-r--r-- | devdocs/elisp/event-input-misc.html | 43 |
1 files changed, 43 insertions, 0 deletions
diff --git a/devdocs/elisp/event-input-misc.html b/devdocs/elisp/event-input-misc.html new file mode 100644 index 00000000..2f5a650e --- /dev/null +++ b/devdocs/elisp/event-input-misc.html @@ -0,0 +1,43 @@ + <h4 class="subsection">Miscellaneous Event Input Features</h4> <p>This section describes how to peek ahead at events without using them up, how to check for pending input, and how to discard pending input. See also the function <code>read-passwd</code> (see <a href="reading-a-password">Reading a Password</a>). </p> <dl> <dt id="unread-command-events">Variable: <strong>unread-command-events</strong> +</dt> <dd> + <p>This variable holds a list of events waiting to be read as command input. The events are used in the order they appear in the list, and removed one by one as they are used. </p> <p>The variable is needed because in some cases a function reads an event and then decides not to use it. Storing the event in this variable causes it to be processed normally, by the command loop or by the functions to read command input. </p> <p>For example, the function that implements numeric prefix arguments reads any number of digits. When it finds a non-digit event, it must unread the event so that it can be read normally by the command loop. Likewise, incremental search uses this feature to unread events with no special meaning in a search, because these events should exit the search and then execute normally. </p> <p>The reliable and easy way to extract events from a key sequence so as to put them in <code>unread-command-events</code> is to use <code>listify-key-sequence</code> (see below). </p> <p>Normally you add events to the front of this list, so that the events most recently unread will be reread first. </p> <p>Events read from this list are not normally added to the current command’s key sequence (as returned by, e.g., <code>this-command-keys</code>), as the events will already have been added once as they were read for the first time. An element of the form <code>(t . <var>event</var>)</code> forces <var>event</var> to be added to the current command’s key sequence. </p> <p>Elements read from this list are normally recorded by the record-keeping features (see <a href="recording-input">Recording Input</a>) and while defining a keyboard macro (see <a href="keyboard-macros">Keyboard Macros</a>). However, an element of the form <code><span class="nolinebreak">(no-record</span> . <var>event</var>)</code> causes <var>event</var> to be processed normally without recording it. </p> +</dd> +</dl> <dl> <dt id="listify-key-sequence">Function: <strong>listify-key-sequence</strong> <em>key</em> +</dt> <dd><p>This function converts the string or vector <var>key</var> to a list of individual events, which you can put in <code>unread-command-events</code>. </p></dd> +</dl> <dl> <dt id="input-pending-p">Function: <strong>input-pending-p</strong> <em>&optional check-timers</em> +</dt> <dd> + <p>This function determines whether any command input is currently available to be read. It returns immediately, with value <code>t</code> if there is available input, <code>nil</code> otherwise. On rare occasions it may return <code>t</code> when no input is available. </p> <p>If the optional argument <var>check-timers</var> is non-<code>nil</code>, then if no input is available, Emacs runs any timers which are ready. See <a href="timers">Timers</a>. </p> +</dd> +</dl> <dl> <dt id="last-input-event">Variable: <strong>last-input-event</strong> +</dt> <dd> +<p>This variable records the last terminal input event read, whether as part of a command or explicitly by a Lisp program. </p> <p>In the example below, the Lisp program reads the character <kbd>1</kbd>, <acronym>ASCII</acronym> code 49. It becomes the value of <code>last-input-event</code>, while <kbd>C-e</kbd> (we assume <kbd>C-x C-e</kbd> command is used to evaluate this expression) remains the value of <code>last-command-event</code>. </p> <div class="example"> <pre class="example">(progn (print (read-char)) + (print last-command-event) + last-input-event) + -| 49 + -| 5 + ⇒ 49 +</pre> +</div> </dd> +</dl> <dl> <dt id="while-no-input">Macro: <strong>while-no-input</strong> <em>body…</em> +</dt> <dd> +<p>This construct runs the <var>body</var> forms and returns the value of the last one—but only if no input arrives. If any input arrives during the execution of the <var>body</var> forms, it aborts them (working much like a quit). The <code>while-no-input</code> form returns <code>nil</code> if aborted by a real quit, and returns <code>t</code> if aborted by arrival of other input. </p> <p>If a part of <var>body</var> binds <code>inhibit-quit</code> to non-<code>nil</code>, arrival of input during those parts won’t cause an abort until the end of that part. </p> <p>If you want to be able to distinguish all possible values computed by <var>body</var> from both kinds of abort conditions, write the code like this: </p> <div class="example"> <pre class="example">(while-no-input + (list + (progn . <var>body</var>))) +</pre> +</div> </dd> +</dl> <dl> <dt id="while-no-input-ignore-events">Variable: <strong>while-no-input-ignore-events</strong> +</dt> <dd> +<p>This variable allow setting which special events <code>while-no-input</code> should ignore. It is a list of event symbols (see <a href="event-examples">Event Examples</a>). </p> </dd> +</dl> <dl> <dt id="discard-input">Function: <strong>discard-input</strong> +</dt> <dd> + <p>This function discards the contents of the terminal input buffer and cancels any keyboard macro that might be in the process of definition. It returns <code>nil</code>. </p> <p>In the following example, the user may type a number of characters right after starting the evaluation of the form. After the <code>sleep-for</code> finishes sleeping, <code>discard-input</code> discards any characters typed during the sleep. </p> <div class="example"> <pre class="example">(progn (sleep-for 2) + (discard-input)) + ⇒ nil +</pre> +</div> </dd> +</dl><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 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/Event-Input-Misc.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Event-Input-Misc.html</a> + </p> +</div> |