Reading One Event

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

Function: read-event &optional prompt suppress-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 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 The Echo Area.

If suppress-input-method is non-nil, then the current input method is disabled for reading this event. If you want to read an event without input-method processing, always do it this way; don't try binding input-method-function (see below).

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 Help Functions. Certain other events, called special events, are also processed directly within read-event (see section 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

This function reads and returns a character of command input. It discards any events that are not characters, until it gets a character.

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

read-event also invokes the current input method, if any. If the value of input-method-function is non-nil, it should be a function; when read-event reads a printing character (including SPC) with no modifier bits, it calls that function, passing the event as an argument.

Variable: input-method-function

If this is non-nil, its value specifies the current input method function.

Note: Don't bind this variable with let. It is often buffer-local, and if you bind it around reading input (which is exactly when you would bind it), switching buffers asynchronously while Emacs is waiting will cause the value to be restored in the wrong buffer.

The input method function should return a list of events which should be used as input. (If the list is nil, that means there is no input, so read-event waits for another event.) These events are processed before the events in unread-command-events. Events returned by the input method function are not passed to the input method function again, even if they are printing characters with no modifier bits.

If the input method function calls read-event or read-key-sequence, it should bind input-method-function to nil first, to prevent recursion.

The input method function is not called when reading the second and subsequent event of a key sequence. Thus, these characters are not subject to input method processing. It is usually a good idea for the input method processing to test the values of overriding-local-map and overriding-terminal-local-map; if either of these variables is non-nil, the input method should put its argument into a list and return that list with no further processing.

Go to the first, previous, next, last section, table of contents.