info/lispref.info-37

   1 This is ../info/lispref.info, produced by makeinfo version 4.0b from
   2 lispref/lispref.texi.
   3
   4 INFO-DIR-SECTION XEmacs Editor
   5 START-INFO-DIR-ENTRY
   6 * Lispref: (lispref).           XEmacs Lisp Reference Manual.
   7 END-INFO-DIR-ENTRY
   8
   9    Edition History:
  10
  11    GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
  12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
  13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
  14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
  15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
  16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
  17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
  18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
  19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
  20
  21    Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
  22 Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
  23 Copyright (C) 1995, 1996 Ben Wing.
  24
  25    Permission is granted to make and distribute verbatim copies of this
  26 manual provided the copyright notice and this permission notice are
  27 preserved on all copies.
  28
  29    Permission is granted to copy and distribute modified versions of
  30 this manual under the conditions for verbatim copying, provided that the
  31 entire resulting derived work is distributed under the terms of a
  32 permission notice identical to this one.
  33
  34    Permission is granted to copy and distribute translations of this
  35 manual into another language, under the above conditions for modified
  36 versions, except that this permission notice may be stated in a
  37 translation approved by the Foundation.
  38
  39    Permission is granted to copy and distribute modified versions of
  40 this manual under the conditions for verbatim copying, provided also
  41 that the section entitled "GNU General Public License" is included
  42 exactly as in the original, and provided that the entire resulting
  43 derived work is distributed under the terms of a permission notice
  44 identical to this one.
  45
  46    Permission is granted to copy and distribute translations of this
  47 manual into another language, under the above conditions for modified
  48 versions, except that the section entitled "GNU General Public License"
  49 may be included in a translation approved by the Free Software
  50 Foundation instead of in the original English.
  51
  52 \1f
  53 File: lispref.info,  Node: Glyph Properties,  Next: Glyph Convenience Functions,  Prev: Creating Glyphs,  Up: Glyph Functions
  54
  55 Glyph Properties
  56 ----------------
  57
  58    Each glyph has a list of properties, which control all of the
  59 aspects of the glyph's appearance.  The following symbols have
  60 predefined meanings:
  61
  62 `image'
  63      The image used to display the glyph.
  64
  65 `baseline'
  66      Percent above baseline that glyph is to be displayed.  Only for
  67      glyphs displayed inside of a buffer.
  68
  69 `contrib-p'
  70      Whether the glyph contributes to the height of the line it's on.
  71      Only for glyphs displayed inside of a buffer.
  72
  73 `face'
  74      Face of this glyph (_not_ a specifier).
  75
  76  - Function: set-glyph-property glyph property value &optional locale
  77           tag-set how-to-add
  78      This function changes a property of a GLYPH.
  79
  80      For built-in properties, the actual value of the property is a
  81      specifier and you cannot change this; but you can change the
  82      specifications within the specifier, and that is what this
  83      function will do.  For user-defined properties, you can use this
  84      function to either change the actual value of the property or, if
  85      this value is a specifier, change the specifications within it.
  86
  87      If PROPERTY is a built-in property, the specifications to be added
  88      to this property can be supplied in many different ways:
  89
  90         * If VALUE is a simple instantiator (e.g. a string naming a
  91           pixmap filename) or a list of instantiators, then the
  92           instantiator(s) will be added as a specification of the
  93           property for the given LOCALE (which defaults to `global' if
  94           omitted).
  95
  96         * If VALUE is a list of specifications (each of which is a cons
  97           of a locale and a list of instantiators), then LOCALE must be
  98           `nil' (it does not make sense to explicitly specify a locale
  99           in this case), and specifications will be added as given.
 100
 101         * If VALUE is a specifier (as would be returned by
 102           `glyph-property' if no LOCALE argument is given), then some
 103           or all of the specifications in the specifier will be added
 104           to the property.  In this case, the function is really
 105           equivalent to `copy-specifier' and LOCALE has the same
 106           semantics (if it is a particular locale, the specification
 107           for the locale will be copied; if a locale type,
 108           specifications for all locales of that type will be copied;
 109           if `nil' or `all', then all specifications will be copied).
 110
 111      HOW-TO-ADD should be either `nil' or one of the symbols `prepend',
 112      `append', `remove-tag-set-prepend', `remove-tag-set-append',
 113      `remove-locale', `remove-locale-type', or `remove-all'.  See
 114      `copy-specifier' and `add-spec-to-specifier' for a description of
 115      what each of these means.  Most of the time, you do not need to
 116      worry about this argument; the default behavior usually is fine.
 117
 118      In general, it is OK to pass an instance object (e.g. as returned
 119      by `glyph-property-instance') as an instantiator in place of an
 120      actual instantiator.  In such a case, the instantiator used to
 121      create that instance object will be used (for example, if you set
 122      a font-instance object as the value of the `font' property, then
 123      the font name used to create that object will be used instead).
 124      If some cases, however, doing this conversion does not make sense,
 125      and this will be noted in the documentation for particular types
 126      of instance objects.
 127
 128      If PROPERTY is not a built-in property, then this function will
 129      simply set its value if LOCALE is `nil'.  However, if LOCALE is
 130      given, then this function will attempt to add VALUE as the
 131      instantiator for the given LOCALE, using `add-spec-to-specifier'.
 132      If the value of the property is not a specifier, it will
 133      automatically be converted into a `generic' specifier.
 134
 135  - Function: glyph-property glyph property &optional locale
 136      This function returns GLYPH's value of the given PROPERTY.
 137
 138      If LOCALE is omitted, the GLYPH's actual value for PROPERTY will
 139      be returned.  For built-in properties, this will be a specifier
 140      object of a type appropriate to the property (e.g. a font or color
 141      specifier).  For other properties, this could be anything.
 142
 143      If LOCALE is supplied, then instead of returning the actual value,
 144      the specification(s) for the given locale or locale type will be
 145      returned.  This will only work if the actual value of PROPERTY is
 146      a specifier (this will always be the case for built-in properties,
 147      but may or may not apply to user-defined properties).  If the
 148      actual value of PROPERTY is not a specifier, this value will
 149      simply be returned regardless of LOCALE.
 150
 151      The return value will be a list of instantiators (e.g. vectors
 152      specifying pixmap data), or a list of specifications, each of
 153      which is a cons of a locale and a list of instantiators.
 154      Specifically, if LOCALE is a particular locale (a buffer, window,
 155      frame, device, or `global'), a list of instantiators for that
 156      locale will be returned.  Otherwise, if LOCALE is a locale type
 157      (one of the symbols `buffer', `window', `frame', or `device'), the
 158      specifications for all locales of that type will be returned.
 159      Finally, if LOCALE is `all', the specifications for all locales of
 160      all types will be returned.
 161
 162      The specifications in a specifier determine what the value of
 163      PROPERTY will be in a particular "domain" or set of circumstances,
 164      which is typically a particular Emacs window along with the buffer
 165      it contains and the frame and device it lies within.  The value is
 166      derived from the instantiator associated with the most specific
 167      locale (in the order buffer, window, frame, device, and `global')
 168      that matches the domain in question.  In other words, given a
 169      domain (i.e. an Emacs window, usually), the specifier for PROPERTY
 170      will first be searched for a specification whose locale is the
 171      buffer contained within that window; then for a specification
 172      whose locale is the window itself; then for a specification whose
 173      locale is the frame that the window is contained within; etc.  The
 174      first instantiator that is valid for the domain (usually this
 175      means that the instantiator is recognized by the device [i.e. the
 176      X server or TTY device] that the domain is on).  The function
 177      `glyph-property-instance' actually does all this, and is used to
 178      determine how to display the glyph.
 179
 180  - Function: glyph-property-instance glyph property &optional domain
 181           default no-fallback
 182      This function returns the instance of GLYPH's PROPERTY in the
 183      specified DOMAIN.
 184
 185      Under most circumstances, DOMAIN will be a particular window, and
 186      the returned instance describes how the specified property
 187      actually is displayed for that window and the particular buffer in
 188      it.  Note that this may not be the same as how the property
 189      appears when the buffer is displayed in a different window or
 190      frame, or how the property appears in the same window if you
 191      switch to another buffer in that window; and in those cases, the
 192      returned instance would be different.
 193
 194      The returned instance is an image-instance object, and you can
 195      query it using the appropriate image instance functions.  For
 196      example, you could use `image-instance-depth' to find out the
 197      depth (number of color planes) of a pixmap displayed in a
 198      particular window.  The results might be different from the
 199      results you would get for another window (perhaps the user
 200      specified a different image for the frame that window is on; or
 201      perhaps the same image was specified but the window is on a
 202      different X server, and that X server has different color
 203      capabilities from this one).
 204
 205      DOMAIN defaults to the selected window if omitted.
 206
 207      DOMAIN can be a frame or device, instead of a window.  The value
 208      returned for such a domain is used in special circumstances when a
 209      more specific domain does not apply; for example, a frame value
 210      might be used for coloring a toolbar, which is conceptually
 211      attached to a frame rather than a particular window.  The value is
 212      also useful in determining what the value would be for a
 213      particular window within the frame or device, if it is not
 214      overridden by a more specific specification.
 215
 216      If PROPERTY does not name a built-in property, its value will
 217      simply be returned unless it is a specifier object, in which case
 218      it will be instanced using `specifier-instance'.
 219
 220      Optional arguments DEFAULT and NO-FALLBACK are the same as in
 221      `specifier-instance'.  *Note Specifiers::.
 222
 223  - Function: remove-glyph-property glyph property &optional locale
 224           tag-set exact-p
 225      This function removes a property from a glyph.  For built-in
 226      properties, this is analogous to `remove-specifier'.  *Note
 227      remove-specifier-p: Specifiers, for the meaning of the LOCALE,
 228      TAG-SET, and EXACT-P arguments.
 229
 230 \1f
 231 File: lispref.info,  Node: Glyph Convenience Functions,  Next: Glyph Dimensions,  Prev: Glyph Properties,  Up: Glyph Functions
 232
 233 Glyph Convenience Functions
 234 ---------------------------
 235
 236    The following functions are provided for working with specific
 237 properties of a glyph.  Note that these are exactly like calling the
 238 general functions described above and passing in the appropriate value
 239 for PROPERTY.
 240
 241    Remember that if you want to determine the "value" of a specific
 242 glyph property, you probably want to use the `*-instance' functions.
 243 For example, to determine whether a glyph contributes to its line
 244 height, use `glyph-contrib-p-instance', not `glyph-contrib-p'. (The
 245 latter will return a boolean specifier or a list of specifications, and
 246 you probably aren't concerned with these.)
 247
 248  - Function: glyph-image glyph &optional locale
 249      This function is equivalent to calling `glyph-property' with a
 250      property of `image'.  The return value will be an image specifier
 251      if LOCALE is `nil' or omitted; otherwise, it will be a
 252      specification or list of specifications.
 253
 254  - Function: set-glyph-image glyph spec &optional locale tag-set
 255           how-to-add
 256      This function is equivalent to calling `set-glyph-property' with a
 257      property of `image'.
 258
 259  - Function: glyph-image-instance glyph &optional domain default
 260           no-fallback
 261      This function returns the instance of GLYPH's image in the given
 262      DOMAIN, and is equivalent to calling `glyph-property-instance'
 263      with a property of `image'.  The return value will be an image
 264      instance.
 265
 266      Normally DOMAIN will be a window or `nil' (meaning the selected
 267      window), and an instance object describing how the image appears
 268      in that particular window and buffer will be returned.
 269
 270  - Function: glyph-contrib-p glyph &optional locale
 271      This function is equivalent to calling `glyph-property' with a
 272      property of `contrib-p'.  The return value will be a boolean
 273      specifier if LOCALE is `nil' or omitted; otherwise, it will be a
 274      specification or list of specifications.
 275
 276  - Function: set-glyph-contrib-p glyph spec &optional locale tag-set
 277           how-to-add
 278      This function is equivalent to calling `set-glyph-property' with a
 279      property of `contrib-p'.
 280
 281  - Function: glyph-contrib-p-instance glyph &optional domain default
 282           no-fallback
 283      This function returns whether the glyph contributes to its line
 284      height in the given DOMAIN, and is equivalent to calling
 285      `glyph-property-instance' with a property of `contrib-p'.  The
 286      return value will be either `nil' or `t'. (Normally DOMAIN will be
 287      a window or `nil', meaning the selected window.)
 288
 289  - Function: glyph-baseline glyph &optional locale
 290      This function is equivalent to calling `glyph-property' with a
 291      property of `baseline'.  The return value will be a specifier if
 292      LOCALE is `nil' or omitted; otherwise, it will be a specification
 293      or list of specifications.
 294
 295  - Function: set-glyph-baseline glyph spec &optional locale tag-set
 296           how-to-add
 297      This function is equivalent to calling `set-glyph-property' with a
 298      property of `baseline'.
 299
 300  - Function: glyph-baseline-instance glyph &optional domain default
 301           no-fallback
 302      This function returns the instance of GLYPH's baseline value in
 303      the given DOMAIN, and is equivalent to calling
 304      `glyph-property-instance' with a property of `baseline'.  The
 305      return value will be an integer or `nil'.
 306
 307      Normally DOMAIN will be a window or `nil' (meaning the selected
 308      window), and an instance object describing the baseline value
 309      appears in that particular window and buffer will be returned.
 310
 311  - Function: glyph-face glyph
 312      This function returns the face of GLYPH. (Remember, this is not a
 313      specifier, but a simple property.)
 314
 315  - Function: set-glyph-face glyph face
 316      This function changes the face of GLYPH to FACE.
 317
 318 \1f
 319 File: lispref.info,  Node: Glyph Dimensions,  Prev: Glyph Convenience Functions,  Up: Glyph Functions
 320
 321 Glyph Dimensions
 322 ----------------
 323
 324  - Function: glyph-width glyph &optional window
 325      This function returns the width of GLYPH on WINDOW.  This may not
 326      be exact as it does not take into account all of the context that
 327      redisplay will.
 328
 329  - Function: glyph-ascent glyph &optional window
 330      This function returns the ascent value of GLYPH on WINDOW.  This
 331      may not be exact as it does not take into account all of the
 332      context that redisplay will.
 333
 334  - Function: glyph-descent glyph &optional window
 335      This function returns the descent value of GLYPH on WINDOW.  This
 336      may not be exact as it does not take into account all of the
 337      context that redisplay will.
 338
 339  - Function: glyph-height glyph &optional window
 340      This function returns the height of GLYPH on WINDOW.  (This is
 341      equivalent to the sum of the ascent and descent values.)  This may
 342      not be exact as it does not take into account all of the context
 343      that redisplay will.
 344
 345 \1f
 346 File: lispref.info,  Node: Images,  Next: Glyph Types,  Prev: Glyph Functions,  Up: Glyphs
 347
 348 Images
 349 ======
 350
 351 * Menu:
 352
 353 * Image Specifiers::            Specifying how an image will appear.
 354 * Image Instantiator Conversion::
 355                                 Conversion is applied to image instantiators
 356                                   at the time they are added to an
 357                                   image specifier or at the time they
 358                                   are passed to `make-image-instance'.
 359 * Image Instances::             What an image specifier gets instanced as.
 360
 361 \1f
 362 File: lispref.info,  Node: Image Specifiers,  Next: Image Instantiator Conversion,  Up: Images
 363
 364 Image Specifiers
 365 ----------------
 366
 367    An image specifier is used to describe the actual image of a glyph.
 368 It works like other specifiers (*note Specifiers::), in that it contains
 369 a number of specifications describing how the image should appear in a
 370 variety of circumstances.  These specifications are called "image
 371 instantiators".  When XEmacs wants to display the image, it instantiates
 372 the image into an "image instance".  Image instances are their own
 373 primitive object type (similar to font instances and color instances),
 374 describing how the image appears in a particular domain. (On the other
 375 hand, image instantiators, which are just descriptions of how the image
 376 should appear, are represented using strings or vectors.)
 377
 378  - Function: image-specifier-p object
 379      This function returns non-`nil' if OBJECT is an image specifier.
 380      Usually, an image specifier results from calling `glyph-image' on
 381      a glyph.
 382
 383  - Function: make-image-specifier spec-list
 384      This function creates a new image specifier object and initializes
 385      it according to SPEC-LIST. *Note Specifiers::.
 386
 387      Note that, in practice, you rarely, if ever, need to actually
 388      create an image specifier! (This function exists mainly for
 389      completeness.) Pretty much the only use for image specifiers is to
 390      control how glyphs are displayed, and the image specifier
 391      associated with a glyph (the `image' property of a glyph) is
 392      created automatically when a glyph is created and need not (and
 393      cannot, for that matter) ever be changed (*note Glyphs::).  In
 394      fact, the design decision to create a separate image specifier
 395      type, rather than make glyphs themselves be specifiers, is
 396      debatable--the other properties of glyphs are rarely used and could
 397      conceivably have been incorporated into the glyph's instantiator.
 398      The rarely used glyph types (buffer, pointer, icon) could also
 399      have been incorporated into the instantiator.
 400
 401    Image instantiators come in many formats: `xbm', `xpm', `gif',
 402 `jpeg', etc.  This describes the format of the data describing the
 403 image.  The resulting image instances also come in many
 404 types--`mono-pixmap', `color-pixmap', `text', `pointer', etc.  This
 405 refers to the behavior of the image and the sorts of places it can
 406 appear. (For example, a color-pixmap image has fixed colors specified
 407 for it, while a mono-pixmap image comes in two unspecified shades
 408 "foreground" and "background" that are determined from the face of the
 409 glyph or surrounding text; a text image appears as a string of text and
 410 has an unspecified foreground, background, and font; a pointer image
 411 behaves like a mono-pixmap image but can only be used as a mouse
 412 pointer [mono-pixmap images cannot be used as mouse pointers]; etc.) It
 413 is important to keep the distinction between image instantiator format
 414 and image instance type in mind.  Typically, a given image instantiator
 415 format can result in many different image instance types (for example,
 416 `xpm' can be instanced as `color-pixmap', `mono-pixmap', or `pointer';
 417 whereas `cursor-font' can be instanced only as `pointer'), and a
 418 particular image instance type can be generated by many different image
 419 instantiator formats (e.g.  `color-pixmap' can be generated by `xpm',
 420 `gif', `jpeg', etc.).
 421
 422    *Note Image Instances::, for a more detailed discussion of image
 423 instance types.
 424
 425    An image instantiator should be a string or a vector of the form
 426
 427       `[FORMAT :KEYWORD VALUE ...]'
 428
 429    i.e. a format symbol followed by zero or more alternating
 430 keyword-value pairs.  The "format" field should be a symbol, one of
 431
 432 `nothing'
 433      Don't display anything; no keywords are valid for this.  Can only
 434      be instanced as `nothing'.
 435
 436 `string'
 437      Display this image as a text string.  Can only be instanced as
 438      `text', although support for instancing as `mono-pixmap' should be
 439      added.
 440
 441 `formatted-string'
 442      Display this image as a text string with replaceable fields,
 443      similar to a modeline format string; not currently implemented.
 444
 445 `xbm'
 446      An X bitmap; only if X support was compiled into this XEmacs.  Can
 447      be instanced as `mono-pixmap', `color-pixmap', or `pointer'.
 448
 449 `xpm'
 450      An XPM pixmap; only if XPM support was compiled into this XEmacs.
 451      Can be instanced as `color-pixmap', `mono-pixmap', or `pointer'.
 452      XPM is an add-on library for X that was designed to rectify the
 453      shortcomings of the XBM format.  Most implementations of X include
 454      the XPM library as a standard part.  If your vendor does not, it
 455      is highly recommended that you download it and install it.  You
 456      can get it from the standard XEmacs FTP site, among other places.
 457
 458 `xface'
 459      An X-Face bitmap, used to encode people's faces in e-mail messages;
 460      only if X-Face support was compiled into this XEmacs.  Can be
 461      instanced as `mono-pixmap', `color-pixmap', or `pointer'.
 462
 463 `gif'
 464      A GIF87 or GIF89 image; only if GIF support was compiled into this
 465      XEmacs.  Can be instanced as `color-pixmap'.  Note that XEmacs
 466      includes GIF decoding functions as a standard part of it, so if
 467      you have X support, you will normally have GIF support, unless you
 468      explicitly disable it at configure time.
 469
 470 `jpeg'
 471      A JPEG-format image; only if JPEG support was compiled into this
 472      XEmacs.  Can be instanced as `color-pixmap'.  If you have the JPEG
 473      libraries present on your system when XEmacs is built, XEmacs will
 474      automatically detect this and use them, unless you explicitly
 475      disable it at configure time.
 476
 477 `png'
 478      A PNG/GIF24 image; only if PNG support was compiled into this
 479      XEmacs.  Can be instanced as `color-pixmap'.
 480
 481 `tiff'
 482      A TIFF-format image; only if TIFF support was compiled into this
 483      XEmacs.
 484
 485 `cursor-font'
 486      One of the standard cursor-font names, such as `watch' or
 487      `right_ptr' under X.  Under X, this is, more specifically, any of
 488      the standard cursor names from appendix B of the Xlib manual [also
 489      known as the file `<X11/cursorfont.h>'] minus the `XC_' prefix.  On
 490      other window systems, the valid names will be specific to the type
 491      of window system.  Can only be instanced as `pointer'.
 492
 493 `font'
 494      A glyph from a font; i.e. the name of a font, and glyph index into
 495      it of the form `FONT fontname index [[mask-font] mask-index]'.
 496      Only if X support was compiled into this XEmacs.  Currently can
 497      only be instanced as `pointer', although this should probably be
 498      fixed.
 499
 500 `mswindows-resource'
 501      An MS Windows pointer resource.  Specifies a resource to retrieve
 502      directly from the system (an OEM resource) or from a file,
 503      particularly an executable file.  If the resource is to be
 504      retrieved from a file, use :file and optionally :resource-id.
 505      Otherwise use :resource-id.  Always specify :resource-type to
 506      specify the type (cursor, bitmap or icon) of the resource.
 507      Possible values for :resource-id are listed below.  Can be
 508      instanced as `pointer' or `color-pixmap'.
 509
 510 `subwindow'
 511      An embedded windowing system window.  Can only be instanced as
 512      `subwindow'.
 513
 514 `button'
 515      A button widget; either a push button, radio button or toggle
 516      button.  Can only be instanced as `widget'.
 517
 518 `combo-box'
 519      A drop list of selectable items in a widget, for editing text.
 520      Can only be instanced as `widget'.
 521
 522 `edit-field'
 523      A text editing widget.  Can only be instanced as `widget'.
 524
 525 `label'
 526      A static, text-only, widget; for displaying text.  Can only be
 527      instanced as `widget'.
 528
 529 `layout'
 530      A widget for controlling the positioning of children underneath it.
 531      Through the use of nested layouts, a widget hierarchy can be
 532      created which can have the appearance of any standard dialog box
 533      or similar arrangement; all of this is counted as one "glyph" and
 534      could appear in many of the places that expect a single glyph.
 535      Can only be instanced as `widget'.
 536
 537 `native-layout'
 538      The native version of a layout widget.  Can only be instanced as
 539      `widget'.
 540
 541 `progress-gauge'
 542      A sliding widget, for showing progress.  Can only be instanced as
 543      `widget'.
 544
 545 `tab-control'
 546      A tab widget; a series of user selectable tabs.  Can only be
 547      instanced as `widget'.
 548
 549 `tree-view'
 550      A folding widget.  Can only be instanced as `widget'.
 551
 552 `scrollbar'
 553      A scrollbar widget.  Can only be instanced as `widget'.
 554
 555 `autodetect'
 556      XEmacs tries to guess what format the data is in.  If X support
 557      exists, the data string will be checked to see if it names a
 558      filename.  If so, and this filename contains XBM or XPM data, the
 559      appropriate sort of pixmap or pointer will be created. [This
 560      includes picking up any specified hotspot or associated mask
 561      file.] Otherwise, if `pointer' is one of the allowable
 562      image-instance types and the string names a valid cursor-font
 563      name, the image will be created as a pointer.  Otherwise, the
 564      image will be displayed as text.  If no X support exists, the
 565      image will always be displayed as text.
 566
 567 `inherit'
 568      Inherit from the background-pixmap property of a face.  Can only be
 569      instanced as `mono-pixmap'.
 570
 571    The valid keywords are:
 572
 573 `:data'
 574      Inline data.  For most formats above, this should be a string.  For
 575      XBM images, this should be a list of three elements: width,
 576      height, and a string of bit data.  This keyword is not valid for
 577      instantiator format `nothing'.
 578
 579 `:file'
 580      Data is contained in a file.  The value is the name of this file.
 581      If both `:data' and `:file' are specified, the image is created
 582      from what is specified in `:data' and the string in `:file'
 583      becomes the value of the `image-instance-file-name' function when
 584      applied to the resulting image-instance.  This keyword is not
 585      valid for instantiator formats `nothing', `string',
 586      `formatted-string', `cursor-font', `font', and `autodetect'.
 587
 588 `:foreground'
 589 `:background'
 590      For `xbm', `xface', `cursor-font', and `font'.  These keywords
 591      allow you to explicitly specify foreground and background colors.
 592      The argument should be anything acceptable to
 593      `make-color-instance'.  This will cause what would be a
 594      `mono-pixmap' to instead be colorized as a two-color color-pixmap,
 595      and specifies the foreground and/or background colors for a pointer
 596      instead of black and white.
 597
 598 `:mask-data'
 599      For `xbm' and `xface'.  This specifies a mask to be used with the
 600      bitmap.  The format is a list of width, height, and bits, like for
 601      `:data'.
 602
 603 `:mask-file'
 604      For `xbm' and `xface'.  This specifies a file containing the mask
 605      data.  If neither a mask file nor inline mask data is given for an
 606      XBM image, and the XBM image comes from a file, XEmacs will look
 607      for a mask file with the same name as the image file but with
 608      `Mask' or `msk' appended.  For example, if you specify the XBM file
 609      `left_ptr' [usually located in `/usr/include/X11/bitmaps'], the
 610      associated mask file `left_ptrmsk' will automatically be picked up.
 611
 612 `:hotspot-x'
 613 `:hotspot-y'
 614      For `xbm' and `xface'.  These keywords specify a hotspot if the
 615      image is instantiated as a `pointer'.  Note that if the XBM image
 616      file specifies a hotspot, it will automatically be picked up if no
 617      explicit hotspot is given.
 618
 619 `:color-symbols'
 620      Only for `xpm'.  This specifies an alist that maps strings that
 621      specify symbolic color names to the actual color to be used for
 622      that symbolic color (in the form of a string or a color-specifier
 623      object).  If this is not specified, the contents of
 624      `xpm-color-symbols' are used to generate the alist.
 625
 626 `:resource-id'
 627      Only for `mswindows-resource'.  This must be either an integer
 628      (which directly specifies a resource number) or a string.  Valid
 629      strings are
 630
 631      For bitmaps:
 632
 633      "close", "uparrow", "dnarrow", "rgarrow", "lfarrow", "reduce",
 634      "zoom", "restore", "reduced", "zoomd", "restored", "uparrowd",
 635      "dnarrowd", "rgarrowd", "lfarrowd", "mnarrow", "combo",
 636      "uparrowi", "dnarrowi", "rgarrowi", "lfarrowi", "size", "btsize",
 637      "check", "checkboxes", and "btncorners".
 638
 639      For cursors:
 640
 641      "normal", "ibeam", "wait", "cross", "up", "sizenwse", "sizenesw",
 642      "sizewe", "sizens", "sizeall", and "no".
 643
 644      For icons:
 645
 646      "sample", "hand", "ques", "bang", "note", and "winlogo".
 647
 648 `:resource-type'
 649      Only for `mswindows-resource'.  This must be a symbol, either
 650      `cursor', `icon', or `bitmap', specifying the type of resource to
 651      be retrieved.
 652
 653 `:face'
 654      Only for `inherit'.  This specifies the face to inherit from.  For
 655      widgets this also specifies the face to use for display. It
 656      defaults to gui-element-face.
 657
 658    Keywords accepted as menu item specs are also accepted by widgets.
 659 These are `:selected', `:active', `:suffix', `:keys', `:style',
 660 `:filter', `:config', `:included', `:key-sequence', `:accelerator',
 661 `:label' and `:callback'.
 662
 663    If instead of a vector, the instantiator is a string, it will be
 664 converted into a vector by looking it up according to the specs in the
 665 `console-type-image-conversion-list' for the console type of the domain
 666 (usually a window; sometimes a frame or device) over which the image is
 667 being instantiated.
 668
 669    If the instantiator specifies data from a file, the data will be
 670 read in at the time that the instantiator is added to the image
 671 specifier (which may be well before the image is actually displayed),
 672 and the instantiator will be converted into one of the inline-data
 673 forms, with the filename retained using a `:file' keyword.  This
 674 implies that the file must exist when the instantiator is added to the
 675 image, but does not need to exist at any other time (e.g. it may safely
 676 be a temporary file).
 677
 678  - Function: valid-image-instantiator-format-p format &optional locale
 679      This function returns non-`nil' if FORMAT is a valid image
 680      instantiator format.
 681
 682      If LOCALE is non-`nil' then the format is checked in that locale.
 683      If LOCALE is `nil' the current console is used.
 684
 685      Note that the return value for many formats listed above depends on
 686      whether XEmacs was compiled with support for that format.
 687
 688  - Function: image-instantiator-format-list
 689      This function return a list of valid image-instantiator formats.
 690
 691  - Variable: xpm-color-symbols
 692      This variable holds definitions of logical color-names used when
 693      reading XPM files.  Elements of this list should be of the form
 694      `(COLOR-NAME FORM-TO-EVALUATE)'.  The COLOR-NAME should be a
 695      string, which is the name of the color to define; the
 696      FORM-TO-EVALUATE should evaluate to a color specifier object, or a
 697      string to be passed to `make-color-instance' (*note Colors::).  If
 698      a loaded XPM file references a symbolic color called COLOR-NAME,
 699      it will display as the computed color instead.
 700
 701      The default value of this variable defines the logical color names
 702      `"foreground"' and `"background"' to be the colors of the
 703      `default' face.
 704
 705  - Variable: x-bitmap-file-path
 706      A list of the directories in which X bitmap files may be found.
 707      If `nil', this is initialized from the `"*bitmapFilePath"'
 708      resource.  This is used by the `make-image-instance' function
 709      (however, note that if the environment variable `XBMLANGPATH' is
 710      set, it is consulted first).
 711
 712 \1f
 713 File: lispref.info,  Node: Image Instantiator Conversion,  Next: Image Instances,  Prev: Image Specifiers,  Up: Images
 714
 715 Image Instantiator Conversion
 716 -----------------------------
 717
 718  - Function: set-console-type-image-conversion-list console-type list
 719      This function sets the image-conversion-list for consoles of the
 720      given CONSOLE-TYPE.  The image-conversion-list specifies how image
 721      instantiators that are strings should be interpreted.  Each
 722      element of the list should be a list of two elements (a regular
 723      expression string and a vector) or a list of three elements (the
 724      preceding two plus an integer index into the vector).  The string
 725      is converted to the vector associated with the first matching
 726      regular expression.  If a vector index is specified, the string
 727      itself is substituted into that position in the vector.
 728
 729      Note: The conversion above is applied when the image instantiator
 730      is added to an image specifier, not when the specifier is actually
 731      instantiated.  Therefore, changing the image-conversion-list only
 732      affects newly-added instantiators.  Existing instantiators in
 733      glyphs and image specifiers will not be affected.
 734
 735  - Function: console-type-image-conversion-list console-type
 736      This function returns the image-conversion-list for consoles of
 737      the given CONSOLE-TYPE.
 738
 739 \1f
 740 File: lispref.info,  Node: Image Instances,  Prev: Image Instantiator Conversion,  Up: Images
 741
 742 Image Instances
 743 ---------------
 744
 745    Image-instance objects encapsulate the way a particular image
 746 (pixmap, etc.) is displayed on a particular device.
 747
 748    In most circumstances, you do not need to directly create image
 749 instances; use a glyph instead.  However, it may occasionally be useful
 750 to explicitly create image instances, if you want more control over the
 751 instantiation process.
 752
 753  - Function: image-instance-p object
 754      This function returns non-`nil' if OBJECT is an image instance.
 755
 756 * Menu:
 757
 758 * Image Instance Types::         Each image instances has a particular type.
 759 * Image Instance Functions::     Functions for working with image instances.
 760
 761 \1f
 762 File: lispref.info,  Node: Image Instance Types,  Next: Image Instance Functions,  Up: Image Instances
 763
 764 Image Instance Types
 765 ....................
 766
 767    Image instances come in a number of different types.  The type of an
 768 image instance specifies the nature of the image: Whether it is a text
 769 string, a mono pixmap, a color pixmap, etc.
 770
 771    The valid image instance types are
 772
 773 `nothing'
 774      Nothing is displayed.
 775
 776 `text'
 777      Displayed as text.  The foreground and background colors and the
 778      font of the text are specified independent of the pixmap.
 779      Typically these attributes will come from the face of the
 780      surrounding text, unless a face is specified for the glyph in
 781      which the image appears.
 782
 783 `mono-pixmap'
 784      Displayed as a mono pixmap (a pixmap with only two colors where the
 785      foreground and background can be specified independent of the
 786      pixmap; typically the pixmap assumes the foreground and background
 787      colors of the text around it, unless a face is specified for the
 788      glyph in which the image appears).
 789
 790 `color-pixmap'
 791      Displayed as a color pixmap.
 792
 793 `pointer'
 794      Used as the mouse pointer for a window.
 795
 796 `subwindow'
 797      A child window that is treated as an image.  This allows (e.g.)
 798      another program to be responsible for drawing into the window.
 799      Not currently implemented.
 800
 801  - Function: valid-image-instance-type-p type
 802      This function returns non-`nil' if TYPE is a valid image instance
 803      type.
 804
 805  - Function: image-instance-type-list
 806      This function returns a list of the valid image instance types.
 807
 808  - Function: image-instance-type image-instance
 809      This function returns the type of the given image instance.  The
 810      return value will be one of `nothing', `text', `mono-pixmap',
 811      `color-pixmap', `pointer', or `subwindow'.
 812
 813  - Function: text-image-instance-p object
 814      This function returns non-`nil' if OBJECT is an image instance of
 815      type `text'.
 816
 817  - Function: mono-pixmap-image-instance-p object
 818      This function returns non-`nil' if OBJECT is an image instance of
 819      type `mono-pixmap'.
 820
 821  - Function: color-pixmap-image-instance-p object
 822      This function returns non-`nil' if OBJECT is an image instance of
 823      type `color-pixmap'.
 824
 825  - Function: pointer-image-instance-p object
 826      This function returns non-`nil' if OBJECT is an image instance of
 827      type `pointer'.
 828
 829  - Function: subwindow-image-instance-p object
 830      This function returns non-`nil' if OBJECT is an image instance of
 831      type `subwindow'.
 832
 833  - Function: nothing-image-instance-p object
 834      This function returns non-`nil' if OBJECT is an image instance of
 835      type `nothing'.
 836
 837  - Function: widget-image-instance-p object
 838      Return `t' if OBJECT is an image instance of type `widget'.
 839
 840 \1f
 841 File: lispref.info,  Node: Image Instance Functions,  Prev: Image Instance Types,  Up: Image Instances
 842
 843 Image Instance Functions
 844 ........................
 845
 846  - Function: make-image-instance data &optional domain dest-types
 847           noerror
 848      This function creates a new image-instance object.
 849
 850      DATA is an image instantiator, which describes the image (*note
 851      Image Specifiers::).
 852
 853      DEST-TYPES should be a list of allowed image instance types that
 854      can be generated.  The DEST-TYPES list is unordered.  If multiple
 855      destination types are possible for a given instantiator, the "most
 856      natural" type for the instantiator's format is chosen. (For XBM,
 857      the most natural types are `mono-pixmap', followed by
 858      `color-pixmap', followed by `pointer'.  For the other normal image
 859      formats, the most natural types are `color-pixmap', followed by
 860      `mono-pixmap', followed by `pointer'.  For the string and
 861      formatted-string formats, the most natural types are `text',
 862      followed by `mono-pixmap' (not currently implemented), followed by
 863      `color-pixmap' (not currently implemented).  For MS Windows
 864      resources, the most natural type for pointer resources is
 865      `pointer', and for the others it's `color-pixmap'.  The other
 866      formats can only be instantiated as one type. (If you want to
 867      control more specifically the order of the types into which an
 868      image is instantiated, just call `make-image-instance' repeatedly
 869      until it succeeds, passing less and less preferred destination
 870      types each time.
 871
 872      If DEST-TYPES is omitted, all possible types are allowed.
 873
 874      DOMAIN specifies the domain to which the image instance will be
 875      attached.  This domain is termed the "governing domain".  The type
 876      of the governing domain depends on the image instantiator format.
 877      (Although, more correctly, it should probably depend on the image
 878      instance type.) For example, pixmap image instances are specific
 879      to a device, but widget image instances are specific to a
 880      particular XEmacs window because in order to display such a widget
 881      when two windows onto the same buffer want to display the widget,
 882      two separate underlying widgets must be created. (That's because a
 883      widget is actually a child window-system window, and all
 884      window-system windows have a unique existence on the screen.) This
 885      means that the governing domain for a pixmap image instance will
 886      be some device (most likely, the only existing device), whereas
 887      the governing domain for a widget image instance will be some
 888      XEmacs window.
 889
 890      If you specify an overly general DOMAIN (e.g. a frame when a
 891      window was wanted), an error is signaled.  If you specify an overly
 892      specific DOMAIN (e.g. a window when a device was wanted), the
 893      corresponding general domain is fetched and used instead.  For
 894      `make-image-instance', it makes no difference whether you specify
 895      an overly specific domain or the properly general domain derived
 896      from it.  However, it does matter when creating an image instance
 897      by instantiating a specifier or glyph (e.g. with
 898      `glyph-image-instance'), because the more specific domain causes
 899      spec lookup to start there and proceed to more general domains. (It
 900      would also matter when creating an image instance with an
 901      instantiator format of `inherit', but we currently disallow this.
 902      #### We should fix this.)  n If omitted, DOMAIN defaults to the
 903      selected window.
 904
 905      NOERROR controls what happens when the image cannot be generated.
 906      If `nil', an error message is generated.  If `t', no messages are
 907      generated and this function returns `nil'.  If anything else, a
 908      warning message is generated and this function returns `nil'.
 909
 910  - Function: colorize-image-instance image-instance foreground
 911           background
 912      This function makes the image instance be displayed in the given
 913      colors.  Image instances come in two varieties: bitmaps, which are
 914      1 bit deep which are rendered in the prevailing foreground and
 915      background colors; and pixmaps, which are of arbitrary depth
 916      (including 1) and which have the colors explicitly specified.
 917      This function converts a bitmap to a pixmap.  If the image
 918      instance was a pixmap already, nothing is done (and `nil' is
 919      returned).  Otherwise `t' is returned.
 920
 921  - Function: image-instance-name image-instance
 922      This function returns the name of the given image instance.
 923
 924  - Function: image-instance-domain image-instance
 925      Return the governing domain of the given IMAGE-INSTANCE.  The
 926      governing domain of an image instance is the domain that the image
 927      instance is specific to.  It is _NOT_ necessarily the domain that
 928      was given to the call to `specifier-instance' that resulted in the
 929      creation of this image instance.  See `make-image-instance' for
 930      more information on governing domains.
 931
 932  - Function: image-instance-string image-instance
 933      This function returns the string of the given image instance.
 934      This will only be non-`nil' for text image instances.
 935
 936  - Function: image-instance-file-name image-instance
 937      This function returns the file name from which IMAGE-INSTANCE was
 938      read, if known.
 939
 940  - Function: image-instance-mask-file-name image-instance
 941      This function returns the file name from which IMAGE-INSTANCE's
 942      mask was read, if known.
 943
 944  - Function: image-instance-depth image-instance
 945      This function returns the depth of the image instance.  This is 0
 946      for a mono pixmap, or a positive integer for a color pixmap.
 947
 948  - Function: image-instance-height image-instance
 949      This function returns the height of the image instance, in pixels.
 950
 951  - Function: image-instance-width image-instance
 952      This function returns the width of the image instance, in pixels.
 953
 954  - Function: image-instance-hotspot-x image-instance
 955      This function returns the X coordinate of the image instance's
 956      hotspot, if known.  This is a point relative to the origin of the
 957      pixmap.  When an image is used as a mouse pointer, the hotspot is
 958      the point on the image that sits over the location that the
 959      pointer points to.  This is, for example, the tip of the arrow or
 960      the center of the crosshairs.
 961
 962      This will always be `nil' for a non-pointer image instance.
 963
 964  - Function: image-instance-hotspot-y image-instance
 965      This function returns the Y coordinate of the image instance's
 966      hotspot, if known.
 967
 968  - Function: image-instance-foreground image-instance
 969      This function returns the foreground color of IMAGE-INSTANCE, if
 970      applicable.  This will be a color instance or `nil'. (It will only
 971      be non-`nil' for colorized mono pixmaps and for pointers.)
 972
 973  - Function: image-instance-background image-instance
 974      This function returns the background color of IMAGE-INSTANCE, if
 975      applicable.  This will be a color instance or `nil'. (It will only
 976      be non-`nil' for colorized mono pixmaps and for pointers.)
 977
 978 \1f
 979 File: lispref.info,  Node: Glyph Types,  Next: Mouse Pointer,  Prev: Images,  Up: Glyphs
 980
 981 Glyph Types
 982 ===========
 983
 984    Each glyph has a particular type, which controls how the glyph's
 985 image is generated.  Each glyph type has a corresponding list of
 986 allowable image instance types that can be generated.  When you call
 987 `glyph-image-instance' to retrieve the image instance of a glyph,
 988 XEmacs does the equivalent of calling `make-image-instance' and passing
 989 in DEST-TYPES the list of allowable image instance types for the
 990 glyph's type.
 991
 992    * `buffer' glyphs can be used as the begin-glyph or end-glyph of an
 993      extent, in the modeline, and in the toolbar.  Their image can be
 994      instantiated as `nothing', `mono-pixmap', `color-pixmap', `text',
 995      and `subwindow'.
 996
 997    * `pointer' glyphs can be used to specify the mouse pointer.  Their
 998      image can be instantiated as `pointer'.
 999
1000    * `icon' glyphs can be used to specify the icon used when a frame is
1001      iconified.  Their image can be instantiated as `mono-pixmap' and
1002      `color-pixmap'.
1003
1004  - Function: glyph-type glyph
1005      This function returns the type of the given glyph.  The return
1006      value will be a symbol, one of `buffer', `pointer', or `icon'.
1007
1008  - Function: valid-glyph-type-p glyph-type
1009      Given a GLYPH-TYPE, this function returns non-`nil' if it is valid.
1010
1011  - Function: glyph-type-list
1012      This function returns a list of valid glyph types.
1013
1014  - Function: buffer-glyph-p object
1015      This function returns non-`nil' if OBJECT is a glyph of type
1016      `buffer'.
1017
1018  - Function: icon-glyph-p object
1019      This function returns non-`nil' if OBJECT is a glyph of type
1020      `icon'.
1021
1022  - Function: pointer-glyph-p object
1023      This function returns non-`nil' if OBJECT is a glyph of type
1024      `pointer'.
1025
1026 \1f
1027 File: lispref.info,  Node: Mouse Pointer,  Next: Redisplay Glyphs,  Prev: Glyph Types,  Up: Glyphs
1028
1029 Mouse Pointer
1030 =============
1031
1032    The shape of the mouse pointer when over a particular section of a
1033 frame is controlled using various glyph variables.  Since the image of
1034 a glyph is a specifier, it can be controlled on a per-buffer,
1035 per-frame, per-window, or per-device basis.
1036
1037    You should use `set-glyph-image' to set the following variables,
1038 _not_ `setq'.
1039
1040  - Glyph: text-pointer-glyph
1041      This variable specifies the shape of the mouse pointer when over
1042      text.
1043
1044  - Glyph: nontext-pointer-glyph
1045      This variable specifies the shape of the mouse pointer when over a
1046      buffer, but not over text.  If unspecified in a particular domain,
1047      `text-pointer-glyph' is used.
1048
1049  - Glyph: modeline-pointer-glyph
1050      This variable specifies the shape of the mouse pointer when over
1051      the modeline.  If unspecified in a particular domain,
1052      `nontext-pointer-glyph' is used.
1053
1054  - Glyph: selection-pointer-glyph
1055      This variable specifies the shape of the mouse pointer when over a
1056      selectable text region.  If unspecified in a particular domain,
1057      `text-pointer-glyph' is used.
1058
1059  - Glyph: gc-pointer-glyph
1060      This variable specifies the shape of the mouse pointer when a
1061      garbage collection is in progress.  If the selected window is on a
1062      window system and this glyph specifies a value (i.e. a pointer
1063      image instance) in the domain of the selected window, the pointer
1064      will be changed as specified during garbage collection.
1065      Otherwise, a message will be printed in the echo area, as
1066      controlled by `gc-message'.
1067
1068  - Glyph: busy-pointer-glyph
1069      This variable specifies the shape of the mouse pointer when XEmacs
1070      is busy.  If unspecified in a particular domain, the pointer is
1071      not changed when XEmacs is busy.
1072
1073  - Glyph: menubar-pointer-glyph
1074      This variable specifies the shape of the mouse pointer when over
1075      the menubar.  If unspecified in a particular domain, the
1076      window-system-provided default pointer is used.
1077
1078  - Glyph: scrollbar-pointer-glyph
1079      This variable specifies the shape of the mouse pointer when over a
1080      scrollbar.  If unspecified in a particular domain, the
1081      window-system-provided default pointer is used.
1082
1083  - Glyph: toolbar-pointer-glyph
1084      This variable specifies the shape of the mouse pointer when over a
1085      toolbar.  If unspecified in a particular domain,
1086      `nontext-pointer-glyph' is used.
1087
1088    Internally, these variables are implemented in
1089 `default-mouse-motion-handler', and thus only take effect when the
1090 mouse moves.  That function calls `set-frame-pointer', which sets the
1091 current mouse pointer for a frame.
1092
1093  - Function: set-frame-pointer frame image-instance
1094      This function sets the mouse pointer of FRAME to the given pointer
1095      image instance.  You should not call this function directly.  (If
1096      you do, the pointer will change again the next time the mouse
1097      moves.)
1098
1099 \1f
1100 File: lispref.info,  Node: Redisplay Glyphs,  Next: Subwindows,  Prev: Mouse Pointer,  Up: Glyphs
1101
1102 Redisplay Glyphs
1103 ================
1104
1105  - Glyph: truncation-glyph
1106      This variable specifies what is displayed at the end of truncated
1107      lines.
1108
1109  - Glyph: continuation-glyph
1110      This variable specifies what is displayed at the end of wrapped
1111      lines.
1112
1113  - Glyph: octal-escape-glyph
1114      This variable specifies what to prefix character codes displayed
1115      in octal with.
1116
1117  - Glyph: hscroll-glyph
1118      This variable specifies what to display at the beginning of
1119      horizontally scrolled lines.
1120
1121  - Glyph: invisible-text-glyph
1122      This variable specifies what to use to indicate the presence of
1123      invisible text.  This is the glyph that is displayed when an
1124      ellipsis is called for, according to `selective-display-ellipses'
1125      or `buffer-invisibility-spec').  Normally this is three dots
1126      ("...").
1127
1128  - Glyph: control-arrow-glyph
1129      This variable specifies what to use as an arrow for control
1130      characters.
1131
1132 \1f
1133 File: lispref.info,  Node: Subwindows,  Prev: Redisplay Glyphs,  Up: Glyphs
1134
1135 Subwindows
1136 ==========
1137
1138    Subwindows are not currently implemented.
1139
1140  - Function: subwindowp object
1141      This function returns non-`nil' if OBJECT is a subwindow.
1142
1143 \1f
1144 File: lispref.info,  Node: Annotations,  Next: Display,  Prev: Glyphs,  Up: Top
1145
1146 Annotations
1147 ***********
1148
1149    An "annotation" is a pixmap or string that is not part of a buffer's
1150 text but is displayed next to a particular location in a buffer.
1151 Annotations can be displayed intermixed with text, in any whitespace at
1152 the beginning or end of a line, or in a special area at the left or
1153 right side of the frame called a "margin", whose size is controllable.
1154 Annotations are implemented using extents (*note Extents::); but you
1155 can work with annotations without knowing how extents work.
1156
1157 * Menu:
1158
1159 * Annotation Basics::           Introduction to annotations.
1160 * Annotation Primitives::       Creating and deleting annotations.
1161 * Annotation Properties::       Retrieving and changing the characteristics
1162                                   of an annotation.
1163 * Margin Primitives::           Controlling the size of the margins.
1164 * Locating Annotations::        Looking for annotations in a buffer.
1165 * Annotation Hooks::            Hooks called at certain times during an
1166                                   annotation's lifetime.
1167