26.10 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 global-set-key and local-set-key functions are convenient interfaces for these operations (see Key Binding Commands). You can also use define-key, a more general function; then you must specify explicitly the map to change.

The way to specify the key sequence that you want to rebind is described above (see Key Sequences).

For the functions below, an error is signaled if keymap is not a keymap or if key is not a string or vector representing a key sequence. You can use event types (symbols) as shorthand for events that are lists.

Function: define-key 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 define-key is binding.

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 define-key defines it as a prefix key so that the rest of key may be defined as specified.

Here is an example that creates a sparse keymap and makes a number of bindings in it:

(setq map (make-sparse-keymap))
    ⇒ #<keymap 0 entries 0xbee>

(define-key map "\C-f" 'forward-char)
    ⇒ forward-char

map
    ⇒ #<keymap 1 entry 0xbee>
(describe-bindings-internal map)
⇒   ; (Inserted in buffer)
C-f             forward-char

;; Build sparse submap for C-x and bind f in that.
(define-key map "\C-xf" 'forward-word)
    ⇒ forward-word

map
    ⇒ #<keymap 2 entries 0xbee>
(describe-bindings-internal map)
⇒   ; (Inserted in buffer)
C-f             forward-char
C-x             << Prefix Command >>

C-x f           forward-word

;; Bind C-p to the ctl-x-map.
(define-key map "\C-p" ctl-x-map)
;; ctl-x-map
⇒ #<keymap Control-X-prefix 77 entries 0x3bf>

;; Bind C-f to foo in the ctl-x-map.
(define-key map "\C-p\C-f" 'foo)
⇒ foo

map
    ⇒ #<keymap 3 entries 0xbee>
(describe-bindings-internal map)
⇒   ; (Inserted in buffer)
C-f             forward-char
C-p             << Prefix command Control-X-prefix >>
C-x             << Prefix Command >>

C-p tab         indent-rigidly
C-p $           set-selective-display
C-p '           expand-abbrev
C-p (           start-kbd-macro
C-p )           end-kbd-macro
   …
C-p C-x         exchange-point-and-mark
C-p C-z         suspend-or-iconify-emacs
C-p M-escape    repeat-complex-command
C-p M-C-[       repeat-complex-command

C-x f           forward-word

C-p 4 .         find-tag-other-window
   …
C-p 4 C-o       display-buffer

C-p 5 0         delete-frame
   …
C-p 5 C-f       find-file-other-frame

   …

C-p a i g       inverse-add-global-abbrev
C-p a i l       inverse-add-mode-abbrev

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.

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

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. Prefix keymaps are checked recursively.

The function returns nil.

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

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

If oldmap is non-nil, then its bindings 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.

If argument prefix is non-nil, then only those occurrences of olddef found in keymaps accessible through the keymap bound to prefix in keymap are redefined. See also accessible-keymaps.

Function: suppress-keymap keymap &optional nodigits

This function changes the contents of the full keymap keymap by making all the printing characters undefined. More precisely, it binds them to the command undefined. This makes 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 SXEmacs.

Most often, suppress-keymap is used to initialize local keymaps of modes such as Rmail and Dired where insertion of text is not desirable and the buffer is read-only. Here is an example taken from the file <sxemacs-src>/lisp/dired.el, showing how the local keymap for Dired mode is set up:

  …
  (setq dired-mode-map (make-keymap))
  (suppress-keymap dired-mode-map)
  (define-key dired-mode-map "r" 'dired-rename-file)
  (define-key dired-mode-map "\C-d" 'dired-flag-file-deleted)
  (define-key dired-mode-map "d" 'dired-flag-file-deleted)
  (define-key dired-mode-map "v" 'dired-view-file)
  (define-key dired-mode-map "e" 'dired-find-file)
  (define-key dired-mode-map "f" 'dired-find-file)
  …