@node Active Keymaps
@section Active Keymaps
@cindex active keymap
-@cindex global keymap
-@cindex local keymap
- Emacs normally contains many keymaps; at any given time, just a few
-of them are @dfn{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.
-
- Normally the active keymaps are the @code{keymap} property keymap,
-the keymaps of any enabled minor modes, the current buffer's local
-keymap, and the global keymap, in that order. Emacs searches for each
-input key sequence in all these keymaps. @xref{Searching Keymaps},
-for more details of this procedure.
-
- When the key sequence starts with a mouse event,
-the active keymaps are determined based on the
-position in that event. If the event happened on a string embedded
-with a @code{display}, @code{before-string}, or @code{after-string}
-property (@pxref{Special Properties}), the non-@code{nil} map
-properties of the string override those of the buffer (if the
-underlying buffer text contains map properties in its text properties
-or overlays, they are ignored).
-
- The @dfn{global keymap} holds the bindings of keys that are defined
-regardless of the current buffer, such as @kbd{C-f}. The variable
-@code{global-map} holds this keymap, which is always active.
-
- Each buffer may have another keymap, its @dfn{local keymap}, which
-may contain new or overriding definitions for keys. The current
-buffer's local keymap is always active except when
-@code{overriding-local-map} overrides it. The @code{local-map} text
-or overlay property can specify an alternative local keymap for certain
-parts of the buffer; see @ref{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
-@code{emulation-mode-map-alists}.
-
- The highest precedence normal keymap comes from the @code{keymap}
-text or overlay property. If that is non-@code{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
-@code{overriding-local-map}, if non-@code{nil}, specifies a keymap
-that replaces all the usual active keymaps except the global keymap.
-
-The very highest precedence keymap comes from
-@code{overriding-terminal-local-map}; it operates on a per-terminal basis and
-is normally used for modal/transient keybindings.
+ Emacs contains many keymaps, but at any time only a few keymaps are
+@dfn{active}. When Emacs receives user input, it translates the input
+event (@pxref{Translation Keymaps}), and looks for a key binding in
+the active keymaps.
+
+ Usually, the active keymaps are: (i) the keymap specified by the
+@code{keymap} property, (ii) the keymaps of enabled minor modes, (iii)
+the current buffer's local keymap, and (iv) the global keymap, in that
+order. Emacs searches for each input key sequence in all these
+keymaps.
+
+ Of these ``usual'' keymaps, the highest-precedence one is specified
+by the @code{keymap} text or overlay property at point, if any. (For
+a mouse input event, Emacs uses the event position instead of point;
+@iftex
+see the next section for details.)
+@end iftex
+@ifnottex
+@pxref{Searching Keymaps}.)
+@end ifnottex
+
+ Next in precedence are keymaps specified by enabled minor modes.
+These keymaps, if any, are specified by the variables
+@code{emulation-mode-map-alists},
+@code{minor-mode-overriding-map-alist}, and
+@code{minor-mode-map-alist}. @xref{Controlling Active Maps}.
-@cindex major mode keymap
- 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 @code{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 @code{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.
+@cindex local keymap
+ Next in precedence is the buffer's @dfn{local keymap}, containing
+key bindings specific to the buffer. The minibuffer also has a local
+keymap (@pxref{Intro to Minibuffers}). If there is a @code{local-map}
+text or overlay property at point, that specifies the local keymap to
+use, in place of the buffer's default local keymap.
- The minibuffer has local keymaps, too; they contain various completion
-and exit commands. @xref{Intro to Minibuffers}.
+@cindex major mode keymap
+ The local keymap is normally set by the buffer's major mode, and
+every buffer with the same major mode shares the same local keymap.
+Hence, if you call @code{local-set-key} (@pxref{Key Binding Commands})
+to change the local keymap in one buffer, that also affects the local
+keymaps in other buffers with the same major mode.
- Emacs has other keymaps that are used in a different way---translating
-events within @code{read-key-sequence}. @xref{Translation Keymaps}.
+@cindex global keymap
+ Finally, the @dfn{global keymap} contains key bindings that are
+defined regardless of the current buffer, such as @kbd{C-f}. It is
+always active, and is bound to the variable @code{global-map}.
+
+ Apart from the above ``usual'' keymaps, Emacs provides special ways
+for programs to make other keymaps active. Firstly, the variable
+@code{overriding-local-map} specifies a keymap that replaces the usual
+active keymaps, except for the global keymap. Secondly, the
+terminal-local variable @code{overriding-terminal-local-map} specifies
+a keymap that takes precedence over @emph{all} other keymaps
+(including @code{overriding-local-map}); this is normally used for
+modal/transient keybindings (the function @code{set-transient-map}
+provides a convenient interface for this). @xref{Controlling Active
+Maps}, for details.
+
+ Making keymaps active is not the only way to use them. Keymaps are
+also used in other ways, such as for translating events within
+@code{read-key-sequence}. @xref{Translation Keymaps}.
@xref{Standard Keymaps}, for a list of some standard keymaps.
position or an event position like the value of @code{event-start}.
Then the maps consulted are determined based on @var{position}.
-An error is signaled if @var{key} is not a string or a vector.
+Emacs signals an error if @var{key} is not a string or a vector.
@example
@group
@section Searching the Active Keymaps
@cindex searching active keymaps for keys
- After translation of event subsequences (@pxref{Translation
-Keymaps}) Emacs looks for them in the active keymaps. Here is a
-pseudo-Lisp description of the order and conditions for searching
-them:
+Here is a pseudo-Lisp summary of how Emacs searches the active
+keymaps:
@lisp
-(or (@var{find-in} @var{transient-map})
- (cond
- (overriding-terminal-local-map
- (@var{find-in} overriding-terminal-local-map))
- (overriding-local-map
- (@var{find-in} overriding-local-map))
- ((or (@var{find-in} (get-char-property (point) 'keymap))
+(or (if overriding-terminal-local-map
+ (@var{find-in} overriding-terminal-local-map))
+ (if overriding-local-map
+ (@var{find-in} overriding-local-map)
+ (or (@var{find-in} (get-char-property (point) 'keymap))
(@var{find-in-any} emulation-mode-map-alists)
(@var{find-in-any} minor-mode-overriding-map-alist)
(@var{find-in-any} minor-mode-map-alist)
(if (get-text-property (point) 'local-map)
(@var{find-in} (get-char-property (point) 'local-map))
- (@var{find-in} (current-local-map))))))
+ (@var{find-in} (current-local-map)))))
(@var{find-in} (current-global-map)))
@end lisp
@noindent
Here, @var{find-in} and @var{find-in-any} are pseudo functions that
-search in one keymap and in an alist of keymaps, respectively.
-(Searching a single keymap for a binding is called @dfn{key lookup};
-see @ref{Key Lookup}.) @var{transient-map} is a pseudo variable that
-represents the effect of a @code{set-transient-map} call
-(@pxref{Controlling Active Maps}).
+search in one keymap and in an alist of keymaps, respectively. Note
+that the @code{set-transient-map} function works by setting
+@code{overriding-terminal-local-map} (@pxref{Controlling Active
+Maps}).
In the above pseudo-code, if a key sequence starts with a mouse
-event, that event's position is used instead of point and the current
-buffer. Mouse events on an embedded string use non-@code{nil} text
-properties from that string instead of the buffer.
-
- When a match is found (@pxref{Key Lookup}), if the binding in the
-keymap is a function, the search is over. However if the keymap entry
-is a symbol with a value or a string, Emacs replaces the input key
-sequences with the variable's value or the string, and restarts the
-search of the active keymaps.
-
- The function finally found might also be remapped. @xref{Remapping
-Commands}.
+event (@pxref{Mouse Events}), that event's position is used instead of
+point, and the event's buffer is used instead of the current buffer.
+In particular, this affects how the @code{keymap} and @code{local-map}
+properties are looked up. If a mouse event occurs on a string
+embedded with a @code{display}, @code{before-string}, or
+@code{after-string} property (@pxref{Special Properties}), and the
+string has a non-@code{nil} @code{keymap} or @code{local-map}
+property, that overrides the corresponding property in the underlying
+buffer text (i.e., the property specified by the underlying text is
+ignored).
+
+ When a key binding is found in one of the active keymaps, and that
+binding is a command, the search is over---the command is executed.
+However, if the binding is a symbol with a value or a string, Emacs
+replaces the input key sequences with the variable's value or the
+string, and restarts the search of the active keymaps. @xref{Key
+Lookup}.
+
+ The command which is finally found might also be remapped.
+@xref{Remapping Commands}.
@node Controlling Active Maps
@section Controlling the Active Keymaps
commands use this function.
@end defun
-@c Emacs 19 feature
@defvar minor-mode-map-alist
@anchor{Definition of minor-mode-map-alist}
This variable is an alist describing keymaps that may or may not be
@end defvar
@defvar emulation-mode-map-alists
-This variable holds a list of keymap alists to use for emulations
+This variable holds a list of keymap alists to use for emulation
modes. It is intended for modes or packages using multiple minor-mode
keymaps. Each element is a keymap alist which has the same format and
meaning as @code{minor-mode-map-alist}, or a symbol with a variable
while @var{keymap} is active; it should return non-@code{nil} if
@var{keymap} should stay active.
-The transient keymap takes precedence over the ``overriding'' maps
-(see above); and unlike them, if no match for a key is found in
-@var{keymap}, the key lookup process continues. For a pseudo-Lisp
-description of exactly how and when this keymap applies,
-@xref{Searching Keymaps}.
+This function works by adding and removing @code{keymap} from the
+variable @code{overriding-terminal-local-map}, which takes precedence
+over all other active keymaps (@pxref{Searching Keymaps}).
@end defun
@node Key Lookup
projects / emacs.git / commitdiff