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 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.
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.
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.
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 like the keywords in define-keymap
, but
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
in repeat-mode
, by putting a repeat-map
property on it,
e.g.
(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 ...))
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.
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.
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