@c -*-texinfo-*-
@c This is part of the XEmacs Lisp Reference Manual.
@c Copyright (C) 1995 Ben Wing.
@c See the file lispref.texi for copying conditions.
@setfilename ../../info/toolbar.info
@node Toolbar, Scrollbars, Dialog Boxes, top
@chapter Toolbar
@cindex toolbar

@menu
* Toolbar Intro::		An introduction.
* Toolbar Descriptor Format::	How to create a toolbar.
* Specifying the Toolbar::	Setting a toolbar.
* Other Toolbar Variables::	Controlling the size of toolbars.
@end menu

@node Toolbar Intro
@section Toolbar Intro

#### Not yet written.

@node Toolbar Descriptor Format
@section Toolbar Descriptor Format

The format of a toolbar descriptor is a list of toolbar button
descriptors.  Each toolbar button descriptor is a vector in one of the
following formats:

@itemize @bullet
@item
@code{[@var{glyph-list} @var{function} @var{enabled-p} @var{help}]}
@item
@code{[:style @var{2d-or-3d}]}
@item
@code{[:style @var{2d-or-3d} :size @var{width-or-height}]}
@item
@code{[:size @var{width-or-height} :style @var{2d-or-3d}]}
@end itemize

Optionally, one of the toolbar-button-descriptors may be @code{nil}
instead of a vector; this signifies the division between the toolbar
buttons that are to be displayed flush-left, and the buttons to be
displayed flush-right.

The first vector format above specifies a normal toolbar button;
the others specify blank areas in the toolbar.

For the first vector format:

@itemize @bullet
@item
@var{glyph-list} should be a list of one to three glyphs (as created by
@code{make-glyph}) or a symbol whose value is such a list.  The first
glyph, which must be provided, is the glyph used to display the toolbar
button when it is in the ``up'' (not pressed) state.  The optional
second glyph is for displaying the button when it is in the ``down''
(pressed) state.  The optional third glyph is for when the button is
disabled.  The function @code{toolbar-make-button-list} is useful in
creating these glyph lists.

@item
Even if you do not provide separate down-state and disabled-state
glyphs, the user will still get visual feedback to indicate which
state the button is in.  Buttons in the up-state are displayed
with a shadowed border that gives a raised appearance to the
button.  Buttons in the down-state are displayed with shadows that
give a recessed appearance.  Buttons in the disabled state and
displayed with no shadows, giving a 2-d effect.

@item
The second element @var{function} is a function to be called when the
toolbar button is activated (i.e. when the mouse is released over the
toolbar button, if the press occurred in the toolbar).  It can be any
form accepted by @code{call-interactively}, since this is how it is
invoked.

@item
The third element @var{enabled-p} specifies whether the toolbar button
is enabled (disabled buttons do nothing when they are activated, and are
displayed differently; see above).  It should be either a boolean or a
form that evaluates to a boolean.

@item
The fourth element @var{help}, if non-@code{nil}, should be a string.
This string is displayed in the echo area when the mouse passes over the
toolbar button.
@end itemize

For the other vector formats (specifying blank areas of the toolbar):

@itemize @bullet
@item
@var{2d-or-3d} should be one of the symbols @code{2d} or @code{3d},
indicating whether the area is displayed with shadows (giving it a
raised, 3-d appearance) or without shadows (giving it a flat
appearance).

@item
@var{width-or-height} specifies the length, in pixels, of the blank
area.  If omitted, it defaults to a device-specific value (8 pixels for
X devices).
@end itemize

@defun toolbar-make-button-list up &optional down disabled
This function calls @code{make-glyph} on each arg and returns a list of
the results.  This is useful for setting the first argument of a toolbar
button descriptor (typically, the result of this function is assigned
to a symbol, which is specified as the first argument of the toolbar
button descriptor).
@end defun

@defun check-toolbar-button-syntax button &optional noerror
Verify the syntax of entry @var{button} in a toolbar description list.
If you want to verify the syntax of a toolbar description list as a
whole, use @code{check-valid-instantiator} with a specifier type of
@code{toolbar}.
@end defun

@node Specifying the Toolbar
@section Specifying the Toolbar

In order to specify a toolbar, set one of the variables
@code{default-toolbar}, @code{top-toolbar}, @code{bottom-toolbar},
@code{left-toolbar}, or @code{right-toolbar}.  These are specifiers,
which means you set them with @code{set-specifier} and query them with
@code{specifier-specs} or @code{specifier-instance}.  You will get an
error if you try to set them using @code{setq}.  @xref{Specifiers} for
more information.

Most of the time, you will set @code{default-toolbar}, which allows
the user to choose where the toolbar should go.

@defvar default-toolbar
The position of this toolbar is specified in the function
@code{default-toolbar-position}.  If the corresponding position-
specific toolbar (e.g. @code{top-toolbar} if
@code{default-toolbar-position} is @code{top}) does not specify a
toolbar in a particular domain, then the value of @code{default-toolbar}
in that domain, of any, will be used instead.
@end defvar

Note that the toolbar at any particular position will not be displayed
unless its thickness (width or height, depending on orientation) is
non-zero.  The thickness is controlled by the variables
@code{top-toolbar-height}, @code{bottom-toolbar-height},
@code{left-toolbar-width}, and @code{right-toolbar-width} (@pxref{Other
Toolbar Variables}).  By default, only @code{top-toolbar-height} has a
non-zero value.

@defun set-default-toolbar-position position
This function sets the position that the @code{default-toolbar} will be
displayed at.  Valid positions are the symbols @code{top},
@code{bottom}, @code{left} and @code{right}.
@end defun

@defun default-toolbar-position
This function return the position that the @code{default-toolbar} will
be displayed at.
@end defun

You can also explicitly set a toolbar at a particular position.  When
redisplay determines what to display at a particular position in a
particular domain (i.e. window), it first consults the position-specific
toolbar.  If that does not yield a toolbar descriptor, the
@code{default-toolbar} is consulted if @code{default-toolbar-position}
indicates this position.

@defvar top-toolbar
Specifier for toolbar at the top of the frame.
@end defvar

@defvar bottom-toolbar
Specifier for toolbar at the bottom of the frame.
@end defvar

@defvar left-toolbar
Specifier for toolbar at the left edge of the frame.
@end defvar

@defvar right-toolbar
Specifier for toolbar at the right edge of the frame.
@end defvar

@defun toolbar-specifier-p object
This function Returns non-nil if @var{object} is an toolbar specifier.
Toolbar specifiers are the actual objects contained in the toolbar
variables described above.
@end defun

@node Other Toolbar Variables
@section Other Toolbar Variables

The variables to control the toolbar height and width are all
specifiers.  @xref{Specifiers}.

@defvar top-toolbar-height
Height of top toolbar.
@end defvar

@defvar bottom-toolbar-height
Height of bottom toolbar.
@end defvar

@defvar left-toolbar-width
Width of left toolbar.
@end defvar

@defvar right-toolbar-width
Width of right toolbar.
@end defvar

You can also reset the toolbar to what it was when XEmacs started up.

@defvar initial-toolbar-spec
The toolbar descriptor used to initialize @code{default-toolbar} at
startup.
@end defvar
