Info Catalog elisp: Creating Keymaps elisp: Keymaps elisp: Prefix Keys

elisp: Inheritance and Keymaps

 
 21.5 Inheritance and Keymaps
 ============================
 
 A keymap can inherit the bindings of another keymap, which we call the
 “parent keymap”.  Such a keymap looks like this:
 
      (keymap ELEMENTS... . PARENT-KEYMAP)
 
 The effect is that this keymap inherits all the bindings of
 PARENT-KEYMAP, whatever they may be at the time a key is looked up, but
 can add to them or override them with ELEMENTS.
 
    If you change the bindings in PARENT-KEYMAP using ‘define-key’ or
 other key-binding functions, these changed bindings are visible in the
 inheriting keymap, unless shadowed by the bindings made by ELEMENTS.
 The converse is not true: if you use ‘define-key’ to change bindings in
 the inheriting keymap, these changes are recorded in ELEMENTS, but have
 no effect on PARENT-KEYMAP.
 
    The proper way to construct a keymap with a parent is to use
 ‘set-keymap-parent’; if you have code that directly constructs a keymap
 with a parent, please convert the program to use ‘set-keymap-parent’
 instead.
 
  -- Function: keymap-parent keymap
      This returns the parent keymap of KEYMAP.  If KEYMAP has no parent,
      ‘keymap-parent’ returns ‘nil’.
 
  -- Function: set-keymap-parent keymap parent
      This sets the parent keymap of KEYMAP to PARENT, and returns
      PARENT.  If PARENT is ‘nil’, this function gives KEYMAP no parent
      at all.
 
      If KEYMAP has submaps (bindings for prefix keys), they too receive
      new parent keymaps that reflect what PARENT specifies for those
      prefix keys.
 
    Here is an example showing how to make a keymap that inherits from
 ‘text-mode-map’:
 
      (let ((map (make-sparse-keymap)))
        (set-keymap-parent map text-mode-map)
        map)
 
    A non-sparse keymap can have a parent too, but this is not very
 useful.  A non-sparse keymap always specifies something as the binding
 for every numeric character code without modifier bits, even if it is
 ‘nil’, so these character’s bindings are never inherited from the parent
 keymap.
 
    Sometimes you want to make a keymap that inherits from more than one
 map.  You can use the function ‘make-composed-keymap’ for this.
 
  -- Function: make-composed-keymap maps &optional parent
      This function returns a new keymap composed of the existing
      keymap(s) MAPS, and optionally inheriting from a parent keymap
      PARENT.  MAPS can be a single keymap or a list of more than one.
      When looking up a key in the resulting new map, Emacs searches in
      each of the MAPS in turn, and then in PARENT, stopping at the first
      match.  A ‘nil’ binding in any one of MAPS overrides any binding in
      PARENT, but it does not override any non-‘nil’ binding in any other
      of the MAPS.
 
 For example, here is how Emacs sets the parent of ‘help-mode-map’, such
 that it inherits from both ‘button-buffer-map’ and ‘special-mode-map’:
 
      (defvar help-mode-map
        (let ((map (make-sparse-keymap)))
          (set-keymap-parent map
            (make-composed-keymap button-buffer-map special-mode-map))
          ... map) ... )
 

Info Catalog elisp: Creating Keymaps elisp: Keymaps elisp: Prefix Keys