(lispref.info)Changing Key Bindings

Next: Key Binding Commands Prev: Functions for Key Lookup Up: Keymaps

Changing Key Bindings

   The way to rebind a key is to change its entry in a keymap.  You can
change the global keymap, so that the change is effective in all buffers
(except those that override the global binding with a local one).  Or
you can change the current buffer's local map, which usually affects all
buffers using the same major mode.  The `global-set-key' and
`local-set-key' functions are convenient interfaces for these
operations.  Or you can use `define-key' and specify explicitly which
map to change.

   People often use `global-set-key' in their `.emacs' file for simple
customization.  For example,

     (global-set-key "\C-x\C-\\" 'next-line)


     (global-set-key [?\C-x ?\C-\\] 'next-line)

redefines `C-x C-\' to move down a line.

     (global-set-key [M-mouse-1] 'mouse-set-point)

redefines the first (leftmost) mouse button, typed with the Meta key, to
set point where you click.

   In writing the key sequence to rebind, it is useful to use the
special escape sequences for control and meta characters (Note: String
Type.).  The syntax `\C-' means that the following character is a
control character and `\M-' means that the following character is a meta
character.  Thus, the string `"\M-x"' is read as containing a single
`M-x', `"\C-f"' is read as containing a single `C-f', and `"\M-\C-x"'
and `"\C-\M-x"' are both read as containing a single `C-M-x'.

   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.
However, 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 Note: 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

     The following example creates a sparse keymap and makes a number of

          (setq map (make-sparse-keymap))
              => (keymap)

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

              => (keymap (6 . forward-char))

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

          => (keymap
              (24 keymap                ; `C-x'
                  (102 . forward-word)) ;      `f'
              (6 . forward-char))       ; `C-f'

          ;; Bind `C-p' to the `ctl-x-map'.
          (define-key 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'.
          (define-key map "\C-p\C-f" 'foo)
          => 'foo

          => (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.

 - Function: substitute-key-definition OLDDEF NEWDEF KEYMAP &optional
     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:

           '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 NEWMAP, not in OLDMAP.
     Thus, you can change one map under the control of the bindings in
     another.  For example,

            '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 '(keymap
                      (?1 . olddef-1)
                      (?2 . olddef-2)
                      (?3 . olddef-1)))
          => (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1))

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

          => (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
     replacing the self-insertion commands for numbers with the
     `digit-argument' function, unless NODIGITS is non-`nil', and by
     replacing the functions for the rest of the printing characters
     with `undefined'.  This means that ordinary insertion of text is
     impossible in a buffer with a local keymap on which
     `suppress-keymap' has been called.

     `suppress-keymap' returns `nil'.

     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 (Note: 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.

     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 `emacs/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)

automatically generated by info2www