Next: Modifying Menus, Previous: Menu Bar, Up: Menu Keymaps
A 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 tool-bar-lines
(X resource ‘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
auto-resize-tool-bars
is non-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 tool-bar
(much like the way the menu
bar is controlled). So you define a tool bar item using
define-key
, like this:
(define-key global-map [tool-bar key] item)
where key is a fake “function key” to distinguish this item from other items, and item is a menu item key binding (see Extended Menu Items), which says how to display this item and how it behaves.
The usual menu keymap item properties, :visible
,
:enable
, :button
, and :filter
, are useful in
tool bar bindings and have their normal meanings. The 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 :help
property specifies a “help-echo” string to display
while the mouse is on that item. This is displayed in the same way as
help-echo
text properties (see Help display).
In addition, you should use the :image
property;
this is how you specify the image to display in the tool bar:
:image
imageIf 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 mode-class
property of special
(see Major Mode Conventions). Major
modes may add items to the global bar by binding [tool-bar
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 tool-bar-map
.
By default, the global map binds
[tool-bar]
as follows:(global-set-key [tool-bar] '(menu-item "tool bar" ignore :filter (lambda (ignore) tool-bar-map)))Thus the tool bar map is derived dynamically from the value of variable
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 makingtool-bar-map
buffer-local and set to a keymap containing only the desired items. Info mode provides an example.
There are two convenience functions for defining tool bar items, as follows.
This function adds an item to the tool bar by modifying
tool-bar-map
. The image to use is defined by icon, which is the base name of an XPM, XBM or PBM image file to located byfind-image
. Given a value ‘"exit"’, say, exit.xpm, exit.pbm and exit.xbm would be searched for in that order on a color display. On a monochrome display, the search order is ‘.pbm’, ‘.xbm’ and ‘.xpm’. The binding to use is the command def, and key is the fake function key symbol in the prefix keymap. The remaining arguments props are additional property list elements to add to the menu item specification.To define items in some local map, bind
`tool-bar-map
withlet
around calls of this function:(defvar foo-tool-bar-map (let ((tool-bar-map (make-sparse-keymap))) (tool-bar-add-item ...) ... tool-bar-map))
This command is a convenience for defining tool bar items which are consistent with existing menu bar bindings. The binding of command is looked up in the menu bar in map (default
global-map
) and modified to add an image specification for icon, which is looked for in the same way as bytool-bar-add-item
. The resulting binding is then placed intool-bar-map
. map must contain an appropriate keymap bound to[menu-bar]
. The remaining arguments props are additional property list elements to add to the menu item specification.
If this variable is non-
nil
, the tool bar automatically resizes to show all defined tool bar items—but not larger than a quarter of the frame's height.
If this variable is non-
nil
, tool bar items display in raised form when the mouse moves over them.
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.
This variable specifies the shadow width for tool bar items. The value is an integer, a number of pixels. The default is 3.
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,
(define-key global-map [tool-bar shell] '(menu-item "Shell" shell :image (image :type xpm :file "shell.xpm")))
then here is how you can define clicking on the same tool bar image with the shift modifier:
(define-key global-map [tool-bar S-shell] 'some-command)
See Function Keys, for more information about how to add modifiers to function keys.