This is Info file ../../info/lispref.info, produced by Makeinfo version 1.68 from the input file lispref.texi. Edition History: GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp Reference Manual (for 19.15 and 20.1, 20.2) v3.2, April, May 1997 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc. Copyright (C) 1995, 1996 Ben Wing. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the Free Software Foundation instead of in the original English.  File: lispref.info, Node: Specifier Types, Next: Adding Specifications, Prev: Specifier Instancing, Up: Specifiers Specifier Types =============== There are various different types of specifiers. The type of a specifier controls what sorts of instantiators are valid, how an instantiator is instantiated, etc. Here is a list of built-in specifier types: `boolean' The valid instantiators are the symbols `t' and `nil'. Instance objects are the same as instantiators so no special instantiation function is needed. `integer' The valid instantiators are integers. Instance objects are the same as instantiators so no special instantiation function is needed. `modeline-shadow-thickness' is an example of an integer specifier (negative thicknesses indicate that the shadow is drawn recessed instead of raised). `natnum' The valid instantiators are natnums (non-negative integers). Instance objects are the same as instantiators so no special instantiation function is needed. Natnum specifiers are used for dimension variables such as `top-toolbar-height'. `generic' All Lisp objects are valid instantiators. Instance objects are the same as instantiators so no special instantiation function is needed. `font' The valid instantiators are strings describing fonts or vectors indicating inheritance from the font of some face. Instance objects are font-instance objects, which are specific to a particular device. The instantiation method for font specifiers can fail, unlike for integer, natnum, boolean, and generic specifiers. `color' The valid instantiators are strings describing colors or vectors indicating inheritance from the foreground or background of some face. Instance objects are color-instance objects, which are specific to a particular device. The instantiation method for color specifiers can fail, as for font specifiers. `image' Images are perhaps the most complicated type of built-in specifier. The valid instantiators are strings (a filename, inline data for a pixmap, or text to be displayed in a text glyph) or vectors describing inline data of various sorts or indicating inheritance from the background-pixmap property of some face. Instance objects are either strings (for text images), image-instance objects (for pixmap images), or subwindow objects (for subwindow images). The instantiation method for image specifiers can fail, as for font and color specifiers. `face-boolean' The valid instantiators are the symbols `t' and `nil' and vectors indicating inheritance from a boolean property of some face. Specifiers of this sort are used for all of the built-in boolean properties of faces. Instance objects are either the symbol `t' or the symbol `nil'. `toolbar' The valid instantiators are toolbar descriptors, which are lists of toolbar-button descriptors (each of which is a vector of two or four elements). *Note Toolbar:: for more information. Color and font instance objects can also be used in turn as instantiators for a new color or font instance object. Since these instance objects are device-specific, the instantiator can be used directly as the new instance object, but only if they are of the same device. If the devices differ, the base color or font of the instantiating object is effectively used instead as the instantiator. *Note Faces and Window-System Objects:: for more information on fonts, colors, and face-boolean specifiers. *Note Glyphs:: for more information about image specifiers. *Note Toolbar:: for more information on toolbar specifiers. - Function: specifier-type SPECIFIER This function returns the type of SPECIFIER. The returned value will be a symbol: one of `integer', `boolean', etc., as listed in the above table. Functions are also provided to query whether an object is a particular kind of specifier: - Function: boolean-specifier-p OBJECT This function returns non-`nil' if OBJECT is a boolean specifier. - Function: integer-specifier-p OBJECT This function returns non-`nil' if OBJECT is an integer specifier. - Function: natnum-specifier-p OBJECT This function returns non-`nil' if OBJECT is a natnum specifier. - Function: generic-specifier-p OBJECT This function returns non-`nil' if OBJECT is a generic specifier. - Function: face-boolean-specifier-p OBJECT This function returns non-`nil' if OBJECT is a face-boolean specifier. - Function: toolbar-specifier-p OBJECT This function returns non-`nil' if OBJECT is a toolbar specifier. - Function: font-specifier-p OBJECT This function returns non-`nil' if OBJECT is a font specifier. - Function: color-specifier-p OBJECT This function returns non-`nil' if OBJECT is a color specifier. - Function: image-specifier-p OBJECT This function returns non-`nil' if OBJECT is an image specifier.  File: lispref.info, Node: Adding Specifications, Next: Retrieving Specifications, Prev: Specifier Types, Up: Specifiers Adding specifications to a Specifier ==================================== - Function: add-spec-to-specifier SPECIFIER INSTANTIATOR &optional LOCALE TAG-SET HOW-TO-ADD This function adds a specification to SPECIFIER. The specification maps from LOCALE (which should be a buffer, window, frame, device, or the symbol `global', and defaults to `global') to INSTANTIATOR, whose allowed values depend on the type of the specifier. Optional argument TAG-SET limits the instantiator to apply only to the specified tag set, which should be a list of tags all of which must match the device being instantiated over (tags are a device type, a device class, or tags defined with `define-specifier-tag'). Specifying a single symbol for TAG-SET is equivalent to specifying a one-element list containing that symbol. Optional argument HOW-TO-ADD specifies what to do if there are already specifications in the specifier. It should be one of `prepend' Put at the beginning of the current list of instantiators for LOCALE. `append' Add to the end of the current list of instantiators for LOCALE. `remove-tag-set-prepend' This is the default. Remove any existing instantiators whose tag set is the same as TAG-SET; then put the new instantiator at the beginning of the current list. `remove-tag-set-append' Remove any existing instantiators whose tag set is the same as TAG-SET; then put the new instantiator at the end of the current list. `remove-locale' Remove all previous instantiators for this locale before adding the new spec. `remove-locale-type' Remove all specifications for all locales of the same type as LOCALE (this includes LOCALE itself) before adding the new spec. `remove-all' Remove all specifications from the specifier before adding the new spec. `remove-tag-set-prepend' is the default. You can retrieve the specifications for a particular locale or locale type with the function `specifier-spec-list' or `specifier-specs'. - Function: add-spec-list-to-specifier SPECIFIER SPEC-LIST &optional HOW-TO-ADD This function adds a "spec-list" (a list of specifications) to SPECIFIER. The format of a spec-list is `((LOCALE (TAG-SET . INSTANTIATOR) ...) ...)' where * LOCALE := a buffer, a window, a frame, a device, or `global' * TAG-SET := an unordered list of zero or more TAGS, each of which is a symbol * TAG := a device class (*note Consoles and Devices::.), a device type, or a tag defined with `define-specifier-tag' * INSTANTIATOR := format determined by the type of specifier The pair `(TAG-SET . INSTANTIATOR)' is called an "inst-pair". A list of inst-pairs is called an "inst-list". The pair `(LOCALE . INST-LIST)' is called a "specification". A spec-list, then, can be viewed as a list of specifications. HOW-TO-ADD specifies how to combine the new specifications with the existing ones, and has the same semantics as for `add-spec-to-specifier'. In many circumstances, the higher-level function `set-specifier' is more convenient and should be used instead. - Function: set-specifier SPECIFIER VALUE &optional HOW-TO-ADD This function adds some specifications to SPECIFIER. VALUE can be a single instantiator or tagged instantiator (added as a global specification), a list of tagged and/or untagged instantiators (added as a global specification), a cons of a locale and instantiator or locale and instantiator list, a list of such conses, or nearly any other reasonable form. More specifically, VALUE can be anything accepted by `canonicalize-spec-list'. HOW-TO-ADD is the same as in `add-spec-to-specifier'. Note that `set-specifier' is exactly complementary to `specifier-specs' except in the case where SPECIFIER has no specs at all in it but `nil' is a valid instantiator (in that case, `specifier-specs' will return `nil' (meaning no specs) and `set-specifier' will interpret the `nil' as meaning "I'm adding a global instantiator and its value is `nil'"), or in strange cases where there is an ambiguity between a spec-list and an inst-list, etc. (The built-in specifier types are designed in such a way as to avoid any such ambiguities.) If you want to work with spec-lists, you should probably not use these functions, but should use the lower-level functions `specifier-spec-list' and `add-spec-list-to-specifier'. These functions always work with fully-qualified spec-lists; thus, there is no ambiguity. - Function: canonicalize-inst-pair INST-PAIR SPECIFIER-TYPE &optional NOERROR This function canonicalizes the given INST-PAIR. SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST will be used for. Canonicalizing means converting to the full form for an inst-pair, i.e. `(TAG-SET . INSTANTIATOR)'. A single, untagged instantiator is given a tag set of `nil' (the empty set), and a single tag is converted into a tag set consisting only of that tag. If NOERROR is non-`nil', signal an error if the inst-pair is invalid; otherwise return `t'. - Function: canonicalize-inst-list INST-LIST SPECIFIER-TYPE &optional NOERROR This function canonicalizes the given INST-LIST (a list of inst-pairs). SPECIFIER-TYPE specifies the type of specifier that this INST-LIST will be used for. Canonicalizing means converting to the full form for an inst-list, i.e. `((TAG-SET . INSTANTIATOR) ...)'. This function accepts a single inst-pair or any abbreviation thereof or a list of (possibly abbreviated) inst-pairs. (See `canonicalize-inst-pair'.) If NOERROR is non-`nil', signal an error if the inst-list is invalid; otherwise return `t'. - Function: canonicalize-spec SPEC SPECIFIER-TYPE &optional NOERROR This function canonicalizes the given SPEC (a specification). SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST will be used for. Canonicalizing means converting to the full form for a spec, i.e. `(LOCALE (TAG-SET . INSTANTIATOR) ...)'. This function accepts a possibly abbreviated inst-list or a cons of a locale and a possibly abbreviated inst-list. (See `canonicalize-inst-list'.) If NOERROR is `nil', signal an error if the specification is invalid; otherwise return `t'. - Function: canonicalize-spec-list SPEC-LIST SPECIFIER-TYPE &optional NOERROR This function canonicalizes the given SPEC-LIST (a list of specifications). SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST will be used for. Canonicalizing means converting to the full form for a spec-list, i.e. `((LOCALE (TAG-SET . INSTANTIATOR) ...) ...)'. This function accepts a possibly abbreviated specification or a list of such things. (See `canonicalize-spec'.) This is the function used to convert spec-lists accepted by `set-specifier' and such into a form suitable for `add-spec-list-to-specifier'. This function tries extremely hard to resolve any ambiguities, and the built-in specifier types (font, image, toolbar, etc.) are designed so that there won't be any ambiguities. If NOERROR is `nil', signal an error if the spec-list is invalid; otherwise return `t'.  File: lispref.info, Node: Retrieving Specifications, Next: Specifier Tag Functions, Prev: Adding Specifications, Up: Specifiers Retrieving the Specifications from a Specifier ============================================== - Function: specifier-spec-list SPECIFIER &optional LOCALE TAG-SET EXACT-P This function returns the spec-list of specifications for SPECIFIER in LOCALE. If LOCALE is a particular locale (a buffer, window, frame, device, or the symbol `global'), a spec-list consisting of the specification for that locale will be returned. If LOCALE is a locale type (i.e. a symbol `buffer', `window', `frame', or `device'), a spec-list of the specifications for all locales of that type will be returned. If LOCALE is `nil' or the symbol `all', a spec-list of all specifications in SPECIFIER will be returned. LOCALE can also be a list of locales, locale types, and/or `all'; the result is as if `specifier-spec-list' were called on each element of the list and the results concatenated together. Only instantiators where TAG-SET (a list of zero or more tags) is a subset of (or possibly equal to) the instantiator's tag set are returned. (The default value of` nil' is a subset of all tag sets, so in this case no instantiators will be screened out.) If EXACT-P is non-`nil', however, TAG-SET must be equal to an instantiator's tag set for the instantiator to be returned. - Function: specifier-specs SPECIFIER &optional LOCALE TAG-SET EXACT-P This function returns the specification(s) for SPECIFIER in LOCALE. If LOCALE is a single locale or is a list of one element containing a single locale, then a "short form" of the instantiators for that locale will be returned. Otherwise, this function is identical to `specifier-spec-list'. The "short form" is designed for readability and not for ease of use in Lisp programs, and is as follows: 1. If there is only one instantiator, then an inst-pair (i.e. cons of tag and instantiator) will be returned; otherwise a list of inst-pairs will be returned. 2. For each inst-pair returned, if the instantiator's tag is `any', the tag will be removed and the instantiator itself will be returned instead of the inst-pair. 3. If there is only one instantiator, its value is `nil', and its tag is `any', a one-element list containing `nil' will be returned rather than just `nil', to distinguish this case from there being no instantiators at all. - Function: specifier-fallback SPECIFIER This function returns the fallback value for SPECIFIER. Fallback values are provided by the C code for certain built-in specifiers to make sure that instancing won't fail even if all specs are removed from the specifier, or to implement simple inheritance behavior (e.g. this method is used to ensure that faces other than `default' inherit their attributes from `default'). By design, you cannot change the fallback value, and specifiers created with `make-specifier' will never have a fallback (although a similar, Lisp-accessible capability may be provided in the future to allow for inheritance). The fallback value will be an inst-list that is instanced like any other inst-list, a specifier of the same type as SPECIFIER (results in inheritance), or `nil' for no fallback. When you instance a specifier, you can explicitly request that the fallback not be consulted. (The C code does this, for example, when merging faces.) See `specifier-instance'.  File: lispref.info, Node: Specifier Tag Functions, Next: Specifier Instancing Functions, Prev: Retrieving Specifications, Up: Specifiers Working With Specifier Tags =========================== A specifier tag set is an entity that is attached to an instantiator and can be used to restrict the scope of that instantiator to a particular device class or device type and/or to mark instantiators added by a particular package so that they can be later removed. A specifier tag set consists of a list of zero of more specifier tags, each of which is a symbol that is recognized by XEmacs as a tag. (The valid device types and device classes are always tags, as are any tags defined by `define-specifier-tag'.) It is called a "tag set" (as opposed to a list) because the order of the tags or the number of times a particular tag occurs does not matter. Each tag has a predicate associated with it, which specifies whether that tag applies to a particular device. The tags which are device types and classes match devices of that type or class. User-defined tags can have any predicate, or none (meaning that all devices match). When attempting to instance a specifier, a particular instantiator is only considered if the device of the domain being instanced over matches all tags in the tag set attached to that instantiator. Most of the time, a tag set is not specified, and the instantiator gets a null tag set, which matches all devices. - Function: valid-specifier-tag-p TAG This function returns non-`nil' if TAG is a valid specifier tag. - Function: valid-specifier-tag-set-p TAG-SET This function returns non-`nil' if TAG-SET is a valid specifier tag set. - Function: canonicalize-tag-set TAG-SET This function canonicalizes the given tag set. Two canonicalized tag sets can be compared with `equal' to see if they represent the same tag set. (Specifically, canonicalizing involves sorting by symbol name and removing duplicates.) - Function: device-matches-specifier-tag-set-p DEVICE TAG-SET This function returns non-`nil' if DEVICE matches specifier tag set TAG-SET. This means that DEVICE matches each tag in the tag set. - Function: define-specifier-tag TAG &optional PREDICATE This function defines a new specifier tag. If PREDICATE is specified, it should be a function of one argument (a device) that specifies whether the tag matches that particular device. If PREDICATE is omitted, the tag matches all devices. You can redefine an existing user-defined specifier tag. However, you cannot redefine the built-in specifier tags (the device types and classes) or the symbols `nil', `t', `all', or `global'. - Function: device-matching-specifier-tag-list &optional DEVICE This function returns a list of all specifier tags matching DEVICE. DEVICE defaults to the selected device if omitted. - Function: specifier-tag-list This function returns a list of all currently-defined specifier tags. This includes the built-in ones (the device types and classes). - Function: specifier-tag-predicate TAG This function returns the predicate for the given specifier tag.  File: lispref.info, Node: Specifier Instancing Functions, Next: Specifier Example, Prev: Specifier Tag Functions, Up: Specifiers Functions for Instancing a Specifier ==================================== - Function: specifier-instance SPECIFIER &optional DOMAIN DEFAULT NO-FALLBACK This function instantiates SPECIFIER (return its value) in DOMAIN. If no instance can be generated for this domain, return DEFAULT. DOMAIN should be a window, frame, or device. Other values that are legal as a locale (e.g. a buffer) are not valid as a domain because they do not provide enough information to identify a particular device (see `valid-specifier-domain-p'). DOMAIN defaults to the selected window if omitted. "Instantiating" a specifier in a particular domain means determining the specifier's "value" in that domain. This is accomplished by searching through the specifications in the specifier that correspond to all locales that can be derived from the given domain, from specific to general. In most cases, the domain is an Emacs window. In that case specifications are searched for as follows: 1. A specification whose locale is the window's buffer; 2. A specification whose locale is the window itself; 3. A specification whose locale is the window's frame; 4. A specification whose locale is the window's frame's device; 5. A specification whose locale is the symbol `global'. If all of those fail, then the C-code-provided fallback value for this specifier is consulted (see `specifier-fallback'). If it is an inst-list, then this function attempts to instantiate that list just as when a specification is located in the first five steps above. If the fallback is a specifier, `specifier-instance' is called recursively on this specifier and the return value used. Note, however, that if the optional argument NO-FALLBACK is non-`nil', the fallback value will not be consulted. Note that there may be more than one specification matching a particular locale; all such specifications are considered before looking for any specifications for more general locales. Any particular specification that is found may be rejected because it is tagged to a particular device class (e.g. `color') or device type (e.g. `x') or both and the device for the given domain does not match this, or because the specification is not valid for the device of the given domain (e.g. the font or color name does not exist for this particular X server). The returned value is dependent on the type of specifier. For example, for a font specifier (as returned by the `face-font' function), the returned value will be a font-instance object. For images, the returned value will be a string, pixmap, or subwindow. - Function: specifier-instance-from-inst-list SPECIFIER DOMAIN INST-LIST &optional DEFAULT This function attempts to convert a particular inst-list into an instance. This attempts to instantiate INST-LIST in the given DOMAIN, as if INST-LIST existed in a specification in SPECIFIER. If the instantiation fails, DEFAULT is returned. In most circumstances, you should not use this function; use `specifier-instance' instead.  File: lispref.info, Node: Specifier Example, Next: Creating Specifiers, Prev: Specifier Instancing Functions, Up: Specifiers Example of Specifier Usage ========================== Now let us present an example to clarify the theoretical discussions we have been through. In this example, we will use the general specifier functions for clarity. Keep in mind that many types of specifiers, and some other types of objects that are associated with specifiers (e.g. faces), provide convenience functions making it easier to work with objects of that type. Let us consider the background color of the default face. A specifier is used to specify how that color will appear in different domains. First, let's retrieve the specifier: (setq sp (face-property 'default 'background)) => # (specifier-specs sp) => ((# (nil . "forest green")) (# (nil . "hot pink")) (# (nil . "puke orange") (nil . "moccasin")) (# (nil . "magenta")) (global ((tty) . "cyan") (nil . "white")) ) Then, say we want to determine what the background color of the default face is for the window currently displaying the buffer `*scratch*'. We call (get-buffer-window "*scratch*") => # (window-frame (get-buffer-window "*scratch*")) => # (specifier-instance sp (get-buffer-window "*scratch*")) => # Note that we passed a window to `specifier-instance', not a buffer. We cannot pass a buffer because a buffer by itself does not provide enough information. The buffer might not be displayed anywhere at all, or could be displayed in many different frames on different devices. The result is arrived at like this: 1. First, we look for a specification matching the buffer displayed in the window, i.e. `*scratch'. There are none, so we proceed. 2. Then, we look for a specification matching the window itself. Again, there are none. 3. Then, we look for a specification matching the window's frame. The specification `(# . "puke orange")' is found. We call the instantiation method for colors, passing it the locale we were searching over (i.e. the window, in this case) and the instantiator (`"puke orange"'). However, the particular device which this window is on (let's say it's an X connection) doesn't recognize the color `"puke orange"', so the specification is rejected. 4. So we continue looking for a specification matching the window's frame. We find `(# . "moccasin")'. Again, we call the instantiation method for colors. This time, the X server our window is on recognizes the color `moccasin', and so the instantiation method succeeds and returns a color instance.  File: lispref.info, Node: Creating Specifiers, Next: Specifier Validation Functions, Prev: Specifier Example, Up: Specifiers Creating New Specifier Objects ============================== - Function: make-specifier TYPE This function creates a new specifier. A specifier is an object that can be used to keep track of a property whose value can be per-buffer, per-window, per-frame, or per-device, and can further be restricted to a particular device-type or device-class. Specifiers are used, for example, for the various built-in properties of a face; this allows a face to have different values in different frames, buffers, etc. For more information, see `specifier-instance', `specifier-specs', and `add-spec-to-specifier'; or, for a detailed description of specifiers, including how they are instantiated over a particular domain (i.e. how their value in that domain is determined), see the chapter on specifiers in the XEmacs Lisp Reference Manual. TYPE specifies the particular type of specifier, and should be one of the symbols `generic', `integer', `natnum', `boolean', `color', `font', `image', `face-boolean', or `toolbar'. For more information on particular types of specifiers, see the functions `generic-specifier-p', `integer-specifier-p', `natnum-specifier-p', `boolean-specifier-p', `color-specifier-p', `font-specifier-p', `image-specifier-p', `face-boolean-specifier-p', and `toolbar-specifier-p'. - Function: make-specifier-and-init TYPE SPEC-LIST &optional DONT-CANONICALIZE This function creates and initialize a new specifier. This is a front-end onto `make-specifier' that allows you to create a specifier and add specs to it at the same time. TYPE specifies the specifier type. SPEC-LIST supplies the specification(s) to be added to the specifier. Normally, almost any reasonable abbreviation of the full spec-list form is accepted, and is converted to the full form; however, if optional argument DONT-CANONICALIZE is non-`nil', this conversion is not performed, and the SPEC-LIST must already be in full form. See `canonicalize-spec-list'.  File: lispref.info, Node: Specifier Validation Functions, Next: Other Specification Functions, Prev: Creating Specifiers, Up: Specifiers Functions for Checking the Validity of Specifier Components =========================================================== - Function: valid-specifier-domain-p DOMAIN This function returns non-`nil' if DOMAIN is a valid specifier domain. A domain is used to instance a specifier (i.e. determine the specifier's value in that domain). Valid domains are a window, frame, or device. (`nil' is not valid.) - Function: valid-specifier-locale-p LOCALE This function returns non-`nil' if LOCALE is a valid specifier locale. Valid locales are a device, a frame, a window, a buffer, and `global'. (`nil' is not valid.) - Function: valid-specifier-locale-type-p LOCALE-TYPE Given a specifier LOCALE-TYPE, this function returns non-nil if it is valid. Valid locale types are the symbols `global', `device', `frame', `window', and `buffer'. (Note, however, that in functions that accept either a locale or a locale type, `global' is considered an individual locale.) - Function: valid-specifier-type-p SPECIFIER-TYPE Given a SPECIFIER-TYPE, this function returns non-`nil' if it is valid. Valid types are `generic', `integer', `boolean', `color', `font', `image', `face-boolean', and `toolbar'. - Function: valid-specifier-tag-p TAG This function returns non-`nil' if TAG is a valid specifier tag. - Function: valid-instantiator-p INSTANTIATOR SPECIFIER-TYPE This function returns non-`nil' if INSTANTIATOR is valid for SPECIFIER-TYPE. - Function: valid-inst-list-p INST-LIST TYPE This function returns non-`nil' if INST-LIST is valid for specifier type TYPE. - Function: valid-spec-list-p SPEC-LIST TYPE This function returns non-`nil' if SPEC-LIST is valid for specifier type TYPE. - Function: check-valid-instantiator INSTANTIATOR SPECIFIER-TYPE This function signals an error if INSTANTIATOR is invalid for SPECIFIER-TYPE. - Function: check-valid-inst-list INST-LIST TYPE This function signals an error if INST-LIST is invalid for specifier type TYPE. - Function: check-valid-spec-list SPEC-LIST TYPE This function signals an error if SPEC-LIST is invalid for specifier type TYPE.  File: lispref.info, Node: Other Specification Functions, Prev: Specifier Validation Functions, Up: Specifiers Other Functions for Working with Specifications in a Specifier ============================================================== - Function: copy-specifier SPECIFIER &optional DEST LOCALE TAG-SET EXACT-P HOW-TO-ADD This function copies SPECIFIER to DEST, or creates a new one if DEST is `nil'. If DEST is `nil' or omitted, a new specifier will be created and the specifications copied into it. Otherwise, the specifications will be copied into the existing specifier in DEST. If LOCALE is `nil' or the symbol `all', all specifications will be copied. If LOCALE is a particular locale, the specification for that particular locale will be copied. If LOCALE is a locale type, the specifications for all locales of that type will be copied. LOCALE can also be a list of locales, locale types, and/or `all'; this is equivalent to calling `copy-specifier' for each of the elements of the list. See `specifier-spec-list' for more information about LOCALE. Only instantiators where TAG-SET (a list of zero or more tags) is a subset of (or possibly equal to) the instantiator's tag set are copied. (The default value of `nil' is a subset of all tag sets, so in this case no instantiators will be screened out.) If EXACT-P is non-`nil', however, TAG-SET must be equal to an instantiator's tag set for the instantiator to be copied. Optional argument HOW-TO-ADD specifies what to do with existing specifications in DEST. If nil, then whichever locales or locale types are copied will first be completely erased in DEST. Otherwise, it is the same as in `add-spec-to-specifier'. - Function: remove-specifier SPECIFIER &optional LOCALE TAG-SET EXACT-P This function removes specification(s) for SPECIFIER. If LOCALE is a particular locale (a buffer, window, frame, device, or the symbol `global'), the specification for that locale will be removed. If instead, LOCALE is a locale type (i.e. a symbol `buffer', `window', `frame', or `device'), the specifications for all locales of that type will be removed. If LOCALE is `nil' or the symbol `all', all specifications will be removed. LOCALE can also be a list of locales, locale types, and/or `all'; this is equivalent to calling `remove-specifier' for each of the elements in the list. Only instantiators where TAG-SET (a list of zero or more tags) is a subset of (or possibly equal to) the instantiator's tag set are removed. (The default value of `nil' is a subset of all tag sets, so in this case no instantiators will be screened out.) If EXACT-P is non-`nil', however, TAG-SET must be equal to an instantiator's tag set for the instantiator to be removed. - Function: map-specifier SPECIFIER FUNC &optional LOCALE MAPARG This function applies FUNC to the specification(s) for LOCALE in SPECIFIER. If LOCALE is a locale, FUNC will be called for that locale. If LOCALE is a locale type, FUNC will be mapped over all locales of that type. If LOCALE is `nil' or the symbol `all', FUNC will be mapped over all locales in SPECIFIER. FUNC is called with four arguments: the SPECIFIER, the locale being mapped over, the inst-list for that locale, and the optional MAPARG. If any invocation of FUNC returns non-`nil', the mapping will stop and the returned value becomes the value returned from `map-specifier'. Otherwise, `map-specifier' returns `nil'. - Function: specifier-locale-type-from-locale LOCALE Given a specifier LOCALE, this function returns its type.  File: lispref.info, Node: Faces and Window-System Objects, Next: Glyphs, Prev: Specifiers, Up: Top Faces and Window-System Objects ******************************* * Menu: * Faces:: Controlling the way text looks. * Fonts:: Controlling the typeface of text. * Colors:: Controlling the color of text and pixmaps.  File: lispref.info, Node: Faces, Next: Fonts, Up: Faces and Window-System Objects Faces ===== A "face" is a named collection of graphical properties: font, foreground color, background color, background pixmap, optional underlining, and (on TTY devices) whether the text is to be highlighted, dimmed, blinking, or displayed in reverse video. Faces control the display of text on the screen. Every face has a name, which is a symbol such as `default' or `modeline'. Each built-in property of a face is controlled using a specifier, which allows it to have separate values in particular buffers, frames, windows, and devices and to further vary according to device type (X or TTY) and device class (color, mono, or grayscale). *Note Specifiers:: for more information. The face named `default' is used for ordinary text. The face named `modeline' is used for displaying the modeline. The face named `highlight' is used for highlighted extents (*note Extents::.). The faces named `left-margin' and `right-margin' are used for the left and right margin areas, respectively (*note Annotations::.). The face named `zmacs-region' is used for the highlighted region between point and mark. * Menu: * Merging Faces:: How XEmacs decides which face to use for a character. * Basic Face Functions:: How to define and examine faces. * Face Properties:: How to access and modify a face's properties. * Face Convenience Functions:: Convenience functions for accessing particular properties of a face. * Other Face Display Functions:: Other functions pertaining to how a a face appears.  File: lispref.info, Node: Merging Faces, Next: Basic Face Functions, Up: Faces Merging Faces for Display ------------------------- Here are all the ways to specify which face to use for display of text: * With defaults. Each frame has a "default face", which is used for all text that doesn't somehow specify another face. The face named `default' applies to the text area, while the faces `left-margin' and `right-margin' apply to the left and right margin areas. * With text properties. A character may have a `face' property; if so, it's displayed with that face. (Text properties are actually implemented in terms of extents.) *Note Text Properties::. * With extents. An extent may have a `face' property, which applies to all the text covered by the extent; in addition, if the `highlight' property is set, the `highlight' property applies when the mouse moves over the extent or if the extent is explicitly highlighted. *Note Extents::. * With annotations. Annotations that are inserted into a buffer can specify their own face. (Annotations are actually implemented in terms of extents.) *Note Annotations::. If these various sources together specify more than one face for a particular character, XEmacs merges the properties of the various faces specified. Extents, text properties, and annotations all use the same underlying representation (as extents). When multiple extents cover one character, an extent with higher priority overrides those with lower priority. *Note Extents::. If no extent covers a particular character, the `default' face is used. If a background pixmap is specified, it determines what will be displayed in the background of text characters. If the background pixmap is actually a pixmap, with its colors specified, those colors are used; if it is a bitmap, the face's foreground and background colors are used to color it.  File: lispref.info, Node: Basic Face Functions, Next: Face Properties, Prev: Merging Faces, Up: Faces Basic Functions for Working with Faces -------------------------------------- The properties a face can specify include the font, the foreground color, the background color, the background pixmap, the underlining, the display table, and (for TTY devices) whether the text is to be highlighted, dimmed, blinking, or displayed in reverse video. The face can also leave these unspecified, causing them to assume the value of the corresponding property of the `default' face. Here are the basic primitives for working with faces. - Function: make-face NAME &optional DOC-STRING TEMPORARY This function defines and returns a new face named NAME, initially with all properties unspecified. It does nothing if there is already a face named NAME. Optional argument DOC-STRING specifies an explanatory string used for descriptive purposes. If optional argument TEMPORARY is non-`nil', the face will automatically disappear when there are no more references to it anywhere in text or Lisp code (otherwise, the face will continue to exist indefinitely even if it is not used). - Function: face-list &optional TEMPORARY This function returns a list of the names of all defined faces. If TEMPORARY is `nil', only the permanent faces are included. If it is `t', only the temporary faces are included. If it is any other non-`nil' value both permanent and temporary are included. - Function: facep OBJECT This function returns whether the given object is a face. - Function: copy-face OLD-FACE NEW-NAME &optional LOCALE HOW-TO-ADD This function defines a new face named NEW-NAME which is a copy of the existing face named OLD-FACE. If there is already a face named NEW-NAME, then it alters the face to have the same properties as OLD-FACE. LOCALE and HOW-TO-ADD let you copy just parts of the old face rather than the whole face, and are as in `copy-specifier' (*note Specifiers::.).