man/lispref/toolbar.texi

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