Creating Keymaps

Here we describe the functions for creating keymaps.

Function: make-sparse-keymap &optional prompt

This function creates and returns a new sparse keymap with no entries. (A sparse keymap is the kind of keymap you usually want.) The new keymap does not contain a char-table, unlike make-keymap, and does not bind any events.

(make-sparse-keymap)
    ⇒ (keymap)

If you specify prompt, that becomes the overall prompt string for the keymap. You should specify this only for menu keymaps (see Defining Menus). A keymap with an overall prompt string will always present a mouse menu or a keyboard menu if it is active for looking up the next input event. Don’t specify an overall prompt string for the main map of a major or minor mode, because that would cause the command loop to present a keyboard menu every time.

Function: make-keymap &optional prompt

This function creates and returns a new full keymap. That keymap contains a char-table (see Char-Tables) with slots for all characters without modifiers. The new keymap initially binds all these characters to nil, and does not bind any other kind of event. The argument prompt specifies a prompt string, as in make-sparse-keymap.

(make-keymap)
    ⇒ (keymap #^[nil nil keymap nil nil nil ...])

A full keymap is more efficient than a sparse keymap when it holds lots of bindings; for just a few, the sparse keymap is better.

Function: define-keymap &key options... &rest pairs...

You can create a keymap with the functions described above, and then use keymap-set (see Changing Key Bindings) to specify key bindings in that map. When writing modes, however, you frequently have to bind a large number of keys at once, and using keymap-set on them all can be tedious and error-prone. Instead you can use define-keymap, which creates a keymap and binds a number of keys. Here’s a very basic example:

(define-keymap
  "n" #'forward-line
  "f" #'previous-line
  "C-c C-c" #'quit-window)

This function creates a new sparse keymap, defines the keystrokes in pairs, and returns the new keymap. It signals an error if there are duplicate key bindings in pairs.

pairs is a list of alternating key bindings and key definitions, as accepted by keymap-set. In addition, the key can be the special symbol :menu, in which case the definition should be a menu definition as accepted by easy-menu-define (see Easy Menu). Here’s a brief example of this usage:

(define-keymap :full t
  "g" #'eww-reload
  :menu '("Eww"
          ["Exit" quit-window t]
          ["Reload" eww-reload t]))

A number of keywords can be used before the key/definition pairs to change features of the new keymap. If any of the feature keywords is missing from the define-keymap call, the default value for that feature is nil. Here’s a list of the available feature keywords:

:full

If non-nil, create a char-table keymap (as from make-keymap) instead of a sparse keymap (as from make-sparse-keymap (see Creating Keymaps). A sparse keymap is the default.

:parent

If non-nil, the value should be a keymap to use as the parent (see Inheritance and Keymaps).

:keymap

If non-nil, the value should be a keymap. Instead of creating a new keymap, the specified keymap is modified instead.

:suppress

If non-nil, the keymap will be suppressed with suppress-keymap (see Changing Key Bindings). By default, digits and the minus sign are exempt from suppressing, but if the value is nodigits, this suppresses digits and minus-sign like it does with other characters.

:name

If non-nil, the value should be a string to use as the menu for the keymap if you use it as a menu with x-popup-menu (see Pop-Up Menus).

:prefix

If non-nil, the value should be a symbol to be used as a prefix command (see Prefix Keys). If this is the case, this symbol is returned by define-keymap instead of the map itself.

Macro: defvar-keymap name &key options... &rest pairs...

By far, the most common thing to do with a keymap is to bind it to a variable. This is what virtually all modes do—a mode called foo almost always has a variable called foo-mode-map.

This macro defines name as a variable, passes options and pairs to define-keymap, and uses the result as the default value for the variable. It signals an error if there are duplicate key bindings in pairs.

options is mostly like the keywords in define-keymap. There’s an additional :doc keyword that provides the doc string for the defined variable. Here’s an example:

(defvar-keymap eww-textarea-map
  :parent text-mode-map
  :doc "Keymap for the eww text area."
  "RET" #'forward-line
  "TAB" #'shr-next-link)

The :prefix keyword can take an additional value, t, which is an abbreviation for using name as the value of that option. I.e. instead of writing

(defvar-keymap foo-map
  :prefix 'foo-map
  ...)

you can write

(defvar-keymap foo-map
  :prefix t
  ...)

Each command in the keymap can be marked as ‘repeatable’, i.e. usable in repeat-mode, by putting a repeat-map property on it, for example:

(put 'undo 'repeat-map 'undo-repeat-map)

where the value of the property is the map to be used by repeat-mode.

To avoid repetitive invocations of put, defvar-keymap also has a :repeat keyword, which can be used to specify which commands in the keymap are usable by repeat-mode. The following values are available:

t

This means all the commands in the keymap are repeatable, and is the most common usage.

(:enter (commands ...) :exit (commands ...)

:continue (commands ...) :hints ((command . "hint") ...))

This specifies that the commands in the :enter list enter repeat-mode, and the commands in the :exit list exit repeat mode.

If the :enter list is empty, then all commands in the map enter repeat-mode. Specifying one or more commands in this list is useful if there is a command which doesn’t exist in the map being defined, but which should have the repeat-map property.

If the :exit list is empty then no commands in the map exit repeat-mode. Specifying one or more commands in this list is useful if the keymap being defined contains a command that should not have the repeat-map property.

The :continue list specifies the commands that should not enter repeat-mode. These command should only continue the already activated repeating sequence.

The :hints list can contain cons pairs where the CAR is a command and the CDR is a string that is displayed alongside of the repeatable key in the echo area.

In order to make e.g. u repeat the undo command, the following two stanzas are equivalent:

(defvar-keymap undo-repeat-map
  "u" #'undo)
(put 'undo 'repeat-map 'undo-repeat-map)

and

(defvar-keymap undo-repeat-map
  :repeat t
  "u" #'undo)

The latter is preferred when there are many commands in the map, all of which should be repeatable.

Function: copy-keymap keymap

This function returns a copy of keymap. This is almost never needed. If you want a keymap that’s like another yet with a few changes, you should use map inheritance rather than copying. I.e., something like:

(let ((map (make-sparse-keymap)))
  (set-keymap-parent map <theirmap>)
  (keymap-set map ...)
  ...)

When performing copy-keymap, any keymaps that appear directly as bindings in keymap are also copied recursively, and so on to any number of levels. However, recursive copying does not take place when the definition of a character is a symbol whose function definition is a keymap; the same symbol appears in the new copy.

(setq map (copy-keymap (current-local-map)))
⇒ (keymap

     ;; (This implements meta characters.)
     (27 keymap
         (83 . center-paragraph)
         (115 . center-line))
     (9 . tab-to-tab-stop))

(eq map (current-local-map))
    ⇒ nil

(equal map (current-local-map))
    ⇒ t