@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
@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
+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
+@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, for @sc{ASCII} characters. However, default
-bindings are still meaningful for events other than @sc{ASCII}
+binding in the keymap, for @sc{ascii} characters. However, default
+bindings are still meaningful for events other than @sc{ascii}
characters. 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
@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
+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.
@example
@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
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}, @sc{ascii} code 27, is another sparse
keymap.
@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
@end defvar
@defvar minor-mode-overriding-map-alist
-@tindex 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}
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}.
+@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
@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
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)
redefines the first (leftmost) mouse button, typed with the Meta key, to
set point where you click.
+@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
+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}.
string 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}
+entirely of @sc{ascii} characters (or meta variants of @sc{ascii}
characters) are preferred to all other key sequences.
If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't
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 @sc{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 @sc{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 @sc{ascii} 32,
+@kbd{~} is @sc{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}.
@end deffn
* 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} 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
@menu
* Simple Menu Items:: A simple kind of menu key binding,
limited in capabilities.
-* Alias Menu Items:: Using command aliases in menu items.
* 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
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,
@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 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.
-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.
(menu-item "Debug on Error" toggle-debug-on-error
:button (:toggle
. (and (boundp 'debug-on-error)
- debug-on-error))
+ debug-on-error)))
@end example
@noindent
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
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
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 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
+show all defined tool bar items---but not larger than a quarter of the
+frame's height.
+@end defvar
+
+@tindex auto-raise-tool-bar-items
+@defvar auto-raise-tool-bar-items
+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-item-margin
+@defvar tool-bar-item-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 1.
+@end defvar
+
+@tindex tool-bar-item-relief
+@defvar tool-bar-item-relief
+This variable specifies the shadow width for tool bar items.
+The value is an integer, a number of pixels. The default is 3.
+@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