21.7.1 Key Sequence Input

The command loop reads input a key sequence at a time, by calling read-key-sequence. Lisp programs can also call this function; for example, describe-key uses it to read the key to describe.

Function: read-key-sequence prompt

This function reads a key sequence and returns it as a string or vector. It keeps reading events until it has accumulated a complete key sequence; that is, enough to specify a non-prefix command using the currently active keymaps.

If the events are all characters and all can fit in a string, then read-key-sequence returns a string (see section 21.6.14 Putting Keyboard Events in Strings). Otherwise, it returns a vector, since a vector can hold all kinds of events--characters, symbols, and lists. The elements of the string or vector are the events in the key sequence.

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.

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 ---------- => "^X^F"

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 section 21.10 Quitting.

Function: read-key-sequence-vector prompt

This is like read-key-sequence except that it always returns the key sequence as a vector, never as a string. See section 21.6.14 Putting Keyboard Events in Strings.

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.

The function read-key-sequence also transforms some mouse events. It converts unbound drag events into click events, and discards unbound button-down events entirely. It also reshuffles focus events and miscellaneous window events so that they never appear in a key sequence with any other events.

When mouse events occur in special parts of a window, such as a mode line or a scroll bar, the event type shows nothing special--it is the same symbol that would normally represent that combination of mouse button and modifier keys. The information about the window part is kept elsewhere in the event--in the coordinates. But read-key-sequence translates this information into imaginary "prefix keys", all of which are symbols: header-line, horizontal-scroll-bar, menu-bar, mode-line, vertical-line, and vertical-scroll-bar. You can define meanings for mouse clicks in special window parts by defining key sequences using these imaginary prefix keys.

For example, if you call read-key-sequence and then click the mouse on the window's mode line, you get two events, like this:

(read-key-sequence "Click on the mode line: ") => [mode-line (mouse-1 (#<window 6 on NEWS> mode-line (40 . 63) 5959987))]

Variable: num-input-keys

This variable's value is the number of key sequences processed so far in this Emacs session. This includes key sequences read from the terminal and key sequences read from keyboard macros being executed.

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.