man/lispref/gutter.texi

   1 @c -*-texinfo-*-
   2 @c This is part of the XEmacs Lisp Reference Manual.
   3 @c Copyright (C) 1994, 1995 Ben Wing.
   4 @c Copyright (C) 1999 Andy Piper.
   5 @c Copyright (C) 1999 Stephen J. Turnbull.
   6 @c See the file lispref.texi for copying conditions.
   7 @setfilename ../../info/gutter.info
   8 @node Gutter, Scrollbars, Toolbar, top
   9 @chapter Gutter
  10 @cindex gutter
  11
  12   A gutter is a rectangle displayed along one edge of a frame.  It
  13 can contain arbitrary text or graphics.
  14
  15 @menu
  16 * Gutter Intro::                An introduction.
  17 * Creating Gutter::             How to create a gutter.
  18 * Gutter Descriptor Format::    Accessing and modifying a gutter's
  19                                   properties.
  20 * Specifying a Gutter::         Setting a gutter's contents.
  21 * Other Gutter Variables::      Controlling the size of gutters.
  22 * Common Gutter Widgets::       Things to put in gutters.
  23 @end menu
  24
  25 @node Gutter Intro, Creating Gutter, Gutter, Gutter
  26 @section Gutter Intro
  27
  28   A @dfn{gutter} is a rectangle displayed along one edge of a frame.  It
  29 can contain arbitrary text or graphics.  It could be considered a
  30 generalization of a toolbar, although toolbars are not currently
  31 implemented using gutters.
  32
  33   In XEmacs, a gutter can be displayed along any of the four edges
  34 of the frame, and two or more different edges can be displaying
  35 gutters simultaneously.  The contents, thickness, and visibility of
  36 the gutters can be controlled separately, and the values can
  37 be per-buffer, per-frame, etc., using specifiers (@pxref{Specifiers}).
  38
  39   Normally, there is one gutter displayed in a frame.  Usually, this is
  40 the default gutter, containing buffer tabs, but modes cab override this
  41 and substitute their own gutter.  This default gutter is usually
  42 positioned along the top of the frame, but this can be changed using
  43 @code{set-default-gutter-position}.
  44
  45   Note that, for each of the gutter properties (contents, thickness,
  46 and visibility), there is a separate specifier for each of the four
  47 gutter positions (top, bottom, left, and right), and an additional
  48 specifier for the ``default'' gutter, i.e. the gutter whose
  49 position is controlled by @code{set-default-gutter-position}.  The
  50 way this works is that @code{set-default-gutter-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 gutter, you
  56 just change the default specifiers, and everything works.  A package
  57 such as VM that wants to put its own gutter in a different location
  58 from the default just sets the position-specific specifiers, and if
  59 the user sets the default gutter to the same position, it will just
  60 not be visible.
  61
  62 @node Creating Gutter, Gutter Descriptor Format, Gutter Intro, Gutter
  63 @section Creating Gutter
  64
  65 @defun make-gutter-specifier spec-list
  66
  67 Return a new @code{gutter} specifier object with the given specification
  68 list.  @var{spec-list} can be a list of specifications (each of which is
  69 a cons of a locale and a list of instantiators), a single instantiator,
  70 or a list of instantiators.  @xref{Specifiers}, for more information
  71 about specifiers.
  72
  73 Gutter specifiers are used to specify the format of a gutter.  The
  74 values of the variables @code{default-gutter}, @code{top-gutter},
  75 @code{left-gutter}, @code{right-gutter}, and @code{bottom-gutter} are
  76 always gutter specifiers.
  77
  78 Valid gutter instantiators are called "gutter descriptors" and are
  79 either strings or property-lists of strings.  See @code{default-gutter}
  80 for a description of the exact format.
  81 @end defun
  82
  83 @defun make-gutter-size-specifier spec-list
  84
  85 Return a new @code{gutter-size} specifier object with the given spec
  86 list.  @var{spec-list} can be a list of specifications (each of which is
  87 a cons of a locale and a list of instantiators), a single instantiator,
  88 or a list of instantiators.  @xref{Specifiers}, for more information
  89 about specifiers.
  90
  91 Gutter-size specifiers are used to specify the size of a gutter.  The
  92 values of the variables @code{default-gutter-size},
  93 @code{top-gutter-size}, @code{left-gutter-size},
  94 @code{right-gutter-size}, and @code{bottom-gutter-size} are always
  95 gutter-size specifiers.
  96
  97 Valid gutter-size instantiators are either integers or the special
  98 symbol @code{autodetect}. If a gutter-size is set to @code{autodetect}
  99 them the size of the gutter will be adjusted to just accommodate the
 100 gutters contents. @code{autodetect} only works for top and bottom
 101 gutters.
 102 @end defun
 103
 104 @defun make-gutter-visible-specifier spec-list
 105
 106 Return a new @code{gutter-visible} specifier object with the given spec
 107 list.  @var{spec-list} can be a list of specifications (each of which is
 108 a cons of a locale and a list of instantiators), a single instantiator,
 109 or a list of instantiators.  @xref{Specifiers}, for more information
 110 about specifiers.
 111
 112 Gutter-visible specifiers are used to specify the visibility of a
 113 gutter.  The values of the variables @code{default-gutter-visible-p},
 114 @code{top-gutter-visible-p}, @code{left-gutter-visible-p},
 115 @code{right-gutter-visible-p}, and @code{bottom-gutter-visible-p} are
 116 always gutter-visible specifiers.
 117
 118 Valid gutter-visible instantiators are @code{t}, @code{nil} or a list of
 119 symbols.  If a gutter-visible instantiator is set to a list of symbols,
 120 and the corresponding gutter specification is a property-list strings,
 121 then elements of the gutter specification will only be visible if the
 122 corresponding symbol occurs in the gutter-visible instantiator.
 123 @end defun
 124
 125 @node Gutter Descriptor Format, Specifying a Gutter, Creating Gutter, Gutter
 126 @section Gutter Descriptor Format
 127
 128   The contents of a gutter are specified using a @dfn{gutter descriptor}.
 129 The format of a gutter descriptor is a list of @dfn{gutter button
 130 descriptors}.  Each gutter button descriptor is a vector in one of the
 131 following formats:
 132
 133 @itemize @bullet
 134 @item
 135 @code{[@var{glyph-list} @var{function} @var{enabled-p} @var{help}]}
 136 @item
 137 @code{[:style @var{2d-or-3d}]}
 138 @item
 139 @code{[:style @var{2d-or-3d} :size @var{width-or-height}]}
 140 @item
 141 @code{[:size @var{width-or-height} :style @var{2d-or-3d}]}
 142 @end itemize
 143
 144   Optionally, one of the gutter button descriptors may be @code{nil}
 145 instead of a vector; this signifies the division between the gutter
 146 buttons that are to be displayed flush-left, and the buttons to be
 147 displayed flush-right.
 148
 149   The first vector format above specifies a normal gutter button;
 150 the others specify blank areas in the gutter.
 151
 152   For the first vector format:
 153
 154 @itemize @bullet
 155 @item
 156 @var{glyph-list} should be a list of one to six glyphs (as created by
 157 @code{make-glyph}) or a symbol whose value is such a list.  The first
 158 glyph, which must be provided, is the glyph used to display the gutter
 159 button when it is in the ``up'' (not pressed) state.  The optional
 160 second glyph is for displaying the button when it is in the ``down''
 161 (pressed) state.  The optional third glyph is for when the button is
 162 disabled.  The last three glyphs are for displaying the button in the
 163 ``up'', ``down'', and ``disabled'' states, respectively, but are used
 164 when the user has called for captioned gutter buttons (using
 165 @code{gutter-buttons-captioned-p}).  The function
 166 @code{gutter-make-button-list} is useful in creating these glyph lists.
 167
 168 @item
 169 Even if you do not provide separate down-state and disabled-state
 170 glyphs, the user will still get visual feedback to indicate which
 171 state the button is in.  Buttons in the up-state are displayed
 172 with a shadowed border that gives a raised appearance to the
 173 button.  Buttons in the down-state are displayed with shadows that
 174 give a recessed appearance.  Buttons in the disabled state are
 175 displayed with no shadows, giving a 2-d effect.
 176
 177 @item
 178 If some of the gutter glyphs are not provided, they inherit as follows:
 179
 180 @example
 181      UP:                up
 182      DOWN:              down -> up
 183      DISABLED:          disabled -> up
 184      CAP-UP:            cap-up -> up
 185      CAP-DOWN:          cap-down -> cap-up -> down -> up
 186      CAP-DISABLED:      cap-disabled -> cap-up -> disabled -> up
 187 @end example
 188
 189 @item
 190 The second element @var{function} is a function to be called when the
 191 gutter button is activated (i.e. when the mouse is released over the
 192 gutter button, if the press occurred in the gutter).  It can be any
 193 form accepted by @code{call-interactively}, since this is how it is
 194 invoked.
 195
 196 @item
 197 The third element @var{enabled-p} specifies whether the gutter button
 198 is enabled (disabled buttons do nothing when they are activated, and are
 199 displayed differently; see above).  It should be either a boolean or a
 200 form that evaluates to a boolean.
 201
 202 @item
 203 The fourth element @var{help}, if non-@code{nil}, should be a string.
 204 This string is displayed in the echo area when the mouse passes over the
 205 gutter button.
 206 @end itemize
 207
 208   For the other vector formats (specifying blank areas of the gutter):
 209
 210 @itemize @bullet
 211 @item
 212 @var{2d-or-3d} should be one of the symbols @code{2d} or @code{3d},
 213 indicating whether the area is displayed with shadows (giving it a
 214 raised, 3-d appearance) or without shadows (giving it a flat
 215 appearance).
 216
 217 @item
 218 @var{width-or-height} specifies the length, in pixels, of the blank
 219 area.  If omitted, it defaults to a device-specific value (8 pixels for
 220 X devices).
 221 @end itemize
 222
 223 @defun gutter-make-button-list up &optional down disabled cap-up cap-down cap-disabled
 224 This function calls @code{make-glyph} on each arg and returns a list of
 225 the results.  This is useful for setting the first argument of a gutter
 226 button descriptor (typically, the result of this function is assigned
 227 to a symbol, which is specified as the first argument of the gutter
 228 button descriptor).
 229 @end defun
 230
 231 @defun check-gutter-button-syntax button &optional noerror
 232 Verify the syntax of entry @var{button} in a gutter description list.
 233 If you want to verify the syntax of a gutter description list as a
 234 whole, use @code{check-valid-instantiator} with a specifier type of
 235 @code{gutter}.
 236 @end defun
 237
 238 @node Specifying a Gutter, Other Gutter Variables, Gutter Descriptor Format, Gutter
 239 @section Specifying a Gutter
 240
 241   In order to specify the contents of a gutter, set one of the specifier
 242 variables @code{default-gutter}, @code{top-gutter},
 243 @code{bottom-gutter}, @code{left-gutter}, or @code{right-gutter}.
 244 These are specifiers, which means you set them with @code{set-specifier}
 245 and query them with @code{specifier-specs} or @code{specifier-instance}.
 246 You will get an error if you try to set them using @code{setq}.  The
 247 valid instantiators for these specifiers are gutter descriptors, as
 248 described above.  @xref{Specifiers}, for more information.
 249
 250   Most of the time, you will set @code{default-gutter}, which allows
 251 the user to choose where the gutter should go.
 252
 253 @defvr Specifier default-gutter
 254 The position of this gutter is specified in the function
 255 @code{default-gutter-position}.  If the corresponding
 256 position-specific gutter (e.g. @code{top-gutter} if
 257 @code{default-gutter-position} is @code{top}) does not specify a
 258 gutter in a particular domain, then the value of @code{default-gutter}
 259 in that domain, of any, will be used instead.
 260 @end defvr
 261
 262   Note that the gutter at any particular position will not be displayed
 263 unless its thickness (width or height, depending on orientation) is
 264 non-zero and its visibility status is true.  The thickness is controlled
 265 by the specifiers @code{top-gutter-height},
 266 @code{bottom-gutter-height}, @code{left-gutter-width}, and
 267 @code{right-gutter-width}, and the visibility status is controlled by
 268 the specifiers @code{top-gutter-visible-p},
 269 @code{bottom-gutter-visible-p}, @code{left-gutter-visible-p}, and
 270 @code{right-gutter-visible-p} (@pxref{Other Gutter Variables}).
 271
 272 @defun set-default-gutter-position position
 273 This function sets the position that the @code{default-gutter} will be
 274 displayed at.  Valid positions are the symbols @code{top},
 275 @code{bottom}, @code{left} and @code{right}.  What this actually does is
 276 set the fallback specifier for the position-specific specifier
 277 corresponding to the given position to @code{default-gutter}, and set
 278 the fallbacks for the other position-specific specifiers to @code{nil}.
 279 It also does the same thing for the position-specific thickness and
 280 visibility specifiers, which inherit from one of
 281 @code{default-gutter-height} or @code{default-gutter-width}, and from
 282 @code{default-gutter-visible-p}, respectively (@pxref{Other Gutter
 283 Variables}).
 284 @end defun
 285
 286 @defun default-gutter-position
 287 This function returns the position that the @code{default-gutter} will
 288 be displayed at.
 289 @end defun
 290
 291   You can also explicitly set a gutter at a particular position.  When
 292 redisplay determines what to display at a particular position in a
 293 particular domain (i.e. window), it first consults the position-specific
 294 gutter.  If that does not yield a gutter descriptor, the
 295 @code{default-gutter} is consulted if @code{default-gutter-position}
 296 indicates this position.
 297
 298 @defvr Specifier top-gutter
 299 Specifier for the gutter at the top of the frame.
 300 @end defvr
 301
 302 @defvr Specifier bottom-gutter
 303 Specifier for the gutter at the bottom of the frame.
 304 @end defvr
 305
 306 @defvr Specifier left-gutter
 307 Specifier for the gutter at the left edge of the frame.
 308 @end defvr
 309
 310 @defvr Specifier right-gutter
 311 Specifier for the gutter at the right edge of the frame.
 312 @end defvr
 313
 314 @defun gutter-specifier-p object
 315 This function returns non-@code{nil} if @var{object} is a gutter specifier.
 316 Gutter specifiers are the actual objects contained in the gutter
 317 variables described above, and their valid instantiators are
 318 gutter descriptors (@pxref{Gutter Descriptor Format}).
 319 @end defun
 320
 321 @node Other Gutter Variables, Common Gutter Widgets, Specifying a Gutter, Gutter
 322 @section Other Gutter Variables
 323
 324   The variables to control the gutter thickness, visibility status, and
 325 captioned status are all specifiers.  @xref{Specifiers}.
 326
 327 @defvr Specifier default-gutter-height
 328 This specifies the height of the default gutter, if it's oriented
 329 horizontally.  The position of the default gutter is specified by the
 330 function @code{set-default-gutter-position}.  If the corresponding
 331 position-specific gutter thickness specifier
 332 (e.g. @code{top-gutter-height} if @code{default-gutter-position} is
 333 @code{top}) does not specify a thickness in a particular domain (a
 334 window or a frame), then the value of @code{default-gutter-height} or
 335 @code{default-gutter-width} (depending on the gutter orientation) in
 336 that domain, if any, will be used instead.
 337 @end defvr
 338
 339 @defvr Specifier default-gutter-width
 340 This specifies the width of the default gutter, if it's oriented
 341 vertically.  This behaves like @code{default-gutter-height}.
 342 @end defvr
 343
 344   Note that @code{default-gutter-height} is only used when
 345 @code{default-gutter-position} is @code{top} or @code{bottom}, and
 346 @code{default-gutter-width} is only used when
 347 @code{default-gutter-position} is @code{left} or @code{right}.
 348
 349 @defvr Specifier top-gutter-height
 350 This specifies the height of the top gutter.
 351 @end defvr
 352
 353 @defvr Specifier bottom-gutter-height
 354 This specifies the height of the bottom gutter.
 355 @end defvr
 356
 357 @defvr Specifier left-gutter-width
 358 This specifies the width of the left gutter.
 359 @end defvr
 360
 361 @defvr Specifier right-gutter-width
 362 This specifies the width of the right gutter.
 363 @end defvr
 364
 365   Note that all of the position-specific gutter thickness specifiers
 366 have a fallback value of zero when they do not correspond to the
 367 default gutter.  Therefore, you will have to set a non-zero thickness
 368 value if you want a position-specific gutter to be displayed.
 369
 370 @defvr Specifier default-gutter-visible-p
 371 This specifies whether the default gutter is visible.  The position of
 372 the default gutter is specified by the function
 373 @code{set-default-gutter-position}.  If the corresponding position-specific
 374 gutter visibility specifier (e.g. @code{top-gutter-visible-p} if
 375 @code{default-gutter-position} is @code{top}) does not specify a
 376 visible-p value in a particular domain (a window or a frame), then the
 377 value of @code{default-gutter-visible-p} in that domain, if any, will
 378 be used instead.
 379 @end defvr
 380
 381 @defvr Specifier top-gutter-visible-p
 382 This specifies whether the top gutter is visible.
 383 @end defvr
 384
 385 @defvr Specifier bottom-gutter-visible-p
 386 This specifies whether the bottom gutter is visible.
 387 @end defvr
 388
 389 @defvr Specifier left-gutter-visible-p
 390 This specifies whether the left gutter is visible.
 391 @end defvr
 392
 393 @defvr Specifier right-gutter-visible-p
 394 This specifies whether the right gutter is visible.
 395 @end defvr
 396
 397 @code{default-gutter-visible-p} and all of the position-specific
 398 gutter visibility specifiers have a fallback value of true.
 399
 400   Internally, gutter thickness and visibility specifiers are instantiated
 401 in both window and frame domains, for different purposes.  The value in
 402 the domain of a frame's selected window specifies the actual gutter
 403 thickness or visibility that you will see in that frame.  The value in
 404 the domain of a frame itself specifies the gutter thickness or
 405 visibility that is used in frame geometry calculations.
 406
 407   Thus, for example, if you set the frame width to 80 characters and the
 408 left gutter width for that frame to 68 pixels, then the frame will be
 409 sized to fit 80 characters plus a 68-pixel left gutter.  If you then
 410 set the left gutter width to 0 for a particular buffer (or if that
 411 buffer does not specify a left gutter or has a @code{nil} value specified for
 412 @code{left-gutter-visible-p}), you will find that, when that buffer is
 413 displayed in the selected window, the window will have a width of 86 or
 414 87 characters -- the frame is sized for a 68-pixel left gutter but the
 415 selected window specifies that the left gutter is not visible, so it is
 416 expanded to take up the slack.
 417
 418 @defvr Specifier gutter-buttons-captioned-p
 419 Whether gutter buttons are captioned.  This affects which glyphs from a
 420 gutter button descriptor are chosen.  @xref{Gutter Descriptor Format}.
 421 @end defvr
 422
 423   You can also reset the gutter to what it was when XEmacs started up.
 424
 425 @defvr Constant initial-gutter-spec
 426 The gutter descriptor used to initialize @code{default-gutter} at
 427 startup.
 428 @end defvr
 429
 430 @node Common Gutter Widgets, , Other Gutter Variables, Gutter
 431 @section Common Gutter Widgets
 432
 433   A gutter can contain arbitrary text.  So, for example, in an Info
 434 buffer you could put the title of the current node in the top gutter,
 435 and it would not scroll out of view in a long node.  (This is an
 436 artificial example, since usually the node name is sufficiently
 437 descriptive, and Info puts that in the mode line.)
 438
 439   A more common use for the gutter is to hold some kind of active
 440 widget.  The buffer-tab facility, available in all XEmacs frames,
 441 creates an array of file-folder-like tabs, which the user can click with
 442 the mouse to switch buffers.  W3 uses a progress-bar widget in the
 443 bottom gutter to give a visual indication of the progress of
 444 time-consuming operations like downloading.
 445
 446 @menu
 447 * Buffer Tabs::         Tabbed divider index metaphor for switching buffers.
 448 * Progress Bars::       Visual indication of operation progress.
 449 @end menu
 450
 451 @node Buffer Tabs, Progress Bars, ,Common Gutter Widgets
 452 @subsection Buffer Tabs
 453
 454   Not documented yet.
 455
 456 @node Progress Bars,  , Buffer Tabs, Common Gutter Widgets
 457 @subsection Progress Bars
 458
 459   Not documented yet.
 460