Mercurial > hg > xemacs-beta

comparison man/lispref/gutter.texi @ 404:2f8bb876ab1d r21-2-32

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