info/lispref.info-36

   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: Merging Faces,  Next: Basic Face Functions,  Up: Faces
  54
  55 Merging Faces for Display
  56 -------------------------
  57
  58    Here are all the ways to specify which face to use for display of
  59 text:
  60
  61    * With defaults.  Each frame has a "default face", which is used for
  62      all text that doesn't somehow specify another face.  The face named
  63      `default' applies to the text area, while the faces `left-margin'
  64      and `right-margin' apply to the left and right margin areas.
  65
  66    * With text properties.  A character may have a `face' property; if
  67      so, it's displayed with that face. (Text properties are actually
  68      implemented in terms of extents.) *Note Text Properties::.
  69
  70    * With extents.  An extent may have a `face' property, which applies
  71      to all the text covered by the extent; in addition, if the
  72      `highlight' property is set, the `highlight' property applies when
  73      the mouse moves over the extent or if the extent is explicitly
  74      highlighted.  *Note Extents::.
  75
  76    * With annotations.  Annotations that are inserted into a buffer can
  77      specify their own face. (Annotations are actually implemented in
  78      terms of extents.)  *Note Annotations::.
  79
  80    If these various sources together specify more than one face for a
  81 particular character, XEmacs merges the properties of the various faces
  82 specified.  Extents, text properties, and annotations all use the same
  83 underlying representation (as extents).  When multiple extents cover one
  84 character, an extent with higher priority overrides those with lower
  85 priority.  *Note Extents::.  If no extent covers a particular character,
  86 the `default' face is used.
  87
  88    If a background pixmap is specified, it determines what will be
  89 displayed in the background of text characters.  If the background
  90 pixmap is actually a pixmap, with its colors specified, those colors are
  91 used; if it is a bitmap, the face's foreground and background colors are
  92 used to color it.
  93
  94 \1f
  95 File: lispref.info,  Node: Basic Face Functions,  Next: Face Properties,  Prev: Merging Faces,  Up: Faces
  96
  97 Basic Functions for Working with Faces
  98 --------------------------------------
  99
 100    The properties a face can specify include the font, the foreground
 101 color, the background color, the background pixmap, the underlining,
 102 the display table, and (for TTY devices) whether the text is to be
 103 highlighted, dimmed, blinking, or displayed in reverse video.  The face
 104 can also leave these unspecified, causing them to assume the value of
 105 the corresponding property of the `default' face.
 106
 107    Here are the basic primitives for working with faces.
 108
 109  - Function: make-face name &optional doc-string temporary
 110      This function defines and returns a new face named NAME, initially
 111      with all properties unspecified.  It does nothing if there is
 112      already a face named NAME.  Optional argument DOC-STRING specifies
 113      an explanatory string used for descriptive purposes.  If optional
 114      argument TEMPORARY is non-`nil', the face will automatically
 115      disappear when there are no more references to it anywhere in text
 116      or Lisp code (otherwise, the face will continue to exist
 117      indefinitely even if it is not used).
 118
 119  - Function: face-list &optional temporary
 120      This function returns a list of the names of all defined faces.  If
 121      TEMPORARY is `nil', only the permanent faces are included.  If it
 122      is `t', only the temporary faces are included.  If it is any other
 123      non-`nil' value both permanent and temporary are included.
 124
 125  - Function: facep object
 126      This function returns `t' if OBJECT is a face, else `nil'.
 127
 128  - Function: copy-face old-face new-name &optional locale tag-set
 129           exact-p how-to-add
 130      This function defines a new face named NEW-NAME which is a copy of
 131      the existing face named OLD-FACE.  If there is already a face
 132      named NEW-NAME, then it alters the face to have the same
 133      properties as OLD-FACE.
 134
 135      LOCALE, TAG-SET, EXACT-P and HOW-TO-ADD let you copy just parts of
 136      the old face rather than the whole face, and are as in
 137      `copy-specifier' (*note Specifiers::).
 138
 139 \1f
 140 File: lispref.info,  Node: Face Properties,  Next: Face Convenience Functions,  Prev: Basic Face Functions,  Up: Faces
 141
 142 Face Properties
 143 ---------------
 144
 145    You can examine and modify the properties of an existing face with
 146 the following functions.
 147
 148    The following symbols have predefined meanings:
 149
 150 `foreground'
 151      The foreground color of the face.
 152
 153 `background'
 154      The background color of the face.
 155
 156 `font'
 157      The font used to display text covered by this face.
 158
 159 `display-table'
 160      The display table of the face.
 161
 162 `background-pixmap'
 163      The pixmap displayed in the background of the face.  Only used by
 164      faces on X devices.
 165
 166 `underline'
 167      Underline all text covered by this face.
 168
 169 `highlight'
 170      Highlight all text covered by this face.  Only used by faces on TTY
 171      devices.
 172
 173 `dim'
 174      Dim all text covered by this face.  Only used by faces on TTY
 175      devices.
 176
 177 `blinking'
 178      Blink all text covered by this face.  Only used by faces on TTY
 179      devices.
 180
 181 `reverse'
 182      Reverse the foreground and background colors.  Only used by faces
 183      on TTY devices.
 184
 185 `doc-string'
 186      Description of what the face's normal use is.  NOTE: This is not a
 187      specifier, unlike all the other built-in properties, and cannot
 188      contain locale-specific values.
 189
 190  - Function: set-face-property face property value &optional locale
 191           tag-set how-to-add
 192      This function changes a property of a FACE.
 193
 194      For built-in properties, the actual value of the property is a
 195      specifier and you cannot change this; but you can change the
 196      specifications within the specifier, and that is what this
 197      function will do.  For user-defined properties, you can use this
 198      function to either change the actual value of the property or, if
 199      this value is a specifier, change the specifications within it.
 200
 201      If PROPERTY is a built-in property, the specifications to be added
 202      to this property can be supplied in many different ways:
 203
 204           If VALUE is a simple instantiator (e.g. a string naming a
 205           font or color) or a list of instantiators, then the
 206           instantiator(s) will be added as a specification of the
 207           property for the given LOCALE (which defaults to `global' if
 208           omitted).
 209
 210           If VALUE is a list of specifications (each of which is a cons
 211           of a locale and a list of instantiators), then LOCALE must be
 212           `nil' (it does not make sense to explicitly specify a locale
 213           in this case), and specifications will be added as given.
 214
 215           If VALUE is a specifier (as would be returned by
 216           `face-property' if no LOCALE argument is given), then some or
 217           all of the specifications in the specifier will be added to
 218           the property.  In this case, the function is really
 219           equivalent to `copy-specifier' and LOCALE has the same
 220           semantics (if it is a particular locale, the specification
 221           for the locale will be copied; if a locale type,
 222           specifications for all locales of that type will be copied;
 223           if `nil' or `all', then all specifications will be copied).
 224
 225      HOW-TO-ADD should be either `nil' or one of the symbols `prepend',
 226      `append', `remove-tag-set-prepend', `remove-tag-set-append',
 227      `remove-locale', `remove-locale-type', or `remove-all'.  See
 228      `copy-specifier' and `add-spec-to-specifier' for a description of
 229      what each of these means.  Most of the time, you do not need to
 230      worry about this argument; the default behavior usually is fine.
 231
 232      In general, it is OK to pass an instance object (e.g. as returned
 233      by `face-property-instance') as an instantiator in place of an
 234      actual instantiator.  In such a case, the instantiator used to
 235      create that instance object will be used (for example, if you set
 236      a font-instance object as the value of the `font' property, then
 237      the font name used to create that object will be used instead).
 238      If some cases, however, doing this conversion does not make sense,
 239      and this will be noted in the documentation for particular types
 240      of instance objects.
 241
 242      If PROPERTY is not a built-in property, then this function will
 243      simply set its value if LOCALE is `nil'.  However, if LOCALE is
 244      given, then this function will attempt to add VALUE as the
 245      instantiator for the given LOCALE, using `add-spec-to-specifier'.
 246      If the value of the property is not a specifier, it will
 247      automatically be converted into a `generic' specifier.
 248
 249  - Function: remove-face-property face property &optional locale
 250           tag-set exact-p
 251      This function removes a property of a FACE.
 252
 253      For built-in properties, this is analogous to `remove-specifier'.
 254      For more information, *Note Other Specification Functions::.
 255
 256      When PROPERTY is not a built-in property, this function will just
 257      remove its value if LOCALE is `nil' or `all'.  However, if LOCALE
 258      is other than that, this function will attempt to remove VALUE as
 259      the instantiator for the given LOCALE with `remove-specifier'.  If
 260      the value of the property is not a specifier, it will be converted
 261      into a `generic' specifier automatically.
 262
 263  - Function: face-property face property &optional locale tag-set
 264           exact-p
 265      This function returns FACE's value of the given PROPERTY.
 266
 267      If LOCALE is omitted, the FACE's actual value for PROPERTY will be
 268      returned.  For built-in properties, this will be a specifier
 269      object of a type appropriate to the property (e.g. a font or color
 270      specifier).  For other properties, this could be anything.
 271
 272      If LOCALE is supplied, then instead of returning the actual value,
 273      the specification(s) for the given locale or locale type will be
 274      returned.  This will only work if the actual value of PROPERTY is
 275      a specifier (this will always be the case for built-in properties,
 276      but not or not may apply to user-defined properties).  If the
 277      actual value of PROPERTY is not a specifier, this value will
 278      simply be returned regardless of LOCALE.
 279
 280      The return value will be a list of instantiators (e.g. strings
 281      specifying a font or color name), or a list of specifications,
 282      each of which is a cons of a locale and a list of instantiators.
 283      Specifically, if LOCALE is a particular locale (a buffer, window,
 284      frame, device, or `global'), a list of instantiators for that
 285      locale will be returned.  Otherwise, if LOCALE is a locale type
 286      (one of the symbols `buffer', `window', `frame', or `device'), the
 287      specifications for all locales of that type will be returned.
 288      Finally, if LOCALE is `all', the specifications for all locales of
 289      all types will be returned.
 290
 291      The specifications in a specifier determine what the value of
 292      PROPERTY will be in a particular "domain" or set of circumstances,
 293      which is typically a particular Emacs window along with the buffer
 294      it contains and the frame and device it lies within.  The value is
 295      derived from the instantiator associated with the most specific
 296      locale (in the order buffer, window, frame, device, and `global')
 297      that matches the domain in question.  In other words, given a
 298      domain (i.e. an Emacs window, usually), the specifier for PROPERTY
 299      will first be searched for a specification whose locale is the
 300      buffer contained within that window; then for a specification
 301      whose locale is the window itself; then for a specification whose
 302      locale is the frame that the window is contained within; etc.  The
 303      first instantiator that is valid for the domain (usually this
 304      means that the instantiator is recognized by the device [i.e. the
 305      X server or TTY device] that the domain is on).  The function
 306      `face-property-instance' actually does all this, and is used to
 307      determine how to display the face.
 308
 309  - Function: face-property-instance face property &optional domain
 310           default no-fallback
 311      This function returns the instance of FACE's PROPERTY in the
 312      specified DOMAIN.
 313
 314      Under most circumstances, DOMAIN will be a particular window, and
 315      the returned instance describes how the specified property
 316      actually is displayed for that window and the particular buffer in
 317      it.  Note that this may not be the same as how the property
 318      appears when the buffer is displayed in a different window or
 319      frame, or how the property appears in the same window if you
 320      switch to another buffer in that window; and in those cases, the
 321      returned instance would be different.
 322
 323      The returned instance will typically be a color-instance,
 324      font-instance, or pixmap-instance object, and you can query it
 325      using the appropriate object-specific functions.  For example, you
 326      could use `color-instance-rgb-components' to find out the RGB
 327      (red, green, and blue) components of how the `background' property
 328      of the `highlight' face is displayed in a particular window.  The
 329      results might be different from the results you would get for
 330      another window (perhaps the user specified a different color for
 331      the frame that window is on; or perhaps the same color was
 332      specified but the window is on a different X server, and that X
 333      server has different RGB values for the color from this one).
 334
 335      DOMAIN defaults to the selected window if omitted.
 336
 337      DOMAIN can be a frame or device, instead of a window.  The value
 338      returned for a such a domain is used in special circumstances when
 339      a more specific domain does not apply; for example, a frame value
 340      might be used for coloring a toolbar, which is conceptually
 341      attached to a frame rather than a particular window.  The value is
 342      also useful in determining what the value would be for a
 343      particular window within the frame or device, if it is not
 344      overridden by a more specific specification.
 345
 346      If PROPERTY does not name a built-in property, its value will
 347      simply be returned unless it is a specifier object, in which case
 348      it will be instanced using `specifier-instance'.
 349
 350      Optional arguments DEFAULT and NO-FALLBACK are the same as in
 351      `specifier-instance'.  *Note Specifiers::.
 352
 353 \1f
 354 File: lispref.info,  Node: Face Convenience Functions,  Next: Other Face Display Functions,  Prev: Face Properties,  Up: Faces
 355
 356 Face Convenience Functions
 357 --------------------------
 358
 359  - Command: set-face-foreground face color &optional locale tag-set
 360           how-to-add
 361  - Command: set-face-background face color &optional locale tag-set
 362           how-to-add
 363      These functions set the foreground (respectively, background)
 364      color of face FACE to COLOR.  The argument COLOR should be a
 365      string (the name of a color) or a color object as returned by
 366      `make-color' (*note Colors::).
 367
 368  - Command: set-face-background-pixmap face pixmap &optional locale
 369           tag-set how-to-add
 370      This function sets the background pixmap of face FACE to PIXMAP.
 371      The argument PIXMAP should be a string (the name of a bitmap or
 372      pixmap file; the directories listed in the variable
 373      `x-bitmap-file-path' will be searched) or a glyph object as
 374      returned by `make-glyph' (*note Glyphs::).  The argument may also
 375      be a list of the form `(WIDTH HEIGHT DATA)' where WIDTH and HEIGHT
 376      are the size in pixels, and DATA is a string, containing the raw
 377      bits of the bitmap.
 378
 379  - Command: set-face-font face font &optional locale tag-set how-to-add
 380      This function sets the font of face FACE.  The argument FONT
 381      should be a string or a font object as returned by `make-font'
 382      (*note Fonts::).
 383
 384  - Command: set-face-underline-p face underline-p &optional locale
 385           tag-set how-to-add
 386      This function sets the underline property of face FACE.
 387
 388  - Function: face-foreground face &optional locale tag-set exact-p
 389  - Function: face-background face &optional locale tag-set exact-p
 390      These functions return the foreground (respectively, background)
 391      color specifier of face FACE.  *Note Colors::.
 392
 393  - Function: face-background-pixmap face &optional locale tag-set
 394           exact-p
 395      This function return the background-pixmap glyph object of face
 396      FACE.
 397
 398  - Function: face-font face &optional locale tag-set exact-p
 399      This function returns the font specifier of face FACE.  (Note:
 400      This is not the same as the function `face-font' in FSF Emacs.)
 401
 402      *Note Fonts::.
 403
 404  - Function: face-font-name face &optional domain
 405      This function returns the name of the font of face FACE, or `nil'
 406      if it is unspecified.  This is basically equivalent to `(font-name
 407      (face-font FACE) DOMAIN)' except that it does not cause an error
 408      if FACE's font is `nil'. (This function is named `face-font' in
 409      FSF Emacs.)
 410
 411  - Function: face-underline-p face &optional locale
 412      This function returns the underline property of face FACE.
 413
 414  - Function: face-foreground-instance face &optional domain
 415  - Function: face-background-instance face &optional domain
 416      These functions return the foreground (respectively, background)
 417      color specifier of face FACE.  *Note Colors::.
 418
 419  - Function: face-background-pixmap-instance face &optional domain
 420      This function return the background-pixmap glyph object of face
 421      FACE.
 422
 423  - Function: face-font-instance face &optional domain
 424      This function returns the font specifier of face FACE.  *Note
 425      Fonts::.
 426
 427 \1f
 428 File: lispref.info,  Node: Other Face Display Functions,  Prev: Face Convenience Functions,  Up: Faces
 429
 430 Other Face Display Functions
 431 ----------------------------
 432
 433  - Command: invert-face face &optional locale
 434      Swap the foreground and background colors of face FACE.  If the
 435      face doesn't specify both foreground and background, then its
 436      foreground and background are set to the default background and
 437      foreground.
 438
 439  - Function: face-equal face1 face2 &optional domain
 440      This returns `t' if the faces FACE1 and FACE2 will display in the
 441      same way.  DOMAIN is as in `face-property-instance'.
 442
 443  - Function: face-differs-from-default-p face &optional domain
 444      This returns `t' if the face FACE displays differently from the
 445      default face.  DOMAIN is as in `face-property-instance'.
 446
 447 \1f
 448 File: lispref.info,  Node: Fonts,  Next: Colors,  Prev: Faces,  Up: Faces and Window-System Objects
 449
 450 Fonts
 451 =====
 452
 453    This section describes how to work with font specifier and font
 454 instance objects, which encapsulate fonts in the window system.
 455
 456 * Menu:
 457
 458 * Font Specifiers::             Specifying how a font will appear.
 459 * Font Instances::              What a font specifier gets instanced as.
 460 * Font Instance Names::         The name of a font instance.
 461 * Font Instance Size::          The size of a font instance.
 462 * Font Instance Characteristics:: Display characteristics of font instances.
 463 * Font Convenience Functions::  Convenience functions that automatically
 464                                   instance and retrieve the properties
 465                                   of a font specifier.
 466
 467 \1f
 468 File: lispref.info,  Node: Font Specifiers,  Next: Font Instances,  Up: Fonts
 469
 470 Font Specifiers
 471 ---------------
 472
 473  - Function: font-specifier-p object
 474      This predicate returns `t' if OBJECT is a font specifier, and
 475      `nil' otherwise.
 476
 477  - Function: make-font-specifier spec-list
 478      Return a new `font' specifier object with the given specification
 479      list.  SPEC-LIST can be a list of specifications (each of which is
 480      a cons of a locale and a list of instantiators), a single
 481      instantiator, or a list of instantiators.  *Note Specifiers::, for
 482      more information about specifiers.
 483
 484      Valid instantiators for font specifiers are:
 485
 486         * A string naming a font (e.g. under X this might be
 487           "-*-courier-medium-r-*-*-*-140-*-*-*-*-iso8859-*" for a
 488           14-point upright medium-weight Courier font).
 489
 490         * A font instance (use that instance directly if the device
 491           matches, or use the string that generated it).
 492
 493         * A vector of no elements (only on TTY's; this means to set no
 494           font at all, thus using the "natural" font of the terminal's
 495           text).
 496
 497         * A vector of one element (a face to inherit from).
 498
 499 \1f
 500 File: lispref.info,  Node: Font Instances,  Next: Font Instance Names,  Prev: Font Specifiers,  Up: Fonts
 501
 502 Font Instances
 503 --------------
 504
 505  - Function: font-instance-p object
 506      This predicate returns `t' if OBJECT is a font instance, and `nil'
 507      otherwise.
 508
 509  - Function: make-font-instance name &optional device noerror
 510      This function creates a new font-instance object of the specified
 511      name.  DEVICE specifies the device this object applies to and
 512      defaults to the selected device.  An error is signalled if the
 513      font is unknown or cannot be allocated; however, if NOERROR is
 514      non-`nil', `nil' is simply returned in this case.
 515
 516      The returned object is a normal, first-class lisp object.  The way
 517      you "deallocate" the font is the way you deallocate any other lisp
 518      object: you drop all pointers to it and allow it to be garbage
 519      collected.  When these objects are GCed, the underlying X data is
 520      deallocated as well.
 521
 522 \1f
 523 File: lispref.info,  Node: Font Instance Names,  Next: Font Instance Size,  Prev: Font Instances,  Up: Fonts
 524
 525 Font Instance Names
 526 -------------------
 527
 528  - Function: list-fonts pattern &optional device
 529      This function returns a list of font names matching the given
 530      pattern.  DEVICE specifies which device to search for names, and
 531      defaults to the currently selected device.
 532
 533  - Function: font-instance-name font-instance
 534      This function returns the name used to allocate FONT-INSTANCE.
 535
 536  - Function: font-instance-truename font-instance
 537      This function returns the canonical name of the given font
 538      instance.  Font names are patterns which may match any number of
 539      fonts, of which the first found is used.  This returns an
 540      unambiguous name for that font (but not necessarily its only
 541      unambiguous name).
 542
 543 \1f
 544 File: lispref.info,  Node: Font Instance Size,  Next: Font Instance Characteristics,  Prev: Font Instance Names,  Up: Fonts
 545
 546 Font Instance Size
 547 ------------------
 548
 549  - Function: x-font-size font
 550      This function returns the nominal size of the given font.  This is
 551      done by parsing its name, so it's likely to lose.  X fonts can be
 552      specified (by the user) in either pixels or 10ths of points, and
 553      this returns the first one it finds, so you have to decide which
 554      units the returned value is measured in yourself ...
 555
 556  - Function: x-find-larger-font font &optional device
 557      This function loads a new, slightly larger version of the given
 558      font (or font name).  Returns the font if it succeeds, `nil'
 559      otherwise.  If scalable fonts are available, this returns a font
 560      which is 1 point larger.  Otherwise, it returns the next larger
 561      version of this font that is defined.
 562
 563  - Function: x-find-smaller-font font &optional device
 564      This function loads a new, slightly smaller version of the given
 565      font (or font name).  Returns the font if it succeeds, `nil'
 566      otherwise.  If scalable fonts are available, this returns a font
 567      which is 1 point smaller.  Otherwise, it returns the next smaller
 568      version of this font that is defined.
 569
 570 \1f
 571 File: lispref.info,  Node: Font Instance Characteristics,  Next: Font Convenience Functions,  Prev: Font Instance Size,  Up: Fonts
 572
 573 Font Instance Characteristics
 574 -----------------------------
 575
 576  - Function: font-instance-properties font-instance
 577      This function returns the properties (an alist or `nil') of
 578      FONT-INSTANCE.
 579
 580  - Function: x-make-font-bold font &optional device
 581      Given an X font specification, this attempts to make a "bold" font.
 582      If it fails, it returns `nil'.
 583
 584  - Function: x-make-font-unbold font &optional device
 585      Given an X font specification, this attempts to make a non-bold
 586      font.  If it fails, it returns `nil'.
 587
 588  - Function: x-make-font-italic font &optional device
 589      Given an X font specification, this attempts to make an "italic"
 590      font.  If it fails, it returns `nil'.
 591
 592  - Function: x-make-font-unitalic font &optional device
 593      Given an X font specification, this attempts to make a non-italic
 594      font.  If it fails, it returns `nil'.
 595
 596  - Function: x-make-font-bold-italic font &optional device
 597      Given an X font specification, this attempts to make a
 598      "bold-italic" font.  If it fails, it returns `nil'.
 599
 600 \1f
 601 File: lispref.info,  Node: Font Convenience Functions,  Prev: Font Instance Characteristics,  Up: Fonts
 602
 603 Font Convenience Functions
 604 --------------------------
 605
 606  - Function: font-name font &optional domain
 607      This function returns the name of the FONT in the specified
 608      DOMAIN, if any.  FONT should be a font specifier object and DOMAIN
 609      is normally a window and defaults to the selected window if
 610      omitted.  This is equivalent to using `specifier-instance' and
 611      applying `font-instance-name' to the result.
 612
 613  - Function: font-truename font &optional domain
 614      This function returns the truename of the FONT in the specified
 615      DOMAIN, if any.  FONT should be a font specifier object and DOMAIN
 616      is normally a window and defaults to the selected window if
 617      omitted.  This is equivalent to using `specifier-instance' and
 618      applying `font-instance-truename' to the result.
 619
 620  - Function: font-properties font &optional domain
 621      This function returns the properties of the FONT in the specified
 622      DOMAIN, if any.  FONT should be a font specifier object and DOMAIN
 623      is normally a window and defaults to the selected window if
 624      omitted.  This is equivalent to using `specifier-instance' and
 625      applying `font-instance-properties' to the result.
 626
 627 \1f
 628 File: lispref.info,  Node: Colors,  Prev: Fonts,  Up: Faces and Window-System Objects
 629
 630 Colors
 631 ======
 632
 633 * Menu:
 634
 635 * Color Specifiers::            Specifying how a color will appear.
 636 * Color Instances::             What a color specifier gets instanced as.
 637 * Color Instance Properties::   Properties of color instances.
 638 * Color Convenience Functions:: Convenience functions that automatically
 639                                   instance and retrieve the properties
 640                                   of a color specifier.
 641
 642 \1f
 643 File: lispref.info,  Node: Color Specifiers,  Next: Color Instances,  Up: Colors
 644
 645 Color Specifiers
 646 ----------------
 647
 648  - Function: color-specifier-p object
 649      This function returns non-`nil' if OBJECT is a color specifier.
 650
 651  - Function: make-color-specifier spec-list
 652      Return a new `color' specifier object with the given specification
 653      list.  SPEC-LIST can be a list of specifications (each of which is
 654      a cons of a locale and a list of instantiators), a single
 655      instantiator, or a list of instantiators.  *Note Specifiers::, for
 656      a detailed description of how specifiers work.
 657
 658      Valid instantiators for color specifiers are:
 659
 660         * A string naming a color (e.g. under X this might be
 661           "lightseagreen2" or "#F534B2").
 662
 663         * A color instance (use that instance directly if the device
 664           matches, or use the string that generated it).
 665
 666         * A vector of no elements (only on TTY's; this means to set no
 667           color at all, thus using the "natural" color of the
 668           terminal's text).
 669
 670         * A vector of one or two elements: a face to inherit from, and
 671           optionally a symbol naming which property of that face to
 672           inherit, either `foreground' or `background' (if omitted,
 673           defaults to the same property that this color specifier is
 674           used for; if this specifier is not part of a face, the
 675           instantiator would not be valid).
 676
 677  - Function: make-face-boolean-specifier spec-list
 678      Return a new `face-boolean' specifier object with the given spec
 679      list.  SPEC-LIST can be a list of specifications (each of which is
 680      a cons of a locale and a list of instantiators), a single
 681      instantiator, or a list of instantiators.  *Note Specifiers::, for
 682      a detailed description of how specifiers work.
 683
 684      Valid instantiators for face-boolean specifiers are
 685
 686         * t or nil.
 687
 688         * A vector of two or three elements: a face to inherit from,
 689           optionally a symbol naming the property of that face to
 690           inherit from (if omitted, defaults to the same property that
 691           this face-boolean specifier is used for; if this specifier is
 692           not part of a face, the instantiator would not be valid), and
 693           optionally a value which, if non-`nil', means to invert the
 694           sense of the inherited property.
 695
 696
 697 \1f
 698 File: lispref.info,  Node: Color Instances,  Next: Color Instance Properties,  Prev: Color Specifiers,  Up: Colors
 699
 700 Color Instances
 701 ---------------
 702
 703    A "color-instance object" is an object describing the way a color
 704 specifier is instanced in a particular domain.  Functions such as
 705 `face-background-instance' return a color-instance object.  For example,
 706
 707      (face-background-instance 'default (next-window))
 708          => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x678d>
 709
 710    The color-instance object returned describes the way the background
 711 color of the `default' face is displayed in the next window after the
 712 selected one.
 713
 714  - Function: color-instance-p object
 715      This function returns non-`nil' if OBJECT is a color-instance.
 716
 717 \1f
 718 File: lispref.info,  Node: Color Instance Properties,  Next: Color Convenience Functions,  Prev: Color Instances,  Up: Colors
 719
 720 Color Instance Properties
 721 -------------------------
 722
 723  - Function: color-instance-name color-instance
 724      This function returns the name used to allocate COLOR-INSTANCE.
 725
 726  - Function: color-instance-rgb-components color-instance
 727      This function returns a three element list containing the red,
 728      green, and blue color components of COLOR-INSTANCE.
 729
 730           (color-instance-rgb-components
 731             (face-background-instance 'default (next-window)))
 732               => (65535 58596 46517)
 733
 734 \1f
 735 File: lispref.info,  Node: Color Convenience Functions,  Prev: Color Instance Properties,  Up: Colors
 736
 737 Color Convenience Functions
 738 ---------------------------
 739
 740  - Function: color-name color &optional domain
 741      This function returns the name of the COLOR in the specified
 742      DOMAIN, if any.  COLOR should be a color specifier object and
 743      DOMAIN is normally a window and defaults to the selected window if
 744      omitted.  This is equivalent to using `specifier-instance' and
 745      applying `color-instance-name' to the result.
 746
 747  - Function: color-rgb-components color &optional domain
 748      This function returns the RGB components of the COLOR in the
 749      specified DOMAIN, if any.  COLOR should be a color specifier
 750      object and DOMAIN is normally a window and defaults to the
 751      selected window if omitted.  This is equivalent to using
 752      `specifier-instance' and applying `color-instance-rgb-components'
 753      to the result.
 754
 755           (color-rgb-components (face-background 'default (next-window)))
 756               => (65535 58596 46517)
 757
 758 \1f
 759 File: lispref.info,  Node: Glyphs,  Next: Annotations,  Prev: Faces and Window-System Objects,  Up: Top
 760
 761 Glyphs
 762 ******
 763
 764    A "glyph" is an object that is used for pixmaps, widgets and images
 765 of all sorts, as well as for things that "act" like pixmaps, such as
 766 non-textual strings ("annotations") displayed in a buffer or in the
 767 margins.  It is used in begin-glyphs and end-glyphs attached to
 768 extents, marginal and textual annotations, overlay arrows
 769 (`overlay-arrow-*' variables), toolbar buttons, mouse pointers, frame
 770 icons, truncation and continuation markers, and the like. (Basically,
 771 any place there is an image or something that acts like an image, there
 772 will be a glyph object representing it.)
 773
 774    The actual image that is displayed (as opposed to its position or
 775 clipping) is defined by an "image specifier" object contained within
 776 the glyph.  The separation between an image specifier object and a
 777 glyph object is made because the glyph includes other properties than
 778 just the actual image: e.g. the face it is displayed in (for text
 779 images), the alignment of the image (when it is in a buffer), etc.
 780
 781  - Function: glyphp object
 782      This function returns `t' if OBJECT is a glyph.
 783
 784 * Menu:
 785
 786 * Glyph Functions::     Functions for working with glyphs.
 787 * Images::              Graphical images displayed in a frame.
 788 * Glyph Types::         Each glyph has a particular type.
 789 * Mouse Pointer::       Controlling the mouse pointer.
 790 * Redisplay Glyphs::    Glyphs controlling various redisplay functions.
 791 * Subwindows::          Inserting an externally-controlled subwindow
 792                           into a buffer.
 793
 794 \1f
 795 File: lispref.info,  Node: Glyph Functions,  Next: Images,  Up: Glyphs
 796
 797 Glyph Functions
 798 ===============
 799
 800 * Menu:
 801
 802 * Creating Glyphs::     Creating new glyphs.
 803 * Glyph Properties::    Accessing and modifying a glyph's properties.
 804 * Glyph Convenience Functions::
 805                         Convenience functions for accessing particular
 806                           properties of a glyph.
 807 * Glyph Dimensions::    Determining the height, width, etc. of a glyph.
 808
 809 \1f
 810 File: lispref.info,  Node: Creating Glyphs,  Next: Glyph Properties,  Up: Glyph Functions
 811
 812 Creating Glyphs
 813 ---------------
 814
 815  - Function: make-glyph &optional spec-list type
 816      This function creates a new glyph object of type TYPE.
 817
 818      SPEC-LIST is used to initialize the glyph's image.  It is
 819      typically an image instantiator (a string or a vector; *Note Image
 820      Specifiers::), but can also be a list of such instantiators (each
 821      one in turn is tried until an image is successfully produced), a
 822      cons of a locale (frame, buffer, etc.) and an instantiator, a list
 823      of such conses, or any other form accepted by
 824      `canonicalize-spec-list'.  *Note Specifiers::, for more
 825      information about specifiers.
 826
 827      TYPE specifies the type of the glyph, which specifies in which
 828      contexts the glyph can be used, and controls the allowable image
 829      types into which the glyph's image can be instantiated.  TYPE
 830      should be one of `buffer' (used for glyphs in an extent, the
 831      modeline, the toolbar, or elsewhere in a buffer), `pointer' (used
 832      for the mouse-pointer), or `icon' (used for a frame's icon), and
 833      defaults to `buffer'.  *Note Glyph Types::.
 834
 835      A glyph in XEmacs does *NOT* refer to a single unit of textual
 836      display (the XEmacs term for this is "rune"), but rather is an
 837      object encapsulating a graphical element, such as an image or
 838      widget (an element such as a button or text field; "widget" is the
 839      term for this under X Windows, and it's called a "control" under
 840      MS Windows).  This graphical element could appear in a buffer, a
 841      margin, a gutter, or a toolbar, or as a mouse pointer or an icon,
 842      for example.
 843
 844      Creating a glyph using `make-glyph' does not specify _where_ the
 845      glyph will be used, but it does specify _what_ the glyph will look
 846      like.  In particular, SPEC-LIST is used to specify this, and it's
 847      used to initialize the glyph's `image' property, which is an image
 848      specifier. (Note that "image" as used in the context of a glyph's
 849      `image' property or in the terms "image specifier", "image
 850      instantiator", or "image instance" does not refer to what people
 851      normally think of as an image (which in XEmacs is called a
 852      "pixmap"), but to any graphical element--a pixmap, a widget, or
 853      even a block of text, when used in the places that call for a
 854      glyph.)  The format of the SPEC-LIST is typically an image
 855      instantiator (a string or a vector; *Note Image Specifiers::), but
 856      can also be a list of such instantiators (each one in turn is
 857      tried until an image is successfully produced), a cons of a locale
 858      (frame, buffer, etc.)  and an instantiator, a list of such conses,
 859      or any other form accepted by `canonicalize-spec-list'. *Note
 860      Specifiers::, for more information about specifiers.
 861
 862      If you're not familiar with specifiers, you should be in order to
 863      understand how glyphs work.  The clearest introduction to
 864      specifiers is in the Lispref manual, available under Info. (Choose
 865      Help->Info->Info Contents on the menubar or type C-h i.) You can
 866      also see `make-specifier' for a capsule summary.  What's important
 867      to keep in mind is that a specifier lets you set a different value
 868      for any particular buffer, window, frame, device, or console.
 869      This allows for a great deal of flexibility; in particular, only
 870      one global glyph needs to exist for a particular purpose (e.g. the
 871      icon used to represent an iconified frame, the mouse pointer used
 872      over particular areas of a frame, etc.), and in these cases you do
 873      not create your own glyph, but rather modify the existing one.
 874
 875      As well as using SPEC-LIST to initialize the glyph, you can set
 876      specifications using `set-glyph-image'.  Note that, due to a
 877      possibly questionable historical design decision, a glyph itself
 878      is not actually a specifier, but rather is an object containing an
 879      image specifier (as well as other, seldom-used properties).
 880      Therefore, you cannot set or access specifications for the glyph's
 881      image by directly using `set-specifier', `specifier-instance' or
 882      the like on the glyph; instead use them on `(glyph-image GLYPH)'
 883      or use the convenience functions `set-glyph-image',
 884      `glyph-image-instance', and `glyph-image'.
 885
 886      Once you have created a glyph, you specify where it will be used as
 887      follows:
 888
 889         * To insert a glyph into a buffer, create an extent in the
 890           buffer and then use `set-extent-begin-glyph' or
 891           `set-extent-end-glyph' to set a glyph to be displayed at the
 892           corresponding edge of the extent. (It is common to create
 893           zero-width extents for this purpose.)
 894
 895         * To insert a glyph into the left or right margin of a buffer,
 896           first make sure the margin is visible by setting a value for
 897           the specifiers `left-margin-width' or `right-margin-width'.
 898           (Not strictly necessary when using margin glyphs with layout
 899           policy `whitespace'.) Then follow the same procedure above
 900           for inserting a glyph in a buffer, and then set a non-default
 901           layout policy for the glyph using
 902           `set-extent-begin-glyph-layout' or
 903           `set-extent-end-glyph-layout'.  Alternatively, use the
 904           high-level annotations API (see `make-annotation'). (In point
 905           of fact, you can also use the annotations API for glyphs in a
 906           buffer, by setting a layout policy of `text'.)
 907
 908         * To insert a glyph into the modeline, just put the glyph
 909           directly as one of the modeline elements. (Unfortunately you
 910           can't currently put a begin glyph or end glyph on one of the
 911           modeline extents--they're ignored.)
 912
 913         * To insert a glyph into a toolbar, specify it as part of a
 914           toolbar instantiator (typically set on the specifier
 915           `default-toolbar').  See `default-toolbar' for more
 916           information. (Note that it is standard practice to use a
 917           symbol in place of the glyph list in the toolbar
 918           instantiator; the symbol is evalled to get the glyph list.
 919           This facilitates both creating the toolbar instantiator and
 920           modifying individual glyphs in a toolbar later on.  For
 921           example, you can change the way that the Mail toolbar button
 922           looks by modifying the value of the variable
 923           `toolbar-mail-icon' (in general, `toolbar-*-icon') and then
 924           calling `(set-specifier-dirty-flag default-toolbar)'.  (####
 925           Unfortunately this doesn't quite work the way it should; the
 926           change will appear in new frames, but not existing ones.
 927
 928         * To insert a glyph into a gutter, create or modify a gutter
 929           instantiator (typically set on the specifier
 930           `default-gutter').  Gutter instantiators consist of strings
 931           or lists of strings, so to insert a glyph, create an extent
 932           over the string, and use `set-extent-begin-glyph' or
 933           `set-extent-end-glyph' to set a glyph to be displayed at the
 934           corresponding edge of the extent, just like for glyphs in a
 935           buffer.
 936
 937         * To use a glyph as the icon for a frame, you do not actually
 938           create a new glyph; rather, you change the specifications for
 939           the existing glyph `frame-icon-glyph'. (Remember that,
 940           because of the specifier nature of glyphs, you can set
 941           different values for any particular buffer or frame.)
 942
 943         * To use a glyph as the mouse pointer, in general you do not
 944           create a new glyph, but rather you change the specifications
 945           of various existing glyphs, such as `text-pointer-glyph' for
 946           the pointer used over text, `modeline-pointer-glyph' for the
 947           pointer used over the modeline, etc.  Do an apropos over
 948           `*-pointer-glyph' to find all of them. (Note also that you
 949           can temporarily set the mouse pointer to some specific shape
 950           by using `set-frame-pointer', which takes an image instance,
 951           as obtained from calling `glyph-image-instance' on a glyph of
 952           type `pointer' - either one of the above-mentioned variables
 953           or one you created yourself.  (See below for what it means to
 954           create a glyph of type `pointer'.)  This pointer will last
 955           only until the next mouse motion event is processed or
 956           certain other things happen, such as creating or deleting a
 957           window. (In fact, the above-mentioned pointer glyph variables
 958           are implemented as part of the default handler for mouse
 959           motion events.  If you want to customize this behavior, take a
 960           look at `mode-motion-hook', or `mouse-motion-handler' if you
 961           really want to get low-level.)
 962
 963         * To use a glyph to control the shape of miscellaneous
 964           redisplay effects such as the truncation and continuation
 965           markers, set the appropriate existing glyph variables, as for
 966           icons and pointers above.  See `continuation-glyph',
 967           `control-arrow-glyph', `hscroll-glyph',
 968           `invisible-text-glyph', `octal-escape-glyph', and
 969           `truncation-glyph'.  See also `overlay-arrow-string', an odd
 970           redisplay leftover which can be set to a glyph you created,
 971           and will cause the glyph to be displayed on top of the text
 972           position specified in the marker stored in
 973           `overlay-arrow-position'.
 974
 975         * To use a glyph in a display table (i.e. to control the
 976           appearance of any individual character), create the
 977           appropriate character glyphs and then set a specification for
 978           the specifier `current-display-table', which controls the
 979           appearance of characters.  You can also set an overriding
 980           display table for use with text displayed in a particular
 981           face; see `set-face-display-table' and `make-display-table'.
 982           #### Note: Display tables do not currently support general
 983           Mule characters.  They will be overhauled at some point to
 984           support this and to provide other features required under
 985           Mule.
 986
 987         * To use a glyph as the background pixmap of a face: Note that
 988           the background pixmap of a face is actually an image
 989           specifier - probably the only place in XEmacs where an image
 990           specifier occurs outside of a glyph.  Similarly to how the
 991           glyph's image specifier works, you don't create your own
 992           image specifier, but rather add specifications to the
 993           existing one (using `set-face-background-pixmap').  Note that
 994           the image instance that is generated in order to actually
 995           display the background pixmap is of type `mono-pixmap',
 996           meaning that it's a two-color image and the foreground and
 997           background of the image get filled in with the corresponding
 998           colors from the face.
 999
1000      It is extremely rare that you will ever have to specify a value for
1001      TYPE, which should be one of `buffer' (used for glyphs in an
1002      extent, the modeline, the toolbar, or elsewhere in a buffer),
1003      `pointer' (used for the mouse-pointer), or `icon' (used for a
1004      frame's icon), and defaults to `buffer'.  The only cases where it
1005      needs to be specified is when creating icon or pointer glyphs, and
1006      in both cases the necessary glyphs have already been created at
1007      startup and are accessed through the appropriate variables, e.g.
1008      `text-pointer-glyph' (or in general, `*-pointer-glyph') and
1009      `frame-icon-glyph'.  *Note Glyph Types::.
1010
1011  - Function: make-glyph-internal &optional type
1012      This function creates a new, uninitialized glyph of type TYPE.
1013
1014  - Function: make-pointer-glyph &optional spec-list
1015      Return a new `pointer-glyph' object with the specification list
1016      SPEC-LIST.  This function is equivalent to calling `make-glyph'
1017      with a TYPE of `pointer'.
1018
1019      It is extremely unlikely that you will ever need to create a
1020      pointer glyph.  Instead, you probably want to be calling
1021      `set-glyph-image' on an existing glyph, e.g. `text-pointer-glyph'.
1022
1023  - Function: make-icon-glyph &optional spec-list
1024      Return a new `pointer-glyph' object with the specification list
1025      SPEC-LIST.  This function is equivalent to calling `make-glyph'
1026      with a TYPE of `icon'.
1027
1028      It is extremely unlikely that you will ever need to create a
1029      pointer glyph.  Instead, you probably want to be calling
1030      `set-glyph-image' on an existing glyph, e.g. `text-pointer-glyph'.
1031