GNU Info

(elisp)Event Input Misc

---

Prev: Quoted Character Input Up: Reading Input

---

Enter node , (file) or (file)node

Miscellaneous Event Input Features
----------------------------------

   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 `read-passwd' (Note: Reading a
Password).

 - Variable: unread-command-events
     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.

     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.

     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.

     The reliable and easy way to extract events from a key sequence so
     as to put them in `unread-command-events' is to use
     `listify-key-sequence' (Note: Strings of Events).

     Normally you add events to the front of this list, so that the
     events most recently unread will be reread first.

 - Function: listify-key-sequence key
     This function converts the string or vector KEY to a list of
     individual events, which you can put in `unread-command-events'.

 - Variable: unread-command-char
     This variable holds a character to be read as command input.  A
     value of -1 means "empty".

     This variable is mostly obsolete now that you can use
     `unread-command-events' instead; it exists only to support programs
     written for Emacs versions 18 and earlier.

 - Function: input-pending-p
     This function determines whether any command input is currently
     available to be read.  It returns immediately, with value `t' if
     there is available input, `nil' otherwise.  On rare occasions it
     may return `t' when no input is available.

 - Variable: last-input-event
 - Variable: last-input-char
     This variable records the last terminal input event read, whether
     as part of a command or explicitly by a Lisp program.

     In the example below, the Lisp program reads the character `1',
     ASCII code 49.  It becomes the value of `last-input-event', while
     `C-e' (we assume `C-x C-e' command is used to evaluate this
     expression) remains the value of `last-command-event'.

          (progn (print (read-char))
                 (print last-command-event)
                 last-input-event)
               -| 49
               -| 5
               => 49

     The alias `last-input-char' exists for compatibility with Emacs
     version 18.

 - Function: discard-input
     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 `nil'.

     In the following example, the user may type a number of characters
     right after starting the evaluation of the form.  After the
     `sleep-for' finishes sleeping, `discard-input' discards any
     characters typed during the sleep.

          (progn (sleep-for 2)
                 (discard-input))
               => nil