+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 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
+@tindex tool-bar-add-item-from-menu
+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
+
+@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-buttons
+@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
+
+@tindex tool-bar-button-margin
+@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
+
+@tindex tool-bar-button-relief
+@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
+
+ 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.
+