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 variables
last-command-char (Command Loop Info).
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.
This variable holds a single event to be read as command input.
This variable is obsolete now that you can use
unread-command-events instead; it exists only to support programs
written for versions of (X)Emacs prior to 19.12.
This function determines whether any command input is currently
available to be read. It returns immediately, with value
there is available input,
nil otherwise. On rare occasions it
t when no input is available.
This variable is set to the last keyboard or mouse button event received.
This variable is off limits: you may not set its value or modify the
event that is its value, as it is destructively modified by
read-key-sequence. If you want to keep a pointer to this value,
you must use
Note: This variable is an alias for
last-input-char in FSF
In the example below, a character is read (the character 1). It
becomes the value of
last-input-event, while C-e (from the
C-x C-e command used to evaluate this expression) remains the
(progn (print (next-command-event)) (print last-command-event) last-input-event) -| #<keypress-event 1> -| #<keypress-event control-E> ⇒ #<keypress-event 1>
If the value of
last-input-event is a keyboard event, then this
is the nearest ASCII equivalent to it.
Remember that there is not a 1:1 mapping between keyboard events and ASCII characters: the set of keyboard events is much larger, so writing code that examines this variable to determine what key has been typed is bad practice, unless you are certain that it will be one of a small set of characters.
Note: This function exists for compatibility with Emacs version 18.
This function discards the contents of the terminal input buffer and
cancels any keyboard macro that might be in the process of definition.
In the following example, the user may type a number of characters right
after starting the evaluation of the form. After the
discard-input discards any characters typed
during the sleep.
(progn (sleep-for 2) (discard-input)) ⇒ nil