The lowest level functions for command input are
This function reads and returns the next event of command input, waiting if necessary until an event is available.
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 Terminal I/O Encoding).
If the optional argument prompt is non-
nil, it should be a string to display in the echo area as a prompt. Otherwise,
read-eventdoes 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 The Echo Area.
If inherit-input-method is non-
nil, then the current input method (if any) is employed to make it possible to enter a non-ASCII character. Otherwise, input method handling is disabled for reading this event.
read-eventmoves the cursor temporarily to the echo area, to the end of any message displayed there. Otherwise
read-eventdoes not move the cursor.
If seconds is non-
nil, it should be a number specifying the maximum time to wait for input, in seconds. If no input arrives within that time,
read-eventstops waiting and returns
nil. A floating point seconds means to wait for a fractional number of seconds. Some systems support only a whole number of seconds; on these systems, seconds is rounded down. If seconds is
read-eventwaits as long as necessary for input to arrive.
If seconds is
nil, Emacs is considered idle while waiting for user input to arrive. Idle timers—those created with
run-with-idle-timer(see Idle Timers)—can run during this period. However, if seconds is non-
nil, the state of idleness remains unchanged. If Emacs is non-idle when
read-eventis called, it remains non-idle throughout the operation of
read-event; if Emacs is idle (which can happen if the call happens inside an idle timer), it remains idle.
read-eventgets an event that is defined as a help character, then in some cases
read-eventprocesses the event directly without returning. See Help Functions. Certain other events, called special events, are also processed directly within
read-event(see Special Events).
Here is what happens if you call
read-eventand then press the right-arrow function key:(read-event) ⇒ right
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),
read-charsignals an error. The arguments work as in
If the event has modifiers, Emacs attempts to resolve them and return the code of the corresponding character. For example, if the user types C-a, the function returns 1, which is the ASCII code of the ‘C-a’ character. If some of the modifiers cannot be reflected in the character code,
read-charleaves the unresolved modifier bits set in the returned event. For example, if the user types C-M-a, the function returns 134217729, 8000001 in hex, i.e. ‘C-a’ with the Meta modifier bit set. This value is not a valid character code: it fails the
characterptest (see Character Codes). Use
event-basic-type(see Classifying Events) to recover the character code with the modifier bits removed; use
event-modifiersto test for modifiers in the character event returned by
In the first example below, the user types the character 1 (ASCII code 49). The second example shows a keyboard macro definition that calls
read-charfrom the minibuffer using
read-charreads the keyboard macro's very next character, which is 1. Then
eval-expressiondisplays its return value in the echo area.(read-char) ⇒ 49 ;; We assume here you use M-: to evaluate this. (symbol-function 'foo) ⇒ "^[:(read-char)^M1" (execute-kbd-macro 'foo) -| 49 ⇒ nil
This function reads and returns a character input event. If the user generates an event which is not a character event,
read-char-exclusiveignores it and reads another event, until it gets a character. The arguments work as in
read-event. The returned value may include modifier bits, as with
None of the above functions suppress quitting.
This variable holds the total number of input events received so far from the terminal—not counting those generated by keyboard macros.
We emphasize that, unlike
read-key-sequence, the functions
not perform the translations described in Translation Keymaps.
If you wish to read a single key taking these translations into
account, use the function
This function reads a single key. It is intermediate between
read-event. 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
key-translation-map(see Translation Keymaps).
The argument prompt is either a string to be displayed in the echo area as a prompt, or
nil, meaning not to display a prompt.
This function uses
read-keyto read and return a single character. It ignores any input that is not a member of chars, a list of accepted characters. Optionally, it will also ignore keyboard-quit events while it is waiting for valid input. If you bind
help-form(see Help Functions) to a non-
nilvalue while calling
read-char-choice, then pressing
help-charcauses it to evaluate
help-formand display the result. It then continues to wait for a valid input character, or keyboard-quit.
Ask user a multiple choice question. prompt should be a string that will be displayed as the prompt.
choices 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.
The return value is the matching value from choices.(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.")))
read-multiple-choice-faceface is used to highlight the matching characters in the name string on graphical terminals.