Info Catalog elisp: Keymap Basics elisp: Keymaps elisp: Creating Keymaps

elisp: Format of Keymaps

 
 21.3 Format of Keymaps
 ======================
 
 Each keymap is a list whose CAR is the symbol ‘keymap’.  The remaining
 elements of the list define the key bindings of the keymap.  A symbol
 whose function definition is a keymap is also a keymap.  Use the
 function ‘keymapp’ (see below) to test whether an object is a keymap.
 
    Several kinds of elements may appear in a keymap, after the symbol
 ‘keymap’ that begins it:
 
 ‘(TYPE . BINDING)’
      This specifies one binding, for events of type TYPE.  Each ordinary
      binding applies to events of a particular “event type”, which is
      always a character or a symbol.  Classifying Events.  In
      this kind of binding, BINDING is a command.
 
 ‘(TYPE ITEM-NAME . BINDING)’
      This specifies a binding which is also a simple menu item that
      displays as ITEM-NAME in the menu.  Simple Menu Items.
 
 ‘(TYPE ITEM-NAME HELP-STRING . BINDING)’
      This is a simple menu item with help string HELP-STRING.
 
 ‘(TYPE menu-item . DETAILS)’
      This specifies a binding which is also an extended menu item.  This
      allows use of other features.  Extended Menu Items.
 
 ‘(t . BINDING)’
      This specifies a “default key binding”; any event not bound by
      other elements of the keymap is given BINDING as its binding.
      Default bindings allow a keymap to bind all possible event types
      without having to enumerate all of them.  A keymap that has a
      default binding completely masks any lower-precedence keymap,
      except for events explicitly bound to ‘nil’ (see below).
 
 ‘CHAR-TABLE’
      If an element of a keymap is a char-table, it counts as holding
      modifier bits::): the element whose index is C is the binding for
      the character C.  This is a compact way to record lots of bindings.
      A keymap with such a char-table is called a “full keymap”.  Other
      keymaps are called “sparse keymaps”.
 
 ‘VECTOR’
      This kind of element is similar to a char-table: the element whose
      index is C is the binding for the character C.  Since the range of
      characters that can be bound this way is limited by the vector
      size, and vector creation allocates space for all character codes
      from 0 up, this format should not be used except for creating menu
      keymaps (Menu Keymaps), where the bindings themselves don’t
      matter.
 
 ‘STRING’
      Aside from elements that specify bindings for keys, a keymap can
      also have a string as an element.  This is called the “overall
      prompt string” and makes it possible to use the keymap as a menu.
      Defining Menus.
 
 ‘(keymap ...)’
      If an element of a keymap is itself a keymap, it counts as if this
      inner keymap were inlined in the outer keymap.  This is used for
      multiple-inheritance, such as in ‘make-composed-keymap’.
 
    When the binding is ‘nil’, it doesn’t constitute a definition but it
 does take precedence over a default binding or a binding in the parent
 keymap.  On the other hand, a binding of ‘nil’ does _not_ override
 lower-precedence keymaps; thus, if the local map gives a binding of
 ‘nil’, Emacs uses the binding from the global map.
 
    Keymaps do not directly record bindings for the meta characters.
 Instead, meta characters are regarded for purposes of key lookup as
 sequences of two characters, the first of which is <ESC> (or whatever is
 currently the value of ‘meta-prefix-char’).  Thus, the key ‘M-a’ is
 internally represented as ‘<ESC> a’, and its global binding is found at
 the slot for ‘a’ in ‘esc-map’ (Prefix Keys).
 
    This conversion applies only to characters, not to function keys or
 other input events; thus, ‘M-<end>’ has nothing to do with ‘<ESC>
 <end>’.
 
    Here as an example is the local keymap for Lisp mode, a sparse
 keymap.  It defines bindings for <DEL>, ‘C-c C-z’, ‘C-M-q’, and ‘C-M-x’
 (the actual value also contains a menu binding, which is omitted here
 for the sake of brevity).
 
      lisp-mode-map
      ⇒
      (keymap
       (3 keymap
          ;; C-c C-z
          (26 . run-lisp))
       (27 keymap
           ;; ‘C-M-x’, treated as ‘<ESC> C-x’
           (24 . lisp-send-defun))
       ;; This part is inherited from ‘lisp-mode-shared-map’.
       keymap
       ;; <DEL>
       (127 . backward-delete-char-untabify)
       (27 keymap
           ;; ‘C-M-q’, treated as ‘<ESC> C-q’
           (17 . indent-sexp)))
 
  -- Function: keymapp object
      This function returns ‘t’ if OBJECT is a keymap, ‘nil’ otherwise.
      More precisely, this function tests for a list whose CAR is
      ‘keymap’, or for a symbol whose function definition satisfies
      ‘keymapp’.
 
           (keymapp '(keymap))
               ⇒ t
           (fset 'foo '(keymap))
           (keymapp 'foo)
               ⇒ t
           (keymapp (current-global-map))
               ⇒ t
 

Info Catalog elisp: Keymap Basics elisp: Keymaps elisp: Creating Keymaps