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