man/lispref/annotations.texi

   1 @c -*-texinfo-*-
   2 @c This is part of the XEmacs Lisp Reference Manual.
   3 @c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
   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
 126 This function creates a marginal annotation at position @var{position} in
 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
 129 policy @var{layout}.  If @var{position} is @code{nil}, point is used.  If
 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
 183
 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