Mercurial > hg > xemacs-beta

comparison man/lispref/toolbar.texi @ 0:376386a54a3c r19-14

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r19-14
author cvs
date Mon, 13 Aug 2007 08:45:50 +0200
parents
children 54f7aa390f4f
comparison
equal deleted inserted replaced
-1:000000000000 0:376386a54a3c
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
6 @node Toolbar, Scrollbars, Dialog Boxes, top
7 @chapter Toolbar
8 @cindex toolbar
9
10 @menu
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.
15 @end menu
16
17 @node Toolbar Intro
18 @section Toolbar Intro
19
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
27 button.
28
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}).
34
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}.
42
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
58 not be visible.
59
60 @node Toolbar Descriptor Format
61 @section Toolbar Descriptor Format
62
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
66 following formats:
67
68 @itemize @bullet
69 @item
70 @code{[@var{glyph-list} @var{function} @var{enabled-p} @var{help}]}
71 @item
72 @code{[:style @var{2d-or-3d}]}
73 @item
74 @code{[:style @var{2d-or-3d} :size @var{width-or-height}]}
75 @item
76 @code{[:size @var{width-or-height} :style @var{2d-or-3d}]}
77 @end itemize
78
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.
83
84 The first vector format above specifies a normal toolbar button;
85 the others specify blank areas in the toolbar.
86
87 For the first vector format:
88
89 @itemize @bullet
90 @item
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.
102
103 @item
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.
111
112 @item
113 If some of the toolbar glyphs are not provided, they inherit as follows:
114
115 @example
116 UP: up
117 DOWN: down -> up
118 DISABLED: disabled -> up
119 CAP-UP: cap-up -> up
120 CAP-DOWN: cap-down -> cap-up -> down -> up
121 CAP-DISABLED: cap-disabled -> cap-up -> disabled -> up
122 @end example
123
124 @item
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
129 invoked.
130
131 @item
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.
136
137 @item
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
140 toolbar button.
141 @end itemize
142
143 For the other vector formats (specifying blank areas of the toolbar):
144
145 @itemize @bullet
146 @item
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
150 appearance).
151
152 @item
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
155 X devices).
156 @end itemize
157
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
163 button descriptor).
164 @end defun
165
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
170 @code{toolbar}.
171 @end defun
172
173 @node Specifying the Toolbar
174 @section Specifying the Toolbar
175
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.
184
185 Most of the time, you will set @code{default-toolbar}, which allows
186 the user to choose where the toolbar should go.
187
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.
195 @end defvr
196
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}).
206
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
218 Variables}).
219 @end defun
220
221 @defun default-toolbar-position
222 This function returns the position that the @code{default-toolbar} will
223 be displayed at.
224 @end defun
225
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.
232
233 @defvr Specifier top-toolbar
234 Specifier for the toolbar at the top of the frame.
235 @end defvr
236
237 @defvr Specifier bottom-toolbar
238 Specifier for the toolbar at the bottom of the frame.
239 @end defvr
240
241 @defvr Specifier left-toolbar
242 Specifier for the toolbar at the left edge of the frame.
243 @end defvr
244
245 @defvr Specifier right-toolbar
246 Specifier for the toolbar at the right edge of the frame.
247 @end defvr
248
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}).
254 @end defun
255
256 @node Other Toolbar Variables
257 @section Other Toolbar Variables
258
259 The variables to control the toolbar thickness, visibility status, and
260 captioned status are all specifiers. @xref{Specifiers}.
261
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.
272 @end defvr
273
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}.
277 @end defvr
278
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}.
283
284 @defvr Specifier top-toolbar-height
285 This specifies the height of the top toolbar.
286 @end defvr
287
288 @defvr Specifier bottom-toolbar-height
289 This specifies the height of the bottom toolbar.
290 @end defvr
291
292 @defvr Specifier left-toolbar-width
293 This specifies the width of the left toolbar.
294 @end defvr
295
296 @defvr Specifier right-toolbar-width
297 This specifies the width of the right toolbar.
298 @end defvr
299
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.
304
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
313 be used instead.
314 @end defvr
315
316 @defvr Specifier top-toolbar-visible-p
317 This specifies whether the top toolbar is visible.
318 @end defvr
319
320 @defvr Specifier bottom-toolbar-visible-p
321 This specifies whether the bottom toolbar is visible.
322 @end defvr
323
324 @defvr Specifier left-toolbar-visible-p
325 This specifies whether the left toolbar is visible.
326 @end defvr
327
328 @defvr Specifier right-toolbar-visible-p
329 This specifies whether the right toolbar is visible.
330 @end defvr
331
332 @code{default-toolbar-visible-p} and all of the position-specific
333 toolbar visibility specifiers have a fallback value of true.
334
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.
341
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.
352
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}.
356 @end defvr
357
358 You can also reset the toolbar to what it was when XEmacs started up.
359
360 @defvr Constant initial-toolbar-spec
361 The toolbar descriptor used to initialize @code{default-toolbar} at
362 startup.
363 @end defvr