Mercurial > hg > xemacs-beta
annotate man/lispref/gutter.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 | 2ba4f06a264d |
| children |
| rev | line source |
|---|---|
| 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
2028
diff
changeset
|
8 @node Gutter, Scrollbars, Toolbar, Top |
| 442 | 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 |