2 @c This is part of the SXEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
4 @c Copyright (C) 1995 Ben Wing.
5 @c Copyright (C) 2005 Sebastian Freundt <hroptatyr@sxemacs.org>
6 @c See the file lispref.texi for copying conditions.
7 @setfilename ../../info/annotations.info
9 @node Annotations, Display, Glyphs, top
13 An @dfn{annotation} is a pixmap or string that is not part of a buffer's
14 text but is displayed next to a particular location in a buffer.
15 Annotations can be displayed intermixed with text, in any whitespace at
16 the beginning or end of a line, or in a special area at the left or
17 right side of the frame called a @dfn{margin}, whose size is
18 controllable. Annotations are implemented using extents
19 (@pxref{Extents}); but you can work with annotations without knowing how
23 * Annotation Basics:: Introduction to annotations.
24 * Annotation Primitives:: Creating and deleting annotations.
25 * Annotation Properties:: Retrieving and changing the characteristics
27 * Margin Primitives:: Controlling the size of the margins.
28 * Locating Annotations:: Looking for annotations in a buffer.
29 * Annotation Hooks:: Hooks called at certain times during an
30 annotation's lifetime.
33 @node Annotation Basics
34 @section Annotation Basics
37 Marginal annotations are notes associated with a particular location in
38 a buffer. They may be displayed in a margin created on the left-hand or
39 right-hand side of the frame, in any whitespace at the beginning or end
40 of a line, or inside of the text itself. Every annotation may have an
41 associated action to be performed when the annotation is selected. The
42 term @dfn{annotation} is used to refer to an individual note. The term
43 @dfn{margin} is generically used to refer to the whitespace before the
44 first character on a line or after the last character on a line.
46 Each annotation has the following characteristics:
49 This is a glyph object and is used as the displayed representation
52 If given, this glyph is used as the displayed representation
53 of the annotation when the mouse is pressed down over the annotation.
55 The face with which to display the glyph.
57 Which side of the text (left or right) the annotation is displayed at.
59 If non-@code{nil}, this field must contain a function capable of being
60 the first argument to @code{funcall}. This function is normally
61 evaluated with a single argument, the value of the @var{data} field,
62 each time the annotation is selected. However, if the @var{with-event}
63 parameter to @code{make-annotation} is non-@code{nil}, the function
64 is called with two arguments. The first argument is the same as
65 before, and the second argument is the event (a button-up event,
66 usually) that activated the annotation.
68 Not used internally. This field can contain any elisp object. It is
69 passed as the first argument to @var{action} described above.
71 A menu displayed when the right mouse button is pressed over the
75 @cindex outside margin
77 The margin is divided into @dfn{outside} and @dfn{inside}. The outside
78 margin is space on the left or right side of the frame which normal text
79 cannot be displayed in. The inside margin is that space between the
80 leftmost or rightmost point at which text can be displayed and where the
81 first or last character actually is.
84 There are four different @dfn{layout types} which affect the exact
85 location an annotation appears.
89 The annotation is placed in the outside margin area. as close as
90 possible to the edge of the frame. If the outside margin is not wide
91 enough for an annotation to fit, it is not displayed.
94 The annotation is placed in the inside margin area, as close as possible
95 to the edge of the frame. If the inside margin is not wide enough for
96 the annotation to fit, it will be displayed using any available outside
97 margin space if and only if the specifier @code{use-left-overflow} or
98 @code{use-right-overflow} (depending on which side the annotation
99 appears in) is non-@code{nil}.
102 The annotation is placed in the inside margin area, as close as possible
103 to the first or last non-whitespace character on a line. If the inside
104 margin is not wide enough for the annotation to fit, it will be
105 displayed if and only if the specifier @code{use-left-overflow} or
106 @code{use-right-overflow} (depending on which side the annotation
107 appears in) is non-@code{nil}.
110 The annotation is placed at the position it is inserted. It will create
111 enough space for itself inside of the text area. It does not take up a
112 place in the logical buffer, only in the display of the buffer.
115 @cindex layout policy
116 The current layout policy is that all @code{whitespace} annotations are
117 displayed first. Next, all @code{inside-margin} annotations are
118 displayed using any remaining space. Finally as many
119 @code{outside-margin} annotations are displayed as possible. The
120 @code{text} annotations will always display as they create their own
124 @node Annotation Primitives
125 @section Annotation Primitives
127 @defun make-annotation glyph &optional position layout buffer with-event d-glyph rightp
128 This function creates a marginal annotation at position @var{position} in
129 @var{buffer}. The annotation is displayed using @var{glyph}, which
130 should be a glyph object or a string, and is positioned using layout
131 policy @var{layout}. If @var{position} is @code{nil}, point is used. If
132 @var{layout} is @code{nil}, @code{whitespace} is used. If @var{buffer}
133 is @code{nil}, the current buffer is used.
135 If @var{with-event} is non-@code{nil}, then when an annotation is
136 activated, the triggering event is passed as the second arg to the
137 annotation function. If @var{d-glyph} is non-@code{nil} then it is used
138 as the glyph that will be displayed when button1 is down. If
139 @var{rightp} is non-@code{nil} then the glyph will be displayed on the
140 right side of the buffer instead of the left.
142 The newly created annotation is returned.
145 @defun delete-annotation annotation
146 This function removes @var{annotation} from its buffer. This does not
147 modify the buffer text.
150 @defun annotationp annotation
151 This function returns @code{t} if @var{annotation} is an annotation,
152 @code{nil} otherwise.
155 @node Annotation Properties
156 @section Annotation Properties
158 @defun annotation-glyph annotation
159 This function returns the glyph object used to display @var{annotation}.
162 @defun set-annotation-glyph annotation glyph &optional layout side
163 This function sets the glyph of @var{annotation} to @var{glyph}, which
164 should be a glyph object. If @var{layout} is non-@code{nil}, set the
165 layout policy of @var{annotation} to @var{layout}. If @var{side} is
166 @code{left} or @code{right}, change the side of the buffer at which the
167 annotation is displayed to the given side. The new value of
168 @code{annotation-glyph} is returned.
171 @defun annotation-down-glyph annotation
172 This function returns the glyph used to display @var{annotation} when
173 the left mouse button is depressed on the annotation.
176 @defun set-annotation-down-glyph annotation glyph
177 This function returns the glyph used to display @var{annotation} when
178 the left mouse button is depressed on the annotation to @var{glyph},
179 which should be a glyph object.
182 @defun annotation-face annotation
183 This function returns the face associated with @var{annotation}.
186 @defun set-annotation-face annotation face
187 This function sets the face associated with @var{annotation} to
191 @defun annotation-layout annotation
192 This function returns the layout policy of @var{annotation}.
195 @defun set-annotation-layout annotation layout
196 This function sets the layout policy of @var{annotation} to
200 @defun annotation-side annotation
201 This function returns the side of the buffer that @var{annotation} is
202 displayed on. Return value is a symbol, either @code{left} or
206 @defun annotation-data annotation
207 This function returns the data associated with @var{annotation}.
210 @defun set-annotation-data annotation data
211 This function sets the data field of @var{annotation} to @var{data}.
212 @var{data} is returned.
215 @defun annotation-action annotation
216 This function returns the action associated with @var{annotation}.
219 @defun set-annotation-action annotation action
220 This function sets the action field of @var{annotation} to @var{action}.
221 @var{action} is returned..
224 @defun annotation-menu annotation
225 This function returns the menu associated with @var{annotation}.
228 @defun set-annotation-menu annotation menu
229 This function sets the menu associated with @var{annotation} to
230 @var{menu}. This menu will be displayed when the right mouse button is
231 pressed over the annotation.
234 @defun annotation-visible annotation
235 This function returns @code{t} if there is enough available space to
236 display @var{annotation}, @code{nil} otherwise.
239 @defun annotation-width annotation
240 This function returns the width of @var{annotation} in pixels.
243 @defun hide-annotation annotation
244 This function removes @var{annotation}'s glyph, making it invisible.
247 @defun reveal-annotation annotation
248 This function restores @var{annotation}'s glyph, making it visible.
252 @node Locating Annotations
253 @section Locating Annotations
255 @defun annotations-in-region start end buffer
256 This function returns a list of all annotations in @var{buffer} which
257 are between @var{start} and @var{end} inclusively.
260 @defun annotations-at &optional position buffer
261 This function returns a list of all annotations at @var{position} in
262 @var{buffer}. If @var{position} is @code{nil} point is used. If
263 @var{buffer} is @code{nil} the current buffer is used.
266 @defun annotation-list &optional buffer
267 This function returns a list of all annotations in @var{buffer}. If
268 @var{buffer} is @code{nil}, the current buffer is used.
271 @defun all-annotations
272 This function returns a list of all annotations in all buffers in
277 @node Margin Primitives
278 @section Margin Primitives
281 The margin widths are controllable on a buffer-local, window-local,
282 frame-local, device-local, or device-type-local basis through the
283 use of specifiers. @xref{Specifiers}.
285 @defvr Specifier left-margin-width
286 This is a specifier variable controlling the width of the left outside
287 margin, in characters. Use @code{set-specifier} to change its value.
290 @defvr Specifier right-margin-width
291 This is a specifier variable controlling the width of the right outside
292 margin, in characters. Use @code{set-specifier} to change its value.
295 @defvr Specifier use-left-overflow
296 If non-@code{nil}, use the left outside margin as extra whitespace when
297 displaying @code{whitespace} and @code{inside-margin} annotations.
298 Defaults to @code{nil}. This is a specifier variable; use
299 @code{set-specifier} to change its value.
302 @defvr Specifier use-right-overflow
303 If non-@code{nil}, use the right outside margin as extra whitespace when
304 displaying @code{whitespace} and @code{inside-margin} annotations.
305 Defaults to @code{nil}. This is a specifier variable; use
306 @code{set-specifier} to change its value.
309 @defun window-left-margin-pixel-width &optional window
310 This function returns the width in pixels of the left outside margin of
311 @var{window}. If @var{window} is @code{nil}, the selected window is
315 @defun window-right-margin-pixel-width &optional window
316 This function returns the width in pixels of the right outside margin of
317 @var{window}. If @var{window} is @code{nil}, the selected window is
321 The margin colors are controlled by the faces @code{left-margin} and
322 @code{right-margin}. These can be set using the X resources
323 @code{Emacs.left-margin.background} and
324 @code{Emacs.left-margin.foreground}; likewise for the right margin.
327 @node Annotation Hooks
328 @section Annotation Hooks
329 @cindex annotation hooks
331 The following three hooks are provided for use with the marginal annotations:
334 @item before-delete-annotation-hook
335 This hook is called immediately before an annotation is destroyed. It
336 is passed a single argument, the annotation being destroyed.
338 @item after-delete-annotation-hook
339 This normal hook is called immediately after an annotation is destroyed.
341 @item make-annotation-hook
342 This hook is called immediately after an annotation is created. It is
343 passed a single argument, the newly created annotation.