Keymaps

• The representation of keymaps has changed to support the new event types. All keymaps now have the form (keymap element element ...). Each element takes one of the following forms:

  prompt-string

  A string as an element of the keymap marks the keymap as a menu, and serves as the overall prompt string for it.

  (key . binding)

  A cons cell binds key to definition. Here key may be any sort of event head--a character, a function key symbol, or a mouse button symbol.

  vector

  A vector of 128 elements binds all the ASCII characters; the nth element holds the binding for character number n.

  (t . binding)

  A cons cell whose CAR is t is a default binding; anything not bound by previous keymap elements is given binding as its binding. Default bindings are important because they allow a keymap to bind all possible events without having to enumerate all the possible function keys and mouse clicks, with all possible modifier prefixes. The function lookup-key (and likewise other functions for examining a key binding) normally report only explicit bindings of the specified key sequence; if there is none, they return nil, even if there is a default binding that would apply to that key sequence if it were actually typed in. However, these functions now take an optional argument accept-defaults which, if non-nil, says to consider default bindings. Note that if a vector in the keymap binds an ASCII character to nil (thus making it "unbound"), the default binding does not apply to the character. Think of the vector element as an explicit binding of nil. Note also that if the keymap for a minor or major mode contains a default binding, it completely masks out any lower-priority keymaps.

• A keymap can now inherit from another keymap. To do this, make the latter keymap the "tail" of the new one. Such a keymap looks like this:

  (keymap bindings... . other-keymap)
  

  The effect is that this keymap inherits all the bindings of other-keymap, but can add to them or override them with bindings. Subsequent changes in the bindings of other-keymap do affect this keymap. For example,

  (setq my-mode-map (cons 'keymap text-mode-map))
  

  makes a keymap that by default inherits all the bindings of Text mode--whatever they may be at the time a key is looked up. Any bindings made explicitly in my-mode-map override the bindings inherited from Text mode, however.
• Minor modes can now have local keymaps. Thus, a key can act a special way when a minor mode is in effect, and then revert to the major mode or global definition when the minor mode is no longer in effect. The precedence of keymaps is now: minor modes (in no particular order), then major mode, and lastly the global map. The new current-minor-mode-maps function returns a list of all the keymaps of currently enabled minor modes, in the other that they apply. To set up a keymap for a minor mode, add an element to the alist minor-mode-map-alist. Its elements look like this:

  (symbol . keymap)
  

  The keymap keymap is active whenever symbol has a non-nil value. Use for symbol the variable which indicates whether the minor mode is enabled. When more than one minor mode keymap is active, their order of precedence is the order of minor-mode-map-alist. But you should design minor modes so that they don't interfere with each other, and if you do this properly, the order will not matter. The function minor-mode-key-binding returns a list of all the active minor mode bindings of key. More precisely, it returns an alist of pairs (modename . binding), where modename is the the variable which enables the minor mode, and binding is key's definition in that mode. If key has no minor-mode bindings, the value is nil. If the first binding is a non-prefix, all subsequent bindings from other minor modes are omitted, since they would be completely shadowed. Similarly, the list omits non-prefix bindings that follow prefix bindings.
• The new function copy-keymap copies a keymap, producing a new keymap with the same key bindings in it. If the keymap contains other keymaps directly, these subkeymaps are copied recursively. If you want to, you can define a prefix key with a binding that is a symbol whose function definition is another keymap. In this case, copy-keymap does not look past the symbol; it doesn't copy the keymap inside the symbol.
• substitute-key-definition now accepts an optional fourth argument, which is a keymap to use as a template.

  (substitute-key-definition olddef newdef keymap oldmap)
  

  finds all characters defined in oldmap as olddef, and defines them in keymap as newdef. In addition, this function now operates recursively on the keymaps that define prefix keys within keymap and oldmap.