@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2000, 2002, 2003,
-@c 2004, 2005 Free Software Foundation, Inc.
+@c 2004, 2005, 2006 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/keymaps
@node Keymaps, Modes, Command Loop, Top
* Inheritance and Keymaps:: How one keymap can inherit the bindings
of another keymap.
* Prefix Keys:: Defining a key with a keymap as its definition.
-* Active Keymaps:: Each buffer has a local keymap
+* Active Keymaps:: How Emacs searches the active keymaps
+ for a key binding.
+* Searching Keymaps:: A pseudo-Lisp summary of searching active maps.
+* Controlling Active Maps:: Each buffer has a local keymap
to override the standard (global) bindings.
A minor mode can also override them.
-* Key Lookup:: How extracting elements from keymaps works.
+* Key Lookup:: Finding a key's binding in one keymap.
* Functions for Key Lookup:: How to request key lookup.
* Changing Key Bindings:: Redefining a key in a keymap.
* Remapping Commands:: Bindings that translate one command to another.
@cindex local keymap
Emacs normally contains many keymaps; at any given time, just a few
-of them are @dfn{active} in that they participate in the
+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.
Emacs searches these keymaps one by one, in a standard order, until it
-finds a binding in one of the keymaps. (Searching a single keymap for a
-binding is called @dfn{key lookup}; see @ref{Key Lookup}.)
+finds a binding in one of the keymaps.
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. Therefore, Emacs
-searches for each input key sequence in all these keymaps.
+searches for each input key sequence in all these keymaps. Here is a
+pseudo-Lisp description of how this process works:
+
+@lisp
+(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-text-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-text-property (point) 'local-map))
+ (@var{find-in} (current-local-map))))))
+ (@var{find-in} (current-global-map)))
+@end lisp
+
+@noindent
+Here, the pseudo-function @var{find-in} means to look up the key
+sequence in a single map, and @var{find-in-any} means to search the
+appropriate keymaps from an alist. (Searching a single keymap for a
+binding is called @dfn{key lookup}; see @ref{Key Lookup}.)
The @dfn{global keymap} holds the bindings of keys that are defined
regardless of the current buffer, such as @kbd{C-f}. The variable
@xref{Standard Keymaps}, for a list of standard keymaps.
+@defun current-active-maps &optional olp
+This returns the list of active keymaps that would be used by the
+command loop in the current circumstances to look up a key sequence.
+Normally it ignores @code{overriding-local-map} and
+@code{overriding-terminal-local-map}, but if @var{olp} is
+non-@code{nil} then it pays attention to them.
+@end defun
+
+@defun key-binding key &optional accept-defaults no-remap
+This function returns the binding for @var{key} according to the
+current active keymaps. The result is @code{nil} if @var{key} is
+undefined in the keymaps.
+
+@c Emacs 19 feature
+The argument @var{accept-defaults} controls checking for default
+bindings, as in @code{lookup-key} (above).
+
+When commands are remapped (@pxref{Remapping Commands}),
+@code{key-binding} normally processes command remappings so as to
+returns the remapped command that will actually be executed. However,
+if @var{no-remap} is non-@code{nil}, @code{key-binding} ignores
+remappings and returns the binding directly specified for @var{key}.
+
+An error is signaled if @var{key} is not a string or a vector.
+
+@example
+@group
+(key-binding "\C-x\C-f")
+ @result{} find-file
+@end group
+@end example
+@end defun
+
+@node Searching Keymaps
+@section Searching the Active Keymaps
+
+ After translation of the input events (@pxref{Translating Input})
+Emacs looks for them in the active keymaps. Here is a pseudo-Lisp
+description of the order in which the active keymaps are searched:
+
+@lisp
+(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-text-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)
+ (@var{find-in} (get-text-property (point) 'local-map))
+ (@var{find-in} (current-local-map)))))
+ (@var{find-in} (current-global-map)))
+@end lisp
+
+@noindent
+The @var{find-in} and @var{find-in-any} are pseudo functions that
+searches in one keymap respectively an alist of keymaps.
+
+@enumerate
+@item
+The function finally found may be remapped
+(@pxref{Remapping Commands}).
+
+@item
+Characters that are bound to @code{self-insert-command} are translated
+according to @code{translation-table-for-input} before insertion.
+
+@item
+@code{current-active-maps} returns a list of the
+currently active keymaps at point.
+
+@item
+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.
+@end enumerate
+
+@node Controlling Active Maps
+@section Controlling the Active Keymaps
+
@defvar 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
+keyboard input to commands. The global keymap is normally this
+keymap. The default global keymap is a full keymap that binds
@code{self-insert-command} to all of the printing characters.
It is normal practice to change the bindings in the global keymap, but you
@cindex keymap entry
@dfn{Key lookup} is the process of finding the binding of a key
-sequence from a given keymap. Actual execution of the binding is not
-part of key lookup.
+sequence from a given keymap. The execution or use of the binding is
+not part of key lookup.
Key lookup uses just the event type of each event in the key sequence;
the rest of the event is ignored. In fact, a key sequence used for key
lookup may designate a mouse event with just its types (a symbol)
instead of the entire event (a list). @xref{Input Events}. Such
-a ``key-sequence'' is insufficient for @code{command-execute} to run,
+a ``key sequence'' is insufficient for @code{command-execute} to run,
but it is sufficient for looking up or rebinding a key.
When the key sequence consists of multiple events, key lookup
@item
@cindex @code{lambda} in keymap
If the @sc{car} of @var{list} is @code{lambda}, then the list is a
-lambda expression. This is presumed to be a command, and is treated as
-such (see above).
+lambda expression. This is presumed to be a function, and is treated
+as such (see above). In order to execute properly as a key binding,
+this function must be a command---it must have an @code{interactive}
+specification. @xref{Defining Commands}.
@item
If the @sc{car} of @var{list} is a keymap and the @sc{cdr} is an event
not cause an error.
@end deffn
-@defun key-binding key &optional accept-defaults no-remap
-This function returns the binding for @var{key} in the current
-keymaps, trying all the active keymaps. The result is @code{nil} if
-@var{key} is undefined in the keymaps.
-
-@c Emacs 19 feature
-The argument @var{accept-defaults} controls checking for default
-bindings, as in @code{lookup-key} (above).
-
-When commands are remapped (@pxref{Remapping Commands}),
-@code{key-binding} normally processes command remappings so as to
-returns the remapped command that will actually be executed. However,
-if @var{no-remap} is non-@code{nil}, @code{key-binding} ignores
-remappings and returns the binding directly specified for @var{key}.
-
-An error is signaled if @var{key} is not a string or a vector.
-
-@example
-@group
-(key-binding "\C-x\C-f")
- @result{} find-file
-@end group
-@end example
-@end defun
-
-@defun current-active-maps &optional olp
-This returns the list of keymaps that would be used by the command
-loop in the current circumstances to look up a key sequence. Normally
-it ignores @code{overriding-local-map} and
-@code{overriding-terminal-local-map}, but if @var{olp} is
-non-@code{nil} then it pays attention to them.
-@end defun
-
@defun local-key-binding key &optional accept-defaults
This function returns the binding for @var{key} in the current
local keymap, or @code{nil} if it is undefined there.
@defvar meta-prefix-char
@cindex @key{ESC}
-This variable is the meta-prefix character code. It is used when
+This variable is the meta-prefix character code. It is used for
translating a meta character to a two-character sequence so it can be
-looked up in a keymap. For useful results, the value should be a prefix
-event (@pxref{Prefix Keys}). The default value is 27, which is the
-@acronym{ASCII} code for @key{ESC}.
+looked up in a keymap. For useful results, the value should be a
+prefix event (@pxref{Prefix Keys}). The default value is 27, which is
+the @acronym{ASCII} code for @key{ESC}.
As long as the value of @code{meta-prefix-char} remains 27, key lookup
translates @kbd{M-b} into @kbd{@key{ESC} b}, which is normally defined
The function @code{substitute-key-definition} scans a keymap for
keys that have a certain binding and rebinds them with a different
-binding. Another feature you can use for similar effects, but which
-is often cleaner, is to add a binding that remaps a command
-(@pxref{Remapping Commands}).
+binding. Another feature which is cleaner and can often produce the
+same results to remap one command into another (@pxref{Remapping
+Commands}).
@defun substitute-key-definition olddef newdef keymap &optional oldmap
@cindex replace bindings
@defvar tool-bar-button-relief
This variable specifies the shadow width for tool bar items.
The value is an integer, a number of pixels. The default is 1.
+@end defvar
+
+@tindex tool-bar-border
+@defvar tool-bar-border
+This variable specifies the height of the border drawn below the tool
+bar area. An integer value specifies height as a number of pixels.
+If the value is one of @code{internal-border-width} (the default) or
+@code{border-width}, the tool bar border height corresponds to the
+corresponding frame parameter.
@end defvar
You can define a special meaning for clicking on a tool bar item with