Mercurial > hg > xemacs-beta

comparison man/lispref/gutter.texi @ 442:abe6d1db359e r21-2-36

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r21-2-36
author cvs
date Mon, 13 Aug 2007 11:35:02 +0200
parents
children 576fb035e263
comparison
equal deleted inserted replaced
441:72a7cfa4a488 442:abe6d1db359e
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 t, nil or a list of symbols. If
119 a gutter-visible instantiator is set to a list of symbols, and the
120 corresponding gutter specification is a property-list strings, then
121 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-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 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