The lowest level functions for command input are read-event,
read-char, and read-char-exclusive.
If you need a function to read a character using the minibuffer, use
read-char-from-minibuffer (see Asking Multiple-Choice Questions).
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. If prompt is
nil or the string ‘""’, read-event 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 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.
If cursor-in-echo-area is non-nil, then read-event
moves the cursor temporarily to the echo area, to the end of any message
displayed there. Otherwise read-event does 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-event stops 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 nil, read-event waits 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-event is 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.
If read-event gets an event that is defined as a help character,
then in some cases read-event processes 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-event and 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-char signals an error. The arguments
work as in read-event.
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-char leaves 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 characterp test
(see Character Codes). Use event-basic-type
(see Classifying Events) to recover the character code with the
modifier bits removed; use event-modifiers to test for
modifiers in the character event returned by read-char.
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-char from the minibuffer using
eval-expression. read-char reads the keyboard macro’s
very next character, which is 1. Then eval-expression
displays 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-exclusive ignores 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 read-char.
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
read-event, read-char, and read-char-exclusive do
not perform the translations described in Keymaps for Translating Sequences of Events.
If you wish to read a single key taking these translations into
account (for example, to read Function Keys in a terminal or
Mouse Events from xterm-mouse-mode), use the function
read-key:
This function reads a single key. It is intermediate between
read-key-sequence and 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 input-decode-map, local-function-key-map,
and key-translation-map (see Keymaps for Translating Sequences of Events).
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.
If argument disable-fallbacks is non-nil then the usual
fallback logic for unbound keys in read-key-sequence is not
applied. This means that mouse button-down and multi-click events
will not be discarded and local-function-key-map and
key-translation-map will not get applied. If nil or
unspecified, the only fallback disabled is downcasing of the last
event.
This function uses read-from-minibuffer to read and return a
single character that is a member of chars, which should be a
list of single characters. It discards any input characters that are
not members of chars, and shows a message to that effect.
The optional argument inhibit-quit is by default ignored, but if
the variable read-char-choice-use-read-key is non-nil,
this function uses read-key instead of
read-from-minibuffer, and in that case inhibit-quit
non-nil means ignore keyboard-quit events while waiting for
valid input. In addition, if read-char-choice-use-read-key is
non-nil, binding help-form (see Help Functions) to a
non-nil value while calling this function causes it to evaluate
help-form and display the result when the user presses
help-char; it then continues to wait for a valid input
character, or for 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.
If optional argument help-string is non-nil, 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 ?.
If optional argument show-help is non-nil, the help
buffer will be displayed immediately, before any user input. If it is
a string, use it as the name of the help buffer.
If optional argument long-form is non-nil, the user
will have to type in long-form answers (using completing-read)
instead of hitting a single key. The answers must be among the second
elements of the values in the choices list.
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.")))
The read-multiple-choice-face face is used to highlight the
matching characters in the name string on graphical terminals.