2 @c This is part of the XEmacs Lisp Reference Manual.
3 @c Copyright (C) 1995, 1996 Ben Wing.
4 @c See the file lispref.texi for copying conditions.
5 @setfilename ../../info/toolbar.info
6 @node Toolbar, Scrollbars, Dialog Boxes, top
11 * Toolbar Intro:: An introduction.
12 * Toolbar Descriptor Format:: How to create a toolbar.
13 * Specifying the Toolbar:: Setting a toolbar's contents.
14 * Other Toolbar Variables:: Controlling the size of toolbars.
18 @section Toolbar Intro
20 A @dfn{toolbar} is a bar of icons displayed along one edge of a frame.
21 You can view a toolbar as a series of menu shortcuts -- the most
22 common menu options can be accessed with a single click rather than
23 a series of clicks and/or drags to select the option from a menu.
24 Consistent with this, a help string (called the @dfn{help-echo})
25 describing what an icon in the toolbar (called a @dfn{toolbar button})
26 does, is displayed in the minibuffer when the mouse is over the
29 In XEmacs, a toolbar can be displayed along any of the four edges
30 of the frame, and two or more different edges can be displaying
31 toolbars simultaneously. The contents, thickness, and visibility of
32 the toolbars can be controlled separately, and the values can
33 be per-buffer, per-frame, etc., using specifiers (@pxref{Specifiers}).
35 Normally, there is one toolbar displayed in a frame. Usually, this is
36 the standard toolbar, but certain modes will override this and
37 substitute their own toolbar. In some cases (e.g. the VM package), a
38 package will supply its own toolbar along a different edge from the
39 standard toolbar, so that both can be visible at once. This standard
40 toolbar is usually positioned along the top of the frame, but this can
41 be changed using @code{set-default-toolbar-position}.
43 Note that, for each of the toolbar properties (contents, thickness,
44 and visibility), there is a separate specifier for each of the four
45 toolbar positions (top, bottom, left, and right), and an additional
46 specifier for the ``default'' toolbar, i.e. the toolbar whose
47 position is controlled by @code{set-default-toolbar-position}. The
48 way this works is that @code{set-default-toolbar-position} arranges
49 things so that the appropriate position-specific specifiers for the
50 default position inherit from the corresponding default specifiers.
51 That way, if the position-specific specifier does not give a value
52 (which it usually doesn't), then the value from the default
53 specifier applies. If you want to control the default toolbar, you
54 just change the default specifiers, and everything works. A package
55 such as VM that wants to put its own toolbar in a different location
56 from the default just sets the position-specific specifiers, and if
57 the user sets the default toolbar to the same position, it will just
60 @node Toolbar Descriptor Format
61 @section Toolbar Descriptor Format
63 The contents of a toolbar are specified using a @dfn{toolbar descriptor}.
64 The format of a toolbar descriptor is a list of @dfn{toolbar button
65 descriptors}. Each toolbar button descriptor is a vector in one of the
70 @code{[@var{glyph-list} @var{function} @var{enabled-p} @var{help}]}
72 @code{[:style @var{2d-or-3d}]}
74 @code{[:style @var{2d-or-3d} :size @var{width-or-height}]}
76 @code{[:size @var{width-or-height} :style @var{2d-or-3d}]}
79 Optionally, one of the toolbar button descriptors may be @code{nil}
80 instead of a vector; this signifies the division between the toolbar
81 buttons that are to be displayed flush-left, and the buttons to be
82 displayed flush-right.
84 The first vector format above specifies a normal toolbar button;
85 the others specify blank areas in the toolbar.
87 For the first vector format:
91 @var{glyph-list} should be a list of one to six glyphs (as created by
92 @code{make-glyph}) or a symbol whose value is such a list. The first
93 glyph, which must be provided, is the glyph used to display the toolbar
94 button when it is in the ``up'' (not pressed) state. The optional
95 second glyph is for displaying the button when it is in the ``down''
96 (pressed) state. The optional third glyph is for when the button is
97 disabled. The last three glyphs are for displaying the button in the
98 ``up'', ``down'', and ``disabled'' states, respectively, but are used
99 when the user has called for captioned toolbar buttons (using
100 @code{toolbar-buttons-captioned-p}). The function
101 @code{toolbar-make-button-list} is useful in creating these glyph lists.
104 Even if you do not provide separate down-state and disabled-state
105 glyphs, the user will still get visual feedback to indicate which
106 state the button is in. Buttons in the up-state are displayed
107 with a shadowed border that gives a raised appearance to the
108 button. Buttons in the down-state are displayed with shadows that
109 give a recessed appearance. Buttons in the disabled state are
110 displayed with no shadows, giving a 2-d effect.
113 If some of the toolbar glyphs are not provided, they inherit as follows:
118 DISABLED: disabled -> up
120 CAP-DOWN: cap-down -> cap-up -> down -> up
121 CAP-DISABLED: cap-disabled -> cap-up -> disabled -> up
125 The second element @var{function} is a function to be called when the
126 toolbar button is activated (i.e. when the mouse is released over the
127 toolbar button, if the press occurred in the toolbar). It can be any
128 form accepted by @code{call-interactively}, since this is how it is
132 The third element @var{enabled-p} specifies whether the toolbar button
133 is enabled (disabled buttons do nothing when they are activated, and are
134 displayed differently; see above). It should be either a boolean or a
135 form that evaluates to a boolean.
138 The fourth element @var{help}, if non-@code{nil}, should be a string.
139 This string is displayed in the echo area when the mouse passes over the
143 For the other vector formats (specifying blank areas of the toolbar):
147 @var{2d-or-3d} should be one of the symbols @code{2d} or @code{3d},
148 indicating whether the area is displayed with shadows (giving it a
149 raised, 3-d appearance) or without shadows (giving it a flat
153 @var{width-or-height} specifies the length, in pixels, of the blank
154 area. If omitted, it defaults to a device-specific value (8 pixels for
158 @defun toolbar-make-button-list up &optional down disabled cap-up cap-down cap-disabled
159 This function calls @code{make-glyph} on each arg and returns a list of
160 the results. This is useful for setting the first argument of a toolbar
161 button descriptor (typically, the result of this function is assigned
162 to a symbol, which is specified as the first argument of the toolbar
166 @defun check-toolbar-button-syntax button &optional noerror
167 Verify the syntax of entry @var{button} in a toolbar description list.
168 If you want to verify the syntax of a toolbar description list as a
169 whole, use @code{check-valid-instantiator} with a specifier type of
173 @node Specifying the Toolbar
174 @section Specifying the Toolbar
176 In order to specify the contents of a toolbar, set one of the specifier
177 variables @code{default-toolbar}, @code{top-toolbar},
178 @code{bottom-toolbar}, @code{left-toolbar}, or @code{right-toolbar}.
179 These are specifiers, which means you set them with @code{set-specifier}
180 and query them with @code{specifier-specs} or @code{specifier-instance}.
181 You will get an error if you try to set them using @code{setq}. The
182 valid instantiators for these specifiers are toolbar descriptors, as
183 described above. @xref{Specifiers}, for more information.
185 Most of the time, you will set @code{default-toolbar}, which allows
186 the user to choose where the toolbar should go.
188 @defvr Specifier default-toolbar
189 The position of this toolbar is specified in the function
190 @code{default-toolbar-position}. If the corresponding
191 position-specific toolbar (e.g. @code{top-toolbar} if
192 @code{default-toolbar-position} is @code{top}) does not specify a
193 toolbar in a particular domain, then the value of @code{default-toolbar}
194 in that domain, of any, will be used instead.
197 Note that the toolbar at any particular position will not be displayed
198 unless its thickness (width or height, depending on orientation) is
199 non-zero and its visibility status is true. The thickness is controlled
200 by the specifiers @code{top-toolbar-height},
201 @code{bottom-toolbar-height}, @code{left-toolbar-width}, and
202 @code{right-toolbar-width}, and the visibility status is controlled by
203 the specifiers @code{top-toolbar-visible-p},
204 @code{bottom-toolbar-visible-p}, @code{left-toolbar-visible-p}, and
205 @code{right-toolbar-visible-p} (@pxref{Other Toolbar Variables}).
207 @defun set-default-toolbar-position position
208 This function sets the position that the @code{default-toolbar} will be
209 displayed at. Valid positions are the symbols @code{top},
210 @code{bottom}, @code{left} and @code{right}. What this actually does is
211 set the fallback specifier for the position-specific specifier
212 corresponding to the given position to @code{default-toolbar}, and set
213 the fallbacks for the other position-specific specifiers to @code{nil}.
214 It also does the same thing for the position-specific thickness and
215 visibility specifiers, which inherit from one of
216 @code{default-toolbar-height} or @code{default-toolbar-width}, and from
217 @code{default-toolbar-visible-p}, respectively (@pxref{Other Toolbar
221 @defun default-toolbar-position
222 This function returns the position that the @code{default-toolbar} will
226 You can also explicitly set a toolbar at a particular position. When
227 redisplay determines what to display at a particular position in a
228 particular domain (i.e. window), it first consults the position-specific
229 toolbar. If that does not yield a toolbar descriptor, the
230 @code{default-toolbar} is consulted if @code{default-toolbar-position}
231 indicates this position.
233 @defvr Specifier top-toolbar
234 Specifier for the toolbar at the top of the frame.
237 @defvr Specifier bottom-toolbar
238 Specifier for the toolbar at the bottom of the frame.
241 @defvr Specifier left-toolbar
242 Specifier for the toolbar at the left edge of the frame.
245 @defvr Specifier right-toolbar
246 Specifier for the toolbar at the right edge of the frame.
249 @defun toolbar-specifier-p object
250 This function returns non-nil if @var{object} is a toolbar specifier.
251 Toolbar specifiers are the actual objects contained in the toolbar
252 variables described above, and their valid instantiators are
253 toolbar descriptors (@pxref{Toolbar Descriptor Format}).
256 @node Other Toolbar Variables
257 @section Other Toolbar Variables
259 The variables to control the toolbar thickness, visibility status, and
260 captioned status are all specifiers. @xref{Specifiers}.
262 @defvr Specifier default-toolbar-height
263 This specifies the height of the default toolbar, if it's oriented
264 horizontally. The position of the default toolbar is specified by the
265 function @code{set-default-toolbar-position}. If the corresponding
266 position-specific toolbar thickness specifier
267 (e.g. @code{top-toolbar-height} if @code{default-toolbar-position} is
268 @code{top}) does not specify a thickness in a particular domain (a
269 window or a frame), then the value of @code{default-toolbar-height} or
270 @code{default-toolbar-width} (depending on the toolbar orientation) in
271 that domain, if any, will be used instead.
274 @defvr Specifier default-toolbar-width
275 This specifies the width of the default toolbar, if it's oriented
276 vertically. This behaves like @code{default-toolbar-height}.
279 Note that @code{default-toolbar-height} is only used when
280 @code{default-toolbar-position} is @code{top} or @code{bottom}, and
281 @code{default-toolbar-width} is only used when
282 @code{default-toolbar-position} is @code{left} or @code{right}.
284 @defvr Specifier top-toolbar-height
285 This specifies the height of the top toolbar.
288 @defvr Specifier bottom-toolbar-height
289 This specifies the height of the bottom toolbar.
292 @defvr Specifier left-toolbar-width
293 This specifies the width of the left toolbar.
296 @defvr Specifier right-toolbar-width
297 This specifies the width of the right toolbar.
300 Note that all of the position-specific toolbar thickness specifiers
301 have a fallback value of zero when they do not correspond to the
302 default toolbar. Therefore, you will have to set a non-zero thickness
303 value if you want a position-specific toolbar to be displayed.
305 @defvr Specifier default-toolbar-visible-p
306 This specifies whether the default toolbar is visible. The position of
307 the default toolbar is specified by the function
308 @code{set-default-toolbar-position}. If the corresponding position-specific
309 toolbar visibility specifier (e.g. @code{top-toolbar-visible-p} if
310 @code{default-toolbar-position} is @code{top}) does not specify a
311 visible-p value in a particular domain (a window or a frame), then the
312 value of @code{default-toolbar-visible-p} in that domain, if any, will
316 @defvr Specifier top-toolbar-visible-p
317 This specifies whether the top toolbar is visible.
320 @defvr Specifier bottom-toolbar-visible-p
321 This specifies whether the bottom toolbar is visible.
324 @defvr Specifier left-toolbar-visible-p
325 This specifies whether the left toolbar is visible.
328 @defvr Specifier right-toolbar-visible-p
329 This specifies whether the right toolbar is visible.
332 @code{default-toolbar-visible-p} and all of the position-specific
333 toolbar visibility specifiers have a fallback value of true.
335 Internally, toolbar thickness and visibility specifiers are instantiated
336 in both window and frame domains, for different purposes. The value in
337 the domain of a frame's selected window specifies the actual toolbar
338 thickness or visibility that you will see in that frame. The value in
339 the domain of a frame itself specifies the toolbar thickness or
340 visibility that is used in frame geometry calculations.
342 Thus, for example, if you set the frame width to 80 characters and the
343 left toolbar width for that frame to 68 pixels, then the frame will be
344 sized to fit 80 characters plus a 68-pixel left toolbar. If you then
345 set the left toolbar width to 0 for a particular buffer (or if that
346 buffer does not specify a left toolbar or has a nil value specified for
347 @code{left-toolbar-visible-p}), you will find that, when that buffer is
348 displayed in the selected window, the window will have a width of 86 or
349 87 characters -- the frame is sized for a 68-pixel left toolbar but the
350 selected window specifies that the left toolbar is not visible, so it is
351 expanded to take up the slack.
353 @defvr Specifier toolbar-buttons-captioned-p
354 Whether toolbar buttons are captioned. This affects which glyphs from a
355 toolbar button descriptor are chosen. @xref{Toolbar Descriptor Format}.
358 You can also reset the toolbar to what it was when XEmacs started up.
360 @defvr Constant initial-toolbar-spec
361 The toolbar descriptor used to initialize @code{default-toolbar} at