442
+ − 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.
2028
+ − 17 * Creating Gutters:: How to create a gutter.
442
+ − 18 * Specifying a Gutter:: Setting a gutter's contents.
+ − 19 * Other Gutter Variables:: Controlling the size of gutters.
+ − 20 * Common Gutter Widgets:: Things to put in gutters.
+ − 21 @end menu
+ − 22
2028
+ − 23 @node Gutter Intro, Creating Gutters, Gutter, Gutter
442
+ − 24 @section Gutter Intro
+ − 25
+ − 26 A @dfn{gutter} is a rectangle displayed along one edge of a frame. It
+ − 27 can contain arbitrary text or graphics. It could be considered a
+ − 28 generalization of a toolbar, although toolbars are not currently
+ − 29 implemented using gutters.
+ − 30
+ − 31 In XEmacs, a gutter can be displayed along any of the four edges
+ − 32 of the frame, and two or more different edges can be displaying
+ − 33 gutters simultaneously. The contents, thickness, and visibility of
+ − 34 the gutters 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 gutter displayed in a frame. Usually, this is
2028
+ − 38 the default gutter, containing buffer tabs, but modes can override this
442
+ − 39 and substitute their own gutter. This default gutter is usually
+ − 40 positioned along the top of the frame, but this can be changed using
+ − 41 @code{set-default-gutter-position}.
+ − 42
+ − 43 Note that, for each of the gutter properties (contents, thickness,
+ − 44 and visibility), there is a separate specifier for each of the four
+ − 45 gutter positions (top, bottom, left, and right), and an additional
+ − 46 specifier for the ``default'' gutter, i.e. the gutter whose
+ − 47 position is controlled by @code{set-default-gutter-position}. The
+ − 48 way this works is that @code{set-default-gutter-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 gutter, you
+ − 54 just change the default specifiers, and everything works. A package
+ − 55 such as VM that wants to put its own gutter in a different location
+ − 56 from the default just sets the position-specific specifiers, and if
+ − 57 the user sets the default gutter to the same position, it will just
+ − 58 not be visible.
+ − 59
2028
+ − 60 @node Creating Gutters, Specifying a Gutter, Gutter Intro, Gutter
+ − 61 @section Creating Gutters
442
+ − 62
+ − 63 @defun make-gutter-specifier spec-list
+ − 64
+ − 65 Return a new @code{gutter} specifier object with the given specification
+ − 66 list. @var{spec-list} can be a list of specifications (each of which is
+ − 67 a cons of a locale and a list of instantiators), a single instantiator,
+ − 68 or a list of instantiators. @xref{Specifiers}, for more information
+ − 69 about specifiers.
+ − 70
+ − 71 Gutter specifiers are used to specify the format of a gutter. The
+ − 72 values of the variables @code{default-gutter}, @code{top-gutter},
+ − 73 @code{left-gutter}, @code{right-gutter}, and @code{bottom-gutter} are
+ − 74 always gutter specifiers.
+ − 75
2028
+ − 76 Valid gutter instantiators are called ``gutter descriptors.'' A gutter
+ − 77 descriptor may be a string, a property-list with symbol keys and string
+ − 78 values, or @code{nil}. If @code{nil}, nothing will be displayed in the
+ − 79 gutter. If a string, the string will be displayed, with text properties
+ − 80 such as faces and additional glyphs taken from the extents in the
+ − 81 string, if any. If a property-list of strings, the string values will
+ − 82 be conditionally concatenated according to the contents of the
+ − 83 corresponding @samp{gutter-visible} variable, and displayed according to
+ − 84 any text properties they contain.
442
+ − 85 @end defun
+ − 86
+ − 87 @defun make-gutter-size-specifier spec-list
+ − 88
+ − 89 Return a new @code{gutter-size} specifier object with the given spec
+ − 90 list. @var{spec-list} can be a list of specifications (each of which is
+ − 91 a cons of a locale and a list of instantiators), a single instantiator,
+ − 92 or a list of instantiators. @xref{Specifiers}, for more information
+ − 93 about specifiers.
+ − 94
2028
+ − 95 Gutter-size specifiers are used to specify the size of a gutter.
+ − 96 The width of top and bottom gutters and the height of left and right
+ − 97 gutters are always adjusted to the size of the frame, so ``size'' means
+ − 98 ``thickness,'' @emph{i.e.}, height for top and bottom gutters and width
+ − 99 for left and right gutters. The values of the variables
+ − 100 @code{default-gutter-size}, @code{top-gutter-size},
+ − 101 @code{left-gutter-size}, @code{right-gutter-size}, and
+ − 102 @code{bottom-gutter-size} are always gutter-size specifiers.
442
+ − 103
+ − 104 Valid gutter-size instantiators are either integers or the special
2028
+ − 105 symbol @code{autodetect}. If a gutter-size is set to @code{autodetect}
442
+ − 106 them the size of the gutter will be adjusted to just accommodate the
2028
+ − 107 gutter's contents. @code{autodetect} only works for top and bottom
442
+ − 108 gutters.
+ − 109 @end defun
+ − 110
+ − 111 @defun make-gutter-visible-specifier spec-list
+ − 112
+ − 113 Return a new @code{gutter-visible} specifier object with the given spec
+ − 114 list. @var{spec-list} can be a list of specifications (each of which is
+ − 115 a cons of a locale and a list of instantiators), a single instantiator,
+ − 116 or a list of instantiators. @xref{Specifiers}, for more information
+ − 117 about specifiers.
+ − 118
+ − 119 Gutter-visible specifiers are used to specify the visibility of a
+ − 120 gutter. The values of the variables @code{default-gutter-visible-p},
+ − 121 @code{top-gutter-visible-p}, @code{left-gutter-visible-p},
+ − 122 @code{right-gutter-visible-p}, and @code{bottom-gutter-visible-p} are
+ − 123 always gutter-visible specifiers.
+ − 124
444
+ − 125 Valid gutter-visible instantiators are @code{t}, @code{nil} or a list of
+ − 126 symbols. If a gutter-visible instantiator is set to a list of symbols,
2028
+ − 127 and the corresponding gutter specification is a property-list of strings,
+ − 128 then property values of the gutter specification will only be visible if the
+ − 129 corresponding key occurs in the gutter-visible instantiator.
442
+ − 130 @end defun
+ − 131
2028
+ − 132 @node Specifying a Gutter, Other Gutter Variables, Creating Gutters, Gutter
442
+ − 133 @section Specifying a Gutter
+ − 134
+ − 135 In order to specify the contents of a gutter, set one of the specifier
+ − 136 variables @code{default-gutter}, @code{top-gutter},
+ − 137 @code{bottom-gutter}, @code{left-gutter}, or @code{right-gutter}.
+ − 138 These are specifiers, which means you set them with @code{set-specifier}
+ − 139 and query them with @code{specifier-specs} or @code{specifier-instance}.
+ − 140 You will get an error if you try to set them using @code{setq}. The
+ − 141 valid instantiators for these specifiers are gutter descriptors, as
+ − 142 described above. @xref{Specifiers}, for more information.
+ − 143
+ − 144 Most of the time, you will set @code{default-gutter}, which allows
+ − 145 the user to choose where the gutter should go.
+ − 146
+ − 147 @defvr Specifier default-gutter
+ − 148 The position of this gutter is specified in the function
444
+ − 149 @code{default-gutter-position}. If the corresponding
442
+ − 150 position-specific gutter (e.g. @code{top-gutter} if
+ − 151 @code{default-gutter-position} is @code{top}) does not specify a
+ − 152 gutter in a particular domain, then the value of @code{default-gutter}
+ − 153 in that domain, of any, will be used instead.
+ − 154 @end defvr
+ − 155
+ − 156 Note that the gutter at any particular position will not be displayed
+ − 157 unless its thickness (width or height, depending on orientation) is
+ − 158 non-zero and its visibility status is true. The thickness is controlled
+ − 159 by the specifiers @code{top-gutter-height},
+ − 160 @code{bottom-gutter-height}, @code{left-gutter-width}, and
+ − 161 @code{right-gutter-width}, and the visibility status is controlled by
+ − 162 the specifiers @code{top-gutter-visible-p},
+ − 163 @code{bottom-gutter-visible-p}, @code{left-gutter-visible-p}, and
+ − 164 @code{right-gutter-visible-p} (@pxref{Other Gutter Variables}).
+ − 165
+ − 166 @defun set-default-gutter-position position
+ − 167 This function sets the position that the @code{default-gutter} will be
+ − 168 displayed at. Valid positions are the symbols @code{top},
+ − 169 @code{bottom}, @code{left} and @code{right}. What this actually does is
+ − 170 set the fallback specifier for the position-specific specifier
+ − 171 corresponding to the given position to @code{default-gutter}, and set
+ − 172 the fallbacks for the other position-specific specifiers to @code{nil}.
+ − 173 It also does the same thing for the position-specific thickness and
+ − 174 visibility specifiers, which inherit from one of
+ − 175 @code{default-gutter-height} or @code{default-gutter-width}, and from
+ − 176 @code{default-gutter-visible-p}, respectively (@pxref{Other Gutter
+ − 177 Variables}).
+ − 178 @end defun
+ − 179
+ − 180 @defun default-gutter-position
+ − 181 This function returns the position that the @code{default-gutter} will
+ − 182 be displayed at.
+ − 183 @end defun
+ − 184
+ − 185 You can also explicitly set a gutter at a particular position. When
+ − 186 redisplay determines what to display at a particular position in a
+ − 187 particular domain (i.e. window), it first consults the position-specific
+ − 188 gutter. If that does not yield a gutter descriptor, the
+ − 189 @code{default-gutter} is consulted if @code{default-gutter-position}
+ − 190 indicates this position.
+ − 191
+ − 192 @defvr Specifier top-gutter
+ − 193 Specifier for the gutter at the top of the frame.
+ − 194 @end defvr
+ − 195
+ − 196 @defvr Specifier bottom-gutter
+ − 197 Specifier for the gutter at the bottom of the frame.
+ − 198 @end defvr
+ − 199
+ − 200 @defvr Specifier left-gutter
+ − 201 Specifier for the gutter at the left edge of the frame.
+ − 202 @end defvr
+ − 203
+ − 204 @defvr Specifier right-gutter
+ − 205 Specifier for the gutter at the right edge of the frame.
+ − 206 @end defvr
+ − 207
+ − 208 @defun gutter-specifier-p object
444
+ − 209 This function returns non-@code{nil} if @var{object} is a gutter specifier.
442
+ − 210 Gutter specifiers are the actual objects contained in the gutter
+ − 211 variables described above, and their valid instantiators are
2028
+ − 212 gutter descriptors.
442
+ − 213 @end defun
+ − 214
+ − 215 @node Other Gutter Variables, Common Gutter Widgets, Specifying a Gutter, Gutter
+ − 216 @section Other Gutter Variables
+ − 217
+ − 218 The variables to control the gutter thickness, visibility status, and
+ − 219 captioned status are all specifiers. @xref{Specifiers}.
+ − 220
+ − 221 @defvr Specifier default-gutter-height
+ − 222 This specifies the height of the default gutter, if it's oriented
+ − 223 horizontally. The position of the default gutter is specified by the
+ − 224 function @code{set-default-gutter-position}. If the corresponding
+ − 225 position-specific gutter thickness specifier
+ − 226 (e.g. @code{top-gutter-height} if @code{default-gutter-position} is
+ − 227 @code{top}) does not specify a thickness in a particular domain (a
+ − 228 window or a frame), then the value of @code{default-gutter-height} or
+ − 229 @code{default-gutter-width} (depending on the gutter orientation) in
+ − 230 that domain, if any, will be used instead.
+ − 231 @end defvr
+ − 232
+ − 233 @defvr Specifier default-gutter-width
+ − 234 This specifies the width of the default gutter, if it's oriented
+ − 235 vertically. This behaves like @code{default-gutter-height}.
+ − 236 @end defvr
+ − 237
+ − 238 Note that @code{default-gutter-height} is only used when
+ − 239 @code{default-gutter-position} is @code{top} or @code{bottom}, and
+ − 240 @code{default-gutter-width} is only used when
+ − 241 @code{default-gutter-position} is @code{left} or @code{right}.
+ − 242
+ − 243 @defvr Specifier top-gutter-height
+ − 244 This specifies the height of the top gutter.
+ − 245 @end defvr
+ − 246
+ − 247 @defvr Specifier bottom-gutter-height
+ − 248 This specifies the height of the bottom gutter.
+ − 249 @end defvr
+ − 250
+ − 251 @defvr Specifier left-gutter-width
+ − 252 This specifies the width of the left gutter.
+ − 253 @end defvr
+ − 254
+ − 255 @defvr Specifier right-gutter-width
+ − 256 This specifies the width of the right gutter.
+ − 257 @end defvr
+ − 258
+ − 259 Note that all of the position-specific gutter thickness specifiers
+ − 260 have a fallback value of zero when they do not correspond to the
+ − 261 default gutter. Therefore, you will have to set a non-zero thickness
+ − 262 value if you want a position-specific gutter to be displayed.
+ − 263
+ − 264 @defvr Specifier default-gutter-visible-p
+ − 265 This specifies whether the default gutter is visible. The position of
+ − 266 the default gutter is specified by the function
+ − 267 @code{set-default-gutter-position}. If the corresponding position-specific
+ − 268 gutter visibility specifier (e.g. @code{top-gutter-visible-p} if
+ − 269 @code{default-gutter-position} is @code{top}) does not specify a
+ − 270 visible-p value in a particular domain (a window or a frame), then the
+ − 271 value of @code{default-gutter-visible-p} in that domain, if any, will
+ − 272 be used instead.
+ − 273 @end defvr
+ − 274
+ − 275 @defvr Specifier top-gutter-visible-p
+ − 276 This specifies whether the top gutter is visible.
+ − 277 @end defvr
+ − 278
+ − 279 @defvr Specifier bottom-gutter-visible-p
+ − 280 This specifies whether the bottom gutter is visible.
+ − 281 @end defvr
+ − 282
+ − 283 @defvr Specifier left-gutter-visible-p
+ − 284 This specifies whether the left gutter is visible.
+ − 285 @end defvr
+ − 286
+ − 287 @defvr Specifier right-gutter-visible-p
+ − 288 This specifies whether the right gutter is visible.
+ − 289 @end defvr
+ − 290
+ − 291 @code{default-gutter-visible-p} and all of the position-specific
+ − 292 gutter visibility specifiers have a fallback value of true.
+ − 293
2028
+ − 294 @c #### is this true?
442
+ − 295 Internally, gutter thickness and visibility specifiers are instantiated
+ − 296 in both window and frame domains, for different purposes. The value in
+ − 297 the domain of a frame's selected window specifies the actual gutter
+ − 298 thickness or visibility that you will see in that frame. The value in
+ − 299 the domain of a frame itself specifies the gutter thickness or
+ − 300 visibility that is used in frame geometry calculations.
+ − 301
+ − 302 Thus, for example, if you set the frame width to 80 characters and the
+ − 303 left gutter width for that frame to 68 pixels, then the frame will be
+ − 304 sized to fit 80 characters plus a 68-pixel left gutter. If you then
+ − 305 set the left gutter width to 0 for a particular buffer (or if that
444
+ − 306 buffer does not specify a left gutter or has a @code{nil} value specified for
442
+ − 307 @code{left-gutter-visible-p}), you will find that, when that buffer is
+ − 308 displayed in the selected window, the window will have a width of 86 or
+ − 309 87 characters -- the frame is sized for a 68-pixel left gutter but the
+ − 310 selected window specifies that the left gutter is not visible, so it is
+ − 311 expanded to take up the slack.
+ − 312
+ − 313 @node Common Gutter Widgets, , Other Gutter Variables, Gutter
+ − 314 @section Common Gutter Widgets
+ − 315
+ − 316 A gutter can contain arbitrary text. So, for example, in an Info
+ − 317 buffer you could put the title of the current node in the top gutter,
+ − 318 and it would not scroll out of view in a long node. (This is an
+ − 319 artificial example, since usually the node name is sufficiently
+ − 320 descriptive, and Info puts that in the mode line.)
+ − 321
+ − 322 A more common use for the gutter is to hold some kind of active
+ − 323 widget. The buffer-tab facility, available in all XEmacs frames,
+ − 324 creates an array of file-folder-like tabs, which the user can click with
2028
+ − 325 the mouse to switch buffers. W3 and font-lock use progress-bar widgets in the
442
+ − 326 bottom gutter to give a visual indication of the progress of
2028
+ − 327 time-consuming operations like downloading and syntax highlighting.
+ − 328
+ − 329 @c #### Remove the following sentence when the subnodes are created.
+ − 330 These widgets are currently documented only in the library
+ − 331 @file{gutter-items}.
442
+ − 332
+ − 333 @menu
+ − 334 * Buffer Tabs:: Tabbed divider index metaphor for switching buffers.
+ − 335 * Progress Bars:: Visual indication of operation progress.
+ − 336 @end menu
+ − 337
2028
+ − 338
442
+ − 339 @node Buffer Tabs, Progress Bars, ,Common Gutter Widgets
+ − 340 @subsection Buffer Tabs
+ − 341
+ − 342 Not documented yet.
+ − 343
2028
+ − 344
442
+ − 345 @node Progress Bars, , Buffer Tabs, Common Gutter Widgets
+ − 346 @subsection Progress Bars
+ − 347
+ − 348 Not documented yet.
+ − 349