23.12 Changing Key Bindings

The way to rebind a key is to change its entry in a keymap. If you change a binding in the global keymap, the change is effective in all buffers (though it has no direct effect in buffers that shadow the global binding with a local one). If you change the current buffer’s local map, that usually affects all buffers using the same major mode. The keymap-global-set and keymap-local-set functions are convenient interfaces for these operations (see Commands for Binding Keys). You can also use keymap-set, a more general function; then you must explicitly specify the map to change.

When choosing the key sequences for Lisp programs to rebind, please follow the Emacs conventions for use of various keys (see Key Binding Conventions).

The functions below signal an error if keymap is not a keymap, or if key is not a valid key.

key is a string representing a single key or a series of key strokes, and must satisfy key-valid-p. Key strokes are separated by a single space character.

Each key stroke is either a single character, or the name of an event, surrounded by angle brackets. In addition, any key stroke may be preceded by one or more modifier keys. Finally, a limited number of characters have a special shorthand syntax. Here’s some example key sequences:

f

The key f.

S o m

A three key sequence of the keys S, o and m.

C-c o

A two key sequence of the keys c with the control modifier and then the key o

H-<left>

The key named left with the hyper modifier.

M-RET

The return key with a meta modifier.

C-M-<space>

The space key with both the control and meta modifiers.

The only keys that have a special shorthand syntax are NUL, RET, TAB, LFD, ESC, SPC and DEL.

The modifiers have to be specified in alphabetical order: ‘A-C-H-M-S-s’, which is ‘Alt-Control-Hyper-Meta-Shift-super’.

Function: keymap-set keymap key binding ¶

This function sets the binding for key in keymap. (If key is more than one event long, the change is actually made in another keymap reached from keymap.) The argument binding can be any Lisp object, but only certain types are meaningful. (For a list of meaningful types, see Key Lookup.) The value returned by keymap-set is binding.

If key is <t>, this sets the default binding in keymap. When an event has no binding of its own, the Emacs command loop uses the keymap’s default binding, if there is one.

Every prefix of key must be a prefix key (i.e., bound to a keymap) or undefined; otherwise an error is signaled. If some prefix of key is undefined, then keymap-set defines it as a prefix key so that the rest of key can be defined as specified.

If there was previously no binding for key in keymap, the new binding is added at the beginning of keymap. The order of bindings in a keymap makes no difference for keyboard input, but it does matter for menu keymaps (see Menu Keymaps).

Function: keymap-unset keymap key &optional remove ¶

This function is the inverse of keymap-set, it unsets the binding for key in keymap, which is the same as setting the binding to nil. In order to instead remove the binding completely, specify remove as non-nil. This only makes a difference if keymap has a parent keymap: if you just unset a key in a child map, it will still shadow the same key in the parent keymap; using remove instead will allow the key in the parent keymap to be used.

Note: using keymap-unset with remove non-nil is intended for users to put in their init file; Emacs packages should avoid using it if possible, since they have complete control over their own keymaps anyway, and they should not be altering other packages’ keymaps.

This example creates a sparse keymap and makes a number of bindings in it:

(setq map (make-sparse-keymap))
    ⇒ (keymap)

(keymap-set map "C-f" 'forward-char)
    ⇒ forward-char

map
    ⇒ (keymap (6 . forward-char))

;; Build sparse submap for C-x and bind f in that.
(keymap-set map "C-x f" 'forward-word)
    ⇒ forward-word

map
⇒ (keymap
    (24 keymap                ; C-x
        (102 . forward-word)) ;      f
    (6 . forward-char))       ; C-f

;; Bind C-p to the ctl-x-map.
(keymap-set map "C-p" ctl-x-map)
;; ctl-x-map
⇒ [nil … find-file … backward-kill-sentence]

;; Bind C-f to foo in the ctl-x-map.
(keymap-set map "C-p C-f" 'foo)
⇒ 'foo

map
⇒ (keymap     ; Note foo in ctl-x-map.
    (16 keymap [nil … foo … backward-kill-sentence])
    (24 keymap
        (102 . forward-word))
    (6 . forward-char))

Note that storing a new binding for C-p C-f actually works by changing an entry in ctl-x-map, and this has the effect of changing the bindings of both C-p C-f and C-x C-f in the default global map.

keymap-set is the general work horse for defining a key in a keymap. 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. See Creating Keymaps, for details.

The function substitute-key-definition scans a keymap for keys that have a certain binding and rebinds them with a different binding. Another feature which is cleaner and can often produce the same results is to remap one command into another (see Remapping Commands).

Function: substitute-key-definition olddef newdef keymap &optional oldmap ¶

This function replaces olddef with newdef for any keys in keymap that were bound to olddef. In other words, olddef is replaced with newdef wherever it appears. The function returns nil.

For example, this redefines C-x C-f, if you do it in an Emacs with standard bindings:

(substitute-key-definition
 'find-file 'find-file-read-only (current-global-map))

If oldmap is non-nil, that changes the behavior of substitute-key-definition: the bindings in oldmap determine which keys to rebind. The rebindings still happen in keymap, not in oldmap. Thus, you can change one map under the control of the bindings in another. For example,

(substitute-key-definition
  'delete-backward-char 'my-funny-delete
  my-map global-map)

puts the special deletion command in my-map for whichever keys are globally bound to the standard deletion command.

Here is an example showing a keymap before and after substitution:

(setq map (list 'keymap
                (cons ?1 olddef-1)
                (cons ?2 olddef-2)
                (cons ?3 olddef-1)))
⇒ (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1))

(substitute-key-definition 'olddef-1 'newdef map)
⇒ nil

map
⇒ (keymap (49 . newdef) (50 . olddef-2) (51 . newdef))

Function: suppress-keymap keymap &optional nodigits ¶

This function changes the contents of the full keymap keymap by remapping self-insert-command to the command undefined (see Remapping Commands). This has the effect of undefining all printing characters, thus making ordinary insertion of text impossible. suppress-keymap returns nil.

If nodigits is nil, then suppress-keymap defines digits to run digit-argument, and - to run negative-argument. Otherwise it makes them undefined like the rest of the printing characters.

The suppress-keymap function does not make it impossible to modify a buffer, as it does not suppress commands such as yank and quoted-insert. To prevent any modification of a buffer, make it read-only (see Read-Only Buffers).

Since this function modifies keymap, you would normally use it on a newly created keymap. Operating on an existing keymap that is used for some other purpose is likely to cause trouble; for example, suppressing global-map would make it impossible to use most of Emacs.

This function can be used to initialize the local keymap of a major mode for which insertion of text is not desirable. But usually such a mode should be derived from special-mode (see Basic Major Modes); then its keymap will automatically inherit from special-mode-map, which is already suppressed. Here is how special-mode-map is defined:

(defvar special-mode-map
  (let ((map (make-sparse-keymap)))
    (suppress-keymap map)
    (keymap-set map "q" 'quit-window)
    …
    map))