|
428
|
1 @c -*-texinfo-*-
|
|
|
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
|
|
442
|
6 @node Toolbar, Gutter, Dialog Boxes, top
|
|
428
|
7 @chapter Toolbar
|
|
|
8 @cindex toolbar
|
|
|
9
|
|
|
10 @menu
|
|
|
11 * Toolbar Intro:: An introduction.
|
|
442
|
12 * Creating Toolbar:: How to create a toolbar.
|
|
|
13 * Toolbar Descriptor Format:: Accessing and modifying a toolbar's
|
|
|
14 properties.
|
|
428
|
15 * Specifying the Toolbar:: Setting a toolbar's contents.
|
|
|
16 * Other Toolbar Variables:: Controlling the size of toolbars.
|
|
|
17 @end menu
|
|
|
18
|
|
|
19 @node Toolbar Intro
|
|
|
20 @section Toolbar Intro
|
|
|
21
|
|
|
22 A @dfn{toolbar} is a bar of icons displayed along one edge of a frame.
|
|
440
|
23 You can view a toolbar as a series of menu shortcuts---the most
|
|
428
|
24 common menu options can be accessed with a single click rather than
|
|
|
25 a series of clicks and/or drags to select the option from a menu.
|
|
|
26 Consistent with this, a help string (called the @dfn{help-echo})
|
|
|
27 describing what an icon in the toolbar (called a @dfn{toolbar button})
|
|
|
28 does, is displayed in the minibuffer when the mouse is over the
|
|
|
29 button.
|
|
|
30
|
|
|
31 In XEmacs, a toolbar can be displayed along any of the four edges
|
|
|
32 of the frame, and two or more different edges can be displaying
|
|
|
33 toolbars simultaneously. The contents, thickness, and visibility of
|
|
|
34 the toolbars can be controlled separately, and the values can
|
|
|
35 be per-buffer, per-frame, etc., using specifiers (@pxref{Specifiers}).
|
|
|
36
|
|
|
37 Normally, there is one toolbar displayed in a frame. Usually, this is
|
|
|
38 the standard toolbar, but certain modes will override this and
|
|
|
39 substitute their own toolbar. In some cases (e.g. the VM package), a
|
|
|
40 package will supply its own toolbar along a different edge from the
|
|
|
41 standard toolbar, so that both can be visible at once. This standard
|
|
|
42 toolbar is usually positioned along the top of the frame, but this can
|
|
|
43 be changed using @code{set-default-toolbar-position}.
|
|
|
44
|
|
|
45 Note that, for each of the toolbar properties (contents, thickness,
|
|
|
46 and visibility), there is a separate specifier for each of the four
|
|
|
47 toolbar positions (top, bottom, left, and right), and an additional
|
|
|
48 specifier for the ``default'' toolbar, i.e. the toolbar whose
|
|
|
49 position is controlled by @code{set-default-toolbar-position}. The
|
|
|
50 way this works is that @code{set-default-toolbar-position} arranges
|
|
|
51 things so that the appropriate position-specific specifiers for the
|
|
|
52 default position inherit from the corresponding default specifiers.
|
|
|
53 That way, if the position-specific specifier does not give a value
|
|
|
54 (which it usually doesn't), then the value from the default
|
|
|
55 specifier applies. If you want to control the default toolbar, you
|
|
|
56 just change the default specifiers, and everything works. A package
|
|
|
57 such as VM that wants to put its own toolbar in a different location
|
|
|
58 from the default just sets the position-specific specifiers, and if
|
|
|
59 the user sets the default toolbar to the same position, it will just
|
|
|
60 not be visible.
|
|
|
61
|
|
442
|
62 @node Creating Toolbar
|
|
|
63 @section Creating Toolbar
|
|
|
64
|
|
|
65 @defun make-toolbar-specifier spec-list
|
|
|
66
|
|
|
67 Return a new @code{toolbar} specifier object with the given
|
|
|
68 specification list. @var{spec-list} can be a list of specifications
|
|
|
69 (each of which is a cons of a locale and a list of instantiators), a
|
|
|
70 single instantiator, or a list of instantiators. @xref{Specifiers}, for
|
|
|
71 more information about specifiers.
|
|
|
72
|
|
|
73 Toolbar specifiers are used to specify the format of a toolbar. The
|
|
|
74 values of the variables @code{default-toolbar}, @code{top-toolbar},
|
|
|
75 @code{left-toolbar}, @code{right-toolbar}, and @code{bottom-toolbar} are
|
|
|
76 always toolbar specifiers.
|
|
|
77
|
|
|
78 Valid toolbar instantiators are called "toolbar descriptors"
|
|
|
79 and are lists of vectors. See @code{default-toolbar} for a description
|
|
|
80 of the exact format.
|
|
|
81 @end defun
|
|
|
82
|
|
1135
|
83 The default toolbar is created in @file{toolbar-items.el}. An example
|
|
|
84 which modifies an existing toolbar (by adding a button) is presented in
|
|
|
85 the specifier section @xref{Simple Specifier Usage}.
|
|
|
86
|
|
428
|
87 @node Toolbar Descriptor Format
|
|
|
88 @section Toolbar Descriptor Format
|
|
|
89
|
|
|
90 The contents of a toolbar are specified using a @dfn{toolbar descriptor}.
|
|
|
91 The format of a toolbar descriptor is a list of @dfn{toolbar button
|
|
|
92 descriptors}. Each toolbar button descriptor is a vector in one of the
|
|
|
93 following formats:
|
|
|
94
|
|
|
95 @itemize @bullet
|
|
|
96 @item
|
|
|
97 @code{[@var{glyph-list} @var{function} @var{enabled-p} @var{help}]}
|
|
|
98 @item
|
|
|
99 @code{[:style @var{2d-or-3d}]}
|
|
|
100 @item
|
|
|
101 @code{[:style @var{2d-or-3d} :size @var{width-or-height}]}
|
|
|
102 @item
|
|
|
103 @code{[:size @var{width-or-height} :style @var{2d-or-3d}]}
|
|
|
104 @end itemize
|
|
|
105
|
|
|
106 Optionally, one of the toolbar button descriptors may be @code{nil}
|
|
|
107 instead of a vector; this signifies the division between the toolbar
|
|
|
108 buttons that are to be displayed flush-left, and the buttons to be
|
|
|
109 displayed flush-right.
|
|
|
110
|
|
|
111 The first vector format above specifies a normal toolbar button;
|
|
|
112 the others specify blank areas in the toolbar.
|
|
|
113
|
|
|
114 For the first vector format:
|
|
|
115
|
|
|
116 @itemize @bullet
|
|
|
117 @item
|
|
|
118 @var{glyph-list} should be a list of one to six glyphs (as created by
|
|
|
119 @code{make-glyph}) or a symbol whose value is such a list. The first
|
|
|
120 glyph, which must be provided, is the glyph used to display the toolbar
|
|
|
121 button when it is in the ``up'' (not pressed) state. The optional
|
|
|
122 second glyph is for displaying the button when it is in the ``down''
|
|
|
123 (pressed) state. The optional third glyph is for when the button is
|
|
|
124 disabled. The last three glyphs are for displaying the button in the
|
|
|
125 ``up'', ``down'', and ``disabled'' states, respectively, but are used
|
|
|
126 when the user has called for captioned toolbar buttons (using
|
|
|
127 @code{toolbar-buttons-captioned-p}). The function
|
|
|
128 @code{toolbar-make-button-list} is useful in creating these glyph lists.
|
|
|
129
|
|
|
130 @item
|
|
|
131 Even if you do not provide separate down-state and disabled-state
|
|
|
132 glyphs, the user will still get visual feedback to indicate which
|
|
|
133 state the button is in. Buttons in the up-state are displayed
|
|
|
134 with a shadowed border that gives a raised appearance to the
|
|
|
135 button. Buttons in the down-state are displayed with shadows that
|
|
|
136 give a recessed appearance. Buttons in the disabled state are
|
|
|
137 displayed with no shadows, giving a 2-d effect.
|
|
|
138
|
|
|
139 @item
|
|
|
140 If some of the toolbar glyphs are not provided, they inherit as follows:
|
|
|
141
|
|
|
142 @example
|
|
|
143 UP: up
|
|
|
144 DOWN: down -> up
|
|
|
145 DISABLED: disabled -> up
|
|
|
146 CAP-UP: cap-up -> up
|
|
|
147 CAP-DOWN: cap-down -> cap-up -> down -> up
|
|
|
148 CAP-DISABLED: cap-disabled -> cap-up -> disabled -> up
|
|
|
149 @end example
|
|
|
150
|
|
|
151 @item
|
|
|
152 The second element @var{function} is a function to be called when the
|
|
|
153 toolbar button is activated (i.e. when the mouse is released over the
|
|
|
154 toolbar button, if the press occurred in the toolbar). It can be any
|
|
|
155 form accepted by @code{call-interactively}, since this is how it is
|
|
|
156 invoked.
|
|
|
157
|
|
|
158 @item
|
|
|
159 The third element @var{enabled-p} specifies whether the toolbar button
|
|
|
160 is enabled (disabled buttons do nothing when they are activated, and are
|
|
|
161 displayed differently; see above). It should be either a boolean or a
|
|
|
162 form that evaluates to a boolean.
|
|
|
163
|
|
|
164 @item
|
|
|
165 The fourth element @var{help}, if non-@code{nil}, should be a string.
|
|
|
166 This string is displayed in the echo area when the mouse passes over the
|
|
|
167 toolbar button.
|
|
|
168 @end itemize
|
|
|
169
|
|
|
170 For the other vector formats (specifying blank areas of the toolbar):
|
|
|
171
|
|
|
172 @itemize @bullet
|
|
|
173 @item
|
|
|
174 @var{2d-or-3d} should be one of the symbols @code{2d} or @code{3d},
|
|
|
175 indicating whether the area is displayed with shadows (giving it a
|
|
|
176 raised, 3-d appearance) or without shadows (giving it a flat
|
|
|
177 appearance).
|
|
|
178
|
|
|
179 @item
|
|
|
180 @var{width-or-height} specifies the length, in pixels, of the blank
|
|
|
181 area. If omitted, it defaults to a device-specific value (8 pixels for
|
|
|
182 X devices).
|
|
|
183 @end itemize
|
|
|
184
|
|
|
185 @defun toolbar-make-button-list up &optional down disabled cap-up cap-down cap-disabled
|
|
|
186 This function calls @code{make-glyph} on each arg and returns a list of
|
|
|
187 the results. This is useful for setting the first argument of a toolbar
|
|
|
188 button descriptor (typically, the result of this function is assigned
|
|
|
189 to a symbol, which is specified as the first argument of the toolbar
|
|
|
190 button descriptor).
|
|
|
191 @end defun
|
|
|
192
|
|
|
193 @defun check-toolbar-button-syntax button &optional noerror
|
|
|
194 Verify the syntax of entry @var{button} in a toolbar description list.
|
|
|
195 If you want to verify the syntax of a toolbar description list as a
|
|
|
196 whole, use @code{check-valid-instantiator} with a specifier type of
|
|
|
197 @code{toolbar}.
|
|
|
198 @end defun
|
|
|
199
|
|
|
200 @node Specifying the Toolbar
|
|
|
201 @section Specifying the Toolbar
|
|
|
202
|
|
|
203 In order to specify the contents of a toolbar, set one of the specifier
|
|
|
204 variables @code{default-toolbar}, @code{top-toolbar},
|
|
|
205 @code{bottom-toolbar}, @code{left-toolbar}, or @code{right-toolbar}.
|
|
|
206 These are specifiers, which means you set them with @code{set-specifier}
|
|
|
207 and query them with @code{specifier-specs} or @code{specifier-instance}.
|
|
|
208 You will get an error if you try to set them using @code{setq}. The
|
|
|
209 valid instantiators for these specifiers are toolbar descriptors, as
|
|
|
210 described above. @xref{Specifiers}, for more information.
|
|
|
211
|
|
|
212 Most of the time, you will set @code{default-toolbar}, which allows
|
|
|
213 the user to choose where the toolbar should go.
|
|
|
214
|
|
|
215 @defvr Specifier default-toolbar
|
|
|
216 The position of this toolbar is specified in the function
|
|
444
|
217 @code{default-toolbar-position}. If the corresponding
|
|
428
|
218 position-specific toolbar (e.g. @code{top-toolbar} if
|
|
|
219 @code{default-toolbar-position} is @code{top}) does not specify a
|
|
|
220 toolbar in a particular domain, then the value of @code{default-toolbar}
|
|
|
221 in that domain, of any, will be used instead.
|
|
|
222 @end defvr
|
|
|
223
|
|
|
224 Note that the toolbar at any particular position will not be displayed
|
|
|
225 unless its thickness (width or height, depending on orientation) is
|
|
|
226 non-zero and its visibility status is true. The thickness is controlled
|
|
|
227 by the specifiers @code{top-toolbar-height},
|
|
|
228 @code{bottom-toolbar-height}, @code{left-toolbar-width}, and
|
|
|
229 @code{right-toolbar-width}, and the visibility status is controlled by
|
|
|
230 the specifiers @code{top-toolbar-visible-p},
|
|
|
231 @code{bottom-toolbar-visible-p}, @code{left-toolbar-visible-p}, and
|
|
|
232 @code{right-toolbar-visible-p} (@pxref{Other Toolbar Variables}).
|
|
|
233
|
|
|
234 @defun set-default-toolbar-position position
|
|
|
235 This function sets the position that the @code{default-toolbar} will be
|
|
|
236 displayed at. Valid positions are the symbols @code{top},
|
|
|
237 @code{bottom}, @code{left} and @code{right}. What this actually does is
|
|
|
238 set the fallback specifier for the position-specific specifier
|
|
|
239 corresponding to the given position to @code{default-toolbar}, and set
|
|
|
240 the fallbacks for the other position-specific specifiers to @code{nil}.
|
|
|
241 It also does the same thing for the position-specific thickness and
|
|
|
242 visibility specifiers, which inherit from one of
|
|
|
243 @code{default-toolbar-height} or @code{default-toolbar-width}, and from
|
|
|
244 @code{default-toolbar-visible-p}, respectively (@pxref{Other Toolbar
|
|
|
245 Variables}).
|
|
|
246 @end defun
|
|
|
247
|
|
|
248 @defun default-toolbar-position
|
|
|
249 This function returns the position that the @code{default-toolbar} will
|
|
|
250 be displayed at.
|
|
|
251 @end defun
|
|
|
252
|
|
|
253 You can also explicitly set a toolbar at a particular position. When
|
|
|
254 redisplay determines what to display at a particular position in a
|
|
|
255 particular domain (i.e. window), it first consults the position-specific
|
|
|
256 toolbar. If that does not yield a toolbar descriptor, the
|
|
|
257 @code{default-toolbar} is consulted if @code{default-toolbar-position}
|
|
|
258 indicates this position.
|
|
|
259
|
|
|
260 @defvr Specifier top-toolbar
|
|
|
261 Specifier for the toolbar at the top of the frame.
|
|
|
262 @end defvr
|
|
|
263
|
|
|
264 @defvr Specifier bottom-toolbar
|
|
|
265 Specifier for the toolbar at the bottom of the frame.
|
|
|
266 @end defvr
|
|
|
267
|
|
|
268 @defvr Specifier left-toolbar
|
|
|
269 Specifier for the toolbar at the left edge of the frame.
|
|
|
270 @end defvr
|
|
|
271
|
|
|
272 @defvr Specifier right-toolbar
|
|
|
273 Specifier for the toolbar at the right edge of the frame.
|
|
|
274 @end defvr
|
|
|
275
|
|
|
276 @defun toolbar-specifier-p object
|
|
444
|
277 This function returns non-@code{nil} if @var{object} is a toolbar specifier.
|
|
428
|
278 Toolbar specifiers are the actual objects contained in the toolbar
|
|
|
279 variables described above, and their valid instantiators are
|
|
|
280 toolbar descriptors (@pxref{Toolbar Descriptor Format}).
|
|
|
281 @end defun
|
|
|
282
|
|
|
283 @node Other Toolbar Variables
|
|
|
284 @section Other Toolbar Variables
|
|
|
285
|
|
|
286 The variables to control the toolbar thickness, visibility status, and
|
|
|
287 captioned status are all specifiers. @xref{Specifiers}.
|
|
|
288
|
|
|
289 @defvr Specifier default-toolbar-height
|
|
|
290 This specifies the height of the default toolbar, if it's oriented
|
|
|
291 horizontally. The position of the default toolbar is specified by the
|
|
|
292 function @code{set-default-toolbar-position}. If the corresponding
|
|
|
293 position-specific toolbar thickness specifier
|
|
|
294 (e.g. @code{top-toolbar-height} if @code{default-toolbar-position} is
|
|
|
295 @code{top}) does not specify a thickness in a particular domain (a
|
|
|
296 window or a frame), then the value of @code{default-toolbar-height} or
|
|
|
297 @code{default-toolbar-width} (depending on the toolbar orientation) in
|
|
|
298 that domain, if any, will be used instead.
|
|
|
299 @end defvr
|
|
|
300
|
|
|
301 @defvr Specifier default-toolbar-width
|
|
|
302 This specifies the width of the default toolbar, if it's oriented
|
|
|
303 vertically. This behaves like @code{default-toolbar-height}.
|
|
|
304 @end defvr
|
|
|
305
|
|
|
306 Note that @code{default-toolbar-height} is only used when
|
|
|
307 @code{default-toolbar-position} is @code{top} or @code{bottom}, and
|
|
|
308 @code{default-toolbar-width} is only used when
|
|
|
309 @code{default-toolbar-position} is @code{left} or @code{right}.
|
|
|
310
|
|
|
311 @defvr Specifier top-toolbar-height
|
|
|
312 This specifies the height of the top toolbar.
|
|
|
313 @end defvr
|
|
|
314
|
|
|
315 @defvr Specifier bottom-toolbar-height
|
|
|
316 This specifies the height of the bottom toolbar.
|
|
|
317 @end defvr
|
|
|
318
|
|
|
319 @defvr Specifier left-toolbar-width
|
|
|
320 This specifies the width of the left toolbar.
|
|
|
321 @end defvr
|
|
|
322
|
|
|
323 @defvr Specifier right-toolbar-width
|
|
|
324 This specifies the width of the right toolbar.
|
|
|
325 @end defvr
|
|
|
326
|
|
|
327 Note that all of the position-specific toolbar thickness specifiers
|
|
|
328 have a fallback value of zero when they do not correspond to the
|
|
|
329 default toolbar. Therefore, you will have to set a non-zero thickness
|
|
|
330 value if you want a position-specific toolbar to be displayed.
|
|
|
331
|
|
|
332 @defvr Specifier default-toolbar-visible-p
|
|
|
333 This specifies whether the default toolbar is visible. The position of
|
|
|
334 the default toolbar is specified by the function
|
|
|
335 @code{set-default-toolbar-position}. If the corresponding position-specific
|
|
|
336 toolbar visibility specifier (e.g. @code{top-toolbar-visible-p} if
|
|
|
337 @code{default-toolbar-position} is @code{top}) does not specify a
|
|
|
338 visible-p value in a particular domain (a window or a frame), then the
|
|
|
339 value of @code{default-toolbar-visible-p} in that domain, if any, will
|
|
|
340 be used instead.
|
|
|
341 @end defvr
|
|
|
342
|
|
|
343 @defvr Specifier top-toolbar-visible-p
|
|
|
344 This specifies whether the top toolbar is visible.
|
|
|
345 @end defvr
|
|
|
346
|
|
|
347 @defvr Specifier bottom-toolbar-visible-p
|
|
|
348 This specifies whether the bottom toolbar is visible.
|
|
|
349 @end defvr
|
|
|
350
|
|
|
351 @defvr Specifier left-toolbar-visible-p
|
|
|
352 This specifies whether the left toolbar is visible.
|
|
|
353 @end defvr
|
|
|
354
|
|
|
355 @defvr Specifier right-toolbar-visible-p
|
|
|
356 This specifies whether the right toolbar is visible.
|
|
|
357 @end defvr
|
|
|
358
|
|
|
359 @code{default-toolbar-visible-p} and all of the position-specific
|
|
|
360 toolbar visibility specifiers have a fallback value of true.
|
|
|
361
|
|
|
362 Internally, toolbar thickness and visibility specifiers are instantiated
|
|
|
363 in both window and frame domains, for different purposes. The value in
|
|
|
364 the domain of a frame's selected window specifies the actual toolbar
|
|
|
365 thickness or visibility that you will see in that frame. The value in
|
|
|
366 the domain of a frame itself specifies the toolbar thickness or
|
|
|
367 visibility that is used in frame geometry calculations.
|
|
|
368
|
|
|
369 Thus, for example, if you set the frame width to 80 characters and the
|
|
|
370 left toolbar width for that frame to 68 pixels, then the frame will be
|
|
|
371 sized to fit 80 characters plus a 68-pixel left toolbar. If you then
|
|
|
372 set the left toolbar width to 0 for a particular buffer (or if that
|
|
444
|
373 buffer does not specify a left toolbar or has a @code{nil} value specified for
|
|
428
|
374 @code{left-toolbar-visible-p}), you will find that, when that buffer is
|
|
|
375 displayed in the selected window, the window will have a width of 86 or
|
|
440
|
376 87 characters---the frame is sized for a 68-pixel left toolbar but the
|
|
428
|
377 selected window specifies that the left toolbar is not visible, so it is
|
|
|
378 expanded to take up the slack.
|
|
|
379
|
|
|
380 @defvr Specifier toolbar-buttons-captioned-p
|
|
|
381 Whether toolbar buttons are captioned. This affects which glyphs from a
|
|
|
382 toolbar button descriptor are chosen. @xref{Toolbar Descriptor Format}.
|
|
|
383 @end defvr
|
|
|
384
|
|
|
385 You can also reset the toolbar to what it was when XEmacs started up.
|
|
|
386
|
|
|
387 @defvr Constant initial-toolbar-spec
|
|
|
388 The toolbar descriptor used to initialize @code{default-toolbar} at
|
|
|
389 startup.
|
|
|
390 @end defvr
|
