www.delorie.com/gnu/docs/elisp-manual-21/elisp_329.html   search  
Buy the book!

GNU Emacs Lisp Reference Manual

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

22.6 Active Keymaps

Emacs normally contains many keymaps; at any given time, just a few of them are active in that they participate in the interpretation of user input. These are the global keymap, the current buffer's local keymap, and the keymaps of any enabled minor modes.

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. Text properties can specify an alternative local map for certain parts of the buffer; see 32.19.4 Properties with Special Meanings.

Each minor mode can have a keymap; if it does, the keymap is active when the minor mode is enabled.

The variable overriding-local-map, if non-nil, specifies another local keymap that overrides the buffer's local map and all the minor mode keymaps.

All the active keymaps are used together to determine what command to execute when a key is entered. Emacs searches these maps one by one, in order of decreasing precedence, until it finds a binding in one of the maps. The procedure for searching a single keymap is called key lookup; see 22.7 Key Lookup.

Normally, Emacs first searches for the key in the minor mode maps, in the order specified by minor-mode-map-alist; if they do not supply a binding for the key, Emacs searches the local map; if that too has no binding, Emacs then searches the global map. However, if overriding-local-map is non-nil, Emacs searches that map first, before the global map.

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 maps 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 section 20.1 Introduction to Minibuffers.

Emacs has other keymaps that are used in a different way--translating events within read-key-sequence. See section 40.8.2 Translating Input Events.

See section H. Standard Keymaps, for a list of standard keymaps.

Variable: global-map
This variable contains the default global keymap that maps Emacs keyboard input to commands. The global keymap is normally this keymap. The default global keymap is a full keymap that binds self-insert-command to all of the printing characters.

It is normal practice to change the bindings in the global map, but you should not assign this variable any value other than the keymap it starts out with.

Function: current-global-map
This function returns the current global keymap. This is the same as the value of global-map unless you change one or the other.

=> (keymap [set-mark-command beginning-of-line ... 

Function: current-local-map
This function returns the current buffer's local keymap, or nil if it has none. In the following example, the keymap for the `*scratch*' buffer (using Lisp Interaction mode) is a sparse keymap in which the entry for ESC, ASCII code 27, is another sparse keymap.

=> (keymap 
    (10 . eval-print-last-sexp) 
    (9 . lisp-indent-line) 
    (127 . backward-delete-char-untabify) 
    (27 keymap 
        (24 . eval-defun) 
        (17 . indent-sexp)))

Function: current-minor-mode-maps
This function returns a list of the keymaps of currently enabled minor modes.

Function: use-global-map keymap
This function makes keymap the new current global keymap. It returns nil.

It is very unusual to change the global keymap.

Function: use-local-map keymap
This function makes keymap the new local keymap of the current buffer. If keymap is nil, then the buffer has no local keymap. use-local-map returns nil. Most major mode commands use this function.

Variable: minor-mode-map-alist
This variable is an alist describing keymaps that may or may not be active according to the values of certain variables. Its elements look like this:

(variable . keymap)

The keymap keymap is active whenever variable has a non-nil value. Typically variable is the variable that enables or disables a minor mode. See section 23.2.2 Keymaps and Minor Modes.

Note that elements of minor-mode-map-alist do not have the same structure as elements of minor-mode-alist. The map must be the CDR of the element; a list with the map as the second element will not do. The CDR can be either a keymap (a list) or a symbol whose function definition is a keymap.

When more than one minor mode keymap is active, their order of priority is the order of minor-mode-map-alist. But you should design minor modes so that they don't interfere with each other. If you do this properly, the order will not matter.

See 23.2.2 Keymaps and Minor Modes, for more information about minor modes. See also minor-mode-key-binding (see section 22.8 Functions for Key Lookup).

Variable: minor-mode-overriding-map-alist
This variable allows major modes to override the key bindings for particular minor modes. The elements of this alist look like the elements of minor-mode-map-alist: (variable . keymap).

If a variable appears as an element of minor-mode-overriding-map-alist, the map specified by that element totally replaces any map specified for the same variable in minor-mode-map-alist.

minor-mode-overriding-map-alist is automatically buffer-local in all buffers.

Variable: overriding-local-map
If non-nil, this variable holds a keymap to use instead of the buffer's local keymap and instead of all the minor mode keymaps. This keymap, if any, overrides all other maps that would have been active, except for the current global map.

Variable: overriding-terminal-local-map
If non-nil, this variable holds a keymap to use instead of overriding-local-map, the buffer's local keymap and all the minor mode keymaps.

This variable is always local to the current terminal and cannot be buffer-local. See section 29.2 Multiple Displays. It is used to implement incremental search mode.

Variable: overriding-local-map-menu-flag
If this variable is non-nil, the value of overriding-local-map or overriding-terminal-local-map can affect the display of the menu bar. The default value is nil, so those map variables have no effect on the menu bar.

Note that these two map variables do affect the execution of key sequences entered using the menu bar, even if they do not affect the menu bar display. So if a menu bar key sequence comes in, you should clear the variables before looking up and executing that key sequence. Modes that use the variables would typically do this anyway; normally they respond to events that they do not handle by "unreading" them and exiting.

Variable: special-event-map
This variable holds a keymap for special events. If an event type has a binding in this keymap, then it is special, and the binding for the event is run directly by read-event. See section 21.8 Special Events.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

  webmaster   donations   bookstore     delorie software   privacy  
  Copyright 2003   by The Free Software Foundation     Updated Jun 2003