26.12 Scanning Keymaps

This section describes functions used to scan all the current keymaps, or all keys within a keymap, 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 accessed (via 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 C-x, which is displayed as ‘[(control x)]’, is a prefix key whose definition is the keymap #<keymap ((control x) #<keymap emacs-lisp-mode-map 8 entries 0x546>) 1 entry 0x8a2>. (The strange notation for the keymap’s name indicates that this is an internal submap of emacs-lisp-mode-map. This is because lisp-interaction-mode-map has set up emacs-lisp-mode-map as its parent, and lisp-interaction-mode-map defines no key sequences beginning with C-x.)

(current-local-map)
⇒ #<keymap lisp-interaction-mode-map 5 entries 0x558>
(accessible-keymaps (current-local-map))
⇒(([] . #<keymap lisp-interaction-mode-map 5 entries 0x558>)
    ([(control x)] .
     #<keymap ((control x) #<keymap emacs-lisp-mode-map 8 entries 0x546>)
              1 entry 0x8a2>))

The following example shows the results of calling accessible-keymaps on a large, complex keymap. Notice how some keymaps were given explicit names using set-keymap-name; those submaps without explicit names are given descriptive names indicating their relationship to their enclosing keymap.

(accessible-keymaps (current-global-map))
⇒ (([] . #<keymap global-map 639 entries 0x221>)
   ([(control c)] . #<keymap mode-specific-command-prefix 1 entry 0x3cb>)
   ([(control h)] . #<keymap help-map 33 entries 0x4ec>)
   ([(control x)] . #<keymap Control-X-prefix 77 entries 0x3bf>)
   ([(meta escape)] .
      #<keymap ((meta escape) #<keymap global-map 639 entries 0x221>)
               3 entries 0x3e0>)
   ([(meta control \[)] .
      #<keymap ((meta escape) #<keymap global-map 639 entries 0x221>)
               3 entries 0x3e0>)
   ([f1] . #<keymap help-map 33 entries 0x4ec>)
   ([(control x) \4] . #<keymap ctl-x-4-prefix 9 entries 0x3c5>)
   ([(control x) \5] . #<keymap ctl-x-5-prefix 8 entries 0x3c8>)
   ([(control x) \6] . #<keymap 13 entries 0x4d2>)
   ([(control x) a] .
      #<keymap (a #<keymap Control-X-prefix 77 entries 0x3bf>)
               8 entries 0x3ef>)
   ([(control x) n] . #<keymap narrowing-prefix 3 entries 0x3dd>)
   ([(control x) r] . #<keymap rectangle-prefix 18 entries 0x3e9>)
   ([(control x) v] . #<keymap vc-prefix-map 13 entries 0x60e>)
   ([(control x) a i] .
     #<keymap (i #<keymap (a #<keymap Control-X-prefix 77 entries 0x3bf>)
                          8 entries 0x3ef>)
              2 entries 0x3f5>))

Function: map-keymap function keymap &optional sort-first

This function applies function to each element of keymap. function will be called with two arguments: a key-description list, and the binding. The order in which the elements of the keymap are passed to the function is unspecified. If the function inserts new elements into the keymap, it may or may not be called with them later. No element of the keymap will ever be passed to the function more than once.

The function will not be called on elements of this keymap’s parents (see Inheritance and Keymaps) or upon keymaps which are contained within this keymap (multi-character definitions). It will be called on META characters since they are not really two-character sequences.

If the optional third argument sort-first is non-nil, then the elements of the keymap will be passed to the mapper function in a canonical order. Otherwise, they will be passed in hash (that is, random) order, which is faster.

Function: keymap-fullness keymap

This function returns the number of bindings in the keymap.

Function: where-is-internal definition &optional keymaps firstonly noindirect event-or-keys

This function returns a list of key sequences (of any length) that are bound to definition in a set of keymaps.

The argument definition can be any object; it is compared with all keymap entries using eq.

keymaps can be either a keymap (meaning search in that keymap and the current global keymap) or a list of keymaps (meaning search in exactly those keymaps and no others). If keymaps is nil, search in the currently applicable maps for event-or-keys.

If keymaps is a keymap, then the maps searched are keymaps and the global keymap. If keymaps is a list of keymaps, then the maps searched are exactly those keymaps, and no others. If keymaps is nil, then the maps used are the current active keymaps for event-or-keys (this is equivalent to specifying (current-keymaps event-or-keys) as the argument to keymaps).

If firstonly is non-nil, then the value is a single vector representing the first key sequence found, rather than a list of all possible key sequences.

If noindirect is non-nil, where-is-internal doesn’t follow indirect keymap bindings. This makes it possible to search for an indirect definition itself.

This function is used by where-is (see Help in The SXEmacs Lisp Reference Manual).

(where-is-internal 'describe-function)
    ⇒ ([(control h) d] [(control h) f] [f1 d] [f1 f])

Function: describe-bindings-internal map &optional all shadow prefix mouse-only-p

This function inserts (into the current buffer) a list of all defined keys and their definitions in map. Optional second argument all says whether to include even “uninteresting” definitions, i.e. symbols with a non-nil suppress-keymap property. Third argument shadow is a list of keymaps whose bindings shadow those of map; if a binding is present in any shadowing map, it is not printed. Fourth argument prefix, if non-nil, should be a key sequence; only bindings which start with that key sequence will be printed. Fifth argument mouse-only-p says to only print bindings for mouse clicks.

describe-bindings-internal is used to implement the help command describe-bindings.

Command: describe-bindings &optional prefix mouse-only-p

This function creates a listing of all defined keys and their definitions. It writes the listing in a buffer named ‘*Help*’ and displays it in a window.

If optional argument 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 the second optional argument mouse-only-p (prefix arg, interactively) is non-nil then only the mouse bindings are displayed.