elisp: Scanning Keymaps
21.16 Scanning Keymaps
======================
This section describes functions used to scan all the current keymaps
for the sake of printing help information.
-- Function: accessible-keymaps keymap &optional prefix
This function returns a list of all the keymaps that can be reached
(via zero or more prefix keys) from KEYMAP. The value is an
association list with elements of the form ‘(KEY . MAP)’, where KEY
is a prefix key whose definition in KEYMAP is MAP.
The elements of the alist are ordered so that the KEY increases in
length. The first element is always ‘([] . KEYMAP)’, because the
specified keymap is accessible from itself with a prefix of no
events.
If PREFIX is given, it should be a prefix key sequence; then
‘accessible-keymaps’ includes only the submaps whose prefixes start
with PREFIX. These elements look just as they do in the value of
‘(accessible-keymaps)’; the only difference is that some elements
are omitted.
In the example below, the returned alist indicates that the key
<ESC>, which is displayed as ‘^[’, is a prefix key whose definition
is the sparse keymap ‘(keymap (83 . center-paragraph) (115 .
foo))’.
(accessible-keymaps (current-local-map))
⇒(([] keymap
(27 keymap ; Note this keymap for <ESC> is repeated below.
(83 . center-paragraph)
(115 . center-line))
(9 . tab-to-tab-stop))
("^[" keymap
(83 . center-paragraph)
(115 . foo)))
In the following example, ‘C-h’ is a prefix key that uses a sparse
keymap starting with ‘(keymap (118 . describe-variable)...)’.
Another prefix, ‘C-x 4’, uses a keymap which is also the value of
the variable ‘ctl-x-4-map’. The event ‘mode-line’ is one of
several dummy events used as prefixes for mouse actions in special
parts of a window.
(accessible-keymaps (current-global-map))
⇒ (([] keymap [set-mark-command beginning-of-line ...
delete-backward-char])
("^H" keymap (118 . describe-variable) ...
(8 . help-for-help))
("^X" keymap [x-flush-mouse-queue ...
backward-kill-sentence])
("^[" keymap [mark-sexp backward-sexp ...
backward-kill-word])
("^X4" keymap (15 . display-buffer) ...)
([mode-line] keymap
(S-mouse-2 . mouse-split-window-horizontally) ...))
These are not all the keymaps you would see in actuality.
-- Function: map-keymap function keymap
The function ‘map-keymap’ calls FUNCTION once for each binding in
KEYMAP. It passes two arguments, the event type and the value of
the binding. If KEYMAP has a parent, the parent’s bindings are
included as well. This works recursively: if the parent has itself
a parent, then the grandparent’s bindings are also included and so
on.
This function is the cleanest way to examine all the bindings in a
keymap.
-- Function: where-is-internal command &optional keymap firstonly
noindirect no-remap
This function is a subroutine used by the ‘where-is’ command (
Help (emacs)Help.). It returns a list of all key sequences (of
any length) that are bound to COMMAND in a set of keymaps.
The argument COMMAND can be any object; it is compared with all
keymap entries using ‘eq’.
If KEYMAP is ‘nil’, then the maps used are the current active
keymaps, disregarding ‘overriding-local-map’ (that is, pretending
its value is ‘nil’). If KEYMAP is a keymap, then the maps searched
are KEYMAP and the global keymap. If KEYMAP is a list of keymaps,
only those keymaps are searched.
Usually it’s best to use ‘overriding-local-map’ as the expression
for KEYMAP. Then ‘where-is-internal’ searches precisely the
keymaps that are active. To search only the global map, pass the
value ‘(keymap)’ (an empty keymap) as KEYMAP.
If FIRSTONLY is ‘non-ascii’, then the value is a single vector
representing the first key sequence found, rather than a list of
all possible key sequences. If FIRSTONLY is ‘t’, then the value is
the first key sequence, except that key sequences consisting
entirely of ASCII characters (or meta variants of ASCII characters)
are preferred to all other key sequences and that the return value
can never be a menu binding.
If NOINDIRECT is non-‘nil’, ‘where-is-internal’ doesn’t look inside
menu-items to find their commands. This makes it possible to
search for a menu-item itself.
The fifth argument, NO-REMAP, determines how this function treats
command remappings (Remapping Commands). There are two
cases of interest:
If a command OTHER-COMMAND is remapped to COMMAND:
If NO-REMAP is ‘nil’, find the bindings for OTHER-COMMAND and
treat them as though they are also bindings for COMMAND. If
NO-REMAP is non-‘nil’, include the vector ‘[remap
OTHER-COMMAND]’ in the list of possible key sequences, instead
of finding those bindings.
If COMMAND is remapped to OTHER-COMMAND:
If NO-REMAP is ‘nil’, return the bindings for OTHER-COMMAND
rather than COMMAND. If NO-REMAP is non-‘nil’, return the
bindings for COMMAND, ignoring the fact that it is remapped.
-- Command: describe-bindings &optional prefix buffer-or-name
This function creates a listing of all current key bindings, and
displays it in a buffer named ‘*Help*’. The text is grouped by
modes—minor modes first, then the major mode, then global bindings.
If PREFIX is non-‘nil’, it should be a prefix key; then the listing
includes only keys that start with PREFIX.
When several characters with consecutive ASCII codes have the same
definition, they are shown together, as ‘FIRSTCHAR..LASTCHAR’. In
this instance, you need to know the ASCII codes to understand which
characters this means. For example, in the default global map, the
characters ‘<SPC> .. ~’ are described by a single line. <SPC> is
ASCII 32, ‘~’ is ASCII 126, and the characters between them include
all the normal printing characters, (e.g., letters, digits,
punctuation, etc.); all these characters are bound to
‘self-insert-command’.
If BUFFER-OR-NAME is non-‘nil’, it should be a buffer or a buffer
name. Then ‘describe-bindings’ lists that buffer’s bindings,
instead of the current buffer’s.
Info Catalog
elisp: Key Binding Commands
elisp: Keymaps
elisp: Menu Keymaps