+
+@node Menu Keymaps
+@section Menu Keymaps
+@cindex menu keymaps
+
+A keymap can operate as a menu as well as defining bindings for
+keyboard keys and mouse buttons. Menus are usually actuated with the
+mouse, but they can function with the keyboard also. If a menu keymap
+is active for the next input event, that activates the keyboard menu
+feature.
+
+@menu
+* Defining Menus:: How to make a keymap that defines a menu.
+* Mouse Menus:: How users actuate the menu with the mouse.
+* Keyboard Menus:: How users actuate the menu 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
+
+@node Defining Menus
+@subsection Defining Menus
+@cindex defining menus
+@cindex menu prompt string
+@cindex prompt string (of menu)
+
+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.
+(@xref{Format of Keymaps}.) The string should describe the purpose of
+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}). If you do not want the keymap to operate as
+a menu, don't specify a prompt string for it.
+
+@defun keymap-prompt keymap
+This function returns the overall prompt string of @var{keymap},
+or @code{nil} if it has none.
+@end defun
+
+The menu's items are the bindings in the keymap. Each binding
+associates an event type to a definition, but the event types have no
+significance for the menu appearance. (Usually we use pseudo-events,
+symbols that the keyboard cannot generate, as the event types for menu
+item bindings.) The menu is generated entirely from the bindings that
+correspond in the keymap to these events.
+
+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
+should define the menu items starting at the bottom of the menu and
+moving to the top, if you care about the order. When you add an item to
+an existing menu, you can specify its position in the menu using
+@code{define-key-after} (@pxref{Modifying Menus}).
+
+@menu
+* 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
+@subsubsection Simple Menu Items
+
+ The simpler (and original) way to define a menu item is to bind some
+event type (it doesn't matter what event type) to a binding like this:
+
+@example
+(@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. 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.}
+
+ You can also supply a second string, called the help string, as follows:
+
+@example
+(@var{item-string} @var{help} . @var{real-binding})
+@end example
+
+@noindent
+@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,
+@code{lookup-key} returns just @var{real-binding}, and only
+@var{real-binding} is used for executing the key.
+
+ If @var{real-binding} is @code{nil}, then @var{item-string} appears in
+the menu but cannot be selected.
+
+ If @var{real-binding} is a symbol and has a non-@code{nil}
+@code{menu-enable} property, that property is an expression that
+controls whether the menu item is enabled. Every time the keymap is
+used to display a menu, Emacs evaluates the expression, and it enables
+the menu item only if the expression's value is non-@code{nil}. When a
+menu item is disabled, it is displayed in a ``fuzzy'' fashion, and
+cannot be selected.
+
+ The menu bar does not recalculate which items are enabled every time you
+look at a menu. This is because the X toolkit requires the whole tree
+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
+
+ An extended-format menu item is a more flexible and also cleaner
+alternative to the simple format. You define an event type with a
+binding that's a list starting with the symbol @code{menu-item}.
+For a non-selectable string, the binding looks like this:
+
+@example
+(menu-item @var{item-name})
+@end example
+
+@noindent
+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
+binding looks like this:
+
+@example
+(menu-item @var{item-name} @var{real-binding}
+ . @var{item-property-list})
+@end example
+
+@noindent
+Here, @var{item-name} is an expression which evaluates to the menu item
+string. Thus, the string need not be a constant. The third element,
+@var{real-binding}, is the command to execute. The tail of the list,
+@var{item-property-list}, has the form of a property list which contains
+other information. Here is a table of the properties that are supported:
+
+@table @code
+@item :enable @var{form}
+The result of evaluating @var{form} determines whether the item is
+enabled (non-@code{nil} means yes). If the item is not enabled,
+you can't really click on it.
+
+@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}, 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: 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;
+when it is called, its argument will be @var{real-binding}. The
+function should return the binding to use instead.
+
+Emacs can call this function at any time that it does redisplay or
+operates on menu data structures, so you should write it so it can
+safely be called at any time.
+@end table
+
+ When an equivalent key binding is cached, the binding looks like this.
+
+@example
+(menu-item @var{item-name} @var{real-binding} (@var{key-binding-data})
+ . @var{item-property-list})
+@end example
+
+@node Menu Separators
+@subsubsection Menu Separators
+@cindex menu separators
+
+ 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.)
+
+ 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
+
+ The usual way to make a menu keymap produce a menu is to make it the
+definition of a prefix key. (A Lisp program can explicitly pop up a
+menu and receive the user's choice---see @ref{Pop-Up Menus}.)
+
+ If the prefix key ends with a mouse event, Emacs handles the menu keymap
+by popping up a visible menu, so that the user can select a choice with
+the mouse. When the user clicks on a menu item, the event generated is
+whatever character or symbol has the binding that brought about that
+menu item. (A menu item may generate a series of events if the menu has
+multiple levels or comes from the menu bar.)
+
+ 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.
+
+@node Keyboard Menus
+@subsection Menus and the Keyboard
+
+ When a prefix key ending with a keyboard event (a character or
+function key) has a definition that is a menu keymap, the keymap
+operates as a keyboard menu; the user specifies the next event by
+choosing a menu item with the keyboard.
+
+ Emacs displays the keyboard menu with the map's overall prompt
+string, followed by the alternatives (the item strings of the map's
+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 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
+for @key{SPC}.
+@end defvar
+
+@node Menu Example
+@subsection Menu Example
+@cindex menu definition example
+
+ Here is a complete example of defining a menu keymap. It is the
+definition of the @samp{Replace} submenu in the @samp{Edit} menu in
+the menu bar, and it uses the extended menu item format
+(@pxref{Extended Menu Items}). First we create the keymap, and give
+it a name:
+
+@smallexample
+(defvar menu-bar-replace-menu (make-sparse-keymap "Replace"))
+@end smallexample
+
+@noindent
+Next we define the menu items:
+
+@smallexample
+(define-key menu-bar-replace-menu [tags-repl-continue]
+ '(menu-item "Continue Replace" tags-loop-continue
+ :help "Continue last tags replace operation"))
+(define-key menu-bar-replace-menu [tags-repl]
+ '(menu-item "Replace in tagged files" tags-query-replace
+ :help "Interactively replace a regexp in all tagged files"))
+(define-key menu-bar-replace-menu [separator-replace-tags]
+ '(menu-item "--"))
+;; @r{@dots{}}
+@end smallexample
+
+@noindent
+Note the symbols which the bindings are ``made for''; these appear
+inside square brackets, in the key sequence being defined. In some
+cases, this symbol is the same as the command name; sometimes it is
+different. These symbols are treated as ``function keys,'' but they are
+not real function keys on the keyboard. They do not affect the
+functioning of the menu itself, but they are ``echoed'' in the echo area
+when the user selects from the menu, and they appear in the output of
+@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-replace-tags}. If one menu has two separators, they
+must have two different key symbols.
+
+ Here is how we make this menu appear as an item in the parent menu:
+
+@example
+(define-key menu-bar-edit-menu [replace]
+ (list 'menu-item "Replace" menu-bar-replace-menu))
+@end example
+
+@noindent
+Note that this incorporates the submenu keymap, which is the value of
+the variable @code{menu-bar-replace-menu}, rather than the symbol
+@code{menu-bar-replace-menu} itself. Using that symbol in the parent
+menu item would be meaningless because @code{menu-bar-replace-menu} is
+not a command.
+
+ If you wanted to attach the same replace menu to a mouse click, you
+can do it this way:
+
+@example
+(define-key global-map [C-S-down-mouse-1]
+ menu-bar-replace-menu)
+@end example
+
+@node Menu Bar
+@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. The items of the menu bar are the 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
+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
+subcommands, and the minor mode subcommands.
+
+ The variable @code{overriding-local-map} is normally ignored when
+determining the menu bar contents. That is, the menu bar is computed
+from the keymaps that would be active if @code{overriding-local-map}
+were @code{nil}. @xref{Active Keymaps}.
+
+ In order for a frame to display a menu bar, its @code{menu-bar-lines}
+parameter must be greater than zero. Emacs uses just one line for the
+menu bar itself; if you specify more than one line, the other lines
+serve to separate the menu bar from the windows in the frame. We
+recommend 1 or 2 as the value of @code{menu-bar-lines}. @xref{Layout
+Parameters}.
+
+ 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.}
+(define-key global-map [menu-bar words]
+ (cons "Words" (make-sparse-keymap "Words")))
+@end group
+
+@group
+;; @r{Define specific subcommands in this menu.}
+(define-key global-map
+ [menu-bar words forward]
+ '("Forward word" . forward-word))
+@end group
+@group
+(define-key global-map
+ [menu-bar words backward]
+ '("Backward word" . backward-word))
+@end group
+@end example
+
+ A local keymap can cancel a menu bar item made by the global keymap by
+rebinding the same fake function key with @code{undefined} as the
+binding. For example, this is how Dired suppresses the @samp{Edit} menu
+bar item:
+
+@example
+(define-key dired-mode-map [menu-bar edit] 'undefined)
+@end example
+
+@noindent
+@code{edit} is the fake function key used by the global map for the
+@samp{Edit} menu bar item. The main reason to suppress a global
+menu bar item is to regain space for mode-specific items.
+
+@defvar menu-bar-final-items
+Normally the menu bar shows global items followed by items defined by the
+local maps.
+
+This variable holds a list of fake function keys for items to display at
+the end of the menu bar rather than in normal sequence. The default
+value is @code{(help-menu)}; thus, the @samp{Help} menu item normally appears
+at the end of the menu bar, following local menu items.
+@end defvar
+
+@defvar menu-bar-update-hook
+This normal hook is run by redisplay to update the menu bar contents,
+before redisplaying the menu bar. You can use it to update submenus
+whose contents should vary. Since this hook is run frequently, we
+advise you to ensure that the functions it calls do not take much time
+in the usual case.
+@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.
+
+ 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
+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
+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
+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
+
+@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
+
+@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
+
+@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
+
+@defvar tool-bar-button-relief
+This variable specifies the shadow width for tool bar items.
+The value is an integer, a number of pixels. The default is 1.
+@end defvar
+
+@defvar tool-bar-border
+This variable specifies the height of the border drawn below the tool
+bar area. An integer value specifies height as a number of pixels.
+If the value is one of @code{internal-border-width} (the default) or
+@code{border-width}, the tool bar border height corresponds to the
+corresponding frame parameter.
+@end defvar
+
+ You can define a special meaning for clicking on a tool bar item with
+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
+
+ When you insert a new item in an existing menu, you probably want to
+put it in a particular place among the menu's existing items. If you
+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 &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} 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)
+@end example
+
+@noindent
+makes a binding for the fake function key @key{DRINK} and puts it
+right after the binding for @key{EAT}.
+
+Here is how to insert an item called @samp{Work} in the @samp{Signals}
+menu of Shell mode, after the item @code{break}:
+
+@example
+(define-key-after
+ (lookup-key shell-mode-map [menu-bar signals])
+ [work] '("Work" . work-command) 'break)
+@end example
+@end defun
+
+@ignore
+ arch-tag: cfb87287-9364-4e46-9e93-6c2f7f6ae794
+@end ignore