@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
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/keymaps
@node Keymaps, Modes, Command Loop, Top
@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
@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
@defun define-prefix-command symbol &optional mapvar prompt
@cindex 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. The return value is @code{symbol}.
as a variable instead.
If @var{prompt} is non-@code{nil}, that becomes the overall prompt
-string for the keymap. The prompt string is useful for menu keymaps
-(@pxref{Menu Keymaps}).
+string for the keymap. The prompt string should be given for menu keymaps
+(@pxref{Defining Menus}).
@end defun
@node Active Keymaps
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.
event (@pxref{Prefix Keys}). The default value is 27, which is the
@sc{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
@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
@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
redefines the first (leftmost) mouse button, typed with the Meta key, to
set point where you click.
-@cindex non-ASCII text in keybindings
+@cindex non-@sc{ascii} text in keybindings
Be careful when using non-@sc{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
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} or @code{define-prefix-command}
+(@pxref{Creating Keymaps}).
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
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,
not defined at all.
@item :help @var{help}
-The value of this property, @var{help}, is the extra help string (not
-currently used by Emacs).
+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.
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
@example
(define-key menu-bar-print-menu [print-region]
'(menu-item "Print Region" print-region
- :enable (mark-active)))
+ :enable mark-active))
@end example
@noindent
@example
(define-key menu-bar-print-menu [print-region]
'(menu-item "Print Region" print-region
- :visible (mark-active)))
+ :visible mark-active))
@end example
@node Menu Bar
bar. Emacs supports tool bars starting with version 21.
The frame parameter @code{tool-bar-lines} (X resource @samp{toolBar})
-controls how may lines' worth of height to reserve for the tool bar. A
+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.
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 is meaningful, and specifies a ``help-echo''
-string to display while the mouse is on that item.
+ 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 @asis
@item item 0
-Used when the iitem is enabled and selected.
+Used when the item is enabled and selected.
@item item 1
Used when the item is enabled and deselected.
@item item 2
@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 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 command 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 looked for in the same way as by
+@code{tool-bar-add-item}. The resulting binding is then placed in
+@code{tool-bar-map}. @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
+
@tindex auto-resize-tool-bar
@defvar auto-resize-tool-bar
If this variable is non-@code{nil}, the tool bar automatically resizes to
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