|
428
|
1 @c -*-texinfo-*-
|
|
|
2 @c This is part of the XEmacs Lisp Reference Manual.
|
|
444
|
3 @c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
|
|
428
|
4 @c Copyright (C) 1995 Ben Wing.
|
|
|
5 @c See the file lispref.texi for copying conditions.
|
|
|
6 @setfilename ../../info/annotations.info
|
|
|
7 @node Annotations, Display, Glyphs, top
|
|
|
8 @chapter Annotations
|
|
|
9 @cindex annotation
|
|
|
10
|
|
|
11 An @dfn{annotation} is a pixmap or string that is not part of a buffer's
|
|
|
12 text but is displayed next to a particular location in a buffer.
|
|
|
13 Annotations can be displayed intermixed with text, in any whitespace at
|
|
|
14 the beginning or end of a line, or in a special area at the left or
|
|
|
15 right side of the frame called a @dfn{margin}, whose size is
|
|
|
16 controllable. Annotations are implemented using extents
|
|
|
17 (@pxref{Extents}); but you can work with annotations without knowing how
|
|
|
18 extents work.
|
|
|
19
|
|
|
20 @menu
|
|
|
21 * Annotation Basics:: Introduction to annotations.
|
|
|
22 * Annotation Primitives:: Creating and deleting annotations.
|
|
|
23 * Annotation Properties:: Retrieving and changing the characteristics
|
|
|
24 of an annotation.
|
|
|
25 * Margin Primitives:: Controlling the size of the margins.
|
|
|
26 * Locating Annotations:: Looking for annotations in a buffer.
|
|
|
27 * Annotation Hooks:: Hooks called at certain times during an
|
|
|
28 annotation's lifetime.
|
|
|
29 @end menu
|
|
|
30
|
|
|
31 @node Annotation Basics
|
|
|
32 @section Annotation Basics
|
|
|
33
|
|
|
34 @cindex margin
|
|
|
35 Marginal annotations are notes associated with a particular location in
|
|
|
36 a buffer. They may be displayed in a margin created on the left-hand or
|
|
|
37 right-hand side of the frame, in any whitespace at the beginning or end
|
|
|
38 of a line, or inside of the text itself. Every annotation may have an
|
|
|
39 associated action to be performed when the annotation is selected. The
|
|
|
40 term @dfn{annotation} is used to refer to an individual note. The term
|
|
|
41 @dfn{margin} is generically used to refer to the whitespace before the
|
|
|
42 first character on a line or after the last character on a line.
|
|
|
43
|
|
|
44 Each annotation has the following characteristics:
|
|
|
45 @table @var
|
|
|
46 @item glyph
|
|
|
47 This is a glyph object and is used as the displayed representation
|
|
|
48 of the annotation.
|
|
|
49 @item down-glyph
|
|
|
50 If given, this glyph is used as the displayed representation
|
|
|
51 of the annotation when the mouse is pressed down over the annotation.
|
|
|
52 @item face
|
|
|
53 The face with which to display the glyph.
|
|
|
54 @item side
|
|
|
55 Which side of the text (left or right) the annotation is displayed at.
|
|
|
56 @item action
|
|
|
57 If non-@code{nil}, this field must contain a function capable of being
|
|
|
58 the first argument to @code{funcall}. This function is normally
|
|
|
59 evaluated with a single argument, the value of the @var{data} field,
|
|
|
60 each time the annotation is selected. However, if the @var{with-event}
|
|
|
61 parameter to @code{make-annotation} is non-@code{nil}, the function
|
|
|
62 is called with two arguments. The first argument is the same as
|
|
|
63 before, and the second argument is the event (a button-up event,
|
|
|
64 usually) that activated the annotation.
|
|
|
65 @item data
|
|
|
66 Not used internally. This field can contain any E-Lisp object. It is
|
|
|
67 passed as the first argument to @var{action} described above.
|
|
|
68 @item menu
|
|
|
69 A menu displayed when the right mouse button is pressed over the
|
|
|
70 annotation.
|
|
|
71 @end table
|
|
|
72
|
|
|
73 @cindex outside margin
|
|
|
74 @cindex inside margin
|
|
|
75 The margin is divided into @dfn{outside} and @dfn{inside}. The outside
|
|
|
76 margin is space on the left or right side of the frame which normal text
|
|
|
77 cannot be displayed in. The inside margin is that space between the
|
|
|
78 leftmost or rightmost point at which text can be displayed and where the
|
|
|
79 first or last character actually is.
|
|
|
80
|
|
|
81 @cindex layout types
|
|
|
82 There are four different @dfn{layout types} which affect the exact
|
|
|
83 location an annotation appears.
|
|
|
84
|
|
|
85 @table @code
|
|
|
86 @item outside-margin
|
|
|
87 The annotation is placed in the outside margin area. as close as
|
|
|
88 possible to the edge of the frame. If the outside margin is not wide
|
|
|
89 enough for an annotation to fit, it is not displayed.
|
|
|
90
|
|
|
91 @item inside-margin
|
|
|
92 The annotation is placed in the inside margin area, as close as possible
|
|
|
93 to the edge of the frame. If the inside margin is not wide enough for
|
|
|
94 the annotation to fit, it will be displayed using any available outside
|
|
|
95 margin space if and only if the specifier @code{use-left-overflow} or
|
|
|
96 @code{use-right-overflow} (depending on which side the annotation
|
|
|
97 appears in) is non-@code{nil}.
|
|
|
98
|
|
|
99 @item whitespace
|
|
|
100 The annotation is placed in the inside margin area, as close as possible
|
|
|
101 to the first or last non-whitespace character on a line. If the inside
|
|
|
102 margin is not wide enough for the annotation to fit, it will be
|
|
|
103 displayed if and only if the specifier @code{use-left-overflow} or
|
|
|
104 @code{use-right-overflow} (depending on which side the annotation
|
|
|
105 appears in) is non-@code{nil}.
|
|
|
106
|
|
|
107 @item text
|
|
|
108 The annotation is placed at the position it is inserted. It will create
|
|
|
109 enough space for itself inside of the text area. It does not take up a
|
|
|
110 place in the logical buffer, only in the display of the buffer.
|
|
|
111 @end table
|
|
|
112
|
|
|
113 @cindex layout policy
|
|
|
114 The current layout policy is that all @code{whitespace} annotations are
|
|
|
115 displayed first. Next, all @code{inside-margin} annotations are
|
|
|
116 displayed using any remaining space. Finally as many
|
|
|
117 @code{outside-margin} annotations are displayed as possible. The
|
|
|
118 @code{text} annotations will always display as they create their own
|
|
|
119 space to display in.
|
|
|
120
|
|
|
121
|
|
|
122 @node Annotation Primitives
|
|
|
123 @section Annotation Primitives
|
|
|
124
|
|
|
125 @defun make-annotation glyph &optional position layout buffer with-event d-glyph rightp
|
|
444
|
126 This function creates a marginal annotation at position @var{position} in
|
|
428
|
127 @var{buffer}. The annotation is displayed using @var{glyph}, which
|
|
|
128 should be a glyph object or a string, and is positioned using layout
|
|
444
|
129 policy @var{layout}. If @var{position} is @code{nil}, point is used. If
|
|
428
|
130 @var{layout} is @code{nil}, @code{whitespace} is used. If @var{buffer}
|
|
|
131 is @code{nil}, the current buffer is used.
|
|
|
132
|
|
|
133 If @var{with-event} is non-@code{nil}, then when an annotation is
|
|
|
134 activated, the triggering event is passed as the second arg to the
|
|
|
135 annotation function. If @var{d-glyph} is non-@code{nil} then it is used
|
|
|
136 as the glyph that will be displayed when button1 is down. If
|
|
|
137 @var{rightp} is non-@code{nil} then the glyph will be displayed on the
|
|
|
138 right side of the buffer instead of the left.
|
|
|
139
|
|
|
140 The newly created annotation is returned.
|
|
|
141 @end defun
|
|
|
142
|
|
|
143 @defun delete-annotation annotation
|
|
|
144 This function removes @var{annotation} from its buffer. This does not
|
|
|
145 modify the buffer text.
|
|
|
146 @end defun
|
|
|
147
|
|
|
148 @defun annotationp annotation
|
|
|
149 This function returns @code{t} if @var{annotation} is an annotation,
|
|
|
150 @code{nil} otherwise.
|
|
|
151 @end defun
|
|
|
152
|
|
|
153 @node Annotation Properties
|
|
|
154 @section Annotation Properties
|
|
|
155
|
|
|
156 @defun annotation-glyph annotation
|
|
|
157 This function returns the glyph object used to display @var{annotation}.
|
|
|
158 @end defun
|
|
|
159
|
|
|
160 @defun set-annotation-glyph annotation glyph &optional layout side
|
|
|
161 This function sets the glyph of @var{annotation} to @var{glyph}, which
|
|
|
162 should be a glyph object. If @var{layout} is non-@code{nil}, set the
|
|
|
163 layout policy of @var{annotation} to @var{layout}. If @var{side} is
|
|
|
164 @code{left} or @code{right}, change the side of the buffer at which the
|
|
|
165 annotation is displayed to the given side. The new value of
|
|
|
166 @code{annotation-glyph} is returned.
|
|
|
167 @end defun
|
|
|
168
|
|
|
169 @defun annotation-down-glyph annotation
|
|
|
170 This function returns the glyph used to display @var{annotation} when
|
|
|
171 the left mouse button is depressed on the annotation.
|
|
|
172 @end defun
|
|
|
173
|
|
|
174 @defun set-annotation-down-glyph annotation glyph
|
|
|
175 This function returns the glyph used to display @var{annotation} when
|
|
|
176 the left mouse button is depressed on the annotation to @var{glyph},
|
|
|
177 which should be a glyph object.
|
|
|
178 @end defun
|
|
|
179
|
|
|
180 @defun annotation-face annotation
|
|
|
181 This function returns the face associated with @var{annotation}.
|
|
|
182 @end defun
|
|
444
|
183
|
|
428
|
184 @defun set-annotation-face annotation face
|
|
|
185 This function sets the face associated with @var{annotation} to
|
|
|
186 @var{face}.
|
|
|
187 @end defun
|
|
|
188
|
|
|
189 @defun annotation-layout annotation
|
|
|
190 This function returns the layout policy of @var{annotation}.
|
|
|
191 @end defun
|
|
|
192
|
|
|
193 @defun set-annotation-layout annotation layout
|
|
|
194 This function sets the layout policy of @var{annotation} to
|
|
|
195 @var{layout}.
|
|
|
196 @end defun
|
|
|
197
|
|
|
198 @defun annotation-side annotation
|
|
|
199 This function returns the side of the buffer that @var{annotation} is
|
|
|
200 displayed on. Return value is a symbol, either @code{left} or
|
|
|
201 @code{right}.
|
|
|
202 @end defun
|
|
|
203
|
|
|
204 @defun annotation-data annotation
|
|
|
205 This function returns the data associated with @var{annotation}.
|
|
|
206 @end defun
|
|
|
207
|
|
|
208 @defun set-annotation-data annotation data
|
|
|
209 This function sets the data field of @var{annotation} to @var{data}.
|
|
|
210 @var{data} is returned.
|
|
|
211 @end defun
|
|
|
212
|
|
|
213 @defun annotation-action annotation
|
|
|
214 This function returns the action associated with @var{annotation}.
|
|
|
215 @end defun
|
|
|
216
|
|
|
217 @defun set-annotation-action annotation action
|
|
|
218 This function sets the action field of @var{annotation} to @var{action}.
|
|
|
219 @var{action} is returned..
|
|
|
220 @end defun
|
|
|
221
|
|
|
222 @defun annotation-menu annotation
|
|
|
223 This function returns the menu associated with @var{annotation}.
|
|
|
224 @end defun
|
|
|
225
|
|
|
226 @defun set-annotation-menu annotation menu
|
|
|
227 This function sets the menu associated with @var{annotation} to
|
|
|
228 @var{menu}. This menu will be displayed when the right mouse button is
|
|
|
229 pressed over the annotation.
|
|
|
230 @end defun
|
|
|
231
|
|
|
232 @defun annotation-visible annotation
|
|
|
233 This function returns @code{t} if there is enough available space to
|
|
|
234 display @var{annotation}, @code{nil} otherwise.
|
|
|
235 @end defun
|
|
|
236
|
|
|
237 @defun annotation-width annotation
|
|
|
238 This function returns the width of @var{annotation} in pixels.
|
|
|
239 @end defun
|
|
|
240
|
|
|
241 @defun hide-annotation annotation
|
|
|
242 This function removes @var{annotation}'s glyph, making it invisible.
|
|
|
243 @end defun
|
|
|
244
|
|
|
245 @defun reveal-annotation annotation
|
|
|
246 This function restores @var{annotation}'s glyph, making it visible.
|
|
|
247 @end defun
|
|
|
248
|
|
|
249 @node Locating Annotations
|
|
|
250 @section Locating Annotations
|
|
|
251
|
|
|
252 @defun annotations-in-region start end buffer
|
|
|
253 This function returns a list of all annotations in @var{buffer} which
|
|
|
254 are between @var{start} and @var{end} inclusively.
|
|
|
255 @end defun
|
|
|
256
|
|
|
257 @defun annotations-at &optional position buffer
|
|
|
258 This function returns a list of all annotations at @var{position} in
|
|
|
259 @var{buffer}. If @var{position} is @code{nil} point is used. If
|
|
|
260 @var{buffer} is @code{nil} the current buffer is used.
|
|
|
261 @end defun
|
|
|
262
|
|
|
263 @defun annotation-list &optional buffer
|
|
|
264 This function returns a list of all annotations in @var{buffer}. If
|
|
|
265 @var{buffer} is @code{nil}, the current buffer is used.
|
|
|
266 @end defun
|
|
|
267
|
|
|
268 @defun all-annotations
|
|
|
269 This function returns a list of all annotations in all buffers in
|
|
|
270 existence.
|
|
|
271 @end defun
|
|
|
272
|
|
|
273 @node Margin Primitives
|
|
|
274 @section Margin Primitives
|
|
|
275 @cindex margin width
|
|
|
276
|
|
|
277 The margin widths are controllable on a buffer-local, window-local,
|
|
|
278 frame-local, device-local, or device-type-local basis through the
|
|
|
279 use of specifiers. @xref{Specifiers}.
|
|
|
280
|
|
|
281 @defvr Specifier left-margin-width
|
|
|
282 This is a specifier variable controlling the width of the left outside
|
|
|
283 margin, in characters. Use @code{set-specifier} to change its value.
|
|
|
284 @end defvr
|
|
|
285
|
|
|
286 @defvr Specifier right-margin-width
|
|
|
287 This is a specifier variable controlling the width of the right outside
|
|
|
288 margin, in characters. Use @code{set-specifier} to change its value.
|
|
|
289 @end defvr
|
|
|
290
|
|
|
291 @defvr Specifier use-left-overflow
|
|
|
292 If non-@code{nil}, use the left outside margin as extra whitespace when
|
|
|
293 displaying @code{whitespace} and @code{inside-margin} annotations.
|
|
|
294 Defaults to @code{nil}. This is a specifier variable; use
|
|
|
295 @code{set-specifier} to change its value.
|
|
|
296 @end defvr
|
|
|
297
|
|
|
298 @defvr Specifier use-right-overflow
|
|
|
299 If non-@code{nil}, use the right outside margin as extra whitespace when
|
|
|
300 displaying @code{whitespace} and @code{inside-margin} annotations.
|
|
|
301 Defaults to @code{nil}. This is a specifier variable; use
|
|
|
302 @code{set-specifier} to change its value.
|
|
|
303 @end defvr
|
|
|
304
|
|
|
305 @defun window-left-margin-pixel-width &optional window
|
|
|
306 This function returns the width in pixels of the left outside margin of
|
|
|
307 @var{window}. If @var{window} is @code{nil}, the selected window is
|
|
|
308 assumed.
|
|
|
309 @end defun
|
|
|
310
|
|
|
311 @defun window-right-margin-pixel-width &optional window
|
|
|
312 This function returns the width in pixels of the right outside margin of
|
|
|
313 @var{window}. If @var{window} is @code{nil}, the selected window is
|
|
|
314 assumed.
|
|
|
315 @end defun
|
|
|
316
|
|
|
317 The margin colors are controlled by the faces @code{left-margin} and
|
|
|
318 @code{right-margin}. These can be set using the X resources
|
|
|
319 @code{Emacs.left-margin.background} and
|
|
|
320 @code{Emacs.left-margin.foreground}; likewise for the right margin.
|
|
|
321
|
|
|
322
|
|
|
323 @node Annotation Hooks
|
|
|
324 @section Annotation Hooks
|
|
|
325 @cindex annotation hooks
|
|
|
326
|
|
|
327 The following three hooks are provided for use with the marginal annotations:
|
|
|
328
|
|
|
329 @table @code
|
|
|
330 @item before-delete-annotation-hook
|
|
|
331 This hook is called immediately before an annotation is destroyed. It
|
|
|
332 is passed a single argument, the annotation being destroyed.
|
|
|
333
|
|
|
334 @item after-delete-annotation-hook
|
|
|
335 This normal hook is called immediately after an annotation is destroyed.
|
|
|
336
|
|
|
337 @item make-annotation-hook
|
|
|
338 This hook is called immediately after an annotation is created. It is
|
|
|
339 passed a single argument, the newly created annotation.
|
|
|
340 @end table
|
