elisp: Keymap Basics
21.2 Keymap Basics
==================
A keymap is a Lisp data structure that specifies “key bindings” for
various key sequences.
A single keymap directly specifies definitions for individual events.
When a key sequence consists of a single event, its binding in a keymap
is the keymap’s definition for that event. The binding of a longer key
sequence is found by an iterative process: first find the definition of
the first event (which must itself be a keymap); then find the second
event’s definition in that keymap, and so on until all the events in the
key sequence have been processed.
If the binding of a key sequence is a keymap, we call the key
sequence a “prefix key”. Otherwise, we call it a “complete key”
(because no more events can be added to it). If the binding is ‘nil’,
we call the key “undefined”. Examples of prefix keys are ‘C-c’, ‘C-x’,
and ‘C-x 4’. Examples of defined complete keys are ‘X’, <RET>, and ‘C-x
4 C-f’. Examples of undefined complete keys are ‘C-x C-g’, and ‘C-c 3’.
Prefix Keys, for more details.
The rule for finding the binding of a key sequence assumes that the
intermediate bindings (found for the events before the last) are all
keymaps; if this is not so, the sequence of events does not form a
unit—it is not really one key sequence. In other words, removing one or
more events from the end of any valid key sequence must always yield a
prefix key. For example, ‘C-f C-n’ is not a key sequence; ‘C-f’ is not
a prefix key, so a longer sequence starting with ‘C-f’ cannot be a key
sequence.
The set of possible multi-event key sequences depends on the bindings
for prefix keys; therefore, it can be different for different keymaps,
and can change when bindings are changed. However, a one-event sequence
is always a key sequence, because it does not depend on any prefix keys
for its well-formedness.
At any time, several primary keymaps are “active”—that is, in use for
finding key bindings. These are the “global map”, which is shared by
all buffers; the “local keymap”, which is usually associated with a
specific major mode; and zero or more “minor mode keymaps”, which belong
to currently enabled minor modes. (Not all minor modes have keymaps.)
The local keymap bindings shadow (i.e., take precedence over) the
corresponding global bindings. The minor mode keymaps shadow both local
and global keymaps. Active Keymaps, for details.
Info Catalog
elisp: Key Sequences
elisp: Keymaps
elisp: Format of Keymaps