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
