1 This is Info file ../../info/lispref.info, produced by Makeinfo version
2 1.68 from the input file lispref.texi.
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: Specifier Instancing, Next: Specifier Types, Prev: Specifiers In-Depth, Up: Specifiers
55 How a Specifier Is Instanced
56 ============================
58 Instancing of a specifier in a particular window domain proceeds as
61 * First, XEmacs searches for a specification whose locale is the
62 same as the window. If that fails, the search is repeated,
63 looking for a locale that is the same as the window's buffer. If
64 that fails, the search is repeated using the window's frame, then
65 using the device that frame is on. Finally, the specification
66 whose locale is the symbol `global' (if there is such a
67 specification) is considered.
69 * The inst-pairs contained in the specification that was found are
70 considered in their order in the inst-list, looking for one whose
71 tag set matches the device that is derived from the window domain.
72 (The tag set is an unordered list of zero or more tag symbols.
73 For all tags that have predicates associated with them, the
74 predicate must match the device.)
76 * If a matching tag set is found, the corresponding instantiator is
77 passed to the specifier's instantiation method, which is specific
78 to the type of the specifier. If it succeeds, the resulting
79 instance object is returned as the result of the instancing and
80 the instancing is done. Otherwise, the operation continues,
81 looking for another matching inst-pair in the current
84 * When there are no more inst-pairs to be considered in the current
85 specification, the search starts over, looking for another
86 specification as in the first step above.
88 * If all specifications are exhausted and no instance object can be
89 derived, the instancing fails. (Actually, this is not completely
90 true. Some specifier objects for built-in properties have a
91 "fallback" value, which is either an inst-list or another
92 specifier object, that is consulted if the instancing is about to
93 fail. If it is an inst-list, the searching proceeds using the
94 inst-pairs in that list. If it is a specifier, the entire
95 instancing starts over using that specifier instead of the given
96 one. Fallback values are set by the C code and cannot be
97 modified, except perhaps indirectly, using any Lisp functions.
98 The purpose of them is to supply some values to make sure that
99 instancing of built-in properties can't fail and to implement some
100 basic specifier inheritance, such as the fact that faces inherit
101 their properties from the `default' face.)
103 It is also possible to instance a specifier over a frame domain or
104 device domain instead of over a window domain. The C code, for example,
105 instances the `top-toolbar-height' variable over a frame domain in
106 order to determine the height of a frame's top toolbar. Instancing over
107 a frame or device is similar to instancing over a window except that
108 specifications for locales that cannot be derived from the domain are
109 ignored. Specifically, instancing over a frame looks first for frame
110 locales, then device locales, then the `global' locale. Instancing
111 over a device domain looks only for device locales and the `global'
115 File: lispref.info, Node: Specifier Types, Next: Adding Specifications, Prev: Specifier Instancing, Up: Specifiers
120 There are various different types of specifiers. The type of a
121 specifier controls what sorts of instantiators are valid, how an
122 instantiator is instantiated, etc. Here is a list of built-in specifier
126 The valid instantiators are the symbols `t' and `nil'. Instance
127 objects are the same as instantiators so no special instantiation
131 The valid instantiators are integers. Instance objects are the
132 same as instantiators so no special instantiation function is
133 needed. `modeline-shadow-thickness' is an example of an integer
134 specifier (negative thicknesses indicate that the shadow is drawn
135 recessed instead of raised).
138 The valid instantiators are natnums (non-negative integers).
139 Instance objects are the same as instantiators so no special
140 instantiation function is needed. Natnum specifiers are used for
141 dimension variables such as `top-toolbar-height'.
144 All Lisp objects are valid instantiators. Instance objects are
145 the same as instantiators so no special instantiation function is
149 The valid instantiators are strings describing fonts or vectors
150 indicating inheritance from the font of some face. Instance
151 objects are font-instance objects, which are specific to a
152 particular device. The instantiation method for font specifiers
153 can fail, unlike for integer, natnum, boolean, and generic
157 The valid instantiators are strings describing colors or vectors
158 indicating inheritance from the foreground or background of some
159 face. Instance objects are color-instance objects, which are
160 specific to a particular device. The instantiation method for
161 color specifiers can fail, as for font specifiers.
164 Images are perhaps the most complicated type of built-in
165 specifier. The valid instantiators are strings (a filename,
166 inline data for a pixmap, or text to be displayed in a text glyph)
167 or vectors describing inline data of various sorts or indicating
168 inheritance from the background-pixmap property of some face.
169 Instance objects are either strings (for text images),
170 image-instance objects (for pixmap images), or subwindow objects
171 (for subwindow images). The instantiation method for image
172 specifiers can fail, as for font and color specifiers.
175 The valid instantiators are the symbols `t' and `nil' and vectors
176 indicating inheritance from a boolean property of some face.
177 Specifiers of this sort are used for all of the built-in boolean
178 properties of faces. Instance objects are either the symbol `t'
182 The valid instantiators are toolbar descriptors, which are lists
183 of toolbar-button descriptors (each of which is a vector of two or
184 four elements). *Note Toolbar::, for more information.
186 Color and font instance objects can also be used in turn as
187 instantiators for a new color or font instance object. Since these
188 instance objects are device-specific, the instantiator can be used
189 directly as the new instance object, but only if they are of the same
190 device. If the devices differ, the base color or font of the
191 instantiating object is effectively used instead as the instantiator.
193 *Note Faces and Window-System Objects::, for more information on
194 fonts, colors, and face-boolean specifiers. *Note Glyphs::, for more
195 information about image specifiers. *Note Toolbar::, for more
196 information on toolbar specifiers.
198 - Function: specifier-type SPECIFIER
199 This function returns the type of SPECIFIER. The returned value
200 will be a symbol: one of `integer', `boolean', etc., as listed in
203 Functions are also provided to query whether an object is a
204 particular kind of specifier:
206 - Function: boolean-specifier-p OBJECT
207 This function returns non-`nil' if OBJECT is a boolean specifier.
209 - Function: integer-specifier-p OBJECT
210 This function returns non-`nil' if OBJECT is an integer specifier.
212 - Function: natnum-specifier-p OBJECT
213 This function returns non-`nil' if OBJECT is a natnum specifier.
215 - Function: generic-specifier-p OBJECT
216 This function returns non-`nil' if OBJECT is a generic specifier.
218 - Function: face-boolean-specifier-p OBJECT
219 This function returns non-`nil' if OBJECT is a face-boolean
222 - Function: toolbar-specifier-p OBJECT
223 This function returns non-`nil' if OBJECT is a toolbar specifier.
225 - Function: font-specifier-p OBJECT
226 This function returns non-`nil' if OBJECT is a font specifier.
228 - Function: color-specifier-p OBJECT
229 This function returns non-`nil' if OBJECT is a color specifier.
231 - Function: image-specifier-p OBJECT
232 This function returns non-`nil' if OBJECT is an image specifier.
235 File: lispref.info, Node: Adding Specifications, Next: Retrieving Specifications, Prev: Specifier Types, Up: Specifiers
237 Adding specifications to a Specifier
238 ====================================
240 - Function: add-spec-to-specifier SPECIFIER INSTANTIATOR &optional
241 LOCALE TAG-SET HOW-TO-ADD
242 This function adds a specification to SPECIFIER. The
243 specification maps from LOCALE (which should be a window, buffer,
244 frame, device, or the symbol `global', and defaults to `global')
245 to INSTANTIATOR, whose allowed values depend on the type of the
246 specifier. Optional argument TAG-SET limits the instantiator to
247 apply only to the specified tag set, which should be a list of
248 tags all of which must match the device being instantiated over
249 (tags are a device type, a device class, or tags defined with
250 `define-specifier-tag'). Specifying a single symbol for TAG-SET
251 is equivalent to specifying a one-element list containing that
252 symbol. Optional argument HOW-TO-ADD specifies what to do if
253 there are already specifications in the specifier. It should be
257 Put at the beginning of the current list of instantiators for
261 Add to the end of the current list of instantiators for
264 `remove-tag-set-prepend'
265 This is the default. Remove any existing instantiators whose
266 tag set is the same as TAG-SET; then put the new instantiator
267 at the beginning of the current list.
269 `remove-tag-set-append'
270 Remove any existing instantiators whose tag set is the same as
271 TAG-SET; then put the new instantiator at the end of the
275 Remove all previous instantiators for this locale before
279 Remove all specifications for all locales of the same type as
280 LOCALE (this includes LOCALE itself) before adding the new
284 Remove all specifications from the specifier before adding
287 `remove-tag-set-prepend' is the default.
289 You can retrieve the specifications for a particular locale or
290 locale type with the function `specifier-spec-list' or
293 - Function: add-spec-list-to-specifier SPECIFIER SPEC-LIST &optional
295 This function adds a "spec-list" (a list of specifications) to
296 SPECIFIER. The format of a spec-list is
298 `((LOCALE (TAG-SET . INSTANTIATOR) ...) ...)'
302 * LOCALE := a window, a buffer, a frame, a device, or `global'
304 * TAG-SET := an unordered list of zero or more TAGS, each of
307 * TAG := a device class (*note Consoles and Devices::.), a
308 device type, or a tag defined with `define-specifier-tag'
310 * INSTANTIATOR := format determined by the type of specifier
312 The pair `(TAG-SET . INSTANTIATOR)' is called an "inst-pair". A
313 list of inst-pairs is called an "inst-list". The pair `(LOCALE .
314 INST-LIST)' is called a "specification". A spec-list, then, can
315 be viewed as a list of specifications.
317 HOW-TO-ADD specifies how to combine the new specifications with
318 the existing ones, and has the same semantics as for
319 `add-spec-to-specifier'.
321 In many circumstances, the higher-level function `set-specifier' is
322 more convenient and should be used instead.
324 - Macro: let-specifier SPECIFIER-LIST &rest BODY
325 This special form temporarily adds specifications to specifiers,
326 evaluates forms in BODY and restores the specifiers to their
327 previous states. The specifiers and their temporary
328 specifications are listed in SPECIFIER-LIST.
330 The format of SPECIFIER-LIST is
332 ((SPECIFIER VALUE &optional LOCALE TAG-SET HOW-TO-ADD) ...)
334 SPECIFIER is the specifier to be temporarily modified. VALUE is
335 the instantiator to be temporarily added to specifier in LOCALE.
336 LOCALE, TAG-SET and HOW-TO-ADD have the same meaning as in
337 `add-spec-to-specifier'.
339 This special form is implemented as a macro; the code resulting
340 from macro expansion will add specifications to specifiers using
341 `add-spec-to-specifier'. After forms in BODY are evaluated, the
342 temporary specifications are removed and old specifier spec-lists
345 LOCALE, TAG-SET and HOW-TO-ADD may be omitted, and default to
346 `nil'. The value of the last form in BODY is returned.
348 NOTE: If you want the specifier's instance to change in all
349 circumstances, use `(selected-window)' as the LOCALE. If LOCALE
350 is `nil' or omitted, it defaults to `global'.
352 The following example removes the 3D modeline effect in the
353 currently selected window for the duration of a second:
355 (let-specifier ((modeline-shadow-thickness 0 (selected-window)))
358 - Function: set-specifier SPECIFIER VALUE &optional HOW-TO-ADD
359 This function adds some specifications to SPECIFIER. VALUE can be
360 a single instantiator or tagged instantiator (added as a global
361 specification), a list of tagged and/or untagged instantiators
362 (added as a global specification), a cons of a locale and
363 instantiator or locale and instantiator list, a list of such
364 conses, or nearly any other reasonable form. More specifically,
365 VALUE can be anything accepted by `canonicalize-spec-list'.
367 HOW-TO-ADD is the same as in `add-spec-to-specifier'.
369 Note that `set-specifier' is exactly complementary to
370 `specifier-specs' except in the case where SPECIFIER has no specs
371 at all in it but `nil' is a valid instantiator (in that case,
372 `specifier-specs' will return `nil' (meaning no specs) and
373 `set-specifier' will interpret the `nil' as meaning "I'm adding a
374 global instantiator and its value is `nil'"), or in strange cases
375 where there is an ambiguity between a spec-list and an inst-list,
376 etc. (The built-in specifier types are designed in such a way as
377 to avoid any such ambiguities.)
379 If you want to work with spec-lists, you should probably not use
380 these functions, but should use the lower-level functions
381 `specifier-spec-list' and `add-spec-list-to-specifier'. These
382 functions always work with fully-qualified spec-lists; thus, there
385 - Function: canonicalize-inst-pair INST-PAIR SPECIFIER-TYPE &optional
387 This function canonicalizes the given INST-PAIR.
389 SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST
392 Canonicalizing means converting to the full form for an inst-pair,
393 i.e. `(TAG-SET . INSTANTIATOR)'. A single, untagged instantiator
394 is given a tag set of `nil' (the empty set), and a single tag is
395 converted into a tag set consisting only of that tag.
397 If NOERROR is non-`nil', signal an error if the inst-pair is
398 invalid; otherwise return `t'.
400 - Function: canonicalize-inst-list INST-LIST SPECIFIER-TYPE &optional
402 This function canonicalizes the given INST-LIST (a list of
405 SPECIFIER-TYPE specifies the type of specifier that this INST-LIST
408 Canonicalizing means converting to the full form for an inst-list,
409 i.e. `((TAG-SET . INSTANTIATOR) ...)'. This function accepts a
410 single inst-pair or any abbreviation thereof or a list of
411 (possibly abbreviated) inst-pairs. (See `canonicalize-inst-pair'.)
413 If NOERROR is non-`nil', signal an error if the inst-list is
414 invalid; otherwise return `t'.
416 - Function: canonicalize-spec SPEC SPECIFIER-TYPE &optional NOERROR
417 This function canonicalizes the given SPEC (a specification).
419 SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST
422 Canonicalizing means converting to the full form for a spec, i.e.
423 `(LOCALE (TAG-SET . INSTANTIATOR) ...)'. This function accepts a
424 possibly abbreviated inst-list or a cons of a locale and a
425 possibly abbreviated inst-list. (See `canonicalize-inst-list'.)
427 If NOERROR is `nil', signal an error if the specification is
428 invalid; otherwise return `t'.
430 - Function: canonicalize-spec-list SPEC-LIST SPECIFIER-TYPE &optional
432 This function canonicalizes the given SPEC-LIST (a list of
435 SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST
438 Canonicalizing means converting to the full form for a spec-list,
439 i.e. `((LOCALE (TAG-SET . INSTANTIATOR) ...) ...)'. This
440 function accepts a possibly abbreviated specification or a list of
441 such things. (See `canonicalize-spec'.) This is the function used
442 to convert spec-lists accepted by `set-specifier' and such into a
443 form suitable for `add-spec-list-to-specifier'.
445 This function tries extremely hard to resolve any ambiguities, and
446 the built-in specifier types (font, image, toolbar, etc.) are
447 designed so that there won't be any ambiguities.
449 If NOERROR is `nil', signal an error if the spec-list is invalid;
450 otherwise return `t'.
453 File: lispref.info, Node: Retrieving Specifications, Next: Specifier Tag Functions, Prev: Adding Specifications, Up: Specifiers
455 Retrieving the Specifications from a Specifier
456 ==============================================
458 - Function: specifier-spec-list SPECIFIER &optional LOCALE TAG-SET
460 This function returns the spec-list of specifications for
463 If LOCALE is a particular locale (a window, buffer, frame, device,
464 or the symbol `global'), a spec-list consisting of the
465 specification for that locale will be returned.
467 If LOCALE is a locale type (i.e. a symbol `window', `buffer',
468 `frame', or `device'), a spec-list of the specifications for all
469 locales of that type will be returned.
471 If LOCALE is `nil' or the symbol `all', a spec-list of all
472 specifications in SPECIFIER will be returned.
474 LOCALE can also be a list of locales, locale types, and/or `all';
475 the result is as if `specifier-spec-list' were called on each
476 element of the list and the results concatenated together.
478 Only instantiators where TAG-SET (a list of zero or more tags) is
479 a subset of (or possibly equal to) the instantiator's tag set are
480 returned. (The default value of` nil' is a subset of all tag sets,
481 so in this case no instantiators will be screened out.) If EXACT-P
482 is non-`nil', however, TAG-SET must be equal to an instantiator's
483 tag set for the instantiator to be returned.
485 - Function: specifier-specs SPECIFIER &optional LOCALE TAG-SET EXACT-P
486 This function returns the specification(s) for SPECIFIER in LOCALE.
488 If LOCALE is a single locale or is a list of one element
489 containing a single locale, then a "short form" of the
490 instantiators for that locale will be returned. Otherwise, this
491 function is identical to `specifier-spec-list'.
493 The "short form" is designed for readability and not for ease of
494 use in Lisp programs, and is as follows:
496 1. If there is only one instantiator, then an inst-pair (i.e.
497 cons of tag and instantiator) will be returned; otherwise a
498 list of inst-pairs will be returned.
500 2. For each inst-pair returned, if the instantiator's tag is
501 `any', the tag will be removed and the instantiator itself
502 will be returned instead of the inst-pair.
504 3. If there is only one instantiator, its value is `nil', and
505 its tag is `any', a one-element list containing `nil' will be
506 returned rather than just `nil', to distinguish this case
507 from there being no instantiators at all.
510 - Function: specifier-fallback SPECIFIER
511 This function returns the fallback value for SPECIFIER. Fallback
512 values are provided by the C code for certain built-in specifiers
513 to make sure that instancing won't fail even if all specs are
514 removed from the specifier, or to implement simple inheritance
515 behavior (e.g. this method is used to ensure that faces other than
516 `default' inherit their attributes from `default'). By design,
517 you cannot change the fallback value, and specifiers created with
518 `make-specifier' will never have a fallback (although a similar,
519 Lisp-accessible capability may be provided in the future to allow
522 The fallback value will be an inst-list that is instanced like any
523 other inst-list, a specifier of the same type as SPECIFIER
524 (results in inheritance), or `nil' for no fallback.
526 When you instance a specifier, you can explicitly request that the
527 fallback not be consulted. (The C code does this, for example, when
528 merging faces.) See `specifier-instance'.
531 File: lispref.info, Node: Specifier Tag Functions, Next: Specifier Instancing Functions, Prev: Retrieving Specifications, Up: Specifiers
533 Working With Specifier Tags
534 ===========================
536 A specifier tag set is an entity that is attached to an instantiator
537 and can be used to restrict the scope of that instantiator to a
538 particular device class or device type and/or to mark instantiators
539 added by a particular package so that they can be later removed.
541 A specifier tag set consists of a list of zero of more specifier
542 tags, each of which is a symbol that is recognized by XEmacs as a tag.
543 (The valid device types and device classes are always tags, as are any
544 tags defined by `define-specifier-tag'.) It is called a "tag set" (as
545 opposed to a list) because the order of the tags or the number of times
546 a particular tag occurs does not matter.
548 Each tag has a predicate associated with it, which specifies whether
549 that tag applies to a particular device. The tags which are device
550 types and classes match devices of that type or class. User-defined
551 tags can have any predicate, or none (meaning that all devices match).
552 When attempting to instance a specifier, a particular instantiator is
553 only considered if the device of the domain being instanced over matches
554 all tags in the tag set attached to that instantiator.
556 Most of the time, a tag set is not specified, and the instantiator
557 gets a null tag set, which matches all devices.
559 - Function: valid-specifier-tag-p TAG
560 This function returns non-`nil' if TAG is a valid specifier tag.
562 - Function: valid-specifier-tag-set-p TAG-SET
563 This function returns non-`nil' if TAG-SET is a valid specifier
566 - Function: canonicalize-tag-set TAG-SET
567 This function canonicalizes the given tag set. Two canonicalized
568 tag sets can be compared with `equal' to see if they represent the
569 same tag set. (Specifically, canonicalizing involves sorting by
570 symbol name and removing duplicates.)
572 - Function: device-matches-specifier-tag-set-p DEVICE TAG-SET
573 This function returns non-`nil' if DEVICE matches specifier tag
574 set TAG-SET. This means that DEVICE matches each tag in the tag
577 - Function: define-specifier-tag TAG &optional PREDICATE
578 This function defines a new specifier tag. If PREDICATE is
579 specified, it should be a function of one argument (a device) that
580 specifies whether the tag matches that particular device. If
581 PREDICATE is omitted, the tag matches all devices.
583 You can redefine an existing user-defined specifier tag. However,
584 you cannot redefine the built-in specifier tags (the device types
585 and classes) or the symbols `nil', `t', `all', or `global'.
587 - Function: device-matching-specifier-tag-list &optional DEVICE
588 This function returns a list of all specifier tags matching
589 DEVICE. DEVICE defaults to the selected device if omitted.
591 - Function: specifier-tag-list
592 This function returns a list of all currently-defined specifier
593 tags. This includes the built-in ones (the device types and
596 - Function: specifier-tag-predicate TAG
597 This function returns the predicate for the given specifier tag.
600 File: lispref.info, Node: Specifier Instancing Functions, Next: Specifier Example, Prev: Specifier Tag Functions, Up: Specifiers
602 Functions for Instancing a Specifier
603 ====================================
605 - Function: specifier-instance SPECIFIER &optional DOMAIN DEFAULT
607 This function instantiates SPECIFIER (return its value) in DOMAIN.
608 If no instance can be generated for this domain, return DEFAULT.
610 DOMAIN should be a window, frame, or device. Other values that
611 are legal as a locale (e.g. a buffer) are not valid as a domain
612 because they do not provide enough information to identify a
613 particular device (see `valid-specifier-domain-p'). DOMAIN
614 defaults to the selected window if omitted.
616 "Instantiating" a specifier in a particular domain means
617 determining the specifier's "value" in that domain. This is
618 accomplished by searching through the specifications in the
619 specifier that correspond to all locales that can be derived from
620 the given domain, from specific to general. In most cases, the
621 domain is an Emacs window. In that case specifications are
622 searched for as follows:
624 1. A specification whose locale is the window itself;
626 2. A specification whose locale is the window's buffer;
628 3. A specification whose locale is the window's frame;
630 4. A specification whose locale is the window's frame's device;
632 5. A specification whose locale is the symbol `global'.
634 If all of those fail, then the C-code-provided fallback value for
635 this specifier is consulted (see `specifier-fallback'). If it is
636 an inst-list, then this function attempts to instantiate that list
637 just as when a specification is located in the first five steps
638 above. If the fallback is a specifier, `specifier-instance' is
639 called recursively on this specifier and the return value used.
640 Note, however, that if the optional argument NO-FALLBACK is
641 non-`nil', the fallback value will not be consulted.
643 Note that there may be more than one specification matching a
644 particular locale; all such specifications are considered before
645 looking for any specifications for more general locales. Any
646 particular specification that is found may be rejected because it
647 is tagged to a particular device class (e.g. `color') or device
648 type (e.g. `x') or both and the device for the given domain does
649 not match this, or because the specification is not valid for the
650 device of the given domain (e.g. the font or color name does not
651 exist for this particular X server).
653 The returned value is dependent on the type of specifier. For
654 example, for a font specifier (as returned by the `face-font'
655 function), the returned value will be a font-instance object. For
656 images, the returned value will be a string, pixmap, or subwindow.
658 - Function: specifier-instance-from-inst-list SPECIFIER DOMAIN
659 INST-LIST &optional DEFAULT
660 This function attempts to convert a particular inst-list into an
661 instance. This attempts to instantiate INST-LIST in the given
662 DOMAIN, as if INST-LIST existed in a specification in SPECIFIER.
663 If the instantiation fails, DEFAULT is returned. In most
664 circumstances, you should not use this function; use
665 `specifier-instance' instead.
668 File: lispref.info, Node: Specifier Example, Next: Creating Specifiers, Prev: Specifier Instancing Functions, Up: Specifiers
670 Example of Specifier Usage
671 ==========================
673 Now let us present an example to clarify the theoretical discussions
674 we have been through. In this example, we will use the general
675 specifier functions for clarity. Keep in mind that many types of
676 specifiers, and some other types of objects that are associated with
677 specifiers (e.g. faces), provide convenience functions making it easier
678 to work with objects of that type.
680 Let us consider the background color of the default face. A
681 specifier is used to specify how that color will appear in different
682 domains. First, let's retrieve the specifier:
684 (setq sp (face-property 'default 'background))
685 => #<color-specifier 0x3da>
688 => ((#<buffer "device.c"> (nil . "forest green"))
689 (#<window on "Makefile" 0x8a2b> (nil . "hot pink"))
690 (#<x-frame "emacs" 0x4ac> (nil . "puke orange")
692 (#<x-frame "VM" 0x4ac> (nil . "magenta"))
693 (global ((tty) . "cyan") (nil . "white"))
696 Then, say we want to determine what the background color of the
697 default face is for the window currently displaying the buffer
700 (get-buffer-window "*scratch*")
701 => #<window on "*scratch*" 0x4ad>
702 (window-frame (get-buffer-window "*scratch*"))
703 => #<x-frame "emacs" 0x4ac>
704 (specifier-instance sp (get-buffer-window "*scratch*"))
705 => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x6309>
707 Note that we passed a window to `specifier-instance', not a buffer.
708 We cannot pass a buffer because a buffer by itself does not provide
709 enough information. The buffer might not be displayed anywhere at all,
710 or could be displayed in many different frames on different devices.
712 The result is arrived at like this:
714 1. First, we look for a specification matching the buffer displayed
715 in the window, i.e. `*scratch'. There are none, so we proceed.
717 2. Then, we look for a specification matching the window itself.
718 Again, there are none.
720 3. Then, we look for a specification matching the window's frame. The
721 specification `(#<x-frame "emacs" 0x4ac> . "puke orange")' is
722 found. We call the instantiation method for colors, passing it the
723 locale we were searching over (i.e. the window, in this case) and
724 the instantiator (`"puke orange"'). However, the particular device
725 which this window is on (let's say it's an X connection) doesn't
726 recognize the color `"puke orange"', so the specification is
729 4. So we continue looking for a specification matching the window's
730 frame. We find `(#<x-frame "emacs" 0x4ac> . "moccasin")'. Again,
731 we call the instantiation method for colors. This time, the X
732 server our window is on recognizes the color `moccasin', and so the
733 instantiation method succeeds and returns a color instance.
736 File: lispref.info, Node: Creating Specifiers, Next: Specifier Validation Functions, Prev: Specifier Example, Up: Specifiers
738 Creating New Specifier Objects
739 ==============================
741 - Function: make-specifier TYPE
742 This function creates a new specifier.
744 A specifier is an object that can be used to keep track of a
745 property whose value can be per-buffer, per-window, per-frame, or
746 per-device, and can further be restricted to a particular
747 device-type or device-class. Specifiers are used, for example,
748 for the various built-in properties of a face; this allows a face
749 to have different values in different frames, buffers, etc. For
750 more information, see `specifier-instance', `specifier-specs', and
751 `add-spec-to-specifier'; or, for a detailed description of
752 specifiers, including how they are instantiated over a particular
753 domain (i.e. how their value in that domain is determined), see
754 the chapter on specifiers in the XEmacs Lisp Reference Manual.
756 TYPE specifies the particular type of specifier, and should be one
757 of the symbols `generic', `integer', `natnum', `boolean', `color',
758 `font', `image', `face-boolean', or `toolbar'.
760 For more information on particular types of specifiers, see the
761 functions `generic-specifier-p', `integer-specifier-p',
762 `natnum-specifier-p', `boolean-specifier-p', `color-specifier-p',
763 `font-specifier-p', `image-specifier-p',
764 `face-boolean-specifier-p', and `toolbar-specifier-p'.
766 - Function: make-specifier-and-init TYPE SPEC-LIST &optional
768 This function creates and initialize a new specifier.
770 This is a front-end onto `make-specifier' that allows you to create
771 a specifier and add specs to it at the same time. TYPE specifies
772 the specifier type. SPEC-LIST supplies the specification(s) to be
773 added to the specifier. Normally, almost any reasonable
774 abbreviation of the full spec-list form is accepted, and is
775 converted to the full form; however, if optional argument
776 DONT-CANONICALIZE is non-`nil', this conversion is not performed,
777 and the SPEC-LIST must already be in full form. See
778 `canonicalize-spec-list'.
781 File: lispref.info, Node: Specifier Validation Functions, Next: Other Specification Functions, Prev: Creating Specifiers, Up: Specifiers
783 Functions for Checking the Validity of Specifier Components
784 ===========================================================
786 - Function: valid-specifier-domain-p DOMAIN
787 This function returns non-`nil' if DOMAIN is a valid specifier
788 domain. A domain is used to instance a specifier (i.e. determine
789 the specifier's value in that domain). Valid domains are a
790 window, frame, or device. (`nil' is not valid.)
792 - Function: valid-specifier-locale-p LOCALE
793 This function returns non-`nil' if LOCALE is a valid specifier
794 locale. Valid locales are a device, a frame, a window, a buffer,
795 and `global'. (`nil' is not valid.)
797 - Function: valid-specifier-locale-type-p LOCALE-TYPE
798 Given a specifier LOCALE-TYPE, this function returns non-nil if it
799 is valid. Valid locale types are the symbols `global', `device',
800 `frame', `window', and `buffer'. (Note, however, that in functions
801 that accept either a locale or a locale type, `global' is
802 considered an individual locale.)
804 - Function: valid-specifier-type-p SPECIFIER-TYPE
805 Given a SPECIFIER-TYPE, this function returns non-`nil' if it is
806 valid. Valid types are `generic', `integer', `boolean', `color',
807 `font', `image', `face-boolean', and `toolbar'.
809 - Function: valid-specifier-tag-p TAG
810 This function returns non-`nil' if TAG is a valid specifier tag.
812 - Function: valid-instantiator-p INSTANTIATOR SPECIFIER-TYPE
813 This function returns non-`nil' if INSTANTIATOR is valid for
816 - Function: valid-inst-list-p INST-LIST TYPE
817 This function returns non-`nil' if INST-LIST is valid for
820 - Function: valid-spec-list-p SPEC-LIST TYPE
821 This function returns non-`nil' if SPEC-LIST is valid for
824 - Function: check-valid-instantiator INSTANTIATOR SPECIFIER-TYPE
825 This function signals an error if INSTANTIATOR is invalid for
828 - Function: check-valid-inst-list INST-LIST TYPE
829 This function signals an error if INST-LIST is invalid for
832 - Function: check-valid-spec-list SPEC-LIST TYPE
833 This function signals an error if SPEC-LIST is invalid for
837 File: lispref.info, Node: Other Specification Functions, Prev: Specifier Validation Functions, Up: Specifiers
839 Other Functions for Working with Specifications in a Specifier
840 ==============================================================
842 - Function: copy-specifier SPECIFIER &optional DEST LOCALE TAG-SET
844 This function copies SPECIFIER to DEST, or creates a new one if
847 If DEST is `nil' or omitted, a new specifier will be created and
848 the specifications copied into it. Otherwise, the specifications
849 will be copied into the existing specifier in DEST.
851 If LOCALE is `nil' or the symbol `all', all specifications will be
852 copied. If LOCALE is a particular locale, the specification for
853 that particular locale will be copied. If LOCALE is a locale
854 type, the specifications for all locales of that type will be
855 copied. LOCALE can also be a list of locales, locale types,
856 and/or `all'; this is equivalent to calling `copy-specifier' for
857 each of the elements of the list. See `specifier-spec-list' for
858 more information about LOCALE.
860 Only instantiators where TAG-SET (a list of zero or more tags) is
861 a subset of (or possibly equal to) the instantiator's tag set are
862 copied. (The default value of `nil' is a subset of all tag sets,
863 so in this case no instantiators will be screened out.) If EXACT-P
864 is non-`nil', however, TAG-SET must be equal to an instantiator's
865 tag set for the instantiator to be copied.
867 Optional argument HOW-TO-ADD specifies what to do with existing
868 specifications in DEST. If nil, then whichever locales or locale
869 types are copied will first be completely erased in DEST.
870 Otherwise, it is the same as in `add-spec-to-specifier'.
872 - Function: remove-specifier SPECIFIER &optional LOCALE TAG-SET EXACT-P
873 This function removes specification(s) for SPECIFIER.
875 If LOCALE is a particular locale (a buffer, window, frame, device,
876 or the symbol `global'), the specification for that locale will be
879 If instead, LOCALE is a locale type (i.e. a symbol `buffer',
880 `window', `frame', or `device'), the specifications for all
881 locales of that type will be removed.
883 If LOCALE is `nil' or the symbol `all', all specifications will be
886 LOCALE can also be a list of locales, locale types, and/or `all';
887 this is equivalent to calling `remove-specifier' for each of the
888 elements in the list.
890 Only instantiators where TAG-SET (a list of zero or more tags) is
891 a subset of (or possibly equal to) the instantiator's tag set are
892 removed. (The default value of `nil' is a subset of all tag sets,
893 so in this case no instantiators will be screened out.) If EXACT-P
894 is non-`nil', however, TAG-SET must be equal to an instantiator's
895 tag set for the instantiator to be removed.
897 - Function: map-specifier SPECIFIER FUNC &optional LOCALE MAPARG
898 This function applies FUNC to the specification(s) for LOCALE in
901 If LOCALE is a locale, FUNC will be called for that locale. If
902 LOCALE is a locale type, FUNC will be mapped over all locales of
903 that type. If LOCALE is `nil' or the symbol `all', FUNC will be
904 mapped over all locales in SPECIFIER.
906 FUNC is called with four arguments: the SPECIFIER, the locale
907 being mapped over, the inst-list for that locale, and the optional
908 MAPARG. If any invocation of FUNC returns non-`nil', the mapping
909 will stop and the returned value becomes the value returned from
910 `map-specifier'. Otherwise, `map-specifier' returns `nil'.
912 - Function: specifier-locale-type-from-locale LOCALE
913 Given a specifier LOCALE, this function returns its type.
916 File: lispref.info, Node: Faces and Window-System Objects, Next: Glyphs, Prev: Specifiers, Up: Top
918 Faces and Window-System Objects
919 *******************************
923 * Faces:: Controlling the way text looks.
924 * Fonts:: Controlling the typeface of text.
925 * Colors:: Controlling the color of text and pixmaps.
928 File: lispref.info, Node: Faces, Next: Fonts, Up: Faces and Window-System Objects
933 A "face" is a named collection of graphical properties: font,
934 foreground color, background color, background pixmap, optional
935 underlining, and (on TTY devices) whether the text is to be highlighted,
936 dimmed, blinking, or displayed in reverse video. Faces control the
937 display of text on the screen. Every face has a name, which is a symbol
938 such as `default' or `modeline'.
940 Each built-in property of a face is controlled using a specifier,
941 which allows it to have separate values in particular buffers, frames,
942 windows, and devices and to further vary according to device type (X or
943 TTY) and device class (color, mono, or grayscale). *Note Specifiers::,
944 for more information.
946 The face named `default' is used for ordinary text. The face named
947 `modeline' is used for displaying the modeline. The face named
948 `highlight' is used for highlighted extents (*note Extents::.). The
949 faces named `left-margin' and `right-margin' are used for the left and
950 right margin areas, respectively (*note Annotations::.). The face
951 named `zmacs-region' is used for the highlighted region between point
956 * Merging Faces:: How XEmacs decides which face to use
958 * Basic Face Functions:: How to define and examine faces.
959 * Face Properties:: How to access and modify a face's properties.
960 * Face Convenience Functions:: Convenience functions for accessing
961 particular properties of a face.
962 * Other Face Display Functions:: Other functions pertaining to how a
966 File: lispref.info, Node: Merging Faces, Next: Basic Face Functions, Up: Faces
968 Merging Faces for Display
969 -------------------------
971 Here are all the ways to specify which face to use for display of
974 * With defaults. Each frame has a "default face", which is used for
975 all text that doesn't somehow specify another face. The face named
976 `default' applies to the text area, while the faces `left-margin'
977 and `right-margin' apply to the left and right margin areas.
979 * With text properties. A character may have a `face' property; if
980 so, it's displayed with that face. (Text properties are actually
981 implemented in terms of extents.) *Note Text Properties::.
983 * With extents. An extent may have a `face' property, which applies
984 to all the text covered by the extent; in addition, if the
985 `highlight' property is set, the `highlight' property applies when
986 the mouse moves over the extent or if the extent is explicitly
987 highlighted. *Note Extents::.
989 * With annotations. Annotations that are inserted into a buffer can
990 specify their own face. (Annotations are actually implemented in
991 terms of extents.) *Note Annotations::.
993 If these various sources together specify more than one face for a
994 particular character, XEmacs merges the properties of the various faces
995 specified. Extents, text properties, and annotations all use the same
996 underlying representation (as extents). When multiple extents cover one
997 character, an extent with higher priority overrides those with lower
998 priority. *Note Extents::. If no extent covers a particular character,
999 the `default' face is used.
1001 If a background pixmap is specified, it determines what will be
1002 displayed in the background of text characters. If the background
1003 pixmap is actually a pixmap, with its colors specified, those colors are
1004 used; if it is a bitmap, the face's foreground and background colors are
1008 File: lispref.info, Node: Basic Face Functions, Next: Face Properties, Prev: Merging Faces, Up: Faces
1010 Basic Functions for Working with Faces
1011 --------------------------------------
1013 The properties a face can specify include the font, the foreground
1014 color, the background color, the background pixmap, the underlining,
1015 the display table, and (for TTY devices) whether the text is to be
1016 highlighted, dimmed, blinking, or displayed in reverse video. The face
1017 can also leave these unspecified, causing them to assume the value of
1018 the corresponding property of the `default' face.
1020 Here are the basic primitives for working with faces.
1022 - Function: make-face NAME &optional DOC-STRING TEMPORARY
1023 This function defines and returns a new face named NAME, initially
1024 with all properties unspecified. It does nothing if there is
1025 already a face named NAME. Optional argument DOC-STRING specifies
1026 an explanatory string used for descriptive purposes. If optional
1027 argument TEMPORARY is non-`nil', the face will automatically
1028 disappear when there are no more references to it anywhere in text
1029 or Lisp code (otherwise, the face will continue to exist
1030 indefinitely even if it is not used).
1032 - Function: face-list &optional TEMPORARY
1033 This function returns a list of the names of all defined faces. If
1034 TEMPORARY is `nil', only the permanent faces are included. If it
1035 is `t', only the temporary faces are included. If it is any other
1036 non-`nil' value both permanent and temporary are included.
1038 - Function: facep OBJECT
1039 This function returns whether the given object is a face.
1041 - Function: copy-face OLD-FACE NEW-NAME &optional LOCALE HOW-TO-ADD
1042 This function defines a new face named NEW-NAME which is a copy of
1043 the existing face named OLD-FACE. If there is already a face
1044 named NEW-NAME, then it alters the face to have the same
1045 properties as OLD-FACE. LOCALE and HOW-TO-ADD let you copy just
1046 parts of the old face rather than the whole face, and are as in
1047 `copy-specifier' (*note Specifiers::.).
projects / chise / xemacs-chise.git.1 / blob