@end defun
@menu
-* Introduction to Specifiers:: Specifiers provide a clean way for
- display and other properties to vary
- (under user control) in a wide variety
- of contexts.
-* Specifiers In-Depth:: Gory details about specifier innards.
-* Specifier Instancing:: Instancing means obtaining the ``value'' of
- a specifier in a particular context.
-* Specifier Types:: Specifiers come in different flavors.
-* Adding Specifications:: Specifications control a specifier's ``value''
- by giving conditions under which a
- particular value is valid.
-* Retrieving Specifications:: Querying a specifier's specifications.
-* Specifier Tag Functions:: Working with specifier tags.
+* Introduction to Specifiers:: Specifiers provide a clean way for
+ display and other properties to vary
+ (under user control) in a wide variety
+ of contexts.
+* Specifiers In-Depth:: Gory details about specifier innards.
+* Specifier Instancing:: Instancing means obtaining the ``value'' of
+ a specifier in a particular context.
+* Specifier Types:: Specifiers come in different flavors.
+* Adding Specifications:: Specifications control a specifier's ``value''
+ by giving conditions under which a
+ particular value is valid.
+* Retrieving Specifications:: Querying a specifier's specifications.
+* Specifier Tag Functions:: Working with specifier tags.
* Specifier Instancing Functions::
- Functions to instance a specifier.
-* Specifier Example:: Making all this stuff clearer.
-* Creating Specifiers:: Creating specifiers for your own use.
+ Functions to instance a specifier.
+* Specifier Example:: Making all this stuff clearer.
+* Creating Specifiers:: Creating specifiers for your own use.
* Specifier Validation Functions::
- Validating the components of a specifier.
+ Validating the components of a specifier.
* Other Specification Functions::
- Other ways of working with specifications.
+ Other ways of working with specifications.
@end menu
@node Introduction to Specifiers
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
+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.
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 @dfn{instantiation})
-might fail -- a font or color might not exist on a particular device,
+might fail---a font or color might not exist on a particular device,
for example.
@node Specifier Instancing
@item 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.
+or four elements). @xref{Toolbar}, for more information.
@end table
Color and font instance objects can also be used in turn as
device. If the devices differ, the base color or font of the
instantiating object is effectively used instead as the instantiator.
-@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
+@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.
@defun specifier-type specifier
more convenient and should be used instead.
@end defun
-@deffn Macro let-specifier specifier-list &rest body
+@defspec let-specifier specifier-list &rest body
This special form temporarily adds specifications to specifiers,
evaluates forms in @var{body} and restores the specifiers to their
previous states. The specifiers and their temporary specifications are
(let-specifier ((modeline-shadow-thickness 0 (selected-window)))
(sit-for 1))
@end example
-@end deffn
+@end defspec
-@defun set-specifier specifier value &optional how-to-add
+@defun set-specifier specifier value &optional locale tag-set how-to-add
This function adds some specifications to @var{specifier}. @var{value}
can be a single instantiator or tagged instantiator (added as a global
specification), a list of tagged and/or untagged instantiators (added as
reasonable form. More specifically, @var{value} can be anything
accepted by @code{canonicalize-spec-list}.
-@var{how-to-add} is the same as in @code{add-spec-to-specifier}.
+@var{locale}, @var{tag-set}, and @var{how-to-add} are the same as in
+@code{add-spec-to-specifier}.
Note that @code{set-specifier} is exactly complementary to
@code{specifier-specs} except in the case where @var{specifier} has no
or the symbol @code{global}), a spec-list consisting of the
specification for that locale will be returned.
-If @var{locale} is a locale type (i.e. a symbol @code{window},
+If @var{locale} is a locale type (i.e. one of the symbols @code{window},
@code{buffer}, @code{frame}, or @code{device}), a spec-list of the
specifications for all locales of that type will be returned.
Only instantiators where @var{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@code{ nil} is a subset of all tag sets,
+returned. (The default value of @code{nil} is a subset of all tag sets,
so in this case no instantiators will be screened out.) If @var{exact-p}
is non-@code{nil}, however, @var{tag-set} must be equal to an
instantiator's tag set for the instantiator to be returned.
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,
+A specifier tag set consists of a list of zero or 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 @code{define-specifier-tag}.) It is called a ``tag set'' (as
@result{} ((#<buffer "device.c"> (nil . "forest green"))
(#<window on "Makefile" 0x8a2b> (nil . "hot pink"))
(#<x-frame "emacs" 0x4ac> (nil . "puke orange")
- (nil . "moccasin"))
+ (nil . "moccasin"))
(#<x-frame "VM" 0x4ac> (nil . "magenta"))
- (global ((tty) . "cyan") (nil . "white"))
+ (global ((tty) . "cyan") (nil . "white"))
)
@end example
@enumerate
@item
First, we look for a specification matching the buffer displayed in the
-window, i.e. @samp{*scratch}. There are none, so we proceed.
+window, i.e. @samp{*scratch*}. There are none, so we proceed.
@item
Then, we look for a specification matching the window itself. Again, there
are none.
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
+buffers, etc. For more information, see @code{specifier-instance},
+@code{specifier-specs}, and @code{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.
@code{face-boolean}, or @code{toolbar}.
For more information on particular types of specifiers, see the
-functions @code{generic-specifier-p}, @code{integer-specifier-p},
-@code{natnum-specifier-p}, @code{boolean-specifier-p},
-@code{color-specifier-p}, @code{font-specifier-p},
-@code{image-specifier-p}, @code{face-boolean-specifier-p}, and
-@code{toolbar-specifier-p}.
+functions @code{make-generic-specifier}, @code{make-integer-specifier},
+@code{make-natnum-specifier}, @code{make-boolean-specifier},
+@code{make-color-specifier}, @code{make-font-specifier},
+@code{make-image-specifier}, @code{make-face-boolean-specifier}, and
+@code{make-toolbar-specifier}.
@end defun
@defun make-specifier-and-init type spec-list &optional dont-canonicalize
be in full form. See @code{canonicalize-spec-list}.
@end defun
+@defun make-integer-specifier spec-list
+
+Return a new @code{integer} specifier object with the given
+specification list. @var{spec-list} can be a list of specifications
+(each of which is a cons of a locale and a list of instantiators), a
+single instantiator, or a list of instantiators.
+
+Valid instantiators for integer specifiers are integers.
+@end defun
+
+@defun make-boolean-specifier spec-list
+
+Return a new @code{boolean} specifier object with the given
+specification list. @var{spec-list} can be a list of specifications
+(each of which is a cons of a locale and a list of instantiators), a
+single instantiator, or a list of instantiators.
+
+Valid instantiators for boolean specifiers are @code{t} and @code{nil}.
+@end defun
+
+@defun make-natnum-specifier spec-list
+
+Return a new @code{natnum} specifier object with the given specification
+list. @var{spec-list} can be a list of specifications (each of which is
+a cons of a locale and a list of instantiators), a single instantiator,
+or a list of instantiators.
+
+Valid instantiators for natnum specifiers are non-negative integers.
+@end defun
+
+@defun make-generic-specifier spec-list
+
+Return a new @code{generic} specifier object with the given
+specification list. @var{spec-list} can be a list of specifications
+(each of which is a cons of a locale and a list of instantiators), a
+single instantiator, or a list of instantiators.
+
+Valid instantiators for generic specifiers are all Lisp values. They
+are returned back unchanged when a specifier is instantiated.
+@end defun
+
+@defun make-display-table-specifier spec-list
+
+Return a new @code{display-table} specifier object with the given spec
+list. @var{spec-list} can be a list of specifications (each of which is
+a cons of a locale and a list of instantiators), a single instantiator,
+or a list of instantiators.
+
+Valid instantiators for display-table specifiers are described in detail
+in the doc string for @code{current-display-table} (@pxref{Active
+Display Table}).
+@end defun
+
@node Specifier Validation Functions
@section Functions for Checking the Validity of Specifier Components
@end defun
@defun valid-specifier-locale-type-p locale-type
-Given a specifier @var{locale-type}, this function returns non-nil if it
+Given a specifier @var{locale-type}, this function returns non-@code{nil} if it
is valid. Valid locale types are the symbols @code{global},
@code{device}, @code{frame}, @code{window}, and @code{buffer}. (Note,
however, that in functions that accept either a locale or a locale type,
instantiator's tag set for the instantiator to be copied.
Optional argument @var{how-to-add} specifies what to do with existing
-specifications in @var{dest}. If nil, then whichever locales or locale
+specifications in @var{dest}. If @code{nil}, then whichever locales or locale
types are copied will first be completely erased in @var{dest}.
Otherwise, it is the same as in @code{add-spec-to-specifier}.
@end defun
projects / chise / xemacs-chise.git.1 / blobdiff