22.7 Active Keymaps

Emacs normally contains many keymaps; at any given time, just a few of them are active, meaning that they participate in the interpretation of user input. All the active keymaps are used together to determine what command to execute when a key is entered. Emacs searches these keymaps one by one, in a standard order, until it finds a binding in one of the keymaps.

Normally the active keymaps are the keymap property keymap, the keymaps of any enabled minor modes, the current buffer's local keymap, and the global keymap, in that order. Therefore, Emacs searches for each input key sequence in all these keymaps. Here is a pseudo-Lisp description of how this process works:

     (or (if overriding-terminal-local-map
             (find-in overriding-terminal-local-map)
           (if overriding-local-map
               (find-in overriding-local-map)
             (or (find-in (get-text-property (point) 'keymap))
                 (find-in-any emulation-mode-map-alists)
                 (find-in-any minor-mode-overriding-map-alist)
                 (find-in-any minor-mode-map-alist)
                 (if (get-text-property (point) 'local-map)
                     (find-in (get-text-property (point) 'local-map))
                   (find-in (current-local-map))))))
         (find-in (current-global-map)))

Here, the pseudo-function find-in means to look up the key sequence in a single map, and find-in-any means to search the appropriate keymaps from an alist. (Searching a single keymap for a binding is called key lookup; see Key Lookup.)

The global keymap holds the bindings of keys that are defined regardless of the current buffer, such as C-f. The variable global-map holds this keymap, which is always active.

Each buffer may have another keymap, its local keymap, which may contain new or overriding definitions for keys. The current buffer's local keymap is always active except when overriding-local-map overrides it. The local-map text or overlay property can specify an alternative local keymap for certain parts of the buffer; see Special Properties.

Each minor mode can have a keymap; if it does, the keymap is active when the minor mode is enabled. Modes for emulation can specify additional active keymaps through the variable emulation-mode-map-alists.

The highest precedence normal keymap comes from the keymap text or overlay property. If that is non-nil, it is the first keymap to be processed, in normal circumstances.

However, there are also special ways for programs to substitute other keymaps for some of those. The variable overriding-local-map, if non-nil, specifies a keymap that replaces all the usual active keymaps except the global keymap. Another way to do this is with overriding-terminal-local-map; it operates on a per-terminal basis. These variables are documented below.

Since every buffer that uses the same major mode normally uses the same local keymap, you can think of the keymap as local to the mode. A change to the local keymap of a buffer (using local-set-key, for example) is seen also in the other buffers that share that keymap.

The local keymaps that are used for Lisp mode and some other major modes exist even if they have not yet been used. These local keymaps are the values of variables such as lisp-mode-map. For most major modes, which are less frequently used, the local keymap is constructed only when the mode is used for the first time in a session.

The minibuffer has local keymaps, too; they contain various completion and exit commands. See Intro to Minibuffers.

Emacs has other keymaps that are used in a different way—translating events within read-key-sequence. See Translation Keymaps.

See Standard Keymaps, for a list of standard keymaps.

Home

Terms of Use

About

Advertise

Subscribe