elisp: Key Sequence Input
20.8.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 &optional continue-echo
dont-downcase-last switch-frame-ok command-loop
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. (Remember that a key
sequence that starts with a mouse event is read using the keymaps
of the buffer in the window that the mouse was in, not the current
buffer.)
If the events are all characters and all can fit in a string, then
‘read-key-sequence’ returns a string (
Strings of Events).
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.
Reading a key sequence includes translating the events in various
ways. 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. The
argument CONTINUE-ECHO, if non-‘nil’, means to echo this key as a
continuation of the previous key.
Normally any upper case event is converted to lower case if the
original event is undefined and the lower case equivalent is
defined. The argument DONT-DOWNCASE-LAST, if non-‘nil’, means do
not convert the last event to lower case. This is appropriate for
reading a key sequence to be defined.
The argument SWITCH-FRAME-OK, if non-‘nil’, means that this
function should process a ‘switch-frame’ event if the user switches
frames before typing anything. If the user switches frames in the
middle of a key sequence, or at the start of the sequence but
SWITCH-FRAME-OK is ‘nil’, then the event will be put off until
after the current key sequence.
The argument COMMAND-LOOP, if non-‘nil’, means that this key
sequence is being read by something that will read commands one
after another. It should be ‘nil’ if the caller will read just one
key sequence.
In the following example, Emacs displays the prompt ‘?’ in the echo
area, and then 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’. Quitting.
-- Function: read-key-sequence-vector prompt &optional continue-echo
dont-downcase-last switch-frame-ok command-loop
This is like ‘read-key-sequence’ except that it always returns the
key sequence as a vector, never as a string. Strings of
Events.
If an input character is upper-case (or has the shift modifier) 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.
When reading input results in such a “shift-translation”, Emacs sets
the variable ‘this-command-keys-shift-translated’ to a non-‘nil’ value.
Lisp programs can examine this variable if they need to modify their
behavior when invoked by shift-translated keys. For example, the
function ‘handle-shift-selection’ examines the value of this variable to
determine how to activate or deactivate the region (
handle-shift-selection The Mark.).
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.
Info Catalog
elisp: Reading Input
elisp: Reading One Event