@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
@chapter Keymaps
@cindex keymap
- The bindings between input events and commands are recorded in data
-structures called @dfn{keymaps}. Each binding in a keymap associates
-(or @dfn{binds}) an individual event type, either to another keymap or to
-a command. When an event type is bound to a keymap, that keymap is used
-to look up the next input event; this continues until a command is
-found. The whole process is called @dfn{key lookup}.
+ The command bindings of input events are recorded in data structures
+called @dfn{keymaps}. Each entry in a keymap associates (or
+@dfn{binds}) an individual event type, either to another keymap or to
+a command. When an event type is bound to a keymap, that keymap is
+used to look up the next input event; this continues until a command
+is found. The whole process is called @dfn{key lookup}.
@menu
-* Keymap Terminology:: Definitions of terms pertaining to keymaps.
+* Key Sequences:: Key sequences as Lisp objects.
+* Keymap Basics:: Basic concepts of keymaps.
* Format of Keymaps:: What a keymap looks like as a Lisp object.
* Creating Keymaps:: Functions to create and copy keymaps.
* 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.
+* Remapping Commands:: A keymap can translate one command to another.
+* Translation Keymaps:: Keymaps for translating sequences of events.
* Key Binding Commands:: Interactive interfaces for redefining keys.
* Scanning Keymaps:: Looking through all keymaps, for printing help.
* Menu Keymaps:: Defining a menu as a keymap.
@end menu
-@node Keymap Terminology
-@section Keymap Terminology
+@node Key Sequences
+@section Key Sequences
@cindex key
@cindex keystroke
+@cindex key sequence
+
+ A @dfn{key sequence}, or @dfn{key} for short, is a sequence of one
+or more input events that form a unit. Input events include
+characters, function keys, and mouse actions (@pxref{Input Events}).
+The Emacs Lisp representation for a key sequence is a string or
+vector. Unless otherwise stated, any Emacs Lisp function that accepts
+a key sequence as an argument can handle both representations.
+
+ In the string representation, alphanumeric characters ordinarily
+stand for themselves; for example, @code{"a"} represents @kbd{a} and
+and @code{"2"} represents @kbd{2}. Control character events are
+prefixed by the substring @code{"\C-"}, and meta characters by
+@code{"\M-"}; for example, @code{"\C-x"} represents the key @kbd{C-x}.
+In addition, the @key{TAB}, @key{RET}, @key{ESC}, and @key{DEL} events
+are represented by @code{"\t"}, @code{"\r"}, @code{"\e"}, and
+@code{"\d"} respectively. The string representation of a complete key
+sequence is the concatenation of the string representations of the
+constituent events; thus, @code{"\C-xl"} represents the key sequence
+@kbd{C-x l}.
+
+ Key sequences containing function keys, mouse button events, or
+non-ASCII characters such as @kbd{C-=} or @kbd{H-a} cannot be
+represented as strings; they have to be represented as vectors.
+
+ In the vector representation, each element of the vector represents
+an input event, in its Lisp form. @xref{Input Events}. For example,
+the vector @code{[?\C-x ?l]} represents the key sequence @kbd{C-x l}.
+
+ For examples of key sequences written in string and vector
+representations, @ref{Init Rebinding,,, emacs, The GNU Emacs Manual}.
+
+@defmac kbd keyseq-text
+This macro converts the text @var{keyseq-text} (a string constant)
+into a key sequence (a string or vector constant). The contents of
+@var{keyseq-text} should describe the key sequence using almost the same
+syntax used in this manual. More precisely, it uses the same syntax
+that Edit Macro mode uses for editing keyboard macros (@pxref{Edit
+Keyboard Macro,,, emacs, The GNU Emacs Manual}); you must surround
+function key names with @samp{<@dots{}>}.
+
+@example
+(kbd "C-x") @result{} "\C-x"
+(kbd "C-x C-f") @result{} "\C-x\C-f"
+(kbd "C-x 4 C-f") @result{} "\C-x4\C-f"
+(kbd "X") @result{} "X"
+(kbd "RET") @result{} "\^M"
+(kbd "C-c SPC") @result{} "\C-c@ "
+(kbd "<f1> SPC") @result{} [f1 32]
+(kbd "C-M-<down>") @result{} [C-M-down]
+@end example
+
+This macro is not meant for use with arguments that vary---only
+with string constants.
+@end defmac
+
+@node Keymap Basics
+@section Keymap Basics
@cindex key binding
@cindex binding of a key
@cindex complete key
@cindex undefined key
- A @dfn{keymap} is a table mapping event types to definitions (which
-can be any Lisp objects, though only certain types are meaningful for
-execution by the command loop). Given an event (or an event type) and a
-keymap, Emacs can get the event's definition. Events include
-characters, function keys, and mouse actions (@pxref{Input Events}).
-
- A sequence of input events that form a unit is called a
-@dfn{key sequence}, or @dfn{key} for short. A sequence of one event
-is always a key sequence, and so are some multi-event sequences.
+ A keymap is a Lisp data structure that specifies @dfn{key bindings}
+for various key sequences.
- A keymap determines a binding or definition for any key sequence. If
-the key sequence is a single event, its binding is the definition of the
-event in the keymap. The binding of a key sequence of more than one
-event is found by an iterative process: the binding of the first event
-is found, and must be a keymap; then the second event's binding is found
-in that keymap, and so on until all the events in the key sequence are
-used up.
+ A single keymap directly specifies definitions for individual
+events. When a key sequence consists of a single event, its binding
+in a keymap is the keymap's definition for that event. The binding of
+a longer key sequence is found by an iterative process: first find the
+definition of the first event (which must itself be a keymap); then
+find the second event's definition in that keymap, and so on until all
+the events in the key sequence have been processed.
If the binding of a key sequence is a keymap, we call the key sequence
a @dfn{prefix key}. Otherwise, we call it a @dfn{complete key} (because
keymaps shadow both local and global keymaps. @xref{Active Keymaps},
for details.
- The Emacs Lisp representation for a key sequence is a string or vector.
-You can enter key sequence constants using the ordinary string or vector
-representation; it is also convenient to use @code{kbd}:
-
-@defmac kbd keyseq-text
-This macro converts the text @var{keyseq-text} (a string constant)
-into a key sequence (a string or vector constant). The contents
-of @var{keyseq-text} should describe the key sequence using the syntax
-used in this manual. More precisely, it uses the same syntax that
-Edit Macro mode uses for editing keyboard macros (@pxref{Edit Keyboard
-Macro,,, emacs, The GNU Emacs Manual}).
-
-@example
-(kbd "C-x") @result{} "\C-x"
-(kbd "C-x C-f") @result{} "\C-x\C-f"
-(kbd "C-x 4 C-f") @result{} "\C-x4\C-f"
-(kbd "X") @result{} "X"
-(kbd "RET") @result{} "\^M"
-(kbd "C-c SPC") @result{} "\C-c@ "
-(kbd "<f1> SPC") @result{} [f1 32]
-(kbd "C-M-<down>") @result{} [C-M-down]
-@end example
-@end defmac
-
@node Format of Keymaps
@section Format of Keymaps
@cindex format of keymaps
@cindex full keymap
@cindex sparse keymap
- A keymap is a list whose @sc{car} is the symbol @code{keymap}. The
+ Each keymap is a list whose @sc{car} is the symbol @code{keymap}. The
remaining elements of the list define the key bindings of the keymap.
A symbol whose function definition is a keymap is also a keymap. Use
the function @code{keymapp} (see below) to test whether an object is a
This specifies one binding, for events of type @var{type}. Each
ordinary binding applies to events of a particular @dfn{event type},
which is always a character or a symbol. @xref{Classifying Events}.
+In this kind of binding, @var{binding} is a command.
+
+@item (@var{type} @var{item-name} @r{[}@var{cache}@r{]} .@: @var{binding})
+This specifies a binding which is also a simple menu item that
+displays as @var{item-name} in the menu. @var{cache}, if present,
+caches certain information for display in the menu. @xref{Simple Menu
+Items}.
+
+@item (@var{type} @var{item-name} @var{help-string} @r{[}@var{cache}@r{]} .@: @var{binding})
+This is a simple menu item with help string @var{help-string}.
+
+@item (@var{type} menu-item .@: @var{details})
+This specifies a binding which is also an extended menu item. This
+allows use of other features. @xref{Extended Menu Items}.
@item (t .@: @var{binding})
@cindex default key binding
@cindex keymap prompt string
@cindex overall prompt string
@cindex prompt string of keymap
-Aside from bindings, a keymap can also have a string as an element.
-This is called the @dfn{overall prompt string} and makes it possible to
-use the keymap as a menu. @xref{Defining Menus}.
+Aside from elements that specify bindings for keys, a keymap can also
+have a string as an element. This is called the @dfn{overall prompt
+string} and makes it possible to use the keymap as a menu.
+@xref{Defining Menus}.
@end table
When the binding is @code{nil}, it doesn't constitute a definition
@end group
@end example
-If you specify @var{prompt}, that becomes the overall prompt string for
-the keymap. The prompt string should be provided for menu keymaps
-(@pxref{Defining Menus}).
+If you specify @var{prompt}, that becomes the overall prompt string
+for the keymap. You should specify this only for menu keymaps
+(@pxref{Defining Menus}). A keymap with an overall prompt string will
+always present a mouse menu or a keyboard menu if it is active for
+looking up the next input event. Don't specify an overall prompt string
+for the main map of a major or minor mode, because that would cause
+the command loop to present a keyboard menu every time.
@end defun
@defun make-keymap &optional prompt
@dfn{parent keymap}. Such a keymap looks like this:
@example
-(keymap @var{bindings}@dots{} . @var{parent-keymap})
+(keymap @var{elements}@dots{} . @var{parent-keymap})
@end example
@noindent
The effect is that this keymap inherits all the bindings of
@var{parent-keymap}, whatever they may be at the time a key is looked up,
-but can add to them or override them with @var{bindings}.
+but can add to them or override them with @var{elements}.
-If you change the bindings in @var{parent-keymap} using @code{define-key}
-or other key-binding functions, these changes are visible in the
-inheriting keymap unless shadowed by @var{bindings}. The converse is
-not true: if you use @code{define-key} to change the inheriting keymap,
-that affects @var{bindings}, but has no effect on @var{parent-keymap}.
+If you change the bindings in @var{parent-keymap} using
+@code{define-key} or other key-binding functions, these changed
+bindings are visible in the inheriting keymap, unless shadowed by the
+bindings made by @var{elements}. The converse is not true: if you use
+@code{define-key} to change bindings in the inheriting keymap, these
+changes are recorded in @var{elements}, but have no effect on
+@var{parent-keymap}.
The proper way to construct a keymap with a parent is to use
@code{set-keymap-parent}; if you have code that directly constructs a
@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}.)
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.
+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 (optionally preceded
+by a symbolic prefix), 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.
The @dfn{global keymap} holds the bindings of keys that are defined
regardless of the current buffer, such as @kbd{C-f}. The variable
and exit commands. @xref{Intro to Minibuffers}.
Emacs has other keymaps that are used in a different way---translating
-events within @code{read-key-sequence}. @xref{Translating Input}.
+events within @code{read-key-sequence}. @xref{Translation Keymaps}.
@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 position
+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.
+
+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}.
+
+If @var{key} starts with a mouse event (perhaps following a prefix
+event), the maps to be consulted are determined based on the event's
+position. Otherwise, they are determined based on the value of point.
+However, you can override either of them by specifying @var{position}.
+If @var{position} is non-@code{nil}, it should be either a buffer
+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.
+
+@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 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:
+
+@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-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-global-map)))
+@end lisp
+
+@noindent
+The @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}.) If the key sequence starts with a mouse event,
+or a symbolic prefix event followed by 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.
+
+@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
Let's use the term @dfn{keymap entry} to describe the value found by
looking up an event type in a keymap. (This doesn't include the item
-string and other extra elements in menu key bindings, because
+string and other extra elements in a keymap element for a menu item, because
@code{lookup-key} and other key lookup functions don't include them in
-the returned value.) While any Lisp object may be stored in a keymap as
-a keymap entry, not all make sense for key lookup. Here is a table of
-the meaningful kinds of keymap entries:
+the returned value.) While any Lisp object may be stored in a keymap
+as a keymap entry, not all make sense for key lookup. Here is a table
+of the meaningful types of keymap entries:
@table @asis
@item @code{nil}
@item @var{list}
@cindex list in keymap
-The meaning of a list depends on the types of the elements of the list.
+The meaning of a list depends on what it contains:
@itemize @bullet
@item
@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
Commands}). You can also use @code{define-key}, a more general
function; then you must specify explicitly the map to change.
+ When choosing the key sequences for Lisp programs to rebind, please
+follow the Emacs conventions for use of various keys (@pxref{Key
+Binding Conventions}).
+
@cindex meta character key constants
@cindex control character key constants
In writing the key sequence to rebind, it is good to use the special
@code{C-H-left}. One advantage of such lists is that the precise
numeric codes for the modifier bits don't appear in compiled files.
- For the functions below, an error is signaled if @var{keymap} is not
-a keymap or if @var{key} is not a string or vector representing a key
-sequence. You can use event types (symbols) as shorthand for events
-that are lists. The @code{kbd} macro (@pxref{Keymap Terminology}) is
-a convenient way to specify the key sequence.
+ The functions below signal an error if @var{keymap} is not a keymap,
+or if @var{key} is not a string or vector representing a key sequence.
+You can use event types (symbols) as shorthand for events that are
+lists. The @code{kbd} macro (@pxref{Key Sequences}) is a convenient
+way to specify the key sequence.
@defun define-key keymap key binding
This function sets the binding for @var{key} in @var{keymap}. (If
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
if an ordinary binding specifies @code{my-kill-line}, this keymap will
remap it to @code{my-other-kill-line}.
-@defun command-remapping command
+@defun command-remapping command &optional position
This function returns the remapping for @var{command} (a symbol),
given the current active keymaps. If @var{command} is not remapped
(which is the usual situation), or not a symbol, the function returns
-@code{nil}.
+@code{nil}. @code{position} can optionally specify a buffer position
+or an event position to determine the keymaps to use, as in
+@code{key-binding}.
@end defun
+@node Translation Keymaps
+@section Keymaps for Translating Sequences of Events
+
+ This section describes keymaps that are used during reading a key
+sequence, to translate certain event sequences into others.
+@code{read-key-sequence} checks every subsequence of the key sequence
+being read, as it is read, against @code{function-key-map} and then
+against @code{key-translation-map}.
+
+@defvar function-key-map
+This variable holds a keymap that describes the character sequences sent
+by function keys on an ordinary character terminal. This keymap has the
+same structure as other keymaps, but is used differently: it specifies
+translations to make while reading key sequences, rather than bindings
+for key sequences.
+
+If @code{function-key-map} ``binds'' a key sequence @var{k} to a vector
+@var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in a
+key sequence, it is replaced with the events in @var{v}.
+
+For example, VT100 terminals send @kbd{@key{ESC} O P} when the
+keypad @key{PF1} key is pressed. Therefore, we want Emacs to translate
+that sequence of events into the single event @code{pf1}. We accomplish
+this by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in
+@code{function-key-map}, when using a VT100.
+
+Thus, typing @kbd{C-c @key{PF1}} sends the character sequence @kbd{C-c
+@key{ESC} O P}; later the function @code{read-key-sequence} translates
+this back into @kbd{C-c @key{PF1}}, which it returns as the vector
+@code{[?\C-c pf1]}.
+
+Entries in @code{function-key-map} are ignored if they conflict with
+bindings made in the minor mode, local, or global keymaps. The intent
+is that the character sequences that function keys send should not have
+command bindings in their own right---but if they do, the ordinary
+bindings take priority.
+
+The value of @code{function-key-map} is usually set up automatically
+according to the terminal's Terminfo or Termcap entry, but sometimes
+those need help from terminal-specific Lisp files. Emacs comes with
+terminal-specific files for many common terminals; their main purpose is
+to make entries in @code{function-key-map} beyond those that can be
+deduced from Termcap and Terminfo. @xref{Terminal-Specific}.
+@end defvar
+
+@defvar key-translation-map
+This variable is another keymap used just like @code{function-key-map}
+to translate input events into other events. It differs from
+@code{function-key-map} in two ways:
+
+@itemize @bullet
+@item
+@code{key-translation-map} goes to work after @code{function-key-map} is
+finished; it receives the results of translation by
+@code{function-key-map}.
+
+@item
+Non-prefix bindings in @code{key-translation-map} override actual key
+bindings. For example, if @kbd{C-x f} has a non-prefix binding in
+@code{key-translation-map}, that translation takes effect even though
+@kbd{C-x f} also has a key binding in the global map.
+@end itemize
+
+Note however that actual key bindings can have an effect on
+@code{key-translation-map}, even though they are overridden by it.
+Indeed, actual key bindings override @code{function-key-map} and thus
+may alter the key sequence that @code{key-translation-map} receives.
+Clearly, it is better to avoid this type of situation.
+
+The intent of @code{key-translation-map} is for users to map one
+character set to another, including ordinary characters normally bound
+to @code{self-insert-command}.
+@end defvar
+
+@cindex key translation function
+You can use @code{function-key-map} or @code{key-translation-map} for
+more than simple aliases, by using a function, instead of a key
+sequence, as the ``translation'' of a key. Then this function is called
+to compute the translation of that key.
+
+The key translation function receives one argument, which is the prompt
+that was specified in @code{read-key-sequence}---or @code{nil} if the
+key sequence is being read by the editor command loop. In most cases
+you can ignore the prompt value.
+
+If the function reads input itself, it can have the effect of altering
+the event that follows. For example, here's how to define @kbd{C-c h}
+to turn the character that follows into a Hyper character:
+
+@example
+@group
+(defun hyperify (prompt)
+ (let ((e (read-event)))
+ (vector (if (numberp e)
+ (logior (lsh 1 24) e)
+ (if (memq 'hyper (event-modifiers e))
+ e
+ (add-event-modifier "H-" e))))))
+
+(defun add-event-modifier (string e)
+ (let ((symbol (if (symbolp e) e (car e))))
+ (setq symbol (intern (concat string
+ (symbol-name symbol))))
+@end group
+@group
+ (if (symbolp e)
+ symbol
+ (cons symbol (cdr e)))))
+
+(define-key function-key-map "\C-ch" 'hyperify)
+@end group
+@end example
+
+ If you have enabled keyboard character set decoding using
+@code{set-keyboard-coding-system}, decoding is done after the
+translations listed above. @xref{Terminal I/O Encoding}. However, in
+future Emacs versions, character set decoding may be done at an
+earlier stage.
+
@node Key Binding Commands
@section Commands for Binding Keys
@section Menu Keymaps
@cindex menu keymaps
-@c Emacs 19 feature
-A keymap can define a menu as well as bindings for keyboard keys and
-mouse button. Menus are usually actuated with the mouse, but they can
-work with the keyboard also.
+A keymap can operate as a menu as well as defining bindings for
+keyboard keys and mouse buttons. Menus are usually actuated with the
+mouse, but they can function with the keyboard also. If a menu keymap
+is active for the next input event, that activates the keyboard menu
+feature.
@menu
* Defining Menus:: How to make a keymap that defines a menu.
* Mouse Menus:: How users actuate the menu with the mouse.
-* Keyboard Menus:: How they actuate it with the keyboard.
+* Keyboard Menus:: How users actuate the menu with the keyboard.
* Menu Example:: Making a simple menu.
* Menu Bar:: How to customize the menu bar.
* Tool Bar:: A tool bar is a row of images.
@cindex menu prompt string
@cindex prompt string (of menu)
-A keymap is suitable for menu use if it has an @dfn{overall prompt
-string}, which is a string that appears as an element of the keymap.
+A keymap acts as a menu if it has an @dfn{overall prompt string},
+which is a string that appears as an element of the keymap.
(@xref{Format of Keymaps}.) The string should describe the purpose of
the menu's commands. Emacs displays the overall prompt string as the
menu title in some cases, depending on the toolkit (if any) used for
displaying menus.@footnote{It is required for menus which do not use a
-toolkit, e.g.@: under MS-DOS.} Keyboard menus also display the overall
-prompt string.
+toolkit, e.g.@: under MS-DOS.} Keyboard menus also display the
+overall prompt string.
-The easiest way to construct a keymap with a prompt string is to specify
-the string as an argument when you call @code{make-keymap},
+The easiest way to construct a keymap with a prompt string is to
+specify the string as an argument when you call @code{make-keymap},
@code{make-sparse-keymap} (@pxref{Creating Keymaps}), or
-@code{define-prefix-command} (@pxref{Definition of define-prefix-command}).
-
+@code{define-prefix-command} (@pxref{Definition of
+define-prefix-command}). If you do not want the keymap to operate as
+a menu, don't specify a prompt string for it.
@defun keymap-prompt keymap
This function returns the overall prompt string of @var{keymap},
or @code{nil} if it has none.
@end defun
+The menu's items are the bindings in the keymap. Each binding
+associates an event type to a definition, but the event types have no
+significance for the menu appearance. (Usually we use pseudo-events,
+symbols that the keyboard cannot generate, as the event types for menu
+item bindings.) The menu is generated entirely from the bindings that
+correspond in the keymap to these events.
+
The order of items in the menu is the same as the order of bindings in
the keymap. Since @code{define-key} puts new bindings at the front, you
should define the menu items starting at the bottom of the menu and
@node Simple Menu Items
@subsubsection Simple Menu Items
- The simpler and older way to define a menu keymap binding
-looks like this:
+ The simpler (and original) way to define a menu item is to bind some
+event type (it doesn't matter what event type) to a binding like this:
@example
(@var{item-string} . @var{real-binding})
encoded using the @code{utf-8} coding system and then rendered by the
toolkit as it sees fit.}
-You can also supply a second string, called the help string, as follows:
+ You can also supply a second string, called the help string, as follows:
@example
(@var{item-string} @var{help} . @var{real-binding})
@end example
+@noindent
@var{help} specifies a ``help-echo'' string to display while the mouse
is on that item in the same way as @code{help-echo} text properties
(@pxref{Help display}).
-As far as @code{define-key} is concerned, @var{item-string} and
+ As far as @code{define-key} is concerned, @var{item-string} and
@var{help-string} are part of the event's binding. However,
@code{lookup-key} returns just @var{real-binding}, and only
@var{real-binding} is used for executing the key.
-If @var{real-binding} is @code{nil}, then @var{item-string} appears in
+ If @var{real-binding} is @code{nil}, then @var{item-string} appears in
the menu but cannot be selected.
-If @var{real-binding} is a symbol and has a non-@code{nil}
+ If @var{real-binding} is a symbol and has a non-@code{nil}
@code{menu-enable} property, that property is an expression that
controls whether the menu item is enabled. Every time the keymap is
used to display a menu, Emacs evaluates the expression, and it enables
menu item is disabled, it is displayed in a ``fuzzy'' fashion, and
cannot be selected.
-The menu bar does not recalculate which items are enabled every time you
+ The menu bar does not recalculate which items are enabled every time you
look at a menu. This is because the X toolkit requires the whole tree
of menus in advance. To force recalculation of the menu bar, call
@code{force-mode-line-update} (@pxref{Mode Line Format}).
-You've probably noticed that menu items show the equivalent keyboard key
+ You've probably noticed that menu items show the equivalent keyboard key
sequence (if any) to invoke the same command. To save time on
recalculation, menu display caches this information in a sublist in the
binding, like this:
@c This line is not too long--rms.
@example
-(@var{item-string} @r{[}@var{help-string}@r{]} (@var{key-binding-data}) . @var{real-binding})
+(@var{item-string} @r{[}@var{help}@r{]} (@var{key-binding-data}) . @var{real-binding})
@end example
@noindent
@kindex menu-item
An extended-format menu item is a more flexible and also cleaner
-alternative to the simple format. It consists of a list that starts
-with the symbol @code{menu-item}. To define a non-selectable string,
-the item looks like this:
+alternative to the simple format. You define an event type with a
+binding that's a list starting with the symbol @code{menu-item}.
+For a non-selectable string, the binding looks like this:
@example
(menu-item @var{item-name})
see @ref{Menu Separators}.
To define a real menu item which can be selected, the extended format
-item looks like this:
+binding looks like this:
@example
(menu-item @var{item-name} @var{real-binding}
safely be called at any time.
@end table
+ When an equivalent key binding is cached, the binding looks like this.
+
+@example
+(menu-item @var{item-name} @var{real-binding} (@var{key-binding-data})
+ . @var{item-property-list})
+@end example
+
@node Menu Separators
@subsubsection Menu Separators
@cindex menu separators
@node Keyboard Menus
@subsection Menus and the Keyboard
-When a prefix key ending with a keyboard event (a character or function
-key) has a definition that is a menu keymap, the user can use the
-keyboard to choose a menu item.
+ When a prefix key ending with a keyboard event (a character or
+function key) has a definition that is a menu keymap, the keymap
+operates as a keyboard menu; the user specifies the next event by
+choosing a menu item with the keyboard.
-Emacs displays the menu's overall prompt string followed by the
-alternatives (the item strings of the bindings) in the echo area. If
-the bindings don't all fit at once, the user can type @key{SPC} to see
-the next line of alternatives. Successive uses of @key{SPC} eventually
-get to the end of the menu and then cycle around to the beginning. (The
-variable @code{menu-prompt-more-char} specifies which character is used
-for this; @key{SPC} is the default.)
+ Emacs displays the keyboard menu with the map's overall prompt
+string, followed by the alternatives (the item strings of the map's
+bindings), in the echo area. If the bindings don't all fit at once,
+the user can type @key{SPC} to see the next line of alternatives.
+Successive uses of @key{SPC} eventually get to the end of the menu and
+then cycle around to the beginning. (The variable
+@code{menu-prompt-more-char} specifies which character is used for
+this; @key{SPC} is the default.)
-When the user has found the desired alternative from the menu, he or she
-should type the corresponding character---the one whose binding is that
-alternative.
+ When the user has found the desired alternative from the menu, he or
+she should type the corresponding character---the one whose binding is
+that alternative.
@ignore
In a menu intended for keyboard use, each menu item must clearly
key for each alternative.
@end ignore
-This way of using menus in an Emacs-like editor was inspired by the
+ This way of using menus in an Emacs-like editor was inspired by the
Hierarkey system.
@defvar menu-prompt-more-char
Note the symbols which the bindings are ``made for''; these appear
inside square brackets, in the key sequence being defined. In some
cases, this symbol is the same as the command name; sometimes it is
-different. These symbols are treated as ``function keys'', but they are
+different. These symbols are treated as ``function keys,'' but they are
not real function keys on the keyboard. They do not affect the
functioning of the menu itself, but they are ``echoed'' in the echo area
when the user selects from the menu, and they appear in the output of
using an indirection through @code{tool-bar-map}.
@defvar tool-bar-map
-@tindex tool-bar-map
By default, the global map binds @code{[tool-bar]} as follows:
@example
(global-set-key [tool-bar]
follows.
@defun tool-bar-add-item icon def key &rest props
-@tindex tool-bar-add-item
This function adds an item to the tool bar by modifying
@code{tool-bar-map}. The image to use is defined by @var{icon}, which
is the base name of an XPM, XBM or PBM image file to be located by
@end defun
@defun tool-bar-add-item-from-menu command icon &optional map &rest props
-@tindex tool-bar-add-item-from-menu
This function is a convenience for defining tool bar items which are
consistent with existing menu bar bindings. The binding of
@var{command} is looked up in the menu bar in @var{map} (default
@code{tool-bar-add-item-from-menu}.
@end defun
-@tindex auto-resize-tool-bar
@defvar auto-resize-tool-bar
If this variable is non-@code{nil}, the tool bar automatically resizes to
show all defined tool bar items---but not larger than a quarter of the
frame's height.
@end defvar
-@tindex auto-raise-tool-bar-buttons
@defvar auto-raise-tool-bar-buttons
If this variable is non-@code{nil}, tool bar items display
in raised form when the mouse moves over them.
@end defvar
-@tindex tool-bar-button-margin
@defvar tool-bar-button-margin
This variable specifies an extra margin to add around tool bar items.
The value is an integer, a number of pixels. The default is 4.
@end defvar
-@tindex tool-bar-button-relief
@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
+
+@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