1 This is ../info/lispref.info, produced by makeinfo version 4.0b from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
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
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.
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.
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.
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.
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.
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.
53 File: lispref.info, Node: Specifiers In-Depth, Next: Specifier Instancing, Prev: Introduction to Specifiers, Up: Specifiers
55 In-Depth Overview of a Specifier
56 ================================
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
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.
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.)
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
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.
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
137 File: lispref.info, Node: Specifier Instancing, Next: Specifier Types, Prev: Specifiers In-Depth, Up: Specifiers
139 How a Specifier Is Instanced
140 ============================
142 Instancing of a specifier in a particular window domain proceeds as
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.
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.)
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
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.
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.)
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'
199 File: lispref.info, Node: Specifier Types, Next: Adding Specifications, Prev: Specifier Instancing, Up: Specifiers
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
210 The valid instantiators are the symbols `t' and `nil'. Instance
211 objects are the same as instantiators so no special instantiation
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).
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'.
228 All Lisp objects are valid instantiators. Instance objects are
229 the same as instantiators so no special instantiation function is
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
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.
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.
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'
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.
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.
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.
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
287 Functions are also provided to query whether an object is a
288 particular kind of specifier:
290 - Function: boolean-specifier-p object
291 This function returns non-`nil' if OBJECT is a boolean specifier.
293 - Function: integer-specifier-p object
294 This function returns non-`nil' if OBJECT is an integer specifier.
296 - Function: natnum-specifier-p object
297 This function returns non-`nil' if OBJECT is a natnum specifier.
299 - Function: generic-specifier-p object
300 This function returns non-`nil' if OBJECT is a generic specifier.
302 - Function: face-boolean-specifier-p object
303 This function returns non-`nil' if OBJECT is a face-boolean
306 - Function: toolbar-specifier-p object
307 This function returns non-`nil' if OBJECT is a toolbar specifier.
309 - Function: font-specifier-p object
310 This function returns non-`nil' if OBJECT is a font specifier.
312 - Function: color-specifier-p object
313 This function returns non-`nil' if OBJECT is a color specifier.
315 - Function: image-specifier-p object
316 This function returns non-`nil' if OBJECT is an image specifier.
319 File: lispref.info, Node: Adding Specifications, Next: Retrieving Specifications, Prev: Specifier Types, Up: Specifiers
321 Adding specifications to a Specifier
322 ====================================
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
341 Put at the beginning of the current list of instantiators for
345 Add to the end of the current list of instantiators for
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.
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
359 Remove all previous instantiators for this locale before
363 Remove all specifications for all locales of the same type as
364 LOCALE (this includes LOCALE itself) before adding the new
368 Remove all specifications from the specifier before adding
371 `remove-tag-set-prepend' is the default.
373 You can retrieve the specifications for a particular locale or
374 locale type with the function `specifier-spec-list' or
377 - Function: add-spec-list-to-specifier specifier spec-list &optional
379 This function adds a "spec-list" (a list of specifications) to
380 SPECIFIER. The format of a spec-list is
382 `((LOCALE (TAG-SET . INSTANTIATOR) ...) ...)'
386 * LOCALE := a window, a buffer, a frame, a device, or `global'
388 * TAG-SET := an unordered list of zero or more TAGS, each of
391 * TAG := a device class (*note Consoles and Devices::), a
392 device type, or a tag defined with `define-specifier-tag'
394 * INSTANTIATOR := format determined by the type of specifier
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.
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'.
405 In many circumstances, the higher-level function `set-specifier' is
406 more convenient and should be used instead.
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.
414 The format of SPECIFIER-LIST is
416 ((SPECIFIER VALUE &optional LOCALE TAG-SET HOW-TO-ADD) ...)
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'.
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
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.
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'.
436 The following example removes the 3D modeline effect in the
437 currently selected window for the duration of a second:
439 (let-specifier ((modeline-shadow-thickness 0 (selected-window)))
442 - Function: set-specifier specifier value &optional locale tag-set
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'.
452 LOCALE, TAG-SET, and HOW-TO-ADD are the same as in
453 `add-spec-to-specifier'.
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.)
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
471 - Function: canonicalize-inst-pair inst-pair specifier-type &optional
473 This function canonicalizes the given INST-PAIR.
475 SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST
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.
483 If NOERROR is non-`nil', signal an error if the inst-pair is
484 invalid; otherwise return `t'.
486 - Function: canonicalize-inst-list inst-list specifier-type &optional
488 This function canonicalizes the given INST-LIST (a list of
491 SPECIFIER-TYPE specifies the type of specifier that this INST-LIST
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'.)
499 If NOERROR is non-`nil', signal an error if the inst-list is
500 invalid; otherwise return `t'.
502 - Function: canonicalize-spec spec specifier-type &optional noerror
503 This function canonicalizes the given SPEC (a specification).
505 SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST
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'.)
513 If NOERROR is `nil', signal an error if the specification is
514 invalid; otherwise return `t'.
516 - Function: canonicalize-spec-list spec-list specifier-type &optional
518 This function canonicalizes the given SPEC-LIST (a list of
521 SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST
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'.
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.
535 If NOERROR is `nil', signal an error if the spec-list is invalid;
536 otherwise return `t'.
539 File: lispref.info, Node: Retrieving Specifications, Next: Specifier Tag Functions, Prev: Adding Specifications, Up: Specifiers
541 Retrieving the Specifications from a Specifier
542 ==============================================
544 - Function: specifier-spec-list specifier &optional locale tag-set
546 This function returns the spec-list of specifications for
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.
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.
557 If LOCALE is `nil' or the symbol `all', a spec-list of all
558 specifications in SPECIFIER will be returned.
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.
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.
571 - Function: specifier-specs specifier &optional locale tag-set exact-p
572 This function returns the specification(s) for SPECIFIER in LOCALE.
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'.
579 The "short form" is designed for readability and not for ease of
580 use in Lisp programs, and is as follows:
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.
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.
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.
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
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.
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'.
617 File: lispref.info, Node: Specifier Tag Functions, Next: Specifier Instancing Functions, Prev: Retrieving Specifications, Up: Specifiers
619 Working With Specifier Tags
620 ===========================
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.
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.
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.
642 Most of the time, a tag set is not specified, and the instantiator
643 gets a null tag set, which matches all devices.
645 - Function: valid-specifier-tag-p tag
646 This function returns non-`nil' if TAG is a valid specifier tag.
648 - Function: valid-specifier-tag-set-p tag-set
649 This function returns non-`nil' if TAG-SET is a valid specifier
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.)
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
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.
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'.
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.
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
682 - Function: specifier-tag-predicate tag
683 This function returns the predicate for the given specifier tag.
686 File: lispref.info, Node: Specifier Instancing Functions, Next: Specifier Example, Prev: Specifier Tag Functions, Up: Specifiers
688 Functions for Instancing a Specifier
689 ====================================
691 - Function: specifier-instance specifier &optional domain default
693 This function instantiates SPECIFIER (return its value) in DOMAIN.
694 If no instance can be generated for this domain, return DEFAULT.
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.
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:
710 1. A specification whose locale is the window itself;
712 2. A specification whose locale is the window's buffer;
714 3. A specification whose locale is the window's frame;
716 4. A specification whose locale is the window's frame's device;
718 5. A specification whose locale is the symbol `global'.
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.
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).
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.
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.
754 File: lispref.info, Node: Specifier Example, Next: Creating Specifiers, Prev: Specifier Instancing Functions, Up: Specifiers
756 Example of Specifier Usage
757 ==========================
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.
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:
770 (setq sp (face-property 'default 'background))
771 => #<color-specifier 0x3da>
774 => ((#<buffer "device.c"> (nil . "forest green"))
775 (#<window on "Makefile" 0x8a2b> (nil . "hot pink"))
776 (#<x-frame "emacs" 0x4ac> (nil . "puke orange")
778 (#<x-frame "VM" 0x4ac> (nil . "magenta"))
779 (global ((tty) . "cyan") (nil . "white"))
782 Then, say we want to determine what the background color of the
783 default face is for the window currently displaying the buffer
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>
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.
798 The result is arrived at like this:
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.
803 2. Then, we look for a specification matching the window itself.
804 Again, there are none.
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
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.
822 File: lispref.info, Node: Creating Specifiers, Next: Specifier Validation Functions, Prev: Specifier Example, Up: Specifiers
824 Creating New Specifier Objects
825 ==============================
827 - Function: make-specifier type
828 This function creates a new specifier.
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.
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'.
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'.
853 - Function: make-specifier-and-init type spec-list &optional
855 This function creates and initialize a new specifier.
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'.
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.
873 Valid instantiators for integer specifiers are integers.
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.
881 Valid instantiators for boolean specifiers are `t' and `nil'.
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.
889 Valid instantiators for natnum specifiers are non-negative
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.
898 Valid instantiators for generic specifiers are all Lisp values.
899 They are returned back unchanged when a specifier is instantiated.
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.
907 Valid instantiators for display-table specifiers are described in
908 detail in the doc string for `current-display-table' (*note Active
912 File: lispref.info, Node: Specifier Validation Functions, Next: Other Specification Functions, Prev: Creating Specifiers, Up: Specifiers
914 Functions for Checking the Validity of Specifier Components
915 ===========================================================
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.)
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.)
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.)
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'.
940 - Function: valid-specifier-tag-p tag
941 This function returns non-`nil' if TAG is a valid specifier tag.
943 - Function: valid-instantiator-p instantiator specifier-type
944 This function returns non-`nil' if INSTANTIATOR is valid for
947 - Function: valid-inst-list-p inst-list type
948 This function returns non-`nil' if INST-LIST is valid for
951 - Function: valid-spec-list-p spec-list type
952 This function returns non-`nil' if SPEC-LIST is valid for
955 - Function: check-valid-instantiator instantiator specifier-type
956 This function signals an error if INSTANTIATOR is invalid for
959 - Function: check-valid-inst-list inst-list type
960 This function signals an error if INST-LIST is invalid for
963 - Function: check-valid-spec-list spec-list type
964 This function signals an error if SPEC-LIST is invalid for
968 File: lispref.info, Node: Other Specification Functions, Prev: Specifier Validation Functions, Up: Specifiers
970 Other Functions for Working with Specifications in a Specifier
971 ==============================================================
973 - Function: copy-specifier specifier &optional dest locale tag-set
975 This function copies SPECIFIER to DEST, or creates a new one if
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.
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.
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.
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'.
1003 - Function: remove-specifier specifier &optional locale tag-set exact-p
1004 This function removes specification(s) for SPECIFIER.
1006 If LOCALE is a particular locale (a buffer, window, frame, device,
1007 or the symbol `global'), the specification for that locale will be
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.
1014 If LOCALE is `nil' or the symbol `all', all specifications will be
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.
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.
1028 - Function: map-specifier specifier func &optional locale maparg
1029 This function applies FUNC to the specification(s) for LOCALE in
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.
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'.
1043 - Function: specifier-locale-type-from-locale locale
1044 Given a specifier LOCALE, this function returns its type.
1047 File: lispref.info, Node: Faces and Window-System Objects, Next: Glyphs, Prev: Specifiers, Up: Top
1049 Faces and Window-System Objects
1050 *******************************
1054 * Faces:: Controlling the way text looks.
1055 * Fonts:: Controlling the typeface of text.
1056 * Colors:: Controlling the color of text and pixmaps.
1059 File: lispref.info, Node: Faces, Next: Fonts, Up: Faces and Window-System Objects
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'.
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.
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
1087 * Merging Faces:: How XEmacs decides which face to use
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