Next: , Previous: Key Sequence Input, Up: Reading Input

21.8.2 Reading One Event

The lowest level functions for command input are read-event, read-char, and read-char-exclusive.

— Function: read-event &optional prompt inherit-input-method seconds

This function reads and returns the next event of command input, waiting if necessary until an event is available. Events can come directly from the user or from a keyboard macro.

If the optional argument prompt is non-nil, it should be a string to display in the echo area as a prompt. Otherwise, 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 value for 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
— Function: read-char &optional prompt inherit-input-method seconds

This function reads and returns a character of command input. 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.

In the first example, 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
— Function: read-char-exclusive &optional prompt inherit-input-method seconds

This function reads and returns a character of command input. If the user generates an event which is not a character, read-char-exclusive ignores it and reads another event, until it gets a character. The arguments work as in read-event.

None of the above functions suppress quitting.

— Variable: num-nonmacro-input-events

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 Translation Keymaps. If you wish to read a single key taking these translations into account, use the function read-key:

— Function: read-key &optional prompt

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 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.

— Function: read-char-choice prompt chars &optional inhibit-quit

This function uses read-key to 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-nil value while calling read-char-choice, then pressing help-char causes it to evaluate help-form and display the result. It then continues to wait for a valid input character, or keyboard-quit.