[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A specifier is an object used to keep track of a property whose value
may vary depending on the particular situation (e.g. particular buffer
displayed in a particular window) that it is used in. The value of many
built-in properties, such as the font, foreground, background, and such
properties of a face and variables such as
modeline-shadow-thickness
and top-toolbar-height
, is
actually a specifier object. The specifier object, in turn, is
“instanced” in a particular situation to yield the real value
of the property in that situation.
This function returns non-nil
if object is a specifier.
1.1 Introduction to Specifiers | Specifiers provide a clean way for display and other properties to vary (under user control) in a wide variety of contexts. | |
1.2 In-Depth Overview of a Specifier | Gory details about specifier innards. | |
1.3 How a Specifier Is Instanced | Instancing means obtaining the “value” of a specifier in a particular context. | |
1.4 Specifier Types | Specifiers come in different flavors. | |
1.5 Adding specifications to a Specifier | Specifications control a specifier’s “value” by giving conditions under which a particular value is valid. | |
1.6 Retrieving the Specifications from a Specifier | Querying a specifier’s specifications. | |
1.7 Working With Specifier Tags | Working with specifier tags. | |
1.8 Functions for Instancing a Specifier | Functions to instance a specifier. | |
1.9 Example of Specifier Usage | Making all this stuff clearer. | |
1.10 Creating New Specifier Objects | Creating specifiers for your own use. | |
1.11 Functions for Checking the Validity of Specifier Components | Validating the components of a specifier. | |
1.12 Other Functions for Working with Specifications in a Specifier | Other ways of working with specifications. |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Sometimes you may want the value of a property to vary depending on
the context the property is used in. A simple example of this in XEmacs
is buffer-local variables. For example, the variable
modeline-format
, which controls the format of the modeline, can
have different values depending on the particular buffer being edited.
The variable has a default value which most modes will use, but a
specialized package such as Calendar might change the variable so
as to tailor the modeline to its own purposes.
Other properties (such as those that can be changed by the
modify-frame-parameters
function, for example the color of the
text cursor) can have frame-local values, although it might also make
sense for them to have buffer-local values. In other cases, you might
want the property to vary depending on the particular window within the
frame that applies (e.g. the top or bottom window in a split frame), the
device type that that frame appears on (X or tty), etc. Perhaps you can
envision some more complicated scenario where you want a particular
value in a specified buffer, another value in all other buffers
displayed on a particular frame, another value in all other buffers
displayed in all other frames on any mono (two-color, e.g. black and
white only) displays, and a default value in all other circumstances.
A specifier is a generalization of this, allowing a great deal of flexibility in controlling exactly what value a property has in which circumstances. It is most commonly used for display properties, such as an image or the foreground color of a face. As a simple example, you can specify that the foreground of the default face be
As a more complicated example, you could specify that the foreground of the default face be
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A specifier object encapsulates a set of specifications, each of which says what its value should be if a particular condition applies. For example, one specification might be “The value should be darkseagreen2 on X devices” another might be “The value should be blue in the *Help* buffer”. In specifier terminology, these conditions are called locales and the values are called instantiators. Given a specifier, a logical question is “What is its value in a particular situation?” This involves looking through the specifications to see which ones apply to this particular situation, and perhaps preferring one over another if more than one applies. In specifier terminology, a “particular situation” is called a domain, and determining its value in a particular domain is called instancing. Most of the time, a domain is identified by a particular window. For example, if the redisplay engine is drawing text in the default face in a particular window, it retrieves the specifier for the foreground color of the default face and instances it in the domain given by that window; in other words, it asks the specifier, “What is your value in this window?”.
More specifically, a specifier contains a set of specifications,
each of which associates a locale (a buffer object, a window
object, a frame object, a device object, or the symbol global
)
with an inst-list, which is a list of one or more
inst-pairs. (For each possible locale, there can be at most one
specification containing that locale.) Each inst-pair is a cons of a
tag set (an unordered list of zero or more symbols, or tags)
and an instantiator (the allowed form of this varies depending on
the type of specifier). In a given specification, there may be more
than one inst-pair with the same tag set; this is unlike for locales.
The tag set is used to restrict the sorts of devices over which the instantiator is valid and to uniquely identify instantiators added by a particular application, so that different applications can work on the same specifier and not interfere with each other. Each tag can have a predicate associated with it, which is a function of one argument (a device) that specifies whether the tag matches that particular device. (If a tag does not have a predicate, it matches all devices.) All tags in a tag set must match a device for the associated inst-pair to be instantiable over that device. (A null tag set is perfectly valid.)
The valid device types (normally x
, tty
, and
stream
) and device classes (normally color
,
grayscale
, and mono
) can always be used as tags, and match
devices of the associated type or class (@pxref{Devices}). User-defined
tags may be defined, with an optional predicate specified. An
application can create its own tag, use it to mark all its
instantiators, and be fairly confident that it will not interfere with
other applications that modify the same specifier – Functions that add
a specification to a specifier usually only overwrite existing
inst-pairs with the same tag set as was given, and a particular tag or
tag set can be specified when removing instantiators.
When a specifier is instanced in a domain, both the locale and the tag set can be viewed as specifying necessary conditions that must apply in that domain for an instantiator to be considered as a possible result of the instancing. More specific locales always override more general locales (thus, there is no particular ordering of the specifications in a specifier); however, the tag sets are simply considered in the order that the inst-pairs occur in the specification’s inst-list.
Note also that the actual object that results from the instancing (called an instance object) may not be the same as the instantiator from which it was derived. For some specifier types (such as integer specifiers and boolean specifiers), the instantiator will be returned directly as the instance object. For other types, however, this is not the case. For example, for font specifiers, the instantiator is a font-description string and the instance object is a font-instance object, which describes how the font is displayed on a particular device. A font-instance object encapsulates such things as the actual font name used to display the font on that device (a font-description string under X is usually a wildcard specification that may resolve to different font names, with possibly different foundries, widths, etc., on different devices), the extra properties of that font on that device, etc. Furthermore, this conversion (called instantiation) might fail – a font or color might not exist on a particular device, for example.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Instancing of a specifier in a particular window domain proceeds as follows:
global
(if there is such a specification) is considered.
default
face.)
It is also possible to instance a specifier over a frame domain or
device domain instead of over a window domain. The C code, for example,
instances the top-toolbar-height
variable over a frame domain in
order to determine the height of a frame’s top toolbar. Instancing over
a frame or device is similar to instancing over a window except that
specifications for locales that cannot be derived from the domain are
ignored. Specifically, instancing over a frame looks first for frame
locales, then device locales, then the global
locale. Instancing
over a device domain looks only for device locales and the global
locale.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 in this specifier 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 in this specifier 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 in this specifier 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). @xref{Toolbar} for more information.
@xref{Faces and Window-System Objects} for more information on fonts, colors, and face-boolean specifiers. @xref{Glyphs} for more information about image specifiers. @xref{Toolbar} for more information on toolbar specifiers.
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:
This function returns non-nil
if object is a boolean
specifier.
This function returns non-nil
if object is an integer
specifier.
This function returns non-nil
if object is a natnum
specifier.
This function returns non-nil
if object is a generic
specifier.
This function returns non-nil
if object is a face-boolean
specifier.
This function returns non-nil
if object is a toolbar
specifier.
This function returns non-nil
if object is a font
specifier.
This function returns non-nil
if object is a color
specifier.
This function returns non-nil
if object is an image
specifier.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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
.
This function adds a spec-list (a list of specifications) to specifier. The format of a spec-list is
((locale (tag-set . instantiator) ...) ...)
where
global
define-specifier-tag
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.
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.
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
.
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 abbrevation 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
.
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
.
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
.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
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:
any
,
the tag will be removed and the instantiator itself will be returned
instead of the inst-pair.
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.
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
.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
This function returns non-nil
if tag is a valid specifier
tag.
This function returns non-nil
if tag-set is a valid
specifier 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.)
This function returns non-nil
if device matches specifier
tag set tag-set. This means that device matches each tag in
the tag set.
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
.
This function returns a list of all specifier tags matching device. device defaults to the selected device if omitted.
This function returns a list of all currently-defined specifier tags. This includes the built-in ones (the device types and classes).
This function returns the predicate for the given specifier tag.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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:
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.
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.
This function returns non-nil
if device matches specifier
tag tag.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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)) ⇒ #<color-specifier 0x3da>
(specifier-specs sp) ⇒ ((#<buffer "device.c"> (nil . "forest green")) (#<window on "Makefile" 0x8a2b> (nil . "hot pink")) (#<x-frame "emacs" 0x4ac> (nil . "puke orange") (nil . "moccasin")) (#<x-frame "VM" 0x4ac> (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 on "*scratch*" 0x4ad> (window-frame (get-buffer-window "*scratch*")) ⇒ #<x-frame "emacs" 0x4ac> (specifier-instance sp (get-buffer-window "*scratch*")) ⇒ #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x6309>
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:
(#<x-frame "emacs" 0x4ac> . "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.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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
.
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
.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.)
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.)
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.)
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
.
This function returns non-nil
if tag is a valid specifier
tag.
This function returns non-nil
if instantiator is valid for
specifier-type.
This function returns non-nil
if inst-list is valid for
specifier type type.
This function returns non-nil
if spec-list is valid for
specifier type type.
This function signals an error if instantiator is invalid for specifier-type.
This function signals an error if inst-list is invalid for specifier type type.
This function signals an error if spec-list is invalid for specifier type type.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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
.
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.
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
.
Given a specifier locale, this function returns its type.
[Top] | [Contents] | [Index] | [ ? ] |
This document was generated on December 6, 2024 using texi2html 5.0.
The buttons in the navigation panels have the following meaning:
Button | Name | Go to | From 1.2.3 go to |
---|---|---|---|
[ << ] | FastBack | Beginning of this chapter or previous chapter | 1 |
[ < ] | Back | Previous section in reading order | 1.2.2 |
[ Up ] | Up | Up section | 1.2 |
[ > ] | Forward | Next section in reading order | 1.2.4 |
[ >> ] | FastForward | Next chapter | 2 |
[Top] | Top | Cover (top) of document | |
[Contents] | Contents | Table of contents | |
[Index] | Index | Index | |
[ ? ] | About | About (help) |
where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
This document was generated on December 6, 2024 using texi2html 5.0.