21.7.2 Reading One Event

The lowest level functions for command input are those that read a single event.

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

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 section 38.4 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 read-event gets an event that is defined as a help character, in some cases read-event processes the event directly without returning. See section 24.5 Help Functions. Certain other events, called special events, are also processed directly within read-event (see section 21.8 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

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

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.