Go to the previous, next section.
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 full 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 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.
Quitting is suppressed inside read-key-sequence. In other words,
a C-g typed while reading with this function is treated like any
other character, and does not set quit-flag. See section 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.
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"
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.
If an input character is an upper case letter and has no key binding,
but the 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 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 itself shows nothing special--only the
symbol that would normally represent that mouse button and modifier
keys. The information about the screen region 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:
mode-line, vertical-line, horizontal-scroll-bar and
vertical-scroll-bar.
For example, if you call read-key-sequence and then click the
mouse on the window's mode line, this is what happens:
(read-key-sequence "Click on the mode line: ")
=> [mode-line
(mouse-1
(#<window 6 on NEWS> mode-line
(40 . 63) 5959987))]
You can define meanings for mouse clicks in special window regions by defining key sequences using these imaginary prefix keys.
Go to the previous, next section.