Mercurial > hg > xemacs-beta
annotate man/lispref/toolbar.texi @ 5791:9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
pointers to all nodes. See xemacs-patches message with ID
<5315f7bf.sHpFD7lXYR05GH6E%james@xemacs.org>.
| author | Jerry James <james@xemacs.org> |
|---|---|
| date | Thu, 27 Mar 2014 08:59:03 -0600 |
| parents | 9eddcb9548e2 |
| children |
| rev | line source |
|---|---|
| 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
1135
diff
changeset
|
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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
1135
diff
changeset
|
19 @node Toolbar Intro, Creating Toolbar, Toolbar, Toolbar |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
1135
diff
changeset
|
62 @node Creating Toolbar, Toolbar Descriptor Format, Toolbar Intro, Toolbar |
| 442 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
1135
diff
changeset
|
87 @node Toolbar Descriptor Format, Specifying the Toolbar, Creating Toolbar, Toolbar |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
1135
diff
changeset
|
200 @node Specifying the Toolbar, Other Toolbar Variables, Toolbar Descriptor Format, Toolbar |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
1135
diff
changeset
|
283 @node Other Toolbar Variables, , Specifying the Toolbar, Toolbar |
| 428 | 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 |