Here we describe the functions for creating keymaps.
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
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.
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-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.
You can create a keymap with the functions described above, and then
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
: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
nil. Here’s a list of the available feature
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.
nil, the value should be a keymap to use as the parent
(see Inheritance and Keymaps).
nil, the value should be a keymap. Instead of creating
a new keymap, the specified keymap is modified instead.
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
nodigits, this suppresses digits and minus-sign like
it does with other characters.
nil, the value should be a string to use as the menu for
the keymap if you use it as a menu with
(see Pop-Up Menus).
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
define-keymap instead of the map itself.
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
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 like the keywords in
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)
Each command in the keymap can be marked as ‘repeatable’, i.e. usable
repeat-mode, by putting a
repeat-map property on it,
(put 'undo 'repeat-map 'undo-repeat-map)
where the value of the property is the map to be used by
To avoid repetitive invocations of
also has a
:repeat keyword, which can be used to specify which
commands in the keymap are usable by
following values are available:
This means all the commands in the keymap are repeatable, and is the most common usage.
(:enter (commands ...) :exit (commands ...))
This specifies that the commands in the
:enter list enter
repeat-mode, and the commands in the
:exit list exit
: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
:exit list is empty then no commands in the map exit
repeat-mode. Specifying one ore more commands in this list is
useful if the keymap being defined contains a command that should not
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)
(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.
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 ...) ...)
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