@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2000, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990-1994, 1998-2012 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@setfilename ../../info/keymaps
@node Keymaps, Modes, Command Loop, Top
@chapter Keymaps
@cindex keymap
@kbd{C-x l}.
Key sequences containing function keys, mouse button events, or
-non-ASCII characters such as @kbd{C-=} or @kbd{H-a} cannot be
+non-@acronym{ASCII} characters such as @kbd{C-=} or @kbd{H-a} cannot be
represented as strings; they have to be represented as vectors.
In the vector representation, each element of the vector represents
which is always a character or a symbol. @xref{Classifying Events}.
In this kind of binding, @var{binding} is a command.
-@item (@var{type} @var{item-name} @r{[}@var{cache}@r{]} .@: @var{binding})
+@item (@var{type} @var{item-name} .@: @var{binding})
This specifies a binding which is also a simple menu item that
-displays as @var{item-name} in the menu. @var{cache}, if present,
-caches certain information for display in the menu. @xref{Simple Menu
-Items}.
+displays as @var{item-name} in the menu. @xref{Simple Menu Items}.
-@item (@var{type} @var{item-name} @var{help-string} @r{[}@var{cache}@r{]} .@: @var{binding})
+@item (@var{type} @var{item-name} @var{help-string} .@: @var{binding})
This is a simple menu item with help string @var{help-string}.
@item (@var{type} menu-item .@: @var{details})
@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
-C-l}, @kbd{M-C-q}, and @kbd{M-C-x}.
+keymap. It defines bindings for @key{DEL}, @kbd{C-c C-z},
+@kbd{C-M-q}, and @kbd{C-M-x} (the actual value also contains a menu
+binding, which is omitted here for the sake of brevity).
@example
@group
@end group
@group
(27 keymap
- ;; @r{@kbd{M-C-x}, treated as @kbd{@key{ESC} C-x}}
- (24 . lisp-send-defun)
- keymap
- ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}}
- (17 . indent-sexp))
+ ;; @r{@kbd{C-M-x}, treated as @kbd{@key{ESC} C-x}}
+ (24 . lisp-send-defun))
@end group
@group
;; @r{This part is inherited from @code{lisp-mode-shared-map}.}
@end group
@group
(27 keymap
- ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}}
- (17 . indent-sexp))
- (9 . lisp-indent-line))
+ ;; @r{@kbd{C-M-q}, treated as @kbd{@key{ESC} C-q}}
+ (17 . indent-sexp)))
@end group
@end example
@code{nil}, so these character's bindings are never inherited from
the parent keymap.
+@cindex keymap inheritance from multiple maps
+ Sometimes you want to make a keymap that inherits from more than one
+map. You can use the function @code{make-composed-keymap} for this.
+
+@defun make-composed-keymap maps &optional parent
+This function returns a new keymap composed of the existing keymap(s)
+@var{maps}, and optionally inheriting from a parent keymap
+@var{parent}. @var{maps} can be a single keymap or a list of more
+than one. When looking up a key in the resulting new map, Emacs
+searches in each of the @var{maps} in turn, and then in @var{parent},
+stopping at the first match. A @code{nil} binding in any one of
+@var{maps} overrides any binding in @var{parent}, but it does not
+override any non-@code{nil} binding in any other of the @var{maps}.
+@end defun
+
+@noindent For example, here is how Emacs sets the parent of
+@code{help-mode-map}, such that it inherits from both
+@code{button-buffer-map} and @code{special-mode-map}:
+
+@example
+(defvar help-mode-map
+ (let ((map (make-sparse-keymap)))
+ (set-keymap-parent map (make-composed-keymap button-buffer-map
+ special-mode-map))
+ ... map) ... )
+@end example
+
+
@node Prefix Keys
@section Prefix Keys
@cindex prefix key
Emacs has other keymaps that are used in a different way---translating
events within @code{read-key-sequence}. @xref{Translation Keymaps}.
- @xref{Standard Keymaps}, for a list of standard keymaps.
+ @xref{Standard Keymaps}, for a list of some standard keymaps.
@defun current-active-maps &optional olp position
This returns the list of active keymaps that would be used by the
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,
+return 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}.
them:
@lisp
-(or (if overriding-terminal-local-map
- (@var{find-in} overriding-terminal-local-map)
- (if overriding-local-map
- (@var{find-in} overriding-local-map)
- (or (@var{find-in} (get-char-property (point) 'keymap))
- (@var{find-in-any} emulation-mode-map-alists)
- (@var{find-in-any} minor-mode-overriding-map-alist)
- (@var{find-in-any} minor-mode-map-alist)
- (if (get-text-property (point) 'local-map)
- (@var{find-in} (get-char-property (point) 'local-map))
- (@var{find-in} (current-local-map))))))
+(or (cond
+ (overriding-terminal-local-map
+ (@var{find-in} overriding-terminal-local-map))
+ (overriding-local-map
+ (@var{find-in} overriding-local-map))
+ ((or (@var{find-in} (get-char-property (point) 'keymap))
+ (@var{find-in-any} emulation-mode-map-alists)
+ (@var{find-in-any} minor-mode-overriding-map-alist)
+ (@var{find-in-any} minor-mode-map-alist)
+ (if (get-text-property (point) 'local-map)
+ (@var{find-in} (get-char-property (point) 'local-map))
+ (@var{find-in} (current-local-map))))))
(@var{find-in} (current-global-map)))
@end lisp
@noindent
-The @var{find-in} and @var{find-in-any} are pseudo functions that
-search in one keymap and in an alist of keymaps, respectively.
-(Searching a single keymap for a binding is called @dfn{key lookup};
-see @ref{Key Lookup}.) If the key sequence starts with a mouse event,
-or a symbolic prefix event followed by a mouse event, that event's
-position is used instead of point and the current buffer. Mouse
-events on an embedded string use non-@code{nil} text properties from
-that string instead of the buffer.
-
-@enumerate
-@item
-The function finally found may be remapped
-(@pxref{Remapping Commands}).
-
-@item
-Characters that are bound to @code{self-insert-command} are translated
-according to @code{translation-table-for-input} before insertion.
-
-@item
-@code{current-active-maps} returns a list of the
-currently active keymaps at point.
-
-@item
-When a match is found (@pxref{Key Lookup}), if the binding in the
+@var{find-in} and @var{find-in-any} are pseudo functions that search
+in one keymap and in an alist of keymaps, respectively. (Searching a
+single keymap for a binding is called @dfn{key lookup}; see @ref{Key
+Lookup}.) If the key sequence starts with a mouse event, or a
+symbolic prefix event followed by a mouse event, that event's position
+is used instead of point and the current buffer. Mouse events on an
+embedded string use non-@code{nil} text properties from that string
+instead of the buffer.
+
+ When a match is found (@pxref{Key Lookup}), if the binding in the
keymap is a function, the search is over. However if the keymap entry
is a symbol with a value or a string, Emacs replaces the input key
sequences with the variable's value or the string, and restarts the
search of the active keymaps.
-@end enumerate
+
+ The function finally found might also be remapped. @xref{Remapping
+Commands}.
@node Controlling Active Maps
@section Controlling the Active Keymaps
@defun current-local-map
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
+@file{*scratch*} buffer (using Lisp Interaction mode) is a sparse keymap
in which the entry for @key{ESC}, @acronym{ASCII} code 27, is another sparse
keymap.
binding is not executable as a command.
@end table
- In short, a keymap entry may be a keymap, a command, a keyboard macro,
-a symbol that leads to one of them, or an indirection or @code{nil}.
-Here is an example of a sparse keymap with two characters bound to
-commands and one bound to another keymap. This map is the normal value
-of @code{emacs-lisp-mode-map}. Note that 9 is the code for @key{TAB},
-127 for @key{DEL}, 27 for @key{ESC}, 17 for @kbd{C-q} and 24 for
-@kbd{C-x}.
-
-@example
-@group
-(keymap (9 . lisp-indent-line)
- (127 . backward-delete-char-untabify)
- (27 keymap (17 . indent-sexp) (24 . eval-defun)))
-@end group
-@end example
+ In short, a keymap entry may be a keymap, a command, a keyboard
+macro, a symbol that leads to one of them, or an indirection or
+@code{nil}.
@node Functions for Key Lookup
@section Functions for Key Lookup
The @code{global-set-key} and @code{local-set-key} functions are
convenient interfaces for these operations (@pxref{Key Binding
Commands}). You can also use @code{define-key}, a more general
-function; then you must specify explicitly the map to change.
+function; then you must explicitly specify the map to change.
When choosing the key sequences for Lisp programs to rebind, please
follow the Emacs conventions for use of various keys (@pxref{Key
example, suppressing @code{global-map} would make it impossible to use
most of Emacs.
-Most often, @code{suppress-keymap} is used to initialize local
-keymaps of modes such as Rmail and Dired where insertion of text is not
-desirable and the buffer is read-only. Here is an example taken from
-the file @file{emacs/lisp/dired.el}, showing how the local keymap for
-Dired mode is set up:
+This function can be used to initialize the local keymap of a major
+mode for which insertion of text is not desirable. But usually such a
+mode should be derived from @code{special-mode} (@pxref{Basic Major
+Modes}); then its keymap will automatically inherit from
+@code{special-mode-map}, which is already suppressed. Here is how
+@code{special-mode-map} is defined:
@smallexample
@group
-(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{}
+(defvar special-mode-map
+ (let ((map (make-sparse-keymap)))
+ (suppress-keymap map)
+ (define-key map "q" 'quit-window)
+ @dots{}
+ map))
@end group
@end smallexample
@end defun
@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.
+ A special kind of key binding can be used to @dfn{remap} one command
+to another, without having to refer to the key sequence(s) bound to
+the original command. To use this feature, 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; for the binding, specify the
+new definition (usually a command name, but possibly any other 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:
+ For example, suppose My mode provides a special command
+@code{my-kill-line}, which should be invoked instead of
+@code{kill-line}. To establish this, its mode keymap should contain
+the following remapping:
@smallexample
(define-key my-mode-map [remap kill-line] 'my-kill-line)
-(define-key my-mode-map [remap kill-word] 'my-kill-word)
@end smallexample
-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}.
+@noindent
+Then, whenever @code{my-mode-map} is active, if the user types
+@kbd{C-k} (the default global key sequence for @code{kill-line}) Emacs
+will instead run @code{my-kill-line}.
-Remapping only works through a single level. In other words,
+ Note that remapping only takes place through active keymaps; for
+example, putting a remapping in a prefix keymap like @code{ctl-x-map}
+typically has no effect, as such keymaps are not themselves active.
+In addition, remapping only works through a single level; in the
+following example,
@smallexample
(define-key my-mode-map [remap kill-line] 'my-kill-line)
@end smallexample
@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}.
+@code{kill-line} is @emph{not} remapped to @code{my-other-kill-line}.
+Instead, if an ordinary key binding specifies @code{kill-line}, it is
+remapped to @code{my-kill-line}; if an ordinary binding specifies
+@code{my-kill-line}, it is remapped to @code{my-other-kill-line}.
+
+To undo the remapping of a command, remap it to @code{nil}; e.g.
+
+@smallexample
+(define-key my-mode-map [remap kill-line] nil)
+@end smallexample
@defun command-remapping command &optional position keymaps
This function returns the remapping for @var{command} (a symbol),
@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}).
+actually bind the multibyte character with code 246, not the byte
+code 246 (@kbd{M-v}) sent by a Latin-1 terminal. In order to use this
+binding, you need to teach Emacs how to decode the keyboard by using an
+appropriate input method (@pxref{Input Methods, , Input Methods, emacs, The GNU
+Emacs Manual}).
@deffn Command global-set-key key binding
This function sets the binding of @var{key} in the current global map
@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
+displays it in a buffer named @file{*Help*}. The text is grouped by
modes---minor modes first, then the major mode, then global bindings.
If @var{prefix} is non-@code{nil}, it should be a prefix key; then the
@cindex defining menus
@cindex menu prompt string
@cindex prompt string (of menu)
+@cindex menu item
A keymap acts as a menu if it has an @dfn{overall prompt string},
which is a string that appears as an element of the keymap.
various features.
* Menu Separators:: Drawing a horizontal line through a menu.
* Alias Menu Items:: Using command aliases in menu items.
+* Toolkit Differences:: Not all toolkits provide the same features.
@end menu
+
@node Simple Menu Items
@subsubsection Simple Menu Items
@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. 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 the Gtk+ toolkit.@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.}
+describe the action of the command it corresponds to. Note that not
+all graphical toolkits can display non-@acronym{ASCII} text in menus
+(it will work for keyboard menus and will work to a large extent with
+the GTK+ toolkit).
You can also supply a second string, called the help string, as follows:
of menus in advance. To force recalculation of the menu bar, call
@code{force-mode-line-update} (@pxref{Mode Line Format}).
- You've probably noticed that menu items show the equivalent keyboard key
-sequence (if any) to invoke the same command. To save time on
-recalculation, menu display caches this information in a sublist in the
-binding, like this:
-
-@c This line is not too long--rms.
-@example
-(@var{item-string} @r{[}@var{help}@r{]} (@var{key-binding-data}) . @var{real-binding})
-@end example
-
-@noindent
-Don't put these sublists in the menu item yourself; menu display
-calculates them automatically. Don't mention keyboard equivalents in
-the item strings themselves, since that is redundant.
-
@node Extended Menu Items
@subsubsection Extended Menu Items
@kindex menu-item
+@cindex extended menu item
An extended-format menu item is a more flexible and also cleaner
alternative to the simple format. You define an event type with a
@var{item-property-list}, has the form of a property list which contains
other information.
- When an equivalent keyboard key binding is cached, the extended menu
-item binding looks like this:
-
-@example
-(menu-item @var{item-name} @var{real-binding} (@var{key-binding-data})
- . @var{item-property-list})
-@end example
-
Here is a table of the properties that are supported:
@table @code
the following word. Thus, @code{"--:singleLine"}, is equivalent to
@code{"--single-line"}.
+ You can use a longer form to specify keywords such as @code{:enable}
+and @code{:visible} for a menu separator:
+
+@code{(menu-item @var{separator-type} nil . @var{item-property-list})}
+
+For example:
+
+@example
+(menu-item "--" nil :visible (boundp 'foo))
+@end example
+
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.
causes menu items for @code{make-read-only} and @code{make-writable} to
show the keyboard bindings for @code{toggle-read-only}.
+@node Toolkit Differences
+@subsubsection Toolkit Differences
+
+The various toolkits with which you can build Emacs do not all support
+the same set of features for menus. Some code works as expected with
+one toolkit, but not under another.
+
+One example is menu actions or buttons in a top-level menu bar. The
+following works with the Lucid toolkit or on MS Windows, but not with
+GTK or Nextstep, where clicking on the item has no effect.
+
+@example
+(defun menu-action-greet ()
+ (interactive)
+ (message "Hello Emacs User!"))
+
+(defun top-level-menu ()
+ (interactive)
+ (define-key lisp-interaction-mode-map [menu-bar m]
+ '(menu-item "Action Button" menu-action-greet)))
+@end example
+
@node Mouse Menus
@subsection Menus and the Mouse
It's often best to use a button-down event to trigger the menu. Then
the user can select a menu item by releasing the button.
- A single keymap can appear as multiple menu panes, if you explicitly
-arrange for this. The way to do this is to make a keymap for each pane,
-then create a binding for each of those maps in the main keymap of the
-menu. Give each of these bindings an item string that starts with
-@samp{@@}. The rest of the item string becomes the name of the pane.
-See the file @file{lisp/mouse.el} for an example of this. Any ordinary
-bindings with @samp{@@}-less item strings are grouped into one pane,
-which appears along with the other panes explicitly created for the
-submaps.
-
- X toolkit menus don't have panes; instead, they can have submenus.
-Every nested keymap becomes a submenu, whether the item string starts
-with @samp{@@} or not. In a toolkit version of Emacs, the only thing
-special about @samp{@@} at the beginning of an item string is that the
-@samp{@@} doesn't appear in the menu item.
-
- Multiple keymaps that define the same menu prefix key produce
-separate panes or separate submenus.
+@cindex submenu
+ If the menu keymap contains a binding to a nested keymap, the nested
+keymap specifies a @dfn{submenu}. There will be a menu item, labeled
+by the nested keymap's item string, and clicking on this item
+automatically pops up the specified submenu. As a special exception,
+if the menu keymap contains a single nested keymap and no other menu
+items, the menu shows the contents of the nested keymap directly, not
+as a submenu.
+
+ However, if Emacs is compiled without X toolkit support, submenus
+are not supported. Each nested keymap is shown as a menu item, but
+clicking on it does not automatically pop up the submenu. If you wish
+to imitate the effect of submenus, you can do that by giving a nested
+keymap an item string which starts with @samp{@@}. This causes Emacs
+to display the nested keymap using a separate @dfn{menu pane}; the
+rest of the item string after the @samp{@@} is the pane label. If
+Emacs is compiled without X toolkit support, menu panes are not used;
+in that case, a @samp{@@} at the beginning of an item string is
+omitted when the menu label is displayed, and has no other effect.
@node Keyboard Menus
@subsection Menus and the Keyboard
she should type the corresponding character---the one whose binding is
that alternative.
-@ignore
-In a menu intended for keyboard use, each menu item must clearly
-indicate what character to type. The best convention to use is to make
-the character the first letter of the item string---that is something
-users will understand without being told. We plan to change this; by
-the time you read this manual, keyboard menus may explicitly name the
-key for each alternative.
-@end ignore
-
- This way of using menus in an Emacs-like editor was inspired by the
-Hierarkey system.
-
@defvar menu-prompt-more-char
This variable specifies the character to use to ask to see
the next line of a menu. Its initial value is 32, the code
@subsection The Menu Bar
@cindex menu bar
- Most window systems allow each frame to have a @dfn{menu bar}---a
-permanently displayed menu stretching horizontally across the top of
-the frame. (In order for a frame to display a menu bar, its
-@code{menu-bar-lines} parameter must be greater than zero.
-@xref{Layout Parameters}.)
-
- The items of the menu bar are the subcommands of the fake ``function
-key'' @code{menu-bar}, as defined in the active keymaps.
+ On graphical displays, there is usually a @dfn{menu bar} at the top
+of each frame. @xref{Menu Bars,,,emacs, The GNU Emacs Manual}. Menu
+bar items are subcommands of the fake ``function key''
+@code{menu-bar}, as defined in the active keymaps.
To add an item to the menu bar, invent a fake ``function key'' of your
own (let's call it @var{key}), and make a binding for the key sequence
@code{[menu-bar @var{key}]}. Most often, the binding is a menu keymap,
so that pressing a button on the menu bar item leads to another menu.
- When more than one active keymap defines the same fake function key
+ When more than one active keymap defines the same ``function key''
for the menu bar, the item appears just once. If the user clicks on
that menu bar item, it brings up a single, combined menu containing
all the subcommands of that item---the global subcommands, the local
Here's an example of setting up a menu bar item:
@example
-@group
-(modify-frame-parameters (selected-frame)
- '((menu-bar-lines . 2)))
-@end group
-
@group
;; @r{Make a menu keymap (with a prompt string)}
;; @r{and make it the menu bar item's definition.}
@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.
-
- 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.
+ A @dfn{tool bar} is a row of clickable icons at the top of a frame,
+just below the menu bar. @xref{Tool Bars,,,emacs, The GNU Emacs
+Manual}.
- If the value of @code{auto-resize-tool-bars} is @code{grow-only},
-the tool bar expands automatically, but does not contract automatically.
-To contract the tool bar, the user has to redraw the frame by entering
-@kbd{C-l}.
+ On each frame, the frame parameter @code{tool-bar-lines} 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.
+If the value is @code{grow-only}, the tool bar expands automatically,
+but does not contract automatically.
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
image.
The @code{:rtl} property specifies an alternative image to use for
-right-to-left languages. Only the Gtk+ version of Emacs supports this
+right-to-left languages. Only the GTK+ version of Emacs supports this
at present.
+Like the menu bar, the tool bar can display separators (@pxref{Menu
+Separators}). Tool bar separators are vertical rather than
+horizontal, though, and only a single style is supported. They are
+represented in the tool bar keymap by @code{(menu-item "--")} entries;
+properties like @code{:visible} are not supported for tool bar
+separators. Separators are rendered natively in GTK+ and Nextstep
+tool bars; in the other cases, they are rendered using an image of a
+vertical line.
+
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
@defvar 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)))
+ `(menu-item ,(purecopy "tool bar") ignore
+ :filter tool-bar-make-keymap))
@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.
+The function @code{tool-bar-make-keymap}, in turn, derives the actual
+tool bar map dynamically from the value of the variable
+@code{tool-bar-map}. Hence, you should normally adjust the default
+(global) tool bar by changing that map. Some major modes, such as
+Info mode, completely replace the global tool bar by making
+@code{tool-bar-map} buffer-local and setting it to a different keymap.
@end defvar
There are two convenience functions for defining tool bar items, as
[work] '("Work" . work-command) 'break)
@end example
@end defun
-
-@ignore
- arch-tag: cfb87287-9364-4e46-9e93-6c2f7f6ae794
-@end ignore