@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
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.
+* 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
+@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
@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
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 program can to substitute
+ 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.
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
+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 event subsequences (@pxref{Translation Keymaps})
+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)
+ (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
+The @var{find-in} and @var{find-in-any} are pseudo functions that
+search in one keymap and in an alist of keymaps, respectively.
+
+@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
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
@code{nil}.
@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
@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
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
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