25.6.1 Key Sequence Input

Lisp programs can read input a key sequence at a time by calling read-key-sequence; for example, describe-key uses it to read the key to describe.

Function: read-key-sequence prompt &optional continue-echo dont-downcase-last

This function reads a sequence of keystrokes or mouse clicks and returns it as a vector of event objects read. It keeps reading events until it has accumulated a full key sequence; that is, enough to specify a non-prefix command using the currently active keymaps.

The vector and the event objects it contains are freshly created (and so will not be side-effected by subsequent calls to this function).

The function read-key-sequence suppresses quitting: C-g typed while reading with this function works like any other character, and does not set quit-flag. See Quitting.

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.

Second optional arg continue-echo non-nil means this key echoes as a continuation of the previous key.

Third optional arg dont-downcase-last non-nil means do not convert the last event to lower case. Normally any upper case event is converted to lower case if the original event is undefined and the lower case equivalent is defined.

This argument is provided mostly for fsf compatibility; the equivalent effect can be achieved more generally by binding retry-undefined-key-binding-unshifted to nil around the call to read-key-sequence.

If the user selects a menu item while we are prompting for a key sequence, the returned value will be a vector of a single menu-selection event (a misc-user event), but an error will be signalled if you pass this value to lookup-key or a related function.

In the example below, the prompt ‘?’ is displayed in the echo area, and the user types C-x C-f.

(read-key-sequence "?")

---------- Echo Area ----------
?C-x C-f
---------- Echo Area ----------

     ⇒ [#<keypress-event control-X> #<keypress-event control-F>]

If an input character is an upper-case letter and has no key binding, but its lower-case equivalent has one, then read-key-sequence converts the character to lower case. Note that lookup-key does not perform case conversion in this way.