Mercurial > hg > xemacs-beta

comparison man/lispref/specifiers.texi @ 412:697ef44129c6 r21-2-14

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r21-2-14
author cvs
date Mon, 13 Aug 2007 11:20:41 +0200
parents 501cfd01ee6d
children
comparison
equal deleted inserted replaced
411:12e008d41344 412:697ef44129c6
20 @defun specifierp object 20 @defun specifierp object
21 This function returns non-@code{nil} if @var{object} is a specifier. 21 This function returns non-@code{nil} if @var{object} is a specifier.
22 @end defun 22 @end defun
23 23
24 @menu 24 @menu
25 * Introduction to Specifiers:: Specifiers provide a clean way for 25 * Introduction to Specifiers:: Specifiers provide a clean way for
26 display and other properties to vary 26 display and other properties to vary
27 (under user control) in a wide variety 27 (under user control) in a wide variety
28 of contexts. 28 of contexts.
29 * Specifiers In-Depth:: Gory details about specifier innards. 29 * Specifiers In-Depth:: Gory details about specifier innards.
30 * Specifier Instancing:: Instancing means obtaining the ``value'' of 30 * Specifier Instancing:: Instancing means obtaining the ``value'' of
31 a specifier in a particular context. 31 a specifier in a particular context.
32 * Specifier Types:: Specifiers come in different flavors. 32 * Specifier Types:: Specifiers come in different flavors.
33 * Adding Specifications:: Specifications control a specifier's ``value'' 33 * Adding Specifications:: Specifications control a specifier's ``value''
34 by giving conditions under which a 34 by giving conditions under which a
35 particular value is valid. 35 particular value is valid.
36 * Retrieving Specifications:: Querying a specifier's specifications. 36 * Retrieving Specifications:: Querying a specifier's specifications.
37 * Specifier Tag Functions:: Working with specifier tags. 37 * Specifier Tag Functions:: Working with specifier tags.
38 * Specifier Instancing Functions:: 38 * Specifier Instancing Functions::
39 Functions to instance a specifier. 39 Functions to instance a specifier.
40 * Specifier Example:: Making all this stuff clearer. 40 * Specifier Example:: Making all this stuff clearer.
41 * Creating Specifiers:: Creating specifiers for your own use. 41 * Creating Specifiers:: Creating specifiers for your own use.
42 * Specifier Validation Functions:: 42 * Specifier Validation Functions::
43 Validating the components of a specifier. 43 Validating the components of a specifier.
44 * Other Specification Functions:: 44 * Other Specification Functions::
45 Other ways of working with specifications. 45 Other ways of working with specifications.
46 @end menu 46 @end menu
47 47
48 @node Introduction to Specifiers 48 @node Introduction to Specifiers
49 @section Introduction to Specifiers 49 @section Introduction to Specifiers
50 50
167 @code{grayscale}, and @code{mono}) can always be used as tags, and match 167 @code{grayscale}, and @code{mono}) can always be used as tags, and match
168 devices of the associated type or class (@pxref{Consoles and Devices}). 168 devices of the associated type or class (@pxref{Consoles and Devices}).
169 User-defined tags may be defined, with an optional predicate specified. 169 User-defined tags may be defined, with an optional predicate specified.
170 An application can create its own tag, use it to mark all its 170 An application can create its own tag, use it to mark all its
171 instantiators, and be fairly confident that it will not interfere with 171 instantiators, and be fairly confident that it will not interfere with
172 other applications that modify the same specifier---Functions that add 172 other applications that modify the same specifier -- Functions that add
173 a specification to a specifier usually only overwrite existing 173 a specification to a specifier usually only overwrite existing
174 inst-pairs with the same tag set as was given, and a particular tag or 174 inst-pairs with the same tag set as was given, and a particular tag or
175 tag set can be specified when removing instantiators. 175 tag set can be specified when removing instantiators.
176 176
177 When a specifier is instanced in a domain, both the locale and the tag 177 When a specifier is instanced in a domain, both the locale and the tag
194 used to display the font on that device (a font-description string 194 used to display the font on that device (a font-description string
195 under X is usually a wildcard specification that may resolve to 195 under X is usually a wildcard specification that may resolve to
196 different font names, with possibly different foundries, widths, etc., 196 different font names, with possibly different foundries, widths, etc.,
197 on different devices), the extra properties of that font on that 197 on different devices), the extra properties of that font on that
198 device, etc. Furthermore, this conversion (called @dfn{instantiation}) 198 device, etc. Furthermore, this conversion (called @dfn{instantiation})
199 might fail---a font or color might not exist on a particular device, 199 might fail -- a font or color might not exist on a particular device,
200 for example. 200 for example.
201 201
202 @node Specifier Instancing 202 @node Specifier Instancing
203 @section How a Specifier Is Instanced 203 @section How a Specifier Is Instanced
204 @cindex fallback (in a specifier) 204 @cindex fallback (in a specifier)
701 A specifier tag set is an entity that is attached to an instantiator 701 A specifier tag set is an entity that is attached to an instantiator
702 and can be used to restrict the scope of that instantiator to a 702 and can be used to restrict the scope of that instantiator to a
703 particular device class or device type and/or to mark instantiators 703 particular device class or device type and/or to mark instantiators
704 added by a particular package so that they can be later removed. 704 added by a particular package so that they can be later removed.
705 705
706 A specifier tag set consists of a list of zero or more specifier tags, 706 A specifier tag set consists of a list of zero of more specifier tags,
707 each of which is a symbol that is recognized by XEmacs as a tag. (The 707 each of which is a symbol that is recognized by XEmacs as a tag. (The
708 valid device types and device classes are always tags, as are any tags 708 valid device types and device classes are always tags, as are any tags
709 defined by @code{define-specifier-tag}.) It is called a ``tag set'' (as 709 defined by @code{define-specifier-tag}.) It is called a ``tag set'' (as
710 opposed to a list) because the order of the tags or the number of times 710 opposed to a list) because the order of the tags or the number of times
711 a particular tag occurs does not matter. 711 a particular tag occurs does not matter.
859 @example 859 @example
860 (specifier-specs sp) 860 (specifier-specs sp)
861 @result{} ((#<buffer "device.c"> (nil . "forest green")) 861 @result{} ((#<buffer "device.c"> (nil . "forest green"))
862 (#<window on "Makefile" 0x8a2b> (nil . "hot pink")) 862 (#<window on "Makefile" 0x8a2b> (nil . "hot pink"))
863 (#<x-frame "emacs" 0x4ac> (nil . "puke orange") 863 (#<x-frame "emacs" 0x4ac> (nil . "puke orange")
864 (nil . "moccasin")) 864 (nil . "moccasin"))
865 (#<x-frame "VM" 0x4ac> (nil . "magenta")) 865 (#<x-frame "VM" 0x4ac> (nil . "magenta"))
866 (global ((tty) . "cyan") (nil . "white")) 866 (global ((tty) . "cyan") (nil . "white"))
867 ) 867 )
868 @end example 868 @end example
869 869
870 Then, say we want to determine what the background color of the default 870 Then, say we want to determine what the background color of the default
871 face is for the window currently displaying the buffer @samp{*scratch*}. 871 face is for the window currently displaying the buffer @samp{*scratch*}.
888 The result is arrived at like this: 888 The result is arrived at like this:
889 889
890 @enumerate 890 @enumerate
891 @item 891 @item
892 First, we look for a specification matching the buffer displayed in the 892 First, we look for a specification matching the buffer displayed in the
893 window, i.e. @samp{*scratch*}. There are none, so we proceed. 893 window, i.e. @samp{*scratch}. There are none, so we proceed.
894 @item 894 @item
895 Then, we look for a specification matching the window itself. Again, there 895 Then, we look for a specification matching the window itself. Again, there
896 are none. 896 are none.
897 @item 897 @item
898 Then, we look for a specification matching the window's frame. The 898 Then, we look for a specification matching the window's frame. The
932 of the symbols @code{generic}, @code{integer}, @code{natnum}, 932 of the symbols @code{generic}, @code{integer}, @code{natnum},
933 @code{boolean}, @code{color}, @code{font}, @code{image}, 933 @code{boolean}, @code{color}, @code{font}, @code{image},
934 @code{face-boolean}, or @code{toolbar}. 934 @code{face-boolean}, or @code{toolbar}.
935 935
936 For more information on particular types of specifiers, see the 936 For more information on particular types of specifiers, see the
937 functions @code{make-generic-specifier}, @code{make-integer-specifier}, 937 functions @code{generic-specifier-p}, @code{integer-specifier-p},
938 @code{make-natnum-specifier}, @code{make-boolean-specifier}, 938 @code{natnum-specifier-p}, @code{boolean-specifier-p},
939 @code{make-color-specifier}, @code{make-font-specifier}, 939 @code{color-specifier-p}, @code{font-specifier-p},
940 @code{make-image-specifier}, @code{make-face-boolean-specifier}, and 940 @code{image-specifier-p}, @code{face-boolean-specifier-p}, and
941 @code{make-toolbar-specifier}. 941 @code{toolbar-specifier-p}.
942 @end defun 942 @end defun
943 943
944 @defun make-specifier-and-init type spec-list &optional dont-canonicalize 944 @defun make-specifier-and-init type spec-list &optional dont-canonicalize
945 This function creates and initialize a new specifier. 945 This function creates and initialize a new specifier.
946 946
952 however, if optional argument @var{dont-canonicalize} is non-@code{nil}, 952 however, if optional argument @var{dont-canonicalize} is non-@code{nil},
953 this conversion is not performed, and the @var{spec-list} must already 953 this conversion is not performed, and the @var{spec-list} must already
954 be in full form. See @code{canonicalize-spec-list}. 954 be in full form. See @code{canonicalize-spec-list}.
955 @end defun 955 @end defun
956 956
957 @defun make-integer-specifier spec-list
958
959 Return a new @code{integer} specifier object with the given
960 specification list. @var{spec-list} can be a list of specifications
961 (each of which is a cons of a locale and a list of instantiators), a
962 single instantiator, or a list of instantiators.
963
964 Valid instantiators for integer specifiers are integers.
965 @end defun
966
967 @defun make-boolean-specifier spec-list
968
969 Return a new @code{boolean} specifier object with the given
970 specification list. @var{spec-list} can be a list of specifications
971 (each of which is a cons of a locale and a list of instantiators), a
972 single instantiator, or a list of instantiators.
973
974 Valid instantiators for boolean specifiers are @code{t} and @code{nil}.
975 @end defun
976
977 @defun make-natnum-specifier spec-list
978
979 Return a new @code{natnum} specifier object with the given specification
980 list. @var{spec-list} can be a list of specifications (each of which is
981 a cons of a locale and a list of instantiators), a single instantiator,
982 or a list of instantiators.
983
984 Valid instantiators for natnum specifiers are non-negative integers.
985 @end defun
986
987 @defun make-generic-specifier spec-list
988
989 Return a new @code{generic} specifier object with the given
990 specification list. @var{spec-list} can be a list of specifications
991 (each of which is a cons of a locale and a list of instantiators), a
992 single instantiator, or a list of instantiators.
993
994 Valid instantiators for generic specifiers are all Lisp values. They
995 are returned back unchanged when a specifier is instantiated.
996 @end defun
997
998 @defun make-display-table-specifier spec-list
999
1000 Return a new @code{display-table} specifier object with the given spec
1001 list. @var{spec-list} can be a list of specifications (each of which is
1002 a cons of a locale and a list of instantiators), a single instantiator,
1003 or a list of instantiators.
1004
1005 Valid instantiators for display-table specifiers are described in detail
1006 in the doc string for @code{current-display-table} (@pxref{Active
1007 Display Table}).
1008 @end defun
1009
1010 @node Specifier Validation Functions 957 @node Specifier Validation Functions
1011 @section Functions for Checking the Validity of Specifier Components 958 @section Functions for Checking the Validity of Specifier Components
1012 959
1013 @defun valid-specifier-domain-p domain 960 @defun valid-specifier-domain-p domain
1014 This function returns non-@code{nil} if @var{domain} is a valid 961 This function returns non-@code{nil} if @var{domain} is a valid