@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2000, 2004
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/keymaps
@node Keymaps, Modes, Command Loop, Top
* Key Lookup:: How extracting elements from keymaps works.
* 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.
* 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.
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
A 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.
-Use the function @code{keymapp} (see below) to test whether an object is
-a 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
+keymap.
Several kinds of elements may appear in a keymap, after the symbol
@code{keymap} that begins it:
elements of the keymap is given @var{binding} as its binding. Default
bindings allow a keymap to bind all possible event types without having
to enumerate all of them. A keymap that has a default binding
-completely masks any lower-precedence keymap.
-
-@item @var{vector}
-If an element of a keymap is a vector, the vector counts as bindings for
-all the @sc{ASCII} characters, codes 0 through 127; vector element
-@var{n} is the binding for the character with code @var{n}. This is a
-compact way to record lots of bindings. A keymap with such a vector is
-called a @dfn{full keymap}. Other keymaps are called @dfn{sparse
-keymaps}.
-
-When a keymap contains a vector, it always defines a binding for each
-@sc{ASCII} character, even if the vector contains @code{nil} for that
-character. Such a binding of @code{nil} overrides any default key
-binding in the keymap. However, default bindings are still meaningful
-for events that are not @sc{ASCII} characters. A binding of @code{nil}
+completely masks any lower-precedence keymap, except for events
+explicitly bound to @code{nil} (see below).
+
+@item @var{char-table}
+If an element of a keymap is a char-table, it counts as holding
+bindings for all character events with no modifier bits
+(@pxref{modifier bits}): element @var{n} is the binding for the
+character with code @var{n}. This is a compact way to record lots of
+bindings. A keymap with such a char-table is called a @dfn{full
+keymap}. Other keymaps are called @dfn{sparse keymaps}.
+
+When a keymap contains a char-table vector, it always defines a
+binding for each character without modifiers. However, if the binding
+is @code{nil}, it doesn't constitute a definition. @code{nil} takes
+precedence over a default binding or a binding in the parent keymap.
+So in a full keymap, default bindings are not meaningful for
+characters without modifiers. They can still apply to characters with
+modifier bits and to non-character events. A binding of @code{nil}
does @emph{not} override lower-precedence keymaps; thus, if the local
map gives a binding of @code{nil}, Emacs uses the binding from the
global map.
@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{Menu Keymaps}.
+use the keymap as a menu. @xref{Defining Menus}.
@end table
@cindex meta characters lookup
Keymaps do not directly record bindings for the meta characters.
-Instead, meta characters are regarded for
-purposes of key lookup as sequences of two characters, the first of
-which is @key{ESC} (or whatever is currently the value of
-@code{meta-prefix-char}). Thus, the key @kbd{M-a} is really represented
-as @kbd{@key{ESC} a}, and its global binding is found at the slot for
-@kbd{a} in @code{esc-map} (@pxref{Prefix Keys}).
+Instead, meta characters are regarded for purposes of key lookup as
+sequences of two characters, the first of which is @key{ESC} (or
+whatever is currently the value of @code{meta-prefix-char}). Thus, the
+key @kbd{M-a} is internally represented as @kbd{@key{ESC} a}, and its
+global binding is found at the slot for @kbd{a} in @code{esc-map}
+(@pxref{Prefix Keys}).
+
+ This conversion applies only to characters, not to function keys or
+other input events; thus, @kbd{M-@key{end}} has nothing to do with
+@kbd{@key{ESC} @key{end}}.
Here as an example is the local keymap for Lisp mode, a sparse
keymap. It defines bindings for @key{DEL} and @key{TAB}, plus @kbd{C-c
@example
@group
lisp-mode-map
-@result{}
+@result{}
@end group
@group
-(keymap
+(keymap
;; @key{TAB}
- (9 . lisp-indent-line)
+ (9 . lisp-indent-line)
@end group
@group
;; @key{DEL}
- (127 . backward-delete-char-untabify)
+ (127 . backward-delete-char-untabify)
@end group
@group
- (3 keymap
+ (3 keymap
;; @kbd{C-c C-l}
- (12 . run-lisp))
+ (12 . run-lisp))
@end group
@group
- (27 keymap
+ (27 keymap
;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}}
- (17 . indent-sexp)
+ (17 . indent-sexp)
;; @r{@kbd{M-C-x}, treated as @kbd{@key{ESC} C-x}}
- (24 . lisp-send-defun)))
+ (24 . lisp-send-defun)))
@end group
@end example
@defun keymapp object
This function returns @code{t} if @var{object} is a keymap, @code{nil}
otherwise. More precisely, this function tests for a list whose
-@sc{car} is @code{keymap}.
+@sc{car} is @code{keymap}, or for a symbol whose function definition
+satisfies @code{keymapp}.
@example
@group
@result{} t
@end group
@group
+(fset 'foo '(keymap))
+(keymapp 'foo)
+ @result{} t
+@end group
+@group
(keymapp (current-global-map))
@result{} t
@end group
@c ??? This should come after make-sparse-keymap
@defun make-keymap &optional prompt
-This function creates and returns a new full keymap (i.e., one
-containing a vector of length 128 for defining all the @sc{ASCII}
-characters). The new keymap initially binds all @sc{ASCII} characters
-to @code{nil}, and does not bind any other kind of event.
+This function creates and returns a new full keymap. That keymap
+contains a char-table (@pxref{Char-Tables}) with slots for all
+characters without modifiers. The new keymap initially binds all
+these characters to @code{nil}, and does not bind any other kind of
+event.
@example
@group
(make-keymap)
- @result{} (keymap [nil nil nil @dots{} nil nil])
+ @result{} (keymap #^[t nil nil nil @dots{} nil nil keymap])
@end group
@end example
If you specify @var{prompt}, that becomes the overall prompt string for
-the keymap. The prompt string is useful for menu keymaps (@pxref{Menu
-Keymaps}).
+the keymap. The prompt string should be provided for menu keymaps
+(@pxref{Defining Menus}).
@end defun
@defun make-sparse-keymap &optional prompt
This function creates and returns a new sparse keymap with no entries.
-The new keymap does not bind any events. The argument @var{prompt}
-specifies a prompt string, as in @code{make-keymap}.
+The new keymap does not contain a char-table, unlike @code{make-keymap},
+and does not bind any events. The argument @var{prompt} specifies a
+prompt string, as in @code{make-keymap}.
@example
@group
@end group
@group
;; @r{(This implements meta characters.)}
- (27 keymap
+ (27 keymap
(83 . center-paragraph)
(115 . center-line))
(9 . tab-to-tab-stop))
prefix keys.
@end defun
-Here is an example showing how to make a keymap that inherits
+ Here is an example showing how to make a keymap that inherits
from @code{text-mode-map}:
@example
map)
@end example
+ A non-sparse keymap can have a parent too, but this is not very
+useful. A non-sparse keymap always specifies something as the binding
+for every numeric character code without modifier bits, even if it is
+@code{nil}, so these character's bindings are never inherited from
+the parent keymap.
+
@node Prefix Keys
@section Prefix Keys
@cindex prefix key
also stored in the variable @code{ctl-x-map}. This keymap defines
bindings for key sequences starting with @kbd{C-x}.
- Here is a list of the standard prefix keys of Emacs and their keymaps:
+ Some of the standard Emacs prefix keys use keymaps that are
+also found in Lisp variables:
@itemize @bullet
@item
@item
@cindex @kbd{C-h}
-@code{help-map} is the global definitions for the @kbd{C-h} prefix key.
+@code{help-map} is the global keymap for the @kbd{C-h} prefix key.
@item
@cindex @kbd{C-c}
@cindex @kbd{C-x}
@vindex ctl-x-map
@findex Control-X-prefix
-@code{ctl-x-map} is the global key map used for the @kbd{C-x} prefix
-key. This map is found via the function definition of the symbol
+@code{ctl-x-map} is the global keymap used for the @kbd{C-x} prefix key.
+This map is found via the function cell of the symbol
@code{Control-X-prefix}.
+@item
+@cindex @kbd{C-x @key{RET}}
+@vindex mule-keymap
+@code{mule-keymap} is the global keymap used for the @kbd{C-x @key{RET}}
+prefix key.
+
@item
@cindex @kbd{C-x 4}
@vindex ctl-x-4-map
@c Emacs 19 feature
@item
-@cindex @kbd{C-x n}
-@cindex @kbd{C-x r}
-@cindex @kbd{C-x a}
-The prefix keys @kbd{C-x n}, @kbd{C-x r} and @kbd{C-x a} use keymaps
-that have no special names.
+@cindex @kbd{C-x 6}
+@vindex 2C-mode-map
+@code{2C-mode-map} is the global keymap used for the @kbd{C-x 6} prefix
+key.
+
+@item
+@cindex @kbd{C-x v}
+@vindex vc-prefix-map
+@code{vc-prefix-map} is the global keymap used for the @kbd{C-x v} prefix
+key.
+
+@item
+@cindex @kbd{M-g}
+@vindex facemenu-keymap
+@code{facemenu-keymap} is the global keymap used for the @kbd{M-g}
+prefix key.
+
+@c Emacs 19 feature
+@item
+The other Emacs prefix keys are @kbd{C-x @@}, @kbd{C-x a i}, @kbd{C-x
+@key{ESC}} and @kbd{@key{ESC} @key{ESC}}. They use keymaps that have no
+special names.
@end itemize
The keymap binding of a prefix key is used for looking up the event
that follows the prefix key. (It may instead be a symbol whose function
definition is a keymap. The effect is the same, but the symbol serves
as a name for the prefix key.) Thus, the binding of @kbd{C-x} is the
-symbol @code{Control-X-prefix}, whose function definition is the keymap
+symbol @code{Control-X-prefix}, whose function cell holds the keymap
for @kbd{C-x} commands. (The same keymap is also the value of
@code{ctl-x-map}.)
@end group
@end example
-@defun define-prefix-command symbol
+@defun define-prefix-command symbol &optional mapvar prompt
@cindex prefix command
+@anchor{Definition of define-prefix-command}
This function prepares @var{symbol} for use as a prefix key's binding:
-it creates a full keymap and stores it as @var{symbol}'s function
+it creates a sparse keymap and stores it as @var{symbol}'s function
definition. Subsequently binding a key sequence to @var{symbol} will
-make that key sequence into a prefix key.
+make that key sequence into a prefix key. The return value is @code{symbol}.
This function also sets @var{symbol} as a variable, with the keymap as
-its value. It returns @var{symbol}.
+its value. But if @var{mapvar} is non-@code{nil}, it sets @var{mapvar}
+as a variable instead.
-@c In Emacs version 18, only the function definition of @var{symbol} was
-@c set, not the value as a variable.
+If @var{prompt} is non-@code{nil}, that becomes the overall prompt
+string for the keymap. The prompt string should be given for menu keymaps
+(@pxref{Defining Menus}).
@end defun
@node Active Keymaps
overrides it. Text properties can specify an alternative local map for
certain parts of the buffer; see @ref{Special Properties}.
- Each minor mode may have a keymap; if it does, the keymap is active
+ Each minor mode can have a keymap; if it does, the keymap is active
when the minor mode is enabled.
The variable @code{overriding-local-map}, if non-@code{nil}, specifies
-another local keymap that overrides the buffer's local map and all the
-minor mode keymaps.
+another local keymap that overrides the buffer's local map and all the
+minor mode keymaps. Modes for emulation can specify additional
+active keymaps through the variable @code{emulation-mode-map-alists}.
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
maps. The procedure for searching a single keymap is called @dfn{key
lookup}; see @ref{Key Lookup}.
-Normally, Emacs first searches for the key in the minor mode
-maps (one map at a time); 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 @code{overriding-local-map} is
-non-@code{nil}, Emacs searches that map first, before the global map.
+ Normally, Emacs first searches for the key in the minor mode maps, in
+the order specified by @code{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
+@code{overriding-local-map} is non-@code{nil}, Emacs searches that map
+first, before the global map.
@cindex major mode keymap
Since every buffer that uses the same major mode normally uses the
The minibuffer has local keymaps, too; they contain various completion
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}.
+
@xref{Standard Keymaps}, for a list of standard keymaps.
@defvar global-map
@example
@group
(current-global-map)
-@result{} (keymap [set-mark-command beginning-of-line @dots{}
+@result{} (keymap [set-mark-command beginning-of-line @dots{}
delete-backward-char])
@end group
@end example
This function returns the current buffer's local keymap, or @code{nil}
if it has none. In the following example, the keymap for the
@samp{*scratch*} buffer (using Lisp Interaction mode) is a sparse keymap
-in which the entry for @key{ESC}, @sc{ASCII} code 27, is another sparse
+in which the entry for @key{ESC}, @acronym{ASCII} code 27, is another sparse
keymap.
@example
@group
(current-local-map)
-@result{} (keymap
- (10 . eval-print-last-sexp)
- (9 . lisp-indent-line)
- (127 . backward-delete-char-untabify)
+@result{} (keymap
+ (10 . eval-print-last-sexp)
+ (9 . lisp-indent-line)
+ (127 . backward-delete-char-untabify)
@end group
@group
- (27 keymap
- (24 . eval-defun)
+ (27 keymap
+ (24 . eval-defun)
(17 . indent-sexp)))
@end group
@end example
Note that elements of @code{minor-mode-map-alist} do not have the same
structure as elements of @code{minor-mode-alist}. The map must be the
-@sc{cdr} of the element; a list with the map as the @sc{cadr} will not
-do. The @sc{cadr} can be either a keymap (a list) or a symbol
-whose function definition is a keymap.
+@sc{cdr} of the element; a list with the map as the second element will
+not do. The @sc{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 @code{minor-mode-map-alist}. But you should design
Lookup}).
@end defvar
-@tindex minor-mode-overriding-map-alist
@defvar 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 @code{minor-mode-map-alist}: @code{(@var{variable}
-. @var{keymap})}. If a variable appears an element
-@code{minor-mode-overriding-map-alist}, that element overrides any
-element for the same variable in @code{minor-mode-map-alist}.
+. @var{keymap})}.
+
+If a variable appears as an element of
+@code{minor-mode-overriding-map-alist}, the map specified by that
+element totally replaces any map specified for the same variable in
+@code{minor-mode-map-alist}.
@code{minor-mode-overriding-map-alist} is automatically buffer-local in
all buffers.
@defvar overriding-local-map
If non-@code{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.
+buffer's local keymap, text property or overlay keymaps, 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.
@end defvar
@defvar overriding-terminal-local-map
If non-@code{nil}, this variable holds a keymap to use instead of
-@code{overriding-local-map}, the buffer's local keymap and all the minor
-mode keymaps.
+@code{overriding-local-map}, the buffer's local keymap, text property
+or overlay keymaps, and all the minor mode keymaps.
This variable is always local to the current terminal and cannot be
buffer-local. @xref{Multiple Displays}. It is used to implement
event is run directly by @code{read-event}. @xref{Special Events}.
@end defvar
+@defvar emulation-mode-map-alists
+This variable holds a list of keymap alists to use for emulations
+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
+binding which is such an alist. The ``active'' keymaps in each alist
+are used before @code{minor-mode-map-alist} and
+@code{minor-mode-overriding-map-alist}.
+@end defvar
+
@node Key Lookup
@section Key Lookup
@cindex key lookup
@result{} find-file
@end group
@group
+(lookup-key (current-global-map) (kbd "C-x C-f"))
+ @result{} find-file
+@end group
+@group
(lookup-key (current-global-map) "\C-x\C-f12345")
@result{} 2
@end group
you explicitly ask about them. (To do this, supply @code{t} as an
element of @var{key}; see @ref{Format of Keymaps}.)
-If @var{key} contains a meta character, that character is implicitly
-replaced by a two-character sequence: the value of
-@code{meta-prefix-char}, followed by the corresponding non-meta
+If @var{key} contains a meta character (not a function key), that
+character is implicitly replaced by a two-character sequence: the value
+of @code{meta-prefix-char}, followed by the corresponding non-meta
character. Thus, the first example below is handled by conversion into
the second example.
not cause an error.
@end deffn
-@defun key-binding key &optional accept-defaults
+@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.
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
@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.
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
-@sc{ASCII} code for @key{ESC}.
+@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 as the @code{backward-word} command. However, if you set
+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
+as the @code{backward-word} command. However, if you were to set
@code{meta-prefix-char} to 24, the code for @kbd{C-x}, then Emacs will
translate @kbd{M-b} into @kbd{C-x b}, whose standard binding is the
-@code{switch-to-buffer} command. Here is an illustration:
+@code{switch-to-buffer} command. (Don't actually do this!) Here is an
+illustration of what would happen:
@smallexample
@group
@end group
@group
(setq meta-prefix-char 24)
- @result{} 24
+ @result{} 24
@end group
@group
(key-binding "\M-b")
@result{} 27 ; @r{Restore the default value!}
@end group
@end smallexample
+
+This translation of one event into two happens only for characters, not
+for other kinds of input events. Thus, @kbd{M-@key{F1}}, a function
+key, is not converted into @kbd{@key{ESC} @key{F1}}.
@end defvar
@node Changing Key Bindings
meaningful. (For a list of meaningful types, see @ref{Key Lookup}.)
The value returned by @code{define-key} is @var{binding}.
+If @var{key} is @code{[t]}, this sets the default binding in
+@var{keymap}. When an event has no binding of its own, the Emacs
+command loop uses the keymap's default binding, if there is one.
+
@cindex invalid prefix key error
@cindex key sequence error
Every prefix of @var{key} must be a prefix key (i.e., bound to a keymap)
If there was previously no binding for @var{key} in @var{keymap}, the
new binding is added at the beginning of @var{keymap}. The order of
-bindings in a keymap makes no difference in most cases, but it does
-matter for menu keymaps (@pxref{Menu Keymaps}).
+bindings in a keymap makes no difference for keyboard input, but it
+does matter for menu keymaps (@pxref{Menu Keymaps}).
@end defun
Here is an example that creates a sparse keymap and makes a number of
@group
;; @r{Build sparse submap for @kbd{C-x} and bind @kbd{f} in that.}
-(define-key map "\C-xf" 'forward-word)
+(define-key map (kbd "C-x f") 'forward-word)
@result{} forward-word
@end group
@group
map
-@result{} (keymap
+@result{} (keymap
(24 keymap ; @kbd{C-x}
(102 . forward-word)) ; @kbd{f}
(6 . forward-char)) ; @kbd{C-f}
@group
;; @r{Bind @kbd{C-p} to the @code{ctl-x-map}.}
-(define-key map "\C-p" ctl-x-map)
+(define-key map (kbd "C-p") ctl-x-map)
;; @code{ctl-x-map}
-@result{} [nil @dots{} find-file @dots{} backward-kill-sentence]
+@result{} [nil @dots{} find-file @dots{} backward-kill-sentence]
@end group
@group
;; @r{Bind @kbd{C-f} to @code{foo} in the @code{ctl-x-map}.}
-(define-key map "\C-p\C-f" 'foo)
+(define-key map (kbd "C-p C-f") 'foo)
@result{} 'foo
@end group
@group
map
@result{} (keymap ; @r{Note @code{foo} in @code{ctl-x-map}.}
(16 keymap [nil @dots{} foo @dots{} backward-kill-sentence])
- (24 keymap
+ (24 keymap
(102 . forward-word))
(6 . forward-char))
@end group
changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the
default global map.
+ 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}).
+
@defun substitute-key-definition olddef newdef keymap &optional oldmap
@cindex replace bindings
This function replaces @var{olddef} with @var{newdef} for any keys in
@smallexample
@group
-(substitute-key-definition
+(substitute-key-definition
'find-file 'find-file-read-only (current-global-map))
@end group
@end smallexample
@c Emacs 19 feature
-If @var{oldmap} is non-@code{nil}, then its bindings determine which
-keys to rebind. The rebindings still happen in @var{keymap}, not in
-@var{oldmap}. Thus, you can change one map under the control of the
+If @var{oldmap} is non-@code{nil}, that changes the behavior of
+@code{substitute-key-definition}: the bindings in @var{oldmap} determine
+which keys to rebind. The rebindings still happen in @var{keymap}, not
+in @var{oldmap}. Thus, you can change one map under the control of the
bindings in another. For example,
@smallexample
puts the special deletion command in @code{my-map} for whichever keys
are globally bound to the standard deletion command.
-@ignore
-@c Emacs 18 only
-Prefix keymaps that appear within @var{keymap} are not checked
-recursively for keys bound to @var{olddef}; they are not changed at all.
-Perhaps it would be better to check nested keymaps recursively.
-@end ignore
-
Here is an example showing a keymap before and after substitution:
@smallexample
@group
-(setq map '(keymap
- (?1 . olddef-1)
- (?2 . olddef-2)
+(setq map '(keymap
+ (?1 . olddef-1)
+ (?2 . olddef-2)
(?3 . olddef-1)))
@result{} (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1))
@end group
@code{negative-argument}. Otherwise it makes them undefined like the
rest of the printing characters.
-@cindex yank suppression
-@cindex @code{quoted-insert} suppression
+@cindex yank suppression
+@cindex @code{quoted-insert} suppression
The @code{suppress-keymap} function does not make it impossible to
modify a buffer, as it does not suppress commands such as @code{yank}
and @code{quoted-insert}. To prevent any modification of a buffer, make
@smallexample
@group
- @dots{}
- (setq dired-mode-map (make-keymap))
- (suppress-keymap dired-mode-map)
- (define-key dired-mode-map "r" 'dired-rename-file)
- (define-key dired-mode-map "\C-d" 'dired-flag-file-deleted)
- (define-key dired-mode-map "d" 'dired-flag-file-deleted)
- (define-key dired-mode-map "v" 'dired-view-file)
- (define-key dired-mode-map "e" 'dired-find-file)
- (define-key dired-mode-map "f" 'dired-find-file)
- @dots{}
+(setq dired-mode-map (make-keymap))
+(suppress-keymap dired-mode-map)
+(define-key dired-mode-map "r" 'dired-rename-file)
+(define-key dired-mode-map "\C-d" 'dired-flag-file-deleted)
+(define-key dired-mode-map "d" 'dired-flag-file-deleted)
+(define-key dired-mode-map "v" 'dired-view-file)
+(define-key dired-mode-map "e" 'dired-find-file)
+(define-key dired-mode-map "f" 'dired-find-file)
+@dots{}
@end group
@end smallexample
@end defun
+@node Remapping Commands
+@section Remapping Commands
+@cindex remapping commands
+
+ A special kind of key binding, using a special ``key sequence''
+which includes a command name, has the effect of @dfn{remapping} that
+command into another. Here's how it works. You make a key binding
+for a key sequence that starts with the dummy event @code{remap},
+followed by the command name you want to remap. Specify the remapped
+definition as the definition in this binding. The remapped definition
+is usually a command name, but it can be any valid definition for
+a key binding.
+
+ Here's an example. Suppose that My mode uses special commands
+@code{my-kill-line} and @code{my-kill-word}, which should be invoked
+instead of @code{kill-line} and @code{kill-word}. It can establish
+this by making these two command-remapping bindings in its keymap:
+
+@example
+(define-key my-mode-map [remap kill-line] 'my-kill-line)
+(define-key my-mode-map [remap kill-word] 'my-kill-word)
+@end example
+
+Whenever @code{my-mode-map} is an active keymap, if the user types
+@kbd{C-k}, Emacs will find the standard global binding of
+@code{kill-line} (assuming nobody has changed it). But
+@code{my-mode-map} remaps @code{kill-line} to @code{my-kill-line},
+so instead of running @code{kill-line}, Emacs runs
+@code{my-kill-line}.
+
+Remapping only works through a single level. In other words,
+
+@example
+(define-key my-mode-map [remap kill-line] 'my-kill-line)
+(define-key my-mode-map [remap my-kill-line] 'my-other-kill-line)
+@end example
+
+@noindent
+does not have the effect of remapping @code{kill-line} into
+@code{my-other-kill-line}. If an ordinary key binding specifies
+@code{kill-line}, this keymap will remap it to @code{my-kill-line};
+if an ordinary binding specifies @code{my-kill-line}, this keymap will
+remap it to @code{my-other-kill-line}.
+
+@defun command-remapping command
+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}.
+@end defun
+
@node Key Binding Commands
@section Commands for Binding Keys
This section describes some convenient interactive interfaces for
changing key bindings. They work by calling @code{define-key}.
- People often use @code{global-set-key} in their @file{.emacs} file for
-simple customization. For example,
+ People often use @code{global-set-key} in their init files
+(@pxref{Init File}) for simple customization. For example,
@smallexample
-(global-set-key "\C-x\C-\\" 'next-line)
+(global-set-key (kbd "C-x C-\\") 'next-line)
@end smallexample
@noindent
redefines the first (leftmost) mouse button, typed with the Meta key, to
set point where you click.
+@cindex non-@acronym{ASCII} text in keybindings
+ Be careful when using non-@acronym{ASCII} text characters in Lisp
+specifications of keys to bind. If these are read as multibyte text, as
+they usually will be in a Lisp file (@pxref{Loading Non-ASCII}), you
+must type the keys as multibyte too. For instance, if you use this:
+
+@smallexample
+(global-set-key "@"o" 'my-function) ; bind o-umlaut
+@end smallexample
+
+@noindent
+or
+
+@smallexample
+(global-set-key ?@"o 'my-function) ; bind o-umlaut
+@end smallexample
+
+@noindent
+and your language environment is multibyte Latin-1, these commands
+actually bind the multibyte character with code 2294, not the unibyte
+Latin-1 character with code 246 (@kbd{M-v}). In order to use this
+binding, you need to enter the multibyte Latin-1 character as keyboard
+input. One way to do this is by using an appropriate input method
+(@pxref{Input Methods, , Input Methods, emacs, The GNU Emacs Manual}).
+
+ If you want to use a unibyte character in the key binding, you can
+construct the key sequence string using @code{multibyte-char-to-unibyte}
+or @code{string-make-unibyte} (@pxref{Converting Representations}).
+
@deffn Command global-set-key key definition
This function sets the binding of @var{key} in the current global map
to @var{definition}.
@var{keymap} is @var{map}.
The elements of the alist are ordered so that the @var{key} increases
-in length. The first element is always @code{("" .@: @var{keymap})},
+in length. The first element is always @code{([] .@: @var{keymap})},
because the specified keymap is accessible from itself with a prefix of
no events.
@smallexample
@group
(accessible-keymaps (current-local-map))
-@result{}(("" keymap
+@result{}(([] keymap
(27 keymap ; @r{Note this keymap for @key{ESC} is repeated below.}
(83 . center-paragraph)
(115 . center-line))
@end group
@group
- ("^[" keymap
- (83 . center-paragraph)
+ ("^[" keymap
+ (83 . center-paragraph)
(115 . foo)))
@end group
@end smallexample
@smallexample
@group
(accessible-keymaps (current-global-map))
-@result{} (("" keymap [set-mark-command beginning-of-line @dots{}
+@result{} (([] keymap [set-mark-command beginning-of-line @dots{}
delete-backward-char])
@end group
@group
These are not all the keymaps you would see in actuality.
@end defun
-@defun where-is-internal command &optional keymap firstonly noindirect
+@defun map-keymap function keymap
+The function @code{map-keymap} calls @var{function} once
+for each binding in @var{keymap}. It passes two arguments,
+the event type and the value of the binding. If @var{keymap}
+has a parent, the parent's bindings are included as well.
+This works recursively: if the parent has itself a parent, then the
+grandparent's bindings are also included and so on.
+
+This function is the cleanest way to examine all the bindings
+in a keymap.
+@end defun
+
+@defun where-is-internal command &optional keymap firstonly noindirect no-remap
This function is a subroutine used by the @code{where-is} command
(@pxref{Help, , Help, emacs,The GNU Emacs Manual}). It returns a list
-of key sequences (of any length) that are bound to @var{command} in a
+of all key sequences (of any length) that are bound to @var{command} in a
set of keymaps.
The argument @var{command} can be any object; it is compared with all
If @var{keymap} is @code{nil}, then the maps used are the current active
keymaps, disregarding @code{overriding-local-map} (that is, pretending
-its value is @code{nil}). If @var{keymap} is non-@code{nil}, then the
-maps searched are @var{keymap} and the global keymap.
+its value is @code{nil}). If @var{keymap} is a keymap, then the
+maps searched are @var{keymap} and the global keymap. If @var{keymap}
+is a list of keymaps, only those keymaps are searched.
Usually it's best to use @code{overriding-local-map} as the expression
for @var{keymap}. Then @code{where-is-internal} searches precisely the
@code{(keymap)} (an empty keymap) as @var{keymap}.
If @var{firstonly} is @code{non-ascii}, then the value is a single
-string representing the first key sequence found, rather than a list of
+vector representing the first key sequence found, rather than a list of
all possible key sequences. If @var{firstonly} is @code{t}, then the
value is the first key sequence, except that key sequences consisting
-entirely of @sc{ASCII} characters (or meta variants of @sc{ASCII}
-characters) are preferred to all other key sequences.
+entirely of @acronym{ASCII} characters (or meta variants of @acronym{ASCII}
+characters) are preferred to all other key sequences and that the
+return value can never be a menu binding.
If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't
follow indirect keymap bindings. This makes it possible to search for
an indirect definition itself.
+When command remapping is in effect (@pxref{Remapping Commands}),
+@code{where-is-internal} figures out when a command will be run due to
+remapping and reports keys accordingly. It also returns @code{nil} if
+@var{command} won't really be run because it has been remapped to some
+other command. However, if @var{no-remap} is non-@code{nil}.
+@code{where-is-internal} ignores remappings.
+
@smallexample
@group
(where-is-internal 'describe-function)
@end smallexample
@end defun
-@deffn Command describe-bindings prefix
+@deffn Command describe-bindings &optional prefix buffer-or-name
This function creates a listing of all current key bindings, and
displays it in a buffer named @samp{*Help*}. The text is grouped by
modes---minor modes first, then the major mode, then global bindings.
The listing describes meta characters as @key{ESC} followed by the
corresponding non-meta character.
-When several characters with consecutive @sc{ASCII} codes have the
+When several characters with consecutive @acronym{ASCII} codes have the
same definition, they are shown together, as
@samp{@var{firstchar}..@var{lastchar}}. In this instance, you need to
-know the @sc{ASCII} codes to understand which characters this means.
+know the @acronym{ASCII} codes to understand which characters this means.
For example, in the default global map, the characters @samp{@key{SPC}
-..@: ~} are described by a single line. @key{SPC} is @sc{ASCII} 32,
-@kbd{~} is @sc{ASCII} 126, and the characters between them include all
+..@: ~} are described by a single line. @key{SPC} is @acronym{ASCII} 32,
+@kbd{~} is @acronym{ASCII} 126, and the characters between them include all
the normal printing characters, (e.g., letters, digits, punctuation,
etc.@:); all these characters are bound to @code{self-insert-command}.
+
+If @var{buffer-or-name} is non-@code{nil}, it should be a buffer or a
+buffer name. Then @code{describe-bindings} lists that buffer's bindings,
+instead of the current buffer's.
@end deffn
@node Menu Keymaps
* Keyboard Menus:: How they actuate it 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.
* Modifying Menus:: How to add new items to a menu.
@end 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.
(@xref{Format of Keymaps}.) The string should describe the purpose of
-the menu. 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} or
-@code{make-sparse-keymap} (@pxref{Creating Keymaps}).
+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.
+
+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}).
+
+
+@defun keymap-prompt keymap
+This function returns the overall prompt string of @var{keymap},
+or @code{nil} if it has none.
+@end defun
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
@code{define-key-after} (@pxref{Modifying Menus}).
@menu
-* Simple Menu Items::
-* Extended Menu Items::
+* Simple Menu Items:: A simple kind of menu key binding,
+ limited in capabilities.
+* Extended Menu Items:: More powerful menu item definitions
+ let you specify keywords to enable
+ various features.
+* Menu Separators:: Drawing a horizontal line through a menu.
+* Alias Menu Items:: Using command aliases in menu items.
@end menu
@node Simple Menu Items
(@var{item-string} . @var{real-binding})
@end example
+@noindent
The @sc{car}, @var{item-string}, is the string to be displayed in the
menu. It should be short---preferably one to three words. It should
-describe the action of the command it corresponds to.
+describe the action of the command it corresponds to. Note that it is
+not generally possible to display non-@acronym{ASCII} text in menus. It will
+work for keyboard menus and will work to a large extent when Emacs is
+built with Gtk+ support.@footnote{In this case, the text is first
+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:
@example
-(@var{item-string} @var{help-string} . @var{real-binding})
+(@var{item-string} @var{help} . @var{real-binding})
@end example
-Currently Emacs does not actually use @var{help-string}; it knows only
-how to ignore @var{help-string} in order to extract @var{real-binding}.
-In the future we may use @var{help-string} as extended documentation for
-the menu item, available on request.
+@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
@var{help-string} are part of the event's binding. However,
calculates them automatically. Don't mention keyboard equivalents in
the item strings themselves, since that is redundant.
-Sometimes it is useful to make menu items that use the ``same'' command
-but with different enable conditions. You can do this by defining alias
-commands. Here's an example that makes two aliases for
-@code{toggle-read-only} and gives them different enable conditions:
-
-@example
-(defalias 'make-read-only 'toggle-read-only)
-(put 'make-read-only 'menu-enable '(not buffer-read-only))
-(defalias 'make-writable 'toggle-read-only)
-(put 'make-writable 'menu-enable 'buffer-read-only)
-@end example
-
-When using aliases in menus, often it is useful to display the
-equivalent key bindings for the ``real'' command name, not the aliases
-(which typically don't have any key bindings except for the menu
-itself). To request this, give the alias symbol a non-@code{nil}
-@code{menu-alias} property. Thus,
-
-@example
-(put 'make-read-only 'menu-alias t)
-(put 'make-writable 'menu-alias t)
-@end example
-
-@noindent
-causes menu items for @code{make-read-only} and @code{make-writable} to
-show the keyboard bindings for @code{toggle-read-only}.
-
@node Extended Menu Items
@subsubsection Extended Menu Items
+@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
@end example
@noindent
-where a string consisting of two or more dashes specifies a separator line.
+A string starting with two or more dashes specifies a separator line;
+see @ref{Menu Separators}.
To define a real menu item which can be selected, the extended format
item looks like this:
other information. Here is a table of the properties that are supported:
@table @code
-@item :enable FORM
+@item :enable @var{form}
The result of evaluating @var{form} determines whether the item is
-enabled (non-@code{nil} means yes).
+enabled (non-@code{nil} means yes). If the item is not enabled,
+you can't really click on it.
-@item :visible FORM
+@item :visible @var{form}
The result of evaluating @var{form} determines whether the item should
actually appear in the menu (non-@code{nil} means yes). If the item
does not appear, then the menu is displayed as if this item were
not defined at all.
@item :help @var{help}
-The value of this property, @var{help}, is the extra help string (not
-currently used).
+The value of this property, @var{help}, specifies a ``help-echo'' string
+to display while the mouse is on that item. This is displayed in the
+same way as @code{help-echo} text properties (@pxref{Help display}).
+Note that this must be a constant string, unlike the @code{help-echo}
+property for text and overlays.
@item :button (@var{type} . @var{selected})
This property provides a way to define radio buttons and toggle buttons.
-The @sc{car}, @var{type}, says which: is should be @code{:toggle} or
+The @sc{car}, @var{type}, says which: it should be @code{:toggle} or
@code{:radio}. The @sc{cdr}, @var{selected}, should be a form; the
result of evaluating it says whether this button is currently selected.
+A @dfn{toggle} is a menu item which is labeled as either ``on'' or ``off''
+according to the value of @var{selected}. The command itself should
+toggle @var{selected}, setting it to @code{t} if it is @code{nil},
+and to @code{nil} if it is @code{t}. Here is how the menu item
+to toggle the @code{debug-on-error} flag is defined:
+
+@example
+(menu-item "Debug on Error" toggle-debug-on-error
+ :button (:toggle
+ . (and (boundp 'debug-on-error)
+ debug-on-error)))
+@end example
+
+@noindent
+This works because @code{toggle-debug-on-error} is defined as a command
+which toggles the variable @code{debug-on-error}.
+
+@dfn{Radio buttons} are a group of menu items, in which at any time one
+and only one is ``selected.'' There should be a variable whose value
+says which one is selected at any time. The @var{selected} form for
+each radio button in the group should check whether the variable has the
+right value for selecting that button. Clicking on the button should
+set the variable so that the button you clicked on becomes selected.
+
+@item :key-sequence @var{key-sequence}
+This property specifies which key sequence is likely to be bound to the
+same command invoked by this menu item. If you specify the right key
+sequence, that makes preparing the menu for display run much faster.
+
+If you specify the wrong key sequence, it has no effect; before Emacs
+displays @var{key-sequence} in the menu, it verifies that
+@var{key-sequence} is really equivalent to this menu item.
+
+@item :key-sequence nil
+This property indicates that there is normally no key binding which is
+equivalent to this menu item. Using this property saves time in
+preparing the menu for display, because Emacs does not need to search
+the keymaps for a keyboard equivalent for this menu item.
+
+However, if the user has rebound this item's definition to a key
+sequence, Emacs ignores the @code{:keys} property and finds the keyboard
+equivalent anyway.
+
+@item :keys @var{string}
+This property specifies that @var{string} is the string to display
+as the keyboard equivalent for this menu item. You can use
+the @samp{\\[...]} documentation construct in @var{string}.
+
@item :filter @var{filter-fn}
This property provides a way to compute the menu item dynamically.
The property value @var{filter-fn} should be a function of one argument;
function should return the binding to use instead.
@end table
+@node Menu Separators
+@subsubsection Menu Separators
+@cindex menu separators
+
+ A menu separator is a kind of menu item that doesn't display any
+text---instead, it divides the menu into subparts with a horizontal line.
+A separator looks like this in the menu keymap:
+
+@example
+(menu-item @var{separator-type})
+@end example
+
+@noindent
+where @var{separator-type} is a string starting with two or more dashes.
+
+ In the simplest case, @var{separator-type} consists of only dashes.
+That specifies the default kind of separator. (For compatibility,
+@code{""} and @code{-} also count as separators.)
+
+ Starting in Emacs 21, certain other values of @var{separator-type}
+specify a different style of separator. Here is a table of them:
+
+@table @code
+@item "--no-line"
+@itemx "--space"
+An extra vertical space, with no actual line.
+
+@item "--single-line"
+A single line in the menu's foreground color.
+
+@item "--double-line"
+A double line in the menu's foreground color.
+
+@item "--single-dashed-line"
+A single dashed line in the menu's foreground color.
+
+@item "--double-dashed-line"
+A double dashed line in the menu's foreground color.
+
+@item "--shadow-etched-in"
+A single line with a 3D sunken appearance. This is the default,
+used separators consisting of dashes only.
+
+@item "--shadow-etched-out"
+A single line with a 3D raised appearance.
+
+@item "--shadow-etched-in-dash"
+A single dashed line with a 3D sunken appearance.
+
+@item "--shadow-etched-out-dash"
+A single dashed line with a 3D raised appearance.
+
+@item "--shadow-double-etched-in"
+Two lines with a 3D sunken appearance.
+
+@item "--shadow-double-etched-out"
+Two lines with a 3D raised appearance.
+
+@item "--shadow-double-etched-in-dash"
+Two dashed lines with a 3D sunken appearance.
+
+@item "--shadow-double-etched-out-dash"
+Two dashed lines with a 3D raised appearance.
+@end table
+
+ You can also give these names in another style, adding a colon after
+the double-dash and replacing each single dash with capitalization of
+the following word. Thus, @code{"--:singleLine"}, is equivalent to
+@code{"--single-line"}.
+
+ Some systems and display toolkits don't really handle all of these
+separator types. If you use a type that isn't supported, the menu
+displays a similar kind of separator that is supported.
+
+@node Alias Menu Items
+@subsubsection Alias Menu Items
+
+ Sometimes it is useful to make menu items that use the ``same''
+command but with different enable conditions. The best way to do this
+in Emacs now is with extended menu items; before that feature existed,
+it could be done by defining alias commands and using them in menu
+items. Here's an example that makes two aliases for
+@code{toggle-read-only} and gives them different enable conditions:
+
+@example
+(defalias 'make-read-only 'toggle-read-only)
+(put 'make-read-only 'menu-enable '(not buffer-read-only))
+(defalias 'make-writable 'toggle-read-only)
+(put 'make-writable 'menu-enable 'buffer-read-only)
+@end example
+
+When using aliases in menus, often it is useful to display the
+equivalent key bindings for the ``real'' command name, not the aliases
+(which typically don't have any key bindings except for the menu
+itself). To request this, give the alias symbol a non-@code{nil}
+@code{menu-alias} property. Thus,
+
+@example
+(put 'make-read-only 'menu-alias t)
+(put 'make-writable 'menu-alias t)
+@end example
+
+@noindent
+causes menu items for @code{make-read-only} and @code{make-writable} to
+show the keyboard bindings for @code{toggle-read-only}.
+
@node Mouse Menus
@subsection Menus and the Mouse
key) has a definition that is a menu keymap, the user can use the
keyboard to choose a menu item.
-Emacs displays the menu alternatives (the item strings of the bindings)
-in the echo area. If they 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 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.)
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
Here is a complete example of defining a menu keymap. It is the
definition of the @samp{Print} submenu in the @samp{Tools} menu in the
-menu bar. First we create the keymap, and give it a name:
+menu bar, and it uses the simple menu item format (@pxref{Simple Menu
+Items}). First we create the keymap, and give it a name:
@example
(defvar menu-bar-print-menu (make-sparse-keymap "Print"))
when the user selects from the menu, and they appear in the output of
@code{where-is} and @code{apropos}.
+ The menu in this example is intended for use with the mouse. If a
+menu is intended for use with the keyboard, that is, if it is bound to
+a key sequence ending with a keyboard event, then the menu items
+should be bound to characters or ``real'' function keys, that can be
+typed with the keyboard.
+
The binding whose definition is @code{("--")} is a separator line.
Like a real menu item, the separator has a key symbol, in this case
@code{separator-ps-print}. If one menu has two separators, they must
can do it this way:
@example
-(define-key global-map [C-S-down-mouse-1] menu-bar-print-menu)
+(define-key global-map [C-S-down-mouse-1]
+ menu-bar-print-menu)
+@end example
+
+ We could equally well use an extended menu item (@pxref{Extended Menu
+Items}) for @code{print-region}, like this:
+
+@example
+(define-key menu-bar-print-menu [print-region]
+ '(menu-item "Print Region" print-region
+ :enable mark-active))
+@end example
+
+@noindent
+With the extended menu item, the enable condition is specified
+inside the menu item itself. If we wanted to make this
+item disappear from the menu entirely when the mark is inactive,
+we could do it this way:
+
+@example
+(define-key menu-bar-print-menu [print-region]
+ '(menu-item "Print Region" print-region
+ :visible mark-active))
@end example
@node Menu Bar
should vary.
@end defvar
+@node Tool Bar
+@subsection Tool bars
+@cindex tool bar
+
+ A @dfn{tool bar} is a row of icons at the top of a frame, that execute
+commands when you click on them---in effect, a kind of graphical menu
+bar. Emacs supports tool bars starting with version 21.
+
+ The frame parameter @code{tool-bar-lines} (X resource @samp{toolBar})
+controls how many lines' worth of height to reserve for the tool bar. A
+zero value suppresses the tool bar. If the value is nonzero, and
+@code{auto-resize-tool-bars} is non-@code{nil}, the tool bar expands and
+contracts automatically as needed to hold the specified contents.
+
+ The tool bar contents are controlled by a menu keymap attached to a
+fake ``function key'' called @code{tool-bar} (much like the way the menu
+bar is controlled). So you define a tool bar item using
+@code{define-key}, like this:
+
+@example
+(define-key global-map [tool-bar @var{key}] @var{item})
+@end example
+
+@noindent
+where @var{key} is a fake ``function key'' to distinguish this item from
+other items, and @var{item} is a menu item key binding (@pxref{Extended
+Menu Items}), which says how to display this item and how it behaves.
+
+ The usual menu keymap item properties, @code{:visible},
+@code{:enable}, @code{:button}, and @code{:filter}, are useful in
+tool bar bindings and have their normal meanings. The @var{real-binding}
+in the item must be a command, not a keymap; in other words, it does not
+work to define a tool bar icon as a prefix key.
+
+ The @code{:help} property specifies a ``help-echo'' string to display
+while the mouse is on that item. This is displayed in the same way as
+@code{help-echo} text properties (@pxref{Help display}).
+
+ In addition, you should use the @code{:image} property;
+this is how you specify the image to display in the tool bar:
+
+@table @code
+@item :image @var{image}
+@var{images} is either a single image specification or a vector of four
+image specifications. If you use a vector of four,
+one of them is used, depending on circumstances:
+
+@table @asis
+@item item 0
+Used when the item is enabled and selected.
+@item item 1
+Used when the item is enabled and deselected.
+@item item 2
+Used when the item is disabled and selected.
+@item item 3
+Used when the item is disabled and deselected.
+@end table
+@end table
+
+If @var{image} is a single image specification, Emacs draws the tool bar
+button in disabled state by applying an edge-detection algorithm to the
+image.
+
+The default tool bar is defined so that items specific to editing do not
+appear for major modes whose command symbol has a @code{mode-class}
+property of @code{special} (@pxref{Major Mode Conventions}). Major
+modes may add items to the global bar by binding @code{[tool-bar
+@var{foo}]} in their local map. It makes sense for some major modes to
+replace the default tool bar items completely, since not many can be
+accommodated conveniently, and the default bindings make this easy by
+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]
+ '(menu-item "tool bar" ignore
+ :filter (lambda (ignore) tool-bar-map)))
+@end example
+@noindent
+Thus the tool bar map is derived dynamically from the value of variable
+@code{tool-bar-map} and you should normally adjust the default (global)
+tool bar by changing that map. Major modes may replace the global bar
+completely by making @code{tool-bar-map} buffer-local and set to a
+keymap containing only the desired items. Info mode provides an
+example.
+@end defvar
+
+There are two convenience functions for defining tool bar items, as
+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
+@code{find-image}. Given a value @samp{"exit"}, say, @file{exit.xpm},
+@file{exit.pbm} and @file{exit.xbm} would be searched for in that order
+on a color display. On a monochrome display, the search order is
+@samp{.pbm}, @samp{.xbm} and @samp{.xpm}. The binding to use is the
+command @var{def}, and @var{key} is the fake function key symbol in the
+prefix keymap. The remaining arguments @var{props} are additional
+property list elements to add to the menu item specification.
+
+To define items in some local map, bind @code{tool-bar-map} with
+@code{let} around calls of this function:
+@example
+(defvar foo-tool-bar-map
+ (let ((tool-bar-map (make-sparse-keymap)))
+ (tool-bar-add-item @dots{})
+ @dots{}
+ tool-bar-map))
+@end example
+@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{global-map}) and modified to add an image specification for
+@var{icon}, which is found in the same way as by
+@code{tool-bar-add-item}. The resulting binding is then placed in
+@code{tool-bar-map}, so use this function only for global tool bar
+items.
+
+@var{map} must contain an appropriate keymap bound to
+@code{[menu-bar]}. The remaining arguments @var{props} are additional
+property list elements to add to the menu item specification.
+@end defun
+
+@defun tool-bar-local-item-from-menu command icon in-map &optional from-map &rest props
+This function is used for making non-global tool bar items. Use it
+like @code{tool-bar-add-item-from-menu} except that @var{in-map}
+specifies the local map to make the definition in. The argument
+@var{from-map} is like the @var{map} argument of
+@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
+
+ You can define a special meaning for clicking on a tool bar item with
+the shift, control, meta, etc., modifiers. You do this by setting up
+additional items that relate to the original item through the fake
+function keys. Specifically, the additional items should use the
+modified versions of the same fake function key used to name the
+original item.
+
+ Thus, if the original item was defined this way,
+
+@example
+(define-key global-map [tool-bar shell]
+ '(menu-item "Shell" shell
+ :image (image :type xpm :file "shell.xpm")))
+@end example
+
+@noindent
+then here is how you can define clicking on the same tool bar image with
+the shift modifier:
+
+@example
+(define-key global-map [tool-bar S-shell] 'some-command)
+@end example
+
+@xref{Function Keys}, for more information about how to add modifiers to
+function keys.
+
@node Modifying Menus
@subsection Modifying Menus
use @code{define-key} to add the item, it normally goes at the front of
the menu. To put it elsewhere in the menu, use @code{define-key-after}:
-@defun define-key-after map key binding after
+@defun define-key-after map key binding &optional after
Define a binding in @var{map} for @var{key}, with value @var{binding},
just like @code{define-key}, but position the binding in @var{map} after
the binding for the event @var{after}. The argument @var{key} should be
of length one---a vector or string with just one element. But
@var{after} should be a single event type---a symbol or a character, not
a sequence. The new binding goes after the binding for @var{after}. If
-@var{after} is @code{t}, then the new binding goes last, at the end of
-the keymap.
+@var{after} is @code{t} or is omitted, then the new binding goes last, at
+the end of the keymap. However, new bindings are added before any
+inherited keymap.
Here is an example:
@example
(define-key-after my-menu [drink]
- '("Drink" . drink-command) 'eat)
+ '("Drink" . drink-command) 'eat)
@end example
@noindent
[work] '("Work" . work-command) 'break)
@end example
@end defun
+
+@ignore
+ arch-tag: cfb87287-9364-4e46-9e93-6c2f7f6ae794
+@end ignore