info/lispref.info-35

   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: Specifiers In-Depth,  Next: Specifier Instancing,  Prev: Introduction to Specifiers,  Up: Specifiers
  54
  55 In-Depth Overview of a Specifier
  56 ================================
  57
  58    A specifier object encapsulates a set of "specifications", each of
  59 which says what its value should be if a particular condition applies.
  60 For example, one specification might be "The value should be
  61 darkseagreen2 on X devices" another might be "The value should be blue
  62 in the *Help* buffer".  In specifier terminology, these conditions are
  63 called "locales" and the values are called "instantiators".  Given a
  64 specifier, a logical question is "What is its value in a particular
  65 situation?" This involves looking through the specifications to see
  66 which ones apply to this particular situation, and perhaps preferring
  67 one over another if more than one applies.  In specifier terminology, a
  68 "particular situation" is called a "domain", and determining its value
  69 in a particular domain is called "instancing".  Most of the time, a
  70 domain is identified by a particular window.  For example, if the
  71 redisplay engine is drawing text in the default face in a particular
  72 window, it retrieves the specifier for the foreground color of the
  73 default face and "instances" it in the domain given by that window; in
  74 other words, it asks the specifier, "What is your value in this
  75 window?".
  76
  77    More specifically, a specifier contains a set of "specifications",
  78 each of which associates a "locale" (a window object, a buffer object,
  79 a frame object, a device object, or the symbol `global') with an
  80 "inst-list", which is a list of one or more "inst-pairs". (For each
  81 possible locale, there can be at most one specification containing that
  82 locale.) Each inst-pair is a cons of a "tag set" (an unordered list of
  83 zero or more symbols, or "tags") and an "instantiator" (the allowed
  84 form of this varies depending on the type of specifier).  In a given
  85 specification, there may be more than one inst-pair with the same tag
  86 set; this is unlike for locales.
  87
  88    The tag set is used to restrict the sorts of devices over which the
  89 instantiator is valid and to uniquely identify instantiators added by a
  90 particular application, so that different applications can work on the
  91 same specifier and not interfere with each other.  Each tag can have a
  92 "predicate" associated with it, which is a function of one argument (a
  93 device) that specifies whether the tag matches that particular device.
  94 (If a tag does not have a predicate, it matches all devices.)  All tags
  95 in a tag set must match a device for the associated inst-pair to be
  96 instantiable over that device.  (A null tag set is perfectly valid.)
  97
  98    The valid device types (normally `x', `tty', and `stream') and
  99 device classes (normally `color', `grayscale', and `mono') can always
 100 be used as tags, and match devices of the associated type or class
 101 (*note Consoles and Devices::).  User-defined tags may be defined, with
 102 an optional predicate specified.  An application can create its own
 103 tag, use it to mark all its instantiators, and be fairly confident that
 104 it will not interfere with other applications that modify the same
 105 specifier--Functions that add a specification to a specifier usually
 106 only overwrite existing inst-pairs with the same tag set as was given,
 107 and a particular tag or tag set can be specified when removing
 108 instantiators.
 109
 110    When a specifier is instanced in a domain, both the locale and the
 111 tag set can be viewed as specifying necessary conditions that must
 112 apply in that domain for an instantiator to be considered as a possible
 113 result of the instancing.  More specific locales always override more
 114 general locales (thus, there is no particular ordering of the
 115 specifications in a specifier); however, the tag sets are simply
 116 considered in the order that the inst-pairs occur in the
 117 specification's inst-list.
 118
 119    Note also that the actual object that results from the instancing
 120 (called an "instance object") may not be the same as the instantiator
 121 from which it was derived.  For some specifier types (such as integer
 122 specifiers and boolean specifiers), the instantiator will be returned
 123 directly as the instance object.  For other types, however, this is not
 124 the case.  For example, for font specifiers, the instantiator is a
 125 font-description string and the instance object is a font-instance
 126 object, which describes how the font is displayed on a particular
 127 device.  A font-instance object encapsulates such things as the actual
 128 font name used to display the font on that device (a font-description
 129 string under X is usually a wildcard specification that may resolve to
 130 different font names, with possibly different foundries, widths, etc.,
 131 on different devices), the extra properties of that font on that
 132 device, etc.  Furthermore, this conversion (called "instantiation")
 133 might fail--a font or color might not exist on a particular device, for
 134 example.
 135
 136 \1f
 137 File: lispref.info,  Node: Specifier Instancing,  Next: Specifier Types,  Prev: Specifiers In-Depth,  Up: Specifiers
 138
 139 How a Specifier Is Instanced
 140 ============================
 141
 142    Instancing of a specifier in a particular window domain proceeds as
 143 follows:
 144
 145    * First, XEmacs searches for a specification whose locale is the
 146      same as the window.  If that fails, the search is repeated,
 147      looking for a locale that is the same as the window's buffer.  If
 148      that fails, the search is repeated using the window's frame, then
 149      using the device that frame is on.  Finally, the specification
 150      whose locale is the symbol `global' (if there is such a
 151      specification) is considered.
 152
 153    * The inst-pairs contained in the specification that was found are
 154      considered in their order in the inst-list, looking for one whose
 155      tag set matches the device that is derived from the window domain.
 156      (The tag set is an unordered list of zero or more tag symbols.
 157      For all tags that have predicates associated with them, the
 158      predicate must match the device.)
 159
 160    * If a matching tag set is found, the corresponding instantiator is
 161      passed to the specifier's instantiation method, which is specific
 162      to the type of the specifier.  If it succeeds, the resulting
 163      instance object is returned as the result of the instancing and
 164      the instancing is done.  Otherwise, the operation continues,
 165      looking for another matching inst-pair in the current
 166      specification.
 167
 168    * When there are no more inst-pairs to be considered in the current
 169      specification, the search starts over, looking for another
 170      specification as in the first step above.
 171
 172    * If all specifications are exhausted and no instance object can be
 173      derived, the instancing fails. (Actually, this is not completely
 174      true.  Some specifier objects for built-in properties have a
 175      "fallback" value, which is either an inst-list or another
 176      specifier object, that is consulted if the instancing is about to
 177      fail.  If it is an inst-list, the searching proceeds using the
 178      inst-pairs in that list.  If it is a specifier, the entire
 179      instancing starts over using that specifier instead of the given
 180      one.  Fallback values are set by the C code and cannot be
 181      modified, except perhaps indirectly, using any Lisp functions.
 182      The purpose of them is to supply some values to make sure that
 183      instancing of built-in properties can't fail and to implement some
 184      basic specifier inheritance, such as the fact that faces inherit
 185      their properties from the `default' face.)
 186
 187    It is also possible to instance a specifier over a frame domain or
 188 device domain instead of over a window domain.  The C code, for example,
 189 instances the `top-toolbar-height' variable over a frame domain in
 190 order to determine the height of a frame's top toolbar.  Instancing over
 191 a frame or device is similar to instancing over a window except that
 192 specifications for locales that cannot be derived from the domain are
 193 ignored.  Specifically, instancing over a frame looks first for frame
 194 locales, then device locales, then the `global' locale.  Instancing
 195 over a device domain looks only for device locales and the `global'
 196 locale.
 197
 198 \1f
 199 File: lispref.info,  Node: Specifier Types,  Next: Adding Specifications,  Prev: Specifier Instancing,  Up: Specifiers
 200
 201 Specifier Types
 202 ===============
 203
 204    There are various different types of specifiers.  The type of a
 205 specifier controls what sorts of instantiators are valid, how an
 206 instantiator is instantiated, etc.  Here is a list of built-in specifier
 207 types:
 208
 209 `boolean'
 210      The valid instantiators are the symbols `t' and `nil'.  Instance
 211      objects are the same as instantiators so no special instantiation
 212      function is needed.
 213
 214 `integer'
 215      The valid instantiators are integers.  Instance objects are the
 216      same as instantiators so no special instantiation function is
 217      needed.  `modeline-shadow-thickness' is an example of an integer
 218      specifier (negative thicknesses indicate that the shadow is drawn
 219      recessed instead of raised).
 220
 221 `natnum'
 222      The valid instantiators are natnums (non-negative integers).
 223      Instance objects are the same as instantiators so no special
 224      instantiation function is needed.  Natnum specifiers are used for
 225      dimension variables such as `top-toolbar-height'.
 226
 227 `generic'
 228      All Lisp objects are valid instantiators.  Instance objects are
 229      the same as instantiators so no special instantiation function is
 230      needed.
 231
 232 `font'
 233      The valid instantiators are strings describing fonts or vectors
 234      indicating inheritance from the font of some face.  Instance
 235      objects are font-instance objects, which are specific to a
 236      particular device.  The instantiation method for font specifiers
 237      can fail, unlike for integer, natnum, boolean, and generic
 238      specifiers.
 239
 240 `color'
 241      The valid instantiators are strings describing colors or vectors
 242      indicating inheritance from the foreground or background of some
 243      face.  Instance objects are color-instance objects, which are
 244      specific to a particular device.  The instantiation method for
 245      color specifiers can fail, as for font specifiers.
 246
 247 `image'
 248      Images are perhaps the most complicated type of built-in
 249      specifier.  The valid instantiators are strings (a filename,
 250      inline data for a pixmap, or text to be displayed in a text glyph)
 251      or vectors describing inline data of various sorts or indicating
 252      inheritance from the background-pixmap property of some face.
 253      Instance objects are either strings (for text images),
 254      image-instance objects (for pixmap images), or subwindow objects
 255      (for subwindow images).  The instantiation method for image
 256      specifiers can fail, as for font and color specifiers.
 257
 258 `face-boolean'
 259      The valid instantiators are the symbols `t' and `nil' and vectors
 260      indicating inheritance from a boolean property of some face.
 261      Specifiers of this sort are used for all of the built-in boolean
 262      properties of faces.  Instance objects are either the symbol `t'
 263      or the symbol `nil'.
 264
 265 `toolbar'
 266      The valid instantiators are toolbar descriptors, which are lists
 267      of toolbar-button descriptors (each of which is a vector of two or
 268      four elements).  *Note Toolbar::, for more information.
 269
 270    Color and font instance objects can also be used in turn as
 271 instantiators for a new color or font instance object.  Since these
 272 instance objects are device-specific, the instantiator can be used
 273 directly as the new instance object, but only if they are of the same
 274 device.  If the devices differ, the base color or font of the
 275 instantiating object is effectively used instead as the instantiator.
 276
 277    *Note Faces and Window-System Objects::, for more information on
 278 fonts, colors, and face-boolean specifiers.  *Note Glyphs::, for more
 279 information about image specifiers.  *Note Toolbar::, for more
 280 information on toolbar specifiers.
 281
 282  - Function: specifier-type specifier
 283      This function returns the type of SPECIFIER.  The returned value
 284      will be a symbol: one of `integer', `boolean', etc., as listed in
 285      the above table.
 286
 287    Functions are also provided to query whether an object is a
 288 particular kind of specifier:
 289
 290  - Function: boolean-specifier-p object
 291      This function returns non-`nil' if OBJECT is a boolean specifier.
 292
 293  - Function: integer-specifier-p object
 294      This function returns non-`nil' if OBJECT is an integer specifier.
 295
 296  - Function: natnum-specifier-p object
 297      This function returns non-`nil' if OBJECT is a natnum specifier.
 298
 299  - Function: generic-specifier-p object
 300      This function returns non-`nil' if OBJECT is a generic specifier.
 301
 302  - Function: face-boolean-specifier-p object
 303      This function returns non-`nil' if OBJECT is a face-boolean
 304      specifier.
 305
 306  - Function: toolbar-specifier-p object
 307      This function returns non-`nil' if OBJECT is a toolbar specifier.
 308
 309  - Function: font-specifier-p object
 310      This function returns non-`nil' if OBJECT is a font specifier.
 311
 312  - Function: color-specifier-p object
 313      This function returns non-`nil' if OBJECT is a color specifier.
 314
 315  - Function: image-specifier-p object
 316      This function returns non-`nil' if OBJECT is an image specifier.
 317
 318 \1f
 319 File: lispref.info,  Node: Adding Specifications,  Next: Retrieving Specifications,  Prev: Specifier Types,  Up: Specifiers
 320
 321 Adding specifications to a Specifier
 322 ====================================
 323
 324  - Function: add-spec-to-specifier specifier instantiator &optional
 325           locale tag-set how-to-add
 326      This function adds a specification to SPECIFIER.  The
 327      specification maps from LOCALE (which should be a window, buffer,
 328      frame, device, or the symbol `global', and defaults to `global')
 329      to INSTANTIATOR, whose allowed values depend on the type of the
 330      specifier.  Optional argument TAG-SET limits the instantiator to
 331      apply only to the specified tag set, which should be a list of
 332      tags all of which must match the device being instantiated over
 333      (tags are a device type, a device class, or tags defined with
 334      `define-specifier-tag').  Specifying a single symbol for TAG-SET
 335      is equivalent to specifying a one-element list containing that
 336      symbol.  Optional argument HOW-TO-ADD specifies what to do if
 337      there are already specifications in the specifier.  It should be
 338      one of
 339
 340     `prepend'
 341           Put at the beginning of the current list of instantiators for
 342           LOCALE.
 343
 344     `append'
 345           Add to the end of the current list of instantiators for
 346           LOCALE.
 347
 348     `remove-tag-set-prepend'
 349           This is the default.  Remove any existing instantiators whose
 350           tag set is the same as TAG-SET; then put the new instantiator
 351           at the beginning of the current list.
 352
 353     `remove-tag-set-append'
 354           Remove any existing instantiators whose tag set is the same as
 355           TAG-SET; then put the new instantiator at the end of the
 356           current list.
 357
 358     `remove-locale'
 359           Remove all previous instantiators for this locale before
 360           adding the new spec.
 361
 362     `remove-locale-type'
 363           Remove all specifications for all locales of the same type as
 364           LOCALE (this includes LOCALE itself) before adding the new
 365           spec.
 366
 367     `remove-all'
 368           Remove all specifications from the specifier before adding
 369           the new spec.
 370
 371      `remove-tag-set-prepend' is the default.
 372
 373      You can retrieve the specifications for a particular locale or
 374      locale type with the function `specifier-spec-list' or
 375      `specifier-specs'.
 376
 377  - Function: add-spec-list-to-specifier specifier spec-list &optional
 378           how-to-add
 379      This function adds a "spec-list" (a list of specifications) to
 380      SPECIFIER.  The format of a spec-list is
 381
 382             `((LOCALE (TAG-SET . INSTANTIATOR) ...) ...)'
 383
 384      where
 385
 386         * LOCALE := a window, a buffer, a frame, a device, or `global'
 387
 388         * TAG-SET := an unordered list of zero or more TAGS, each of
 389           which is a symbol
 390
 391         * TAG := a device class (*note Consoles and Devices::), a
 392           device type, or a tag defined with `define-specifier-tag'
 393
 394         * INSTANTIATOR := format determined by the type of specifier
 395
 396      The pair `(TAG-SET . INSTANTIATOR)' is called an "inst-pair".  A
 397      list of inst-pairs is called an "inst-list".  The pair `(LOCALE .
 398      INST-LIST)' is called a "specification".  A spec-list, then, can
 399      be viewed as a list of specifications.
 400
 401      HOW-TO-ADD specifies how to combine the new specifications with
 402      the existing ones, and has the same semantics as for
 403      `add-spec-to-specifier'.
 404
 405      In many circumstances, the higher-level function `set-specifier' is
 406      more convenient and should be used instead.
 407
 408  - Special Form: let-specifier specifier-list &rest body
 409      This special form temporarily adds specifications to specifiers,
 410      evaluates forms in BODY and restores the specifiers to their
 411      previous states.  The specifiers and their temporary
 412      specifications are listed in SPECIFIER-LIST.
 413
 414      The format of SPECIFIER-LIST is
 415
 416           ((SPECIFIER VALUE &optional LOCALE TAG-SET HOW-TO-ADD) ...)
 417
 418      SPECIFIER is the specifier to be temporarily modified.  VALUE is
 419      the instantiator to be temporarily added to specifier in LOCALE.
 420      LOCALE, TAG-SET and HOW-TO-ADD have the same meaning as in
 421      `add-spec-to-specifier'.
 422
 423      This special form is implemented as a macro; the code resulting
 424      from macro expansion will add specifications to specifiers using
 425      `add-spec-to-specifier'.  After forms in BODY are evaluated, the
 426      temporary specifications are removed and old specifier spec-lists
 427      are restored.
 428
 429      LOCALE, TAG-SET and HOW-TO-ADD may be omitted, and default to
 430      `nil'.  The value of the last form in BODY is returned.
 431
 432      NOTE: If you want the specifier's instance to change in all
 433      circumstances, use `(selected-window)' as the LOCALE.  If LOCALE
 434      is `nil' or omitted, it defaults to `global'.
 435
 436      The following example removes the 3D modeline effect in the
 437      currently selected window for the duration of a second:
 438
 439           (let-specifier ((modeline-shadow-thickness 0 (selected-window)))
 440             (sit-for 1))
 441
 442  - Function: set-specifier specifier value &optional locale tag-set
 443           how-to-add
 444      This function adds some specifications to SPECIFIER.  VALUE can be
 445      a single instantiator or tagged instantiator (added as a global
 446      specification), a list of tagged and/or untagged instantiators
 447      (added as a global specification), a cons of a locale and
 448      instantiator or locale and instantiator list, a list of such
 449      conses, or nearly any other reasonable form.  More specifically,
 450      VALUE can be anything accepted by `canonicalize-spec-list'.
 451
 452      LOCALE, TAG-SET, and HOW-TO-ADD are the same as in
 453      `add-spec-to-specifier'.
 454
 455      Note that `set-specifier' is exactly complementary to
 456      `specifier-specs' except in the case where SPECIFIER has no specs
 457      at all in it but `nil' is a valid instantiator (in that case,
 458      `specifier-specs' will return `nil' (meaning no specs) and
 459      `set-specifier' will interpret the `nil' as meaning "I'm adding a
 460      global instantiator and its value is `nil'"), or in strange cases
 461      where there is an ambiguity between a spec-list and an inst-list,
 462      etc. (The built-in specifier types are designed in such a way as
 463      to avoid any such ambiguities.)
 464
 465      If you want to work with spec-lists, you should probably not use
 466      these functions, but should use the lower-level functions
 467      `specifier-spec-list' and `add-spec-list-to-specifier'.  These
 468      functions always work with fully-qualified spec-lists; thus, there
 469      is no ambiguity.
 470
 471  - Function: canonicalize-inst-pair inst-pair specifier-type &optional
 472           noerror
 473      This function canonicalizes the given INST-PAIR.
 474
 475      SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST
 476      will be used for.
 477
 478      Canonicalizing means converting to the full form for an inst-pair,
 479      i.e.  `(TAG-SET . INSTANTIATOR)'.  A single, untagged instantiator
 480      is given a tag set of `nil' (the empty set), and a single tag is
 481      converted into a tag set consisting only of that tag.
 482
 483      If NOERROR is non-`nil', signal an error if the inst-pair is
 484      invalid; otherwise return `t'.
 485
 486  - Function: canonicalize-inst-list inst-list specifier-type &optional
 487           noerror
 488      This function canonicalizes the given INST-LIST (a list of
 489      inst-pairs).
 490
 491      SPECIFIER-TYPE specifies the type of specifier that this INST-LIST
 492      will be used for.
 493
 494      Canonicalizing means converting to the full form for an inst-list,
 495      i.e.  `((TAG-SET . INSTANTIATOR) ...)'.  This function accepts a
 496      single inst-pair or any abbreviation thereof or a list of
 497      (possibly abbreviated) inst-pairs. (See `canonicalize-inst-pair'.)
 498
 499      If NOERROR is non-`nil', signal an error if the inst-list is
 500      invalid; otherwise return `t'.
 501
 502  - Function: canonicalize-spec spec specifier-type &optional noerror
 503      This function canonicalizes the given SPEC (a specification).
 504
 505      SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST
 506      will be used for.
 507
 508      Canonicalizing means converting to the full form for a spec, i.e.
 509      `(LOCALE (TAG-SET . INSTANTIATOR) ...)'.  This function accepts a
 510      possibly abbreviated inst-list or a cons of a locale and a
 511      possibly abbreviated inst-list. (See `canonicalize-inst-list'.)
 512
 513      If NOERROR is `nil', signal an error if the specification is
 514      invalid; otherwise return `t'.
 515
 516  - Function: canonicalize-spec-list spec-list specifier-type &optional
 517           noerror
 518      This function canonicalizes the given SPEC-LIST (a list of
 519      specifications).
 520
 521      SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST
 522      will be used for.
 523
 524      Canonicalizing means converting to the full form for a spec-list,
 525      i.e.  `((LOCALE (TAG-SET . INSTANTIATOR) ...) ...)'.  This
 526      function accepts a possibly abbreviated specification or a list of
 527      such things. (See `canonicalize-spec'.) This is the function used
 528      to convert spec-lists accepted by `set-specifier' and such into a
 529      form suitable for `add-spec-list-to-specifier'.
 530
 531      This function tries extremely hard to resolve any ambiguities, and
 532      the built-in specifier types (font, image, toolbar, etc.) are
 533      designed so that there won't be any ambiguities.
 534
 535      If NOERROR is `nil', signal an error if the spec-list is invalid;
 536      otherwise return `t'.
 537
 538 \1f
 539 File: lispref.info,  Node: Retrieving Specifications,  Next: Specifier Tag Functions,  Prev: Adding Specifications,  Up: Specifiers
 540
 541 Retrieving the Specifications from a Specifier
 542 ==============================================
 543
 544  - Function: specifier-spec-list specifier &optional locale tag-set
 545           exact-p
 546      This function returns the spec-list of specifications for
 547      SPECIFIER in LOCALE.
 548
 549      If LOCALE is a particular locale (a window, buffer, frame, device,
 550      or the symbol `global'), a spec-list consisting of the
 551      specification for that locale will be returned.
 552
 553      If LOCALE is a locale type (i.e. one of the symbols `window',
 554      `buffer', `frame', or `device'), a spec-list of the specifications
 555      for all locales of that type will be returned.
 556
 557      If LOCALE is `nil' or the symbol `all', a spec-list of all
 558      specifications in SPECIFIER will be returned.
 559
 560      LOCALE can also be a list of locales, locale types, and/or `all';
 561      the result is as if `specifier-spec-list' were called on each
 562      element of the list and the results concatenated together.
 563
 564      Only instantiators where TAG-SET (a list of zero or more tags) is
 565      a subset of (or possibly equal to) the instantiator's tag set are
 566      returned.  (The default value of `nil' is a subset of all tag sets,
 567      so in this case no instantiators will be screened out.) If EXACT-P
 568      is non-`nil', however, TAG-SET must be equal to an instantiator's
 569      tag set for the instantiator to be returned.
 570
 571  - Function: specifier-specs specifier &optional locale tag-set exact-p
 572      This function returns the specification(s) for SPECIFIER in LOCALE.
 573
 574      If LOCALE is a single locale or is a list of one element
 575      containing a single locale, then a "short form" of the
 576      instantiators for that locale will be returned.  Otherwise, this
 577      function is identical to `specifier-spec-list'.
 578
 579      The "short form" is designed for readability and not for ease of
 580      use in Lisp programs, and is as follows:
 581
 582        1. If there is only one instantiator, then an inst-pair (i.e.
 583           cons of tag and instantiator) will be returned; otherwise a
 584           list of inst-pairs will be returned.
 585
 586        2. For each inst-pair returned, if the instantiator's tag is
 587           `any', the tag will be removed and the instantiator itself
 588           will be returned instead of the inst-pair.
 589
 590        3. If there is only one instantiator, its value is `nil', and
 591           its tag is `any', a one-element list containing `nil' will be
 592           returned rather than just `nil', to distinguish this case
 593           from there being no instantiators at all.
 594
 595
 596  - Function: specifier-fallback specifier
 597      This function returns the fallback value for SPECIFIER.  Fallback
 598      values are provided by the C code for certain built-in specifiers
 599      to make sure that instancing won't fail even if all specs are
 600      removed from the specifier, or to implement simple inheritance
 601      behavior (e.g. this method is used to ensure that faces other than
 602      `default' inherit their attributes from `default').  By design,
 603      you cannot change the fallback value, and specifiers created with
 604      `make-specifier' will never have a fallback (although a similar,
 605      Lisp-accessible capability may be provided in the future to allow
 606      for inheritance).
 607
 608      The fallback value will be an inst-list that is instanced like any
 609      other inst-list, a specifier of the same type as SPECIFIER
 610      (results in inheritance), or `nil' for no fallback.
 611
 612      When you instance a specifier, you can explicitly request that the
 613      fallback not be consulted. (The C code does this, for example, when
 614      merging faces.) See `specifier-instance'.
 615
 616 \1f
 617 File: lispref.info,  Node: Specifier Tag Functions,  Next: Specifier Instancing Functions,  Prev: Retrieving Specifications,  Up: Specifiers
 618
 619 Working With Specifier Tags
 620 ===========================
 621
 622    A specifier tag set is an entity that is attached to an instantiator
 623 and can be used to restrict the scope of that instantiator to a
 624 particular device class or device type and/or to mark instantiators
 625 added by a particular package so that they can be later removed.
 626
 627    A specifier tag set consists of a list of zero or more specifier
 628 tags, each of which is a symbol that is recognized by XEmacs as a tag.
 629 (The valid device types and device classes are always tags, as are any
 630 tags defined by `define-specifier-tag'.) It is called a "tag set" (as
 631 opposed to a list) because the order of the tags or the number of times
 632 a particular tag occurs does not matter.
 633
 634    Each tag has a predicate associated with it, which specifies whether
 635 that tag applies to a particular device.  The tags which are device
 636 types and classes match devices of that type or class.  User-defined
 637 tags can have any predicate, or none (meaning that all devices match).
 638 When attempting to instance a specifier, a particular instantiator is
 639 only considered if the device of the domain being instanced over matches
 640 all tags in the tag set attached to that instantiator.
 641
 642    Most of the time, a tag set is not specified, and the instantiator
 643 gets a null tag set, which matches all devices.
 644
 645  - Function: valid-specifier-tag-p tag
 646      This function returns non-`nil' if TAG is a valid specifier tag.
 647
 648  - Function: valid-specifier-tag-set-p tag-set
 649      This function returns non-`nil' if TAG-SET is a valid specifier
 650      tag set.
 651
 652  - Function: canonicalize-tag-set tag-set
 653      This function canonicalizes the given tag set.  Two canonicalized
 654      tag sets can be compared with `equal' to see if they represent the
 655      same tag set. (Specifically, canonicalizing involves sorting by
 656      symbol name and removing duplicates.)
 657
 658  - Function: device-matches-specifier-tag-set-p device tag-set
 659      This function returns non-`nil' if DEVICE matches specifier tag
 660      set TAG-SET.  This means that DEVICE matches each tag in the tag
 661      set.
 662
 663  - Function: define-specifier-tag tag &optional predicate
 664      This function defines a new specifier tag.  If PREDICATE is
 665      specified, it should be a function of one argument (a device) that
 666      specifies whether the tag matches that particular device.  If
 667      PREDICATE is omitted, the tag matches all devices.
 668
 669      You can redefine an existing user-defined specifier tag.  However,
 670      you cannot redefine the built-in specifier tags (the device types
 671      and classes) or the symbols `nil', `t', `all', or `global'.
 672
 673  - Function: device-matching-specifier-tag-list &optional device
 674      This function returns a list of all specifier tags matching
 675      DEVICE.  DEVICE defaults to the selected device if omitted.
 676
 677  - Function: specifier-tag-list
 678      This function returns a list of all currently-defined specifier
 679      tags.  This includes the built-in ones (the device types and
 680      classes).
 681
 682  - Function: specifier-tag-predicate tag
 683      This function returns the predicate for the given specifier tag.
 684
 685 \1f
 686 File: lispref.info,  Node: Specifier Instancing Functions,  Next: Specifier Example,  Prev: Specifier Tag Functions,  Up: Specifiers
 687
 688 Functions for Instancing a Specifier
 689 ====================================
 690
 691  - Function: specifier-instance specifier &optional domain default
 692           no-fallback
 693      This function instantiates SPECIFIER (return its value) in DOMAIN.
 694      If no instance can be generated for this domain, return DEFAULT.
 695
 696      DOMAIN should be a window, frame, or device.  Other values that
 697      are legal as a locale (e.g. a buffer) are not valid as a domain
 698      because they do not provide enough information to identify a
 699      particular device (see `valid-specifier-domain-p').  DOMAIN
 700      defaults to the selected window if omitted.
 701
 702      "Instantiating" a specifier in a particular domain means
 703      determining the specifier's "value" in that domain.  This is
 704      accomplished by searching through the specifications in the
 705      specifier that correspond to all locales that can be derived from
 706      the given domain, from specific to general.  In most cases, the
 707      domain is an Emacs window.  In that case specifications are
 708      searched for as follows:
 709
 710        1. A specification whose locale is the window itself;
 711
 712        2. A specification whose locale is the window's buffer;
 713
 714        3. A specification whose locale is the window's frame;
 715
 716        4. A specification whose locale is the window's frame's device;
 717
 718        5. A specification whose locale is the symbol `global'.
 719
 720      If all of those fail, then the C-code-provided fallback value for
 721      this specifier is consulted (see `specifier-fallback').  If it is
 722      an inst-list, then this function attempts to instantiate that list
 723      just as when a specification is located in the first five steps
 724      above.  If the fallback is a specifier, `specifier-instance' is
 725      called recursively on this specifier and the return value used.
 726      Note, however, that if the optional argument NO-FALLBACK is
 727      non-`nil', the fallback value will not be consulted.
 728
 729      Note that there may be more than one specification matching a
 730      particular locale; all such specifications are considered before
 731      looking for any specifications for more general locales.  Any
 732      particular specification that is found may be rejected because it
 733      is tagged to a particular device class (e.g. `color') or device
 734      type (e.g. `x') or both and the device for the given domain does
 735      not match this, or because the specification is not valid for the
 736      device of the given domain (e.g.  the font or color name does not
 737      exist for this particular X server).
 738
 739      The returned value is dependent on the type of specifier.  For
 740      example, for a font specifier (as returned by the `face-font'
 741      function), the returned value will be a font-instance object.  For
 742      images, the returned value will be a string, pixmap, or subwindow.
 743
 744  - Function: specifier-instance-from-inst-list specifier domain
 745           inst-list &optional default
 746      This function attempts to convert a particular inst-list into an
 747      instance.  This attempts to instantiate INST-LIST in the given
 748      DOMAIN, as if INST-LIST existed in a specification in SPECIFIER.
 749      If the instantiation fails, DEFAULT is returned.  In most
 750      circumstances, you should not use this function; use
 751      `specifier-instance' instead.
 752
 753 \1f
 754 File: lispref.info,  Node: Specifier Example,  Next: Creating Specifiers,  Prev: Specifier Instancing Functions,  Up: Specifiers
 755
 756 Example of Specifier Usage
 757 ==========================
 758
 759    Now let us present an example to clarify the theoretical discussions
 760 we have been through.  In this example, we will use the general
 761 specifier functions for clarity.  Keep in mind that many types of
 762 specifiers, and some other types of objects that are associated with
 763 specifiers (e.g. faces), provide convenience functions making it easier
 764 to work with objects of that type.
 765
 766    Let us consider the background color of the default face.  A
 767 specifier is used to specify how that color will appear in different
 768 domains.  First, let's retrieve the specifier:
 769
 770      (setq sp (face-property 'default 'background))
 771          =>   #<color-specifier 0x3da>
 772
 773      (specifier-specs sp)
 774          =>   ((#<buffer "device.c"> (nil . "forest green"))
 775                       (#<window on "Makefile" 0x8a2b> (nil . "hot pink"))
 776                       (#<x-frame "emacs" 0x4ac> (nil . "puke orange")
 777                                                 (nil . "moccasin"))
 778                       (#<x-frame "VM" 0x4ac> (nil . "magenta"))
 779                       (global ((tty) . "cyan") (nil . "white"))
 780                      )
 781
 782    Then, say we want to determine what the background color of the
 783 default face is for the window currently displaying the buffer
 784 `*scratch*'.  We call
 785
 786      (get-buffer-window "*scratch*")
 787          => #<window on "*scratch*" 0x4ad>
 788      (window-frame (get-buffer-window "*scratch*"))
 789          => #<x-frame "emacs" 0x4ac>
 790      (specifier-instance sp (get-buffer-window "*scratch*"))
 791          => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x6309>
 792
 793    Note that we passed a window to `specifier-instance', not a buffer.
 794 We cannot pass a buffer because a buffer by itself does not provide
 795 enough information.  The buffer might not be displayed anywhere at all,
 796 or could be displayed in many different frames on different devices.
 797
 798    The result is arrived at like this:
 799
 800   1. First, we look for a specification matching the buffer displayed
 801      in the window, i.e. `*scratch*'.  There are none, so we proceed.
 802
 803   2. Then, we look for a specification matching the window itself.
 804      Again, there are none.
 805
 806   3. Then, we look for a specification matching the window's frame.  The
 807      specification `(#<x-frame "emacs" 0x4ac> . "puke orange")' is
 808      found.  We call the instantiation method for colors, passing it the
 809      locale we were searching over (i.e. the window, in this case) and
 810      the instantiator (`"puke orange"').  However, the particular device
 811      which this window is on (let's say it's an X connection) doesn't
 812      recognize the color `"puke orange"', so the specification is
 813      rejected.
 814
 815   4. So we continue looking for a specification matching the window's
 816      frame.  We find `(#<x-frame "emacs" 0x4ac> . "moccasin")'.  Again,
 817      we call the instantiation method for colors.  This time, the X
 818      server our window is on recognizes the color `moccasin', and so the
 819      instantiation method succeeds and returns a color instance.
 820
 821 \1f
 822 File: lispref.info,  Node: Creating Specifiers,  Next: Specifier Validation Functions,  Prev: Specifier Example,  Up: Specifiers
 823
 824 Creating New Specifier Objects
 825 ==============================
 826
 827  - Function: make-specifier type
 828      This function creates a new specifier.
 829
 830      A specifier is an object that can be used to keep track of a
 831      property whose value can be per-buffer, per-window, per-frame, or
 832      per-device, and can further be restricted to a particular
 833      device-type or device-class.  Specifiers are used, for example,
 834      for the various built-in properties of a face; this allows a face
 835      to have different values in different frames, buffers, etc.  For
 836      more information, see `specifier-instance', `specifier-specs', and
 837      `add-spec-to-specifier'; or, for a detailed description of
 838      specifiers, including how they are instantiated over a particular
 839      domain (i.e. how their value in that domain is determined), see
 840      the chapter on specifiers in the XEmacs Lisp Reference Manual.
 841
 842      TYPE specifies the particular type of specifier, and should be one
 843      of the symbols `generic', `integer', `natnum', `boolean', `color',
 844      `font', `image', `face-boolean', or `toolbar'.
 845
 846      For more information on particular types of specifiers, see the
 847      functions `make-generic-specifier', `make-integer-specifier',
 848      `make-natnum-specifier', `make-boolean-specifier',
 849      `make-color-specifier', `make-font-specifier',
 850      `make-image-specifier', `make-face-boolean-specifier', and
 851      `make-toolbar-specifier'.
 852
 853  - Function: make-specifier-and-init type spec-list &optional
 854           dont-canonicalize
 855      This function creates and initialize a new specifier.
 856
 857      This is a front-end onto `make-specifier' that allows you to create
 858      a specifier and add specs to it at the same time.  TYPE specifies
 859      the specifier type.  SPEC-LIST supplies the specification(s) to be
 860      added to the specifier. Normally, almost any reasonable
 861      abbreviation of the full spec-list form is accepted, and is
 862      converted to the full form; however, if optional argument
 863      DONT-CANONICALIZE is non-`nil', this conversion is not performed,
 864      and the SPEC-LIST must already be in full form.  See
 865      `canonicalize-spec-list'.
 866
 867  - Function: make-integer-specifier spec-list
 868      Return a new `integer' specifier object with the given
 869      specification list.  SPEC-LIST can be a list of specifications
 870      (each of which is a cons of a locale and a list of instantiators),
 871      a single instantiator, or a list of instantiators.
 872
 873      Valid instantiators for integer specifiers are integers.
 874
 875  - Function: make-boolean-specifier spec-list
 876      Return a new `boolean' specifier object with the given
 877      specification list.  SPEC-LIST can be a list of specifications
 878      (each of which is a cons of a locale and a list of instantiators),
 879      a single instantiator, or a list of instantiators.
 880
 881      Valid instantiators for boolean specifiers are `t' and `nil'.
 882
 883  - Function: make-natnum-specifier spec-list
 884      Return a new `natnum' specifier object with the given specification
 885      list.  SPEC-LIST can be a list of specifications (each of which is
 886      a cons of a locale and a list of instantiators), a single
 887      instantiator, or a list of instantiators.
 888
 889      Valid instantiators for natnum specifiers are non-negative
 890      integers.
 891
 892  - Function: make-generic-specifier spec-list
 893      Return a new `generic' specifier object with the given
 894      specification list.  SPEC-LIST can be a list of specifications
 895      (each of which is a cons of a locale and a list of instantiators),
 896      a single instantiator, or a list of instantiators.
 897
 898      Valid instantiators for generic specifiers are all Lisp values.
 899      They are returned back unchanged when a specifier is instantiated.
 900
 901  - Function: make-display-table-specifier spec-list
 902      Return a new `display-table' specifier object with the given spec
 903      list.  SPEC-LIST can be a list of specifications (each of which is
 904      a cons of a locale and a list of instantiators), a single
 905      instantiator, or a list of instantiators.
 906
 907      Valid instantiators for display-table specifiers are described in
 908      detail in the doc string for `current-display-table' (*note Active
 909      Display Table::).
 910
 911 \1f
 912 File: lispref.info,  Node: Specifier Validation Functions,  Next: Other Specification Functions,  Prev: Creating Specifiers,  Up: Specifiers
 913
 914 Functions for Checking the Validity of Specifier Components
 915 ===========================================================
 916
 917  - Function: valid-specifier-domain-p domain
 918      This function returns non-`nil' if DOMAIN is a valid specifier
 919      domain.  A domain is used to instance a specifier (i.e. determine
 920      the specifier's value in that domain).  Valid domains are a
 921      window, frame, or device.  (`nil' is not valid.)
 922
 923  - Function: valid-specifier-locale-p locale
 924      This function returns non-`nil' if LOCALE is a valid specifier
 925      locale.  Valid locales are a device, a frame, a window, a buffer,
 926      and `global'.  (`nil' is not valid.)
 927
 928  - Function: valid-specifier-locale-type-p locale-type
 929      Given a specifier LOCALE-TYPE, this function returns non-`nil' if
 930      it is valid.  Valid locale types are the symbols `global',
 931      `device', `frame', `window', and `buffer'. (Note, however, that in
 932      functions that accept either a locale or a locale type, `global'
 933      is considered an individual locale.)
 934
 935  - Function: valid-specifier-type-p specifier-type
 936      Given a SPECIFIER-TYPE, this function returns non-`nil' if it is
 937      valid.  Valid types are `generic', `integer', `boolean', `color',
 938      `font', `image', `face-boolean', and `toolbar'.
 939
 940  - Function: valid-specifier-tag-p tag
 941      This function returns non-`nil' if TAG is a valid specifier tag.
 942
 943  - Function: valid-instantiator-p instantiator specifier-type
 944      This function returns non-`nil' if INSTANTIATOR is valid for
 945      SPECIFIER-TYPE.
 946
 947  - Function: valid-inst-list-p inst-list type
 948      This function returns non-`nil' if INST-LIST is valid for
 949      specifier type TYPE.
 950
 951  - Function: valid-spec-list-p spec-list type
 952      This function returns non-`nil' if SPEC-LIST is valid for
 953      specifier type TYPE.
 954
 955  - Function: check-valid-instantiator instantiator specifier-type
 956      This function signals an error if INSTANTIATOR is invalid for
 957      SPECIFIER-TYPE.
 958
 959  - Function: check-valid-inst-list inst-list type
 960      This function signals an error if INST-LIST is invalid for
 961      specifier type TYPE.
 962
 963  - Function: check-valid-spec-list spec-list type
 964      This function signals an error if SPEC-LIST is invalid for
 965      specifier type TYPE.
 966
 967 \1f
 968 File: lispref.info,  Node: Other Specification Functions,  Prev: Specifier Validation Functions,  Up: Specifiers
 969
 970 Other Functions for Working with Specifications in a Specifier
 971 ==============================================================
 972
 973  - Function: copy-specifier specifier &optional dest locale tag-set
 974           exact-p how-to-add
 975      This function copies SPECIFIER to DEST, or creates a new one if
 976      DEST is `nil'.
 977
 978      If DEST is `nil' or omitted, a new specifier will be created and
 979      the specifications copied into it.  Otherwise, the specifications
 980      will be copied into the existing specifier in DEST.
 981
 982      If LOCALE is `nil' or the symbol `all', all specifications will be
 983      copied.  If LOCALE is a particular locale, the specification for
 984      that particular locale will be copied.  If LOCALE is a locale
 985      type, the specifications for all locales of that type will be
 986      copied.  LOCALE can also be a list of locales, locale types,
 987      and/or `all'; this is equivalent to calling `copy-specifier' for
 988      each of the elements of the list.  See `specifier-spec-list' for
 989      more information about LOCALE.
 990
 991      Only instantiators where TAG-SET (a list of zero or more tags) is
 992      a subset of (or possibly equal to) the instantiator's tag set are
 993      copied.  (The default value of `nil' is a subset of all tag sets,
 994      so in this case no instantiators will be screened out.) If EXACT-P
 995      is non-`nil', however, TAG-SET must be equal to an instantiator's
 996      tag set for the instantiator to be copied.
 997
 998      Optional argument HOW-TO-ADD specifies what to do with existing
 999      specifications in DEST.  If `nil', then whichever locales or locale
1000      types are copied will first be completely erased in DEST.
1001      Otherwise, it is the same as in `add-spec-to-specifier'.
1002
1003  - Function: remove-specifier specifier &optional locale tag-set exact-p
1004      This function removes specification(s) for SPECIFIER.
1005
1006      If LOCALE is a particular locale (a buffer, window, frame, device,
1007      or the symbol `global'), the specification for that locale will be
1008      removed.
1009
1010      If instead, LOCALE is a locale type (i.e. a symbol `buffer',
1011      `window', `frame', or `device'), the specifications for all
1012      locales of that type will be removed.
1013
1014      If LOCALE is `nil' or the symbol `all', all specifications will be
1015      removed.
1016
1017      LOCALE can also be a list of locales, locale types, and/or `all';
1018      this is equivalent to calling `remove-specifier' for each of the
1019      elements in the list.
1020
1021      Only instantiators where TAG-SET (a list of zero or more tags) is
1022      a subset of (or possibly equal to) the instantiator's tag set are
1023      removed.  (The default value of `nil' is a subset of all tag sets,
1024      so in this case no instantiators will be screened out.) If EXACT-P
1025      is non-`nil', however, TAG-SET must be equal to an instantiator's
1026      tag set for the instantiator to be removed.
1027
1028  - Function: map-specifier specifier func &optional locale maparg
1029      This function applies FUNC to the specification(s) for LOCALE in
1030      SPECIFIER.
1031
1032      If LOCALE is a locale, FUNC will be called for that locale.  If
1033      LOCALE is a locale type, FUNC will be mapped over all locales of
1034      that type.  If LOCALE is `nil' or the symbol `all', FUNC will be
1035      mapped over all locales in SPECIFIER.
1036
1037      FUNC is called with four arguments: the SPECIFIER, the locale
1038      being mapped over, the inst-list for that locale, and the optional
1039      MAPARG.  If any invocation of FUNC returns non-`nil', the mapping
1040      will stop and the returned value becomes the value returned from
1041      `map-specifier'.  Otherwise, `map-specifier' returns `nil'.
1042
1043  - Function: specifier-locale-type-from-locale locale
1044      Given a specifier LOCALE, this function returns its type.
1045
1046 \1f
1047 File: lispref.info,  Node: Faces and Window-System Objects,  Next: Glyphs,  Prev: Specifiers,  Up: Top
1048
1049 Faces and Window-System Objects
1050 *******************************
1051
1052 * Menu:
1053
1054 * Faces::               Controlling the way text looks.
1055 * Fonts::               Controlling the typeface of text.
1056 * Colors::              Controlling the color of text and pixmaps.
1057
1058 \1f
1059 File: lispref.info,  Node: Faces,  Next: Fonts,  Up: Faces and Window-System Objects
1060
1061 Faces
1062 =====
1063
1064    A "face" is a named collection of graphical properties: font,
1065 foreground color, background color, background pixmap, optional
1066 underlining, and (on TTY devices) whether the text is to be highlighted,
1067 dimmed, blinking, or displayed in reverse video.  Faces control the
1068 display of text on the screen.  Every face has a name, which is a symbol
1069 such as `default' or `modeline'.
1070
1071    Each built-in property of a face is controlled using a specifier,
1072 which allows it to have separate values in particular buffers, frames,
1073 windows, and devices and to further vary according to device type (X or
1074 TTY) and device class (color, mono, or grayscale).  *Note Specifiers::,
1075 for more information.
1076
1077    The face named `default' is used for ordinary text.  The face named
1078 `modeline' is used for displaying the modeline.  The face named
1079 `highlight' is used for highlighted extents (*note Extents::).  The
1080 faces named `left-margin' and `right-margin' are used for the left and
1081 right margin areas, respectively (*note Annotations::).  The face named
1082 `zmacs-region' is used for the highlighted region between point and
1083 mark.
1084
1085 * Menu:
1086
1087 * Merging Faces::               How XEmacs decides which face to use
1088                                   for a character.
1089 * Basic Face Functions::        How to define and examine faces.
1090 * Face Properties::             How to access and modify a face's properties.
1091 * Face Convenience Functions::  Convenience functions for accessing
1092                                   particular properties of a face.
1093 * Other Face Display Functions:: Other functions pertaining to how a
1094                                   a face appears.
1095