|
0
|
1 @c -*-texinfo-*-
|
|
|
2 @c This is part of the XEmacs Lisp Reference Manual.
|
|
|
3 @c Copyright (C) 1995, 1996 Ben Wing.
|
|
|
4 @c See the file lispref.texi for copying conditions.
|
|
|
5 @setfilename ../../info/specifiers.info
|
|
|
6 @node Specifiers, Faces and Window-System Objects, Extents, top
|
|
|
7 @chapter Specifiers
|
|
|
8 @cindex specifier
|
|
|
9
|
|
|
10 A specifier is an object used to keep track of a property whose value
|
|
|
11 may vary depending on the particular situation (e.g. particular buffer
|
|
|
12 displayed in a particular window) that it is used in. The value of many
|
|
|
13 built-in properties, such as the font, foreground, background, and such
|
|
|
14 properties of a face and variables such as
|
|
|
15 @code{modeline-shadow-thickness} and @code{top-toolbar-height}, is
|
|
|
16 actually a specifier object. The specifier object, in turn, is
|
|
|
17 ``instanced'' in a particular situation to yield the real value
|
|
|
18 of the property in that situation.
|
|
|
19
|
|
|
20 @defun specifierp object
|
|
|
21 This function returns non-@code{nil} if @var{object} is a specifier.
|
|
|
22 @end defun
|
|
|
23
|
|
|
24 @menu
|
|
|
25 * Introduction to Specifiers:: Specifiers provide a clean way for
|
|
|
26 display and other properties to vary
|
|
|
27 (under user control) in a wide variety
|
|
|
28 of contexts.
|
|
|
29 * Specifiers In-Depth:: Gory details about specifier innards.
|
|
|
30 * Specifier Instancing:: Instancing means obtaining the ``value'' of
|
|
|
31 a specifier in a particular context.
|
|
|
32 * Specifier Types:: Specifiers come in different flavors.
|
|
|
33 * Adding Specifications:: Specifications control a specifier's ``value''
|
|
|
34 by giving conditions under which a
|
|
|
35 particular value is valid.
|
|
|
36 * Retrieving Specifications:: Querying a specifier's specifications.
|
|
|
37 * Specifier Tag Functions:: Working with specifier tags.
|
|
|
38 * Specifier Instancing Functions::
|
|
|
39 Functions to instance a specifier.
|
|
|
40 * Specifier Example:: Making all this stuff clearer.
|
|
|
41 * Creating Specifiers:: Creating specifiers for your own use.
|
|
|
42 * Specifier Validation Functions::
|
|
|
43 Validating the components of a specifier.
|
|
|
44 * Other Specification Functions::
|
|
|
45 Other ways of working with specifications.
|
|
|
46 @end menu
|
|
|
47
|
|
|
48 @node Introduction to Specifiers
|
|
|
49 @section Introduction to Specifiers
|
|
|
50
|
|
|
51 Sometimes you may want the value of a property to vary depending on
|
|
|
52 the context the property is used in. A simple example of this in XEmacs
|
|
|
53 is buffer-local variables. For example, the variable
|
|
|
54 @code{modeline-format}, which controls the format of the modeline, can
|
|
|
55 have different values depending on the particular buffer being edited.
|
|
|
56 The variable has a default value which most modes will use, but a
|
|
|
57 specialized package such as Calendar might change the variable so
|
|
|
58 as to tailor the modeline to its own purposes.
|
|
|
59
|
|
|
60 Other properties (such as those that can be changed by the
|
|
|
61 @code{modify-frame-parameters} function, for example the color of the
|
|
|
62 text cursor) can have frame-local values, although it might also make
|
|
|
63 sense for them to have buffer-local values. In other cases, you might
|
|
|
64 want the property to vary depending on the particular window within the
|
|
|
65 frame that applies (e.g. the top or bottom window in a split frame), the
|
|
|
66 device type that that frame appears on (X or tty), etc. Perhaps you can
|
|
|
67 envision some more complicated scenario where you want a particular
|
|
|
68 value in a specified buffer, another value in all other buffers
|
|
|
69 displayed on a particular frame, another value in all other buffers
|
|
|
70 displayed in all other frames on any mono (two-color, e.g. black and
|
|
|
71 white only) displays, and a default value in all other circumstances.
|
|
|
72
|
|
|
73 A @dfn{specifier} is a generalization of this, allowing a great deal
|
|
|
74 of flexibility in controlling exactly what value a property has in which
|
|
|
75 circumstances. It is most commonly used for display properties, such as
|
|
|
76 an image or the foreground color of a face. As a simple example, you can
|
|
|
77 specify that the foreground of the default face be
|
|
|
78
|
|
|
79 @itemize @bullet
|
|
|
80 @item
|
|
|
81 blue for a particular buffer
|
|
|
82 @item
|
|
|
83 green for all other buffers
|
|
|
84 @end itemize
|
|
|
85
|
|
|
86 As a more complicated example, you could specify that the foreground of
|
|
|
87 the default face be
|
|
|
88
|
|
|
89 @itemize @bullet
|
|
|
90 @item
|
|
|
91 forest green for all buffers displayed in a particular Emacs window, or
|
|
|
92 green if the X server doesn't recognize the color @samp{forest green}
|
|
|
93 @item
|
|
|
94 blue for all buffers displayed in a particular frame
|
|
|
95 @item
|
|
|
96 red for all other buffers displayed on a color device
|
|
|
97 @item
|
|
|
98 white for all other buffers
|
|
|
99 @end itemize
|
|
|
100
|
|
|
101 @node Specifiers In-Depth
|
|
|
102 @section In-Depth Overview of a Specifier
|
|
|
103 @cindex specification (in a specifier)
|
|
|
104 @cindex domain (in a specifier)
|
|
|
105 @cindex locale (in a specifier)
|
|
|
106 @cindex instantiator (in a specifier)
|
|
|
107 @cindex instancing (in a specifier)
|
|
|
108 @cindex instance (in a specifier)
|
|
|
109 @cindex inst-list (in a specifier)
|
|
|
110 @cindex inst-pair (in a specifier)
|
|
|
111 @cindex tag (in a specifier)
|
|
|
112 @cindex tag set (in a specifier)
|
|
|
113 @cindex specifier, specification
|
|
|
114 @cindex specifier, domain
|
|
|
115 @cindex specifier, locale
|
|
|
116 @cindex specifier, instantiator
|
|
|
117 @cindex specifier, instancing
|
|
|
118 @cindex specifier, instance
|
|
|
119 @cindex specifier, inst-list
|
|
|
120 @cindex specifier, inst-pair
|
|
|
121 @cindex specifier, tag
|
|
|
122 @cindex specifier, tag set
|
|
|
123
|
|
|
124 A specifier object encapsulates a set of @dfn{specifications}, each of
|
|
|
125 which says what its value should be if a particular condition applies.
|
|
|
126 For example, one specification might be ``The value should be
|
|
|
127 darkseagreen2 on X devices'' another might be ``The value should be blue
|
|
|
128 in the *Help* buffer''. In specifier terminology, these conditions are
|
|
|
129 called @dfn{locales} and the values are called @dfn{instantiators}.
|
|
|
130 Given a specifier, a logical question is ``What is its value in a
|
|
|
131 particular situation?'' This involves looking through the specifications
|
|
|
132 to see which ones apply to this particular situation, and perhaps
|
|
|
133 preferring one over another if more than one applies. In specifier
|
|
|
134 terminology, a ``particular situation'' is called a @dfn{domain}, and
|
|
|
135 determining its value in a particular domain is called @dfn{instancing}.
|
|
|
136 Most of the time, a domain is identified by a particular window. For
|
|
|
137 example, if the redisplay engine is drawing text in the default face in
|
|
|
138 a particular window, it retrieves the specifier for the foreground color
|
|
|
139 of the default face and @dfn{instances} it in the domain given by that
|
|
|
140 window; in other words, it asks the specifier, ``What is your value in
|
|
|
141 this window?''.
|
|
|
142
|
|
|
143 More specifically, a specifier contains a set of @dfn{specifications},
|
|
|
144 each of which associates a @dfn{locale} (a buffer object, a window
|
|
|
145 object, a frame object, a device object, or the symbol @code{global})
|
|
|
146 with an @dfn{inst-list}, which is a list of one or more
|
|
|
147 @dfn{inst-pairs}. (For each possible locale, there can be at most one
|
|
|
148 specification containing that locale.) Each inst-pair is a cons of a
|
|
|
149 @dfn{tag set} (an unordered list of zero or more symbols, or @dfn{tags})
|
|
|
150 and an @dfn{instantiator} (the allowed form of this varies depending on
|
|
|
151 the type of specifier). In a given specification, there may be more
|
|
|
152 than one inst-pair with the same tag set; this is unlike for locales.
|
|
|
153
|
|
|
154 The tag set is used to restrict the sorts of devices over which the
|
|
|
155 instantiator is valid and to uniquely identify instantiators added by a
|
|
|
156 particular application, so that different applications can work on the
|
|
|
157 same specifier and not interfere with each other. Each tag can have a
|
|
|
158 @dfn{predicate} associated with it, which is a function of one argument
|
|
|
159 (a device) that specifies whether the tag matches that particular
|
|
|
160 device. (If a tag does not have a predicate, it matches all devices.)
|
|
|
161 All tags in a tag set must match a device for the associated inst-pair
|
|
|
162 to be instantiable over that device. (A null tag set is perfectly
|
|
|
163 valid.)
|
|
|
164
|
|
|
165 The valid device types (normally @code{x}, @code{tty}, and
|
|
|
166 @code{stream}) and device classes (normally @code{color},
|
|
|
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}).
|
|
|
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
|
|
|
171 instantiators, and be fairly confident that it will not interfere with
|
|
|
172 other applications that modify the same specifier -- Functions that add
|
|
|
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
|
|
|
175 tag set can be specified when removing instantiators.
|
|
|
176
|
|
|
177 When a specifier is instanced in a domain, both the locale and the tag
|
|
|
178 set can be viewed as specifying necessary conditions that must apply in
|
|
|
179 that domain for an instantiator to be considered as a possible result of
|
|
|
180 the instancing. More specific locales always override more general
|
|
|
181 locales (thus, there is no particular ordering of the specifications in
|
|
|
182 a specifier); however, the tag sets are simply considered in the order
|
|
|
183 that the inst-pairs occur in the specification's inst-list.
|
|
|
184
|
|
|
185 Note also that the actual object that results from the instancing
|
|
|
186 (called an @dfn{instance object}) may not be the same as the instantiator
|
|
|
187 from which it was derived. For some specifier types (such as integer
|
|
|
188 specifiers and boolean specifiers), the instantiator will be returned
|
|
|
189 directly as the instance object. For other types, however, this
|
|
|
190 is not the case. For example, for font specifiers, the instantiator
|
|
|
191 is a font-description string and the instance object is a font-instance
|
|
|
192 object, which describes how the font is displayed on a particular device.
|
|
|
193 A font-instance object encapsulates such things as the actual font name
|
|
|
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
|
|
|
196 different font names, with possibly different foundries, widths, etc.,
|
|
|
197 on different devices), the extra properties of that font on that
|
|
|
198 device, etc. Furthermore, this conversion (called @dfn{instantiation})
|
|
|
199 might fail -- a font or color might not exist on a particular device,
|
|
|
200 for example.
|
|
|
201
|
|
|
202 @node Specifier Instancing
|
|
|
203 @section How a Specifier Is Instanced
|
|
|
204 @cindex fallback (in a specifier)
|
|
|
205 @cindex specifier, fallback
|
|
|
206
|
|
|
207 Instancing of a specifier in a particular window domain proceeds as
|
|
|
208 follows:
|
|
|
209
|
|
|
210 @itemize @bullet
|
|
|
211 @item
|
|
|
212 First, XEmacs searches for a specification whose locale is the same as
|
|
|
213 the window's buffer. If that fails, the search is repeated, looking for
|
|
|
214 a locale that is the same as the window itself. If that fails, the
|
|
|
215 search is repeated using the window's frame, then using the device that
|
|
|
216 frame is on. Finally, the specification whose locale is the symbol
|
|
|
217 @code{global} (if there is such a specification) is considered.
|
|
|
218 @item
|
|
|
219 The inst-pairs contained in the specification that was found are
|
|
|
220 considered in their order in the inst-list, looking for one whose tag
|
|
|
221 set matches the device that is derived from the window domain. (The
|
|
|
222 tag set is an unordered list of zero or more tag symbols. For all
|
|
|
223 tags that have predicates associated with them, the predicate must
|
|
|
224 match the device.)
|
|
|
225 @item
|
|
|
226 If a matching tag set is found, the corresponding instantiator is passed
|
|
|
227 to the specifier's instantiation method, which is specific to the type
|
|
|
228 of the specifier. If it succeeds, the resulting instance object is
|
|
|
229 returned as the result of the instancing and the instancing is done.
|
|
|
230 Otherwise, the operation continues, looking for another matching
|
|
|
231 inst-pair in the current specification.
|
|
|
232 @item
|
|
|
233 When there are no more inst-pairs to be considered in the current
|
|
|
234 specification, the search starts over, looking for another specification
|
|
|
235 as in the first step above.
|
|
|
236 @item
|
|
|
237 If all specifications are exhausted and no instance object can be
|
|
|
238 derived, the instancing fails. (Actually, this is not completely true.
|
|
|
239 Some specifier objects for built-in properties have a @dfn{fallback}
|
|
|
240 value, which is either an inst-list or another specifier object, that is
|
|
|
241 consulted if the instancing is about to fail. If it is an inst-list,
|
|
|
242 the searching proceeds using the inst-pairs in that list. If it is a
|
|
|
243 specifier, the entire instancing starts over using that specifier
|
|
|
244 instead of the given one. Fallback values are set by the C code and
|
|
|
245 cannot be modified, except perhaps indirectly, using any Lisp functions.
|
|
|
246 The purpose of them is to supply some values to make sure that
|
|
|
247 instancing of built-in properties can't fail and to implement some basic
|
|
|
248 specifier inheritance, such as the fact that faces inherit their
|
|
|
249 properties from the @code{default} face.)
|
|
|
250 @end itemize
|
|
|
251
|
|
|
252 It is also possible to instance a specifier over a frame domain or
|
|
|
253 device domain instead of over a window domain. The C code, for example,
|
|
|
254 instances the @code{top-toolbar-height} variable over a frame domain in
|
|
|
255 order to determine the height of a frame's top toolbar. Instancing over
|
|
|
256 a frame or device is similar to instancing over a window except that
|
|
|
257 specifications for locales that cannot be derived from the domain are
|
|
|
258 ignored. Specifically, instancing over a frame looks first for frame
|
|
|
259 locales, then device locales, then the @code{global} locale. Instancing
|
|
|
260 over a device domain looks only for device locales and the @code{global}
|
|
|
261 locale.
|
|
|
262
|
|
|
263 @node Specifier Types
|
|
|
264 @section Specifier Types
|
|
|
265
|
|
|
266 There are various different types of specifiers. The type of a
|
|
|
267 specifier controls what sorts of instantiators are valid, how an
|
|
|
268 instantiator is instantiated, etc. Here is a list of built-in specifier
|
|
|
269 types:
|
|
|
270
|
|
|
271 @table @code
|
|
|
272 @item boolean
|
|
|
273 The valid instantiators are the symbols @code{t} and @code{nil}.
|
|
|
274 Instance objects are the same as instantiators so no special
|
|
|
275 instantiation function is needed.
|
|
|
276
|
|
|
277 @item integer
|
|
|
278 The valid instantiators are integers. Instance objects are the same as
|
|
|
279 instantiators so no special instantiation function is needed.
|
|
|
280 @code{modeline-shadow-thickness} is an example of an integer specifier
|
|
|
281 (negative thicknesses indicate that the shadow is drawn recessed instead
|
|
|
282 of raised).
|
|
|
283
|
|
|
284 @item natnum
|
|
|
285 The valid instantiators are natnums (non-negative integers). Instance
|
|
|
286 objects are the same as instantiators so no special instantiation
|
|
|
287 function is needed. Natnum specifiers are used for dimension variables
|
|
|
288 such as @code{top-toolbar-height}.
|
|
|
289
|
|
|
290 @item generic
|
|
|
291 All Lisp objects are valid instantiators. Instance objects are the same
|
|
|
292 as instantiators so no special instantiation function is needed.
|
|
|
293
|
|
|
294 @item font
|
|
|
295 The valid instantiators are strings describing fonts or vectors
|
|
2
|
296 indicating inheritance from the font of some face. Instance objects are
|
|
|
297 font-instance objects, which are specific to a particular device. The
|
|
|
298 instantiation method for font specifiers can fail, unlike for integer,
|
|
|
299 natnum, boolean, and generic specifiers.
|
|
0
|
300
|
|
|
301 @item color
|
|
|
302 The valid instantiators are strings describing colors or vectors
|
|
|
303 indicating inheritance from the foreground or background of some face.
|
|
|
304 Instance objects are color-instance objects, which are specific to a
|
|
2
|
305 particular device. The instantiation method for color specifiers can fail,
|
|
0
|
306 as for font specifiers.
|
|
|
307
|
|
|
308 @item image
|
|
|
309 Images are perhaps the most complicated type of built-in specifier. The
|
|
|
310 valid instantiators are strings (a filename, inline data for a pixmap,
|
|
|
311 or text to be displayed in a text glyph) or vectors describing inline
|
|
|
312 data of various sorts or indicating inheritance from the
|
|
|
313 background-pixmap property of some face. Instance objects are either
|
|
|
314 strings (for text images), image-instance objects (for pixmap images),
|
|
|
315 or subwindow objects (for subwindow images). The instantiation method
|
|
2
|
316 for image specifiers can fail, as for font and color specifiers.
|
|
0
|
317
|
|
|
318 @item face-boolean
|
|
|
319 The valid instantiators are the symbols @code{t} and @code{nil} and
|
|
|
320 vectors indicating inheritance from a boolean property of some face.
|
|
|
321 Specifiers of this sort are used for all of the built-in boolean
|
|
|
322 properties of faces. Instance objects are either the symbol @code{t}
|
|
|
323 or the symbol @code{nil}.
|
|
|
324
|
|
|
325 @item toolbar
|
|
|
326 The valid instantiators are toolbar descriptors, which are lists
|
|
|
327 of toolbar-button descriptors (each of which is a vector of two
|
|
|
328 or four elements). @xref{Toolbar} for more information.
|
|
|
329 @end table
|
|
|
330
|
|
2
|
331 Color and font instance objects can also be used in turn as
|
|
|
332 instantiators for a new color or font instance object. Since these
|
|
|
333 instance objects are device-specific, the instantiator can be used
|
|
|
334 directly as the new instance object, but only if they are of the same
|
|
|
335 device. If the devices differ, the base color or font of the
|
|
|
336 instantiating object is effectively used instead as the instantiator.
|
|
|
337
|
|
0
|
338 @xref{Faces and Window-System Objects} for more information on fonts,
|
|
|
339 colors, and face-boolean specifiers. @xref{Glyphs} for more information
|
|
|
340 about image specifiers. @xref{Toolbar} for more information on toolbar
|
|
|
341 specifiers.
|
|
|
342
|
|
|
343 @defun specifier-type specifier
|
|
|
344 This function returns the type of @var{specifier}. The returned value
|
|
|
345 will be a symbol: one of @code{integer}, @code{boolean}, etc., as
|
|
|
346 listed in the above table.
|
|
|
347 @end defun
|
|
|
348
|
|
|
349 Functions are also provided to query whether an object is a particular
|
|
|
350 kind of specifier:
|
|
|
351
|
|
|
352 @defun boolean-specifier-p object
|
|
|
353 This function returns non-@code{nil} if @var{object} is a boolean
|
|
|
354 specifier.
|
|
|
355 @end defun
|
|
|
356
|
|
|
357 @defun integer-specifier-p object
|
|
|
358 This function returns non-@code{nil} if @var{object} is an integer
|
|
|
359 specifier.
|
|
|
360 @end defun
|
|
|
361
|
|
|
362 @defun natnum-specifier-p object
|
|
|
363 This function returns non-@code{nil} if @var{object} is a natnum
|
|
|
364 specifier.
|
|
|
365 @end defun
|
|
|
366
|
|
|
367 @defun generic-specifier-p object
|
|
|
368 This function returns non-@code{nil} if @var{object} is a generic
|
|
|
369 specifier.
|
|
|
370 @end defun
|
|
|
371
|
|
|
372 @defun face-boolean-specifier-p object
|
|
|
373 This function returns non-@code{nil} if @var{object} is a face-boolean
|
|
|
374 specifier.
|
|
|
375 @end defun
|
|
|
376
|
|
|
377 @defun toolbar-specifier-p object
|
|
|
378 This function returns non-@code{nil} if @var{object} is a toolbar
|
|
|
379 specifier.
|
|
|
380 @end defun
|
|
|
381
|
|
|
382 @defun font-specifier-p object
|
|
|
383 This function returns non-@code{nil} if @var{object} is a font
|
|
|
384 specifier.
|
|
|
385 @end defun
|
|
|
386
|
|
|
387 @defun color-specifier-p object
|
|
|
388 This function returns non-@code{nil} if @var{object} is a color
|
|
|
389 specifier.
|
|
|
390 @end defun
|
|
|
391
|
|
|
392 @defun image-specifier-p object
|
|
|
393 This function returns non-@code{nil} if @var{object} is an image
|
|
|
394 specifier.
|
|
|
395 @end defun
|
|
|
396
|
|
|
397 @node Adding Specifications
|
|
|
398 @section Adding specifications to a Specifier
|
|
|
399
|
|
|
400 @defun add-spec-to-specifier specifier instantiator &optional locale tag-set how-to-add
|
|
|
401 This function adds a specification to @var{specifier}. The
|
|
|
402 specification maps from @var{locale} (which should be a buffer, window,
|
|
|
403 frame, device, or the symbol @code{global}, and defaults to
|
|
|
404 @code{global}) to @var{instantiator}, whose allowed values depend on the
|
|
|
405 type of the specifier. Optional argument @var{tag-set} limits the
|
|
|
406 instantiator to apply only to the specified tag set, which should be a
|
|
|
407 list of tags all of which must match the device being instantiated over
|
|
|
408 (tags are a device type, a device class, or tags defined with
|
|
|
409 @code{define-specifier-tag}). Specifying a single symbol for
|
|
|
410 @var{tag-set} is equivalent to specifying a one-element list containing
|
|
|
411 that symbol. Optional argument @var{how-to-add} specifies what to do if
|
|
|
412 there are already specifications in the specifier. It should be one of
|
|
|
413
|
|
|
414 @table @code
|
|
|
415 @item prepend
|
|
|
416 Put at the beginning of the current list of instantiators for @var{locale}.
|
|
|
417 @item append
|
|
|
418 Add to the end of the current list of instantiators for @var{locale}.
|
|
|
419 @item remove-tag-set-prepend
|
|
|
420 This is the default. Remove any existing instantiators whose tag set is
|
|
|
421 the same as @var{tag-set}; then put the new instantiator at the
|
|
|
422 beginning of the current list.
|
|
|
423 @item remove-tag-set-append
|
|
|
424 Remove any existing instantiators whose tag set is the same as
|
|
|
425 @var{tag-set}; then put the new instantiator at the end of the current
|
|
|
426 list.
|
|
|
427 @item remove-locale
|
|
|
428 Remove all previous instantiators for this locale before adding the new
|
|
|
429 spec.
|
|
|
430 @item remove-locale-type
|
|
|
431 Remove all specifications for all locales of the same type as
|
|
|
432 @var{locale} (this includes @var{locale} itself) before adding the new
|
|
|
433 spec.
|
|
|
434 @item remove-all
|
|
|
435 Remove all specifications from the specifier before adding the new spec.
|
|
|
436 @end table
|
|
|
437
|
|
|
438 @code{remove-tag-set-prepend} is the default.
|
|
|
439
|
|
|
440 You can retrieve the specifications for a particular locale or locale type
|
|
|
441 with the function @code{specifier-spec-list} or @code{specifier-specs}.
|
|
|
442 @end defun
|
|
|
443
|
|
|
444 @defun add-spec-list-to-specifier specifier spec-list &optional how-to-add
|
|
|
445 This function adds a @dfn{spec-list} (a list of specifications) to
|
|
|
446 @var{specifier}. The format of a spec-list is
|
|
|
447
|
|
|
448 @example
|
|
|
449 @code{((@var{locale} (@var{tag-set} . @var{instantiator}) ...) ...)}
|
|
|
450 @end example
|
|
|
451
|
|
|
452 where
|
|
|
453
|
|
|
454 @itemize @bullet
|
|
|
455 @item
|
|
|
456 @var{locale} := a buffer, a window, a frame, a device, or @code{global}
|
|
|
457 @item
|
|
|
458 @var{tag-set} := an unordered list of zero or more @var{tags}, each of
|
|
|
459 which is a symbol
|
|
|
460 @item
|
|
|
461 @var{tag} := a device class (@pxref{Consoles and Devices}), a device type,
|
|
|
462 or a tag defined with @code{define-specifier-tag}
|
|
|
463 @item
|
|
|
464 @var{instantiator} := format determined by the type of specifier
|
|
|
465 @end itemize
|
|
|
466
|
|
|
467 The pair @code{(@var{tag-set} . @var{instantiator})} is called an
|
|
|
468 @dfn{inst-pair}. A list of inst-pairs is called an @dfn{inst-list}.
|
|
|
469 The pair @code{(@var{locale} . @var{inst-list})} is called a
|
|
|
470 @dfn{specification}. A spec-list, then, can be viewed as a list of
|
|
|
471 specifications.
|
|
|
472
|
|
|
473 @var{how-to-add} specifies how to combine the new specifications with
|
|
|
474 the existing ones, and has the same semantics as for
|
|
|
475 @code{add-spec-to-specifier}.
|
|
|
476
|
|
|
477 In many circumstances, the higher-level function @code{set-specifier} is
|
|
|
478 more convenient and should be used instead.
|
|
|
479 @end defun
|
|
|
480
|
|
|
481 @defun set-specifier specifier value &optional how-to-add
|
|
|
482 This function adds some specifications to @var{specifier}. @var{value}
|
|
|
483 can be a single instantiator or tagged instantiator (added as a global
|
|
|
484 specification), a list of tagged and/or untagged instantiators (added as
|
|
|
485 a global specification), a cons of a locale and instantiator or locale
|
|
|
486 and instantiator list, a list of such conses, or nearly any other
|
|
|
487 reasonable form. More specifically, @var{value} can be anything
|
|
|
488 accepted by @code{canonicalize-spec-list}.
|
|
|
489
|
|
|
490 @var{how-to-add} is the same as in @code{add-spec-to-specifier}.
|
|
|
491
|
|
|
492 Note that @code{set-specifier} is exactly complementary to
|
|
|
493 @code{specifier-specs} except in the case where @var{specifier} has no
|
|
|
494 specs at all in it but @code{nil} is a valid instantiator (in that case,
|
|
|
495 @code{specifier-specs} will return @code{nil} (meaning no specs) and
|
|
|
496 @code{set-specifier} will interpret the @code{nil} as meaning ``I'm
|
|
|
497 adding a global instantiator and its value is @code{nil}''), or in
|
|
|
498 strange cases where there is an ambiguity between a spec-list and an
|
|
|
499 inst-list, etc. (The built-in specifier types are designed in such a way
|
|
|
500 as to avoid any such ambiguities.)
|
|
|
501
|
|
|
502 If you want to work with spec-lists, you should probably not use these
|
|
|
503 functions, but should use the lower-level functions
|
|
|
504 @code{specifier-spec-list} and @code{add-spec-list-to-specifier}. These
|
|
|
505 functions always work with fully-qualified spec-lists; thus, there is no
|
|
|
506 ambiguity.
|
|
|
507 @end defun
|
|
|
508
|
|
|
509 @defun canonicalize-inst-pair inst-pair specifier-type &optional noerror
|
|
|
510 This function canonicalizes the given @var{inst-pair}.
|
|
|
511
|
|
|
512 @var{specifier-type} specifies the type of specifier that this
|
|
|
513 @var{spec-list} will be used for.
|
|
|
514
|
|
|
515 Canonicalizing means converting to the full form for an inst-pair, i.e.
|
|
|
516 @code{(@var{tag-set} . @var{instantiator})}. A single, untagged
|
|
|
517 instantiator is given a tag set of @code{nil} (the empty set), and a
|
|
|
518 single tag is converted into a tag set consisting only of that tag.
|
|
|
519
|
|
|
520 If @var{noerror} is non-@code{nil}, signal an error if the inst-pair is
|
|
|
521 invalid; otherwise return @code{t}.
|
|
|
522 @end defun
|
|
|
523
|
|
|
524 @defun canonicalize-inst-list inst-list specifier-type &optional noerror
|
|
|
525 This function canonicalizes the given @var{inst-list} (a list of
|
|
|
526 inst-pairs).
|
|
|
527
|
|
|
528 @var{specifier-type} specifies the type of specifier that this @var{inst-list}
|
|
|
529 will be used for.
|
|
|
530
|
|
|
531 Canonicalizing means converting to the full form for an inst-list, i.e.
|
|
|
532 @code{((@var{tag-set} . @var{instantiator}) ...)}. This function
|
|
30
|
533 accepts a single inst-pair or any abbreviation thereof or a list of
|
|
0
|
534 (possibly abbreviated) inst-pairs. (See @code{canonicalize-inst-pair}.)
|
|
|
535
|
|
|
536 If @var{noerror} is non-@code{nil}, signal an error if the inst-list is
|
|
|
537 invalid; otherwise return @code{t}.
|
|
|
538 @end defun
|
|
|
539
|
|
|
540 @defun canonicalize-spec spec specifier-type &optional noerror
|
|
|
541 This function canonicalizes the given @var{spec} (a specification).
|
|
|
542
|
|
|
543 @var{specifier-type} specifies the type of specifier that this
|
|
|
544 @var{spec-list} will be used for.
|
|
|
545
|
|
|
546 Canonicalizing means converting to the full form for a spec, i.e.
|
|
|
547 @code{(@var{locale} (@var{tag-set} . @var{instantiator}) ...)}. This
|
|
|
548 function accepts a possibly abbreviated inst-list or a cons of a locale
|
|
|
549 and a possibly abbreviated inst-list. (See
|
|
|
550 @code{canonicalize-inst-list}.)
|
|
|
551
|
|
|
552 If @var{noerror} is @code{nil}, signal an error if the specification is
|
|
|
553 invalid; otherwise return @code{t}.
|
|
|
554 @end defun
|
|
|
555
|
|
|
556 @defun canonicalize-spec-list spec-list specifier-type &optional noerror
|
|
|
557 This function canonicalizes the given @var{spec-list} (a list of
|
|
|
558 specifications).
|
|
|
559
|
|
|
560 @var{specifier-type} specifies the type of specifier that this
|
|
|
561 @var{spec-list} will be used for.
|
|
|
562
|
|
|
563 Canonicalizing means converting to the full form for a spec-list, i.e.
|
|
|
564 @code{((@var{locale} (@var{tag-set} . @var{instantiator}) ...) ...)}.
|
|
|
565 This function accepts a possibly abbreviated specification or a list of
|
|
|
566 such things. (See @code{canonicalize-spec}.) This is the function used
|
|
|
567 to convert spec-lists accepted by @code{set-specifier} and such into a
|
|
|
568 form suitable for @code{add-spec-list-to-specifier}.
|
|
|
569
|
|
|
570 This function tries extremely hard to resolve any ambiguities,
|
|
|
571 and the built-in specifier types (font, image, toolbar, etc.) are
|
|
|
572 designed so that there won't be any ambiguities.
|
|
|
573
|
|
|
574 If @var{noerror} is @code{nil}, signal an error if the spec-list is
|
|
|
575 invalid; otherwise return @code{t}.
|
|
|
576 @end defun
|
|
|
577
|
|
|
578 @node Retrieving Specifications
|
|
|
579 @section Retrieving the Specifications from a Specifier
|
|
|
580
|
|
|
581 @defun specifier-spec-list specifier &optional locale tag-set exact-p
|
|
|
582 This function returns the spec-list of specifications for
|
|
|
583 @var{specifier} in @var{locale}.
|
|
|
584
|
|
|
585 If @var{locale} is a particular locale (a buffer, window, frame, device,
|
|
|
586 or the symbol @code{global}), a spec-list consisting of the
|
|
|
587 specification for that locale will be returned.
|
|
|
588
|
|
|
589 If @var{locale} is a locale type (i.e. a symbol @code{buffer},
|
|
|
590 @code{window}, @code{frame}, or @code{device}), a spec-list of the
|
|
|
591 specifications for all locales of that type will be returned.
|
|
|
592
|
|
|
593 If @var{locale} is @code{nil} or the symbol @code{all}, a spec-list of
|
|
|
594 all specifications in @var{specifier} will be returned.
|
|
|
595
|
|
|
596 @var{locale} can also be a list of locales, locale types, and/or
|
|
|
597 @code{all}; the result is as if @code{specifier-spec-list} were called
|
|
|
598 on each element of the list and the results concatenated together.
|
|
|
599
|
|
|
600 Only instantiators where @var{tag-set} (a list of zero or more tags) is
|
|
|
601 a subset of (or possibly equal to) the instantiator's tag set are
|
|
|
602 returned. (The default value of@code{ nil} is a subset of all tag sets,
|
|
|
603 so in this case no instantiators will be screened out.) If @var{exact-p}
|
|
|
604 is non-@code{nil}, however, @var{tag-set} must be equal to an
|
|
|
605 instantiator's tag set for the instantiator to be returned.
|
|
|
606 @end defun
|
|
|
607
|
|
|
608 @defun specifier-specs specifier &optional locale tag-set exact-p
|
|
|
609 This function returns the specification(s) for @var{specifier} in
|
|
|
610 @var{locale}.
|
|
|
611
|
|
|
612 If @var{locale} is a single locale or is a list of one element
|
|
|
613 containing a single locale, then a ``short form'' of the instantiators
|
|
|
614 for that locale will be returned. Otherwise, this function is identical
|
|
|
615 to @code{specifier-spec-list}.
|
|
|
616
|
|
|
617 The ``short form'' is designed for readability and not for ease of use
|
|
|
618 in Lisp programs, and is as follows:
|
|
|
619
|
|
|
620 @enumerate
|
|
|
621 @item
|
|
|
622 If there is only one instantiator, then an inst-pair (i.e. cons of tag
|
|
|
623 and instantiator) will be returned; otherwise a list of inst-pairs will
|
|
|
624 be returned.
|
|
|
625 @item
|
|
|
626 For each inst-pair returned, if the instantiator's tag is @code{any},
|
|
|
627 the tag will be removed and the instantiator itself will be returned
|
|
|
628 instead of the inst-pair.
|
|
|
629 @item
|
|
|
630 If there is only one instantiator, its value is @code{nil}, and its tag
|
|
|
631 is @code{any}, a one-element list containing @code{nil} will be returned
|
|
|
632 rather than just @code{nil}, to distinguish this case from there being
|
|
|
633 no instantiators at all.
|
|
|
634 @end enumerate
|
|
|
635
|
|
|
636 @end defun
|
|
|
637
|
|
|
638 @defun specifier-fallback specifier
|
|
|
639 This function returns the fallback value for @var{specifier}. Fallback
|
|
|
640 values are provided by the C code for certain built-in specifiers to
|
|
|
641 make sure that instancing won't fail even if all specs are removed from
|
|
|
642 the specifier, or to implement simple inheritance behavior (e.g. this
|
|
|
643 method is used to ensure that faces other than @code{default} inherit
|
|
|
644 their attributes from @code{default}). By design, you cannot change the
|
|
|
645 fallback value, and specifiers created with @code{make-specifier} will
|
|
|
646 never have a fallback (although a similar, Lisp-accessible capability
|
|
|
647 may be provided in the future to allow for inheritance).
|
|
|
648
|
|
|
649 The fallback value will be an inst-list that is instanced like
|
|
|
650 any other inst-list, a specifier of the same type as @var{specifier}
|
|
|
651 (results in inheritance), or @code{nil} for no fallback.
|
|
|
652
|
|
|
653 When you instance a specifier, you can explicitly request that the
|
|
|
654 fallback not be consulted. (The C code does this, for example, when
|
|
|
655 merging faces.) See @code{specifier-instance}.
|
|
|
656 @end defun
|
|
|
657
|
|
|
658 @node Specifier Tag Functions
|
|
|
659 @section Working With Specifier Tags
|
|
|
660
|
|
|
661 A specifier tag set is an entity that is attached to an instantiator
|
|
|
662 and can be used to restrict the scope of that instantiator to a
|
|
|
663 particular device class or device type and/or to mark instantiators
|
|
|
664 added by a particular package so that they can be later removed.
|
|
|
665
|
|
|
666 A specifier tag set consists of a list of zero of more specifier tags,
|
|
|
667 each of which is a symbol that is recognized by XEmacs as a tag. (The
|
|
|
668 valid device types and device classes are always tags, as are any tags
|
|
|
669 defined by @code{define-specifier-tag}.) It is called a ``tag set'' (as
|
|
|
670 opposed to a list) because the order of the tags or the number of times
|
|
|
671 a particular tag occurs does not matter.
|
|
|
672
|
|
|
673 Each tag has a predicate associated with it, which specifies whether
|
|
|
674 that tag applies to a particular device. The tags which are device
|
|
|
675 types and classes match devices of that type or class. User-defined
|
|
|
676 tags can have any predicate, or none (meaning that all devices match).
|
|
|
677 When attempting to instance a specifier, a particular instantiator is
|
|
|
678 only considered if the device of the domain being instanced over matches
|
|
|
679 all tags in the tag set attached to that instantiator.
|
|
|
680
|
|
|
681 Most of the time, a tag set is not specified, and the instantiator gets
|
|
|
682 a null tag set, which matches all devices.
|
|
|
683
|
|
|
684 @defun valid-specifier-tag-p tag
|
|
|
685 This function returns non-@code{nil} if @var{tag} is a valid specifier
|
|
|
686 tag.
|
|
|
687 @end defun
|
|
|
688
|
|
|
689 @defun valid-specifier-tag-set-p tag-set
|
|
|
690 This function returns non-@code{nil} if @var{tag-set} is a valid
|
|
|
691 specifier tag set.
|
|
|
692 @end defun
|
|
|
693
|
|
|
694 @defun canonicalize-tag-set tag-set
|
|
|
695 This function canonicalizes the given tag set. Two canonicalized tag
|
|
|
696 sets can be compared with @code{equal} to see if they represent the same
|
|
|
697 tag set. (Specifically, canonicalizing involves sorting by symbol name
|
|
|
698 and removing duplicates.)
|
|
|
699 @end defun
|
|
|
700
|
|
|
701 @defun device-matches-specifier-tag-set-p device tag-set
|
|
|
702 This function returns non-@code{nil} if @var{device} matches specifier
|
|
|
703 tag set @var{tag-set}. This means that @var{device} matches each tag in
|
|
|
704 the tag set.
|
|
|
705 @end defun
|
|
|
706
|
|
|
707 @defun define-specifier-tag tag &optional predicate
|
|
|
708 This function defines a new specifier tag. If @var{predicate} is
|
|
|
709 specified, it should be a function of one argument (a device) that
|
|
|
710 specifies whether the tag matches that particular device. If
|
|
|
711 @var{predicate} is omitted, the tag matches all devices.
|
|
|
712
|
|
|
713 You can redefine an existing user-defined specifier tag. However, you
|
|
|
714 cannot redefine the built-in specifier tags (the device types and
|
|
|
715 classes) or the symbols @code{nil}, @code{t}, @code{all}, or
|
|
|
716 @code{global}.
|
|
|
717 @end defun
|
|
|
718
|
|
|
719 @defun device-matching-specifier-tag-list &optional device
|
|
|
720 This function returns a list of all specifier tags matching
|
|
|
721 @var{device}. @var{device} defaults to the selected device if omitted.
|
|
|
722 @end defun
|
|
|
723
|
|
|
724 @defun specifier-tag-list
|
|
|
725 This function returns a list of all currently-defined specifier tags.
|
|
|
726 This includes the built-in ones (the device types and classes).
|
|
|
727 @end defun
|
|
|
728
|
|
|
729 @defun specifier-tag-predicate tag
|
|
|
730 This function returns the predicate for the given specifier tag.
|
|
|
731 @end defun
|
|
|
732
|
|
|
733 @node Specifier Instancing Functions
|
|
|
734 @section Functions for Instancing a Specifier
|
|
|
735
|
|
|
736 @defun specifier-instance specifier &optional domain default no-fallback
|
|
|
737 This function instantiates @var{specifier} (return its value) in
|
|
|
738 @var{domain}. If no instance can be generated for this domain, return
|
|
|
739 @var{default}.
|
|
|
740
|
|
|
741 @var{domain} should be a window, frame, or device. Other values that
|
|
|
742 are legal as a locale (e.g. a buffer) are not valid as a domain because
|
|
|
743 they do not provide enough information to identify a particular device
|
|
|
744 (see @code{valid-specifier-domain-p}). @var{domain} defaults to the
|
|
|
745 selected window if omitted.
|
|
|
746
|
|
|
747 @dfn{Instantiating} a specifier in a particular domain means determining
|
|
|
748 the specifier's ``value'' in that domain. This is accomplished by
|
|
|
749 searching through the specifications in the specifier that correspond to
|
|
|
750 all locales that can be derived from the given domain, from specific to
|
|
|
751 general. In most cases, the domain is an Emacs window. In that case
|
|
|
752 specifications are searched for as follows:
|
|
|
753
|
|
|
754 @enumerate
|
|
|
755 @item
|
|
|
756 A specification whose locale is the window's buffer;
|
|
|
757 @item
|
|
|
758 A specification whose locale is the window itself;
|
|
|
759 @item
|
|
|
760 A specification whose locale is the window's frame;
|
|
|
761 @item
|
|
|
762 A specification whose locale is the window's frame's device;
|
|
|
763 @item
|
|
|
764 A specification whose locale is the symbol @code{global}.
|
|
|
765 @end enumerate
|
|
|
766
|
|
|
767 If all of those fail, then the C-code-provided fallback value for this
|
|
|
768 specifier is consulted (see @code{specifier-fallback}). If it is an
|
|
|
769 inst-list, then this function attempts to instantiate that list just as
|
|
|
770 when a specification is located in the first five steps above. If the
|
|
|
771 fallback is a specifier, @code{specifier-instance} is called recursively
|
|
|
772 on this specifier and the return value used. Note, however, that if the
|
|
|
773 optional argument @var{no-fallback} is non-@code{nil}, the fallback
|
|
|
774 value will not be consulted.
|
|
|
775
|
|
|
776 Note that there may be more than one specification matching a particular
|
|
|
777 locale; all such specifications are considered before looking for any
|
|
|
778 specifications for more general locales. Any particular specification
|
|
|
779 that is found may be rejected because it is tagged to a particular
|
|
|
780 device class (e.g. @code{color}) or device type (e.g. @code{x}) or both
|
|
|
781 and the device for the given domain does not match this, or because the
|
|
|
782 specification is not valid for the device of the given domain (e.g. the
|
|
|
783 font or color name does not exist for this particular X server).
|
|
|
784
|
|
|
785 The returned value is dependent on the type of specifier. For example,
|
|
|
786 for a font specifier (as returned by the @code{face-font} function), the
|
|
|
787 returned value will be a font-instance object. For images, the returned
|
|
|
788 value will be a string, pixmap, or subwindow.
|
|
|
789 @end defun
|
|
|
790
|
|
|
791 @defun specifier-instance-from-inst-list specifier domain inst-list &optional default
|
|
|
792 This function attempts to convert a particular inst-list into an
|
|
|
793 instance. This attempts to instantiate @var{inst-list} in the given
|
|
|
794 @var{domain}, as if @var{inst-list} existed in a specification in
|
|
|
795 @var{specifier}. If the instantiation fails, @var{default} is returned.
|
|
|
796 In most circumstances, you should not use this function; use
|
|
|
797 @code{specifier-instance} instead.
|
|
|
798 @end defun
|
|
|
799
|
|
|
800 @node Specifier Example
|
|
|
801 @section Example of Specifier Usage
|
|
|
802
|
|
|
803 Now let us present an example to clarify the theoretical discussions we
|
|
|
804 have been through. In this example, we will use the general specifier
|
|
|
805 functions for clarity. Keep in mind that many types of specifiers, and
|
|
|
806 some other types of objects that are associated with specifiers
|
|
|
807 (e.g. faces), provide convenience functions making it easier to work
|
|
|
808 with objects of that type.
|
|
|
809
|
|
|
810 Let us consider the background color of the default face. A specifier
|
|
|
811 is used to specify how that color will appear in different domains.
|
|
|
812 First, let's retrieve the specifier:
|
|
|
813
|
|
|
814 @example
|
|
|
815 (setq sp (face-property 'default 'background))
|
|
|
816 @result{} #<color-specifier 0x3da>
|
|
|
817 @end example
|
|
|
818
|
|
|
819 @example
|
|
|
820 (specifier-specs sp)
|
|
|
821 @result{} ((#<buffer "device.c"> (nil . "forest green"))
|
|
|
822 (#<window on "Makefile" 0x8a2b> (nil . "hot pink"))
|
|
|
823 (#<x-frame "emacs" 0x4ac> (nil . "puke orange")
|
|
|
824 (nil . "moccasin"))
|
|
|
825 (#<x-frame "VM" 0x4ac> (nil . "magenta"))
|
|
|
826 (global ((tty) . "cyan") (nil . "white"))
|
|
|
827 )
|
|
|
828 @end example
|
|
|
829
|
|
|
830 Then, say we want to determine what the background color of the default
|
|
|
831 face is for the window currently displaying the buffer @samp{*scratch*}.
|
|
|
832 We call
|
|
|
833
|
|
|
834 @example
|
|
|
835 (get-buffer-window "*scratch*")
|
|
|
836 @result{} #<window on "*scratch*" 0x4ad>
|
|
|
837 (window-frame (get-buffer-window "*scratch*"))
|
|
|
838 @result{} #<x-frame "emacs" 0x4ac>
|
|
|
839 (specifier-instance sp (get-buffer-window "*scratch*"))
|
|
|
840 @result{} #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x6309>
|
|
|
841 @end example
|
|
|
842
|
|
|
843 Note that we passed a window to @code{specifier-instance}, not a buffer.
|
|
|
844 We cannot pass a buffer because a buffer by itself does not provide enough
|
|
|
845 information. The buffer might not be displayed anywhere at all, or
|
|
|
846 could be displayed in many different frames on different devices.
|
|
|
847
|
|
|
848 The result is arrived at like this:
|
|
|
849
|
|
|
850 @enumerate
|
|
|
851 @item
|
|
|
852 First, we look for a specification matching the buffer displayed in the
|
|
|
853 window, i.e. @samp{*scratch}. There are none, so we proceed.
|
|
|
854 @item
|
|
|
855 Then, we look for a specification matching the window itself. Again, there
|
|
|
856 are none.
|
|
|
857 @item
|
|
|
858 Then, we look for a specification matching the window's frame. The
|
|
|
859 specification @code{(#<x-frame "emacs" 0x4ac> . "puke orange")} is
|
|
|
860 found. We call the instantiation method for colors, passing it the
|
|
|
861 locale we were searching over (i.e. the window, in this case) and the
|
|
|
862 instantiator (@samp{"puke orange"}). However, the particular device
|
|
|
863 which this window is on (let's say it's an X connection) doesn't
|
|
|
864 recognize the color @samp{"puke orange"}, so the specification is
|
|
|
865 rejected.
|
|
|
866 @item
|
|
|
867 So we continue looking for a specification matching the window's frame.
|
|
|
868 We find @samp{(#<x-frame "emacs" 0x4ac> . "moccasin")}. Again, we
|
|
|
869 call the instantiation method for colors. This time, the X server
|
|
|
870 our window is on recognizes the color @samp{moccasin}, and so the
|
|
|
871 instantiation method succeeds and returns a color instance.
|
|
|
872 @end enumerate
|
|
|
873
|
|
|
874 @node Creating Specifiers
|
|
|
875 @section Creating New Specifier Objects
|
|
|
876
|
|
|
877 @defun make-specifier type
|
|
|
878 This function creates a new specifier.
|
|
|
879
|
|
|
880 A specifier is an object that can be used to keep track of a property
|
|
|
881 whose value can be per-buffer, per-window, per-frame, or per-device,
|
|
|
882 and can further be restricted to a particular device-type or device-class.
|
|
|
883 Specifiers are used, for example, for the various built-in properties of a
|
|
|
884 face; this allows a face to have different values in different frames,
|
|
|
885 buffers, etc. For more information, see `specifier-instance',
|
|
|
886 `specifier-specs', and `add-spec-to-specifier'; or, for a detailed
|
|
|
887 description of specifiers, including how they are instantiated over a
|
|
|
888 particular domain (i.e. how their value in that domain is determined),
|
|
|
889 see the chapter on specifiers in the XEmacs Lisp Reference Manual.
|
|
|
890
|
|
|
891 @var{type} specifies the particular type of specifier, and should be one
|
|
|
892 of the symbols @code{generic}, @code{integer}, @code{natnum},
|
|
|
893 @code{boolean}, @code{color}, @code{font}, @code{image},
|
|
|
894 @code{face-boolean}, or @code{toolbar}.
|
|
|
895
|
|
|
896 For more information on particular types of specifiers, see the
|
|
|
897 functions @code{generic-specifier-p}, @code{integer-specifier-p},
|
|
|
898 @code{natnum-specifier-p}, @code{boolean-specifier-p},
|
|
|
899 @code{color-specifier-p}, @code{font-specifier-p},
|
|
|
900 @code{image-specifier-p}, @code{face-boolean-specifier-p}, and
|
|
|
901 @code{toolbar-specifier-p}.
|
|
|
902 @end defun
|
|
|
903
|
|
|
904 @defun make-specifier-and-init type spec-list &optional dont-canonicalize
|
|
|
905 This function creates and initialize a new specifier.
|
|
|
906
|
|
|
907 This is a front-end onto @code{make-specifier} that allows you to create
|
|
|
908 a specifier and add specs to it at the same time. @var{type} specifies
|
|
|
909 the specifier type. @var{spec-list} supplies the specification(s) to be
|
|
|
910 added to the specifier. Normally, almost any reasonable abbreviation of
|
|
|
911 the full spec-list form is accepted, and is converted to the full form;
|
|
|
912 however, if optional argument @var{dont-canonicalize} is non-@code{nil},
|
|
|
913 this conversion is not performed, and the @var{spec-list} must already
|
|
|
914 be in full form. See @code{canonicalize-spec-list}.
|
|
|
915 @end defun
|
|
|
916
|
|
|
917 @node Specifier Validation Functions
|
|
|
918 @section Functions for Checking the Validity of Specifier Components
|
|
|
919
|
|
|
920 @defun valid-specifier-domain-p domain
|
|
|
921 This function returns non-@code{nil} if @var{domain} is a valid
|
|
|
922 specifier domain. A domain is used to instance a specifier
|
|
|
923 (i.e. determine the specifier's value in that domain). Valid domains
|
|
|
924 are a window, frame, or device. (@code{nil} is not valid.)
|
|
|
925 @end defun
|
|
|
926
|
|
|
927 @defun valid-specifier-locale-p locale
|
|
|
928 This function returns non-@code{nil} if @var{locale} is a valid
|
|
|
929 specifier locale. Valid locales are a device, a frame, a window, a
|
|
|
930 buffer, and @code{global}. (@code{nil} is not valid.)
|
|
|
931 @end defun
|
|
|
932
|
|
|
933 @defun valid-specifier-locale-type-p locale-type
|
|
|
934 Given a specifier @var{locale-type}, this function returns non-nil if it
|
|
|
935 is valid. Valid locale types are the symbols @code{global},
|
|
|
936 @code{device}, @code{frame}, @code{window}, and @code{buffer}. (Note,
|
|
|
937 however, that in functions that accept either a locale or a locale type,
|
|
|
938 @code{global} is considered an individual locale.)
|
|
|
939 @end defun
|
|
|
940
|
|
|
941 @defun valid-specifier-type-p specifier-type
|
|
|
942 Given a @var{specifier-type}, this function returns non-@code{nil} if it
|
|
|
943 is valid. Valid types are @code{generic}, @code{integer},
|
|
|
944 @code{boolean}, @code{color}, @code{font}, @code{image},
|
|
|
945 @code{face-boolean}, and @code{toolbar}.
|
|
|
946 @end defun
|
|
|
947
|
|
|
948 @defun valid-specifier-tag-p tag
|
|
|
949 This function returns non-@code{nil} if @var{tag} is a valid specifier
|
|
|
950 tag.
|
|
|
951 @end defun
|
|
|
952
|
|
|
953 @defun valid-instantiator-p instantiator specifier-type
|
|
|
954 This function returns non-@code{nil} if @var{instantiator} is valid for
|
|
|
955 @var{specifier-type}.
|
|
|
956 @end defun
|
|
|
957
|
|
|
958 @defun valid-inst-list-p inst-list type
|
|
|
959 This function returns non-@code{nil} if @var{inst-list} is valid for
|
|
|
960 specifier type @var{type}.
|
|
|
961 @end defun
|
|
|
962
|
|
|
963 @defun valid-spec-list-p spec-list type
|
|
|
964 This function returns non-@code{nil} if @var{spec-list} is valid for
|
|
|
965 specifier type @var{type}.
|
|
|
966 @end defun
|
|
|
967
|
|
|
968 @defun check-valid-instantiator instantiator specifier-type
|
|
|
969 This function signals an error if @var{instantiator} is invalid for
|
|
|
970 @var{specifier-type}.
|
|
|
971 @end defun
|
|
|
972
|
|
|
973 @defun check-valid-inst-list inst-list type
|
|
|
974 This function signals an error if @var{inst-list} is invalid for
|
|
|
975 specifier type @var{type}.
|
|
|
976 @end defun
|
|
|
977
|
|
|
978 @defun check-valid-spec-list spec-list type
|
|
|
979 This function signals an error if @var{spec-list} is invalid for
|
|
|
980 specifier type @var{type}.
|
|
|
981 @end defun
|
|
|
982
|
|
|
983 @node Other Specification Functions
|
|
|
984 @section Other Functions for Working with Specifications in a Specifier
|
|
|
985
|
|
|
986 @defun copy-specifier specifier &optional dest locale tag-set exact-p how-to-add
|
|
|
987 This function copies @var{specifier} to @var{dest}, or creates a new one
|
|
|
988 if @var{dest} is @code{nil}.
|
|
|
989
|
|
|
990 If @var{dest} is @code{nil} or omitted, a new specifier will be created
|
|
|
991 and the specifications copied into it. Otherwise, the specifications
|
|
|
992 will be copied into the existing specifier in @var{dest}.
|
|
|
993
|
|
|
994 If @var{locale} is @code{nil} or the symbol @code{all}, all
|
|
|
995 specifications will be copied. If @var{locale} is a particular locale,
|
|
|
996 the specification for that particular locale will be copied. If
|
|
|
997 @var{locale} is a locale type, the specifications for all locales of
|
|
|
998 that type will be copied. @var{locale} can also be a list of locales,
|
|
|
999 locale types, and/or @code{all}; this is equivalent to calling
|
|
|
1000 @code{copy-specifier} for each of the elements of the list. See
|
|
|
1001 @code{specifier-spec-list} for more information about @var{locale}.
|
|
|
1002
|
|
|
1003 Only instantiators where @var{tag-set} (a list of zero or more tags) is
|
|
|
1004 a subset of (or possibly equal to) the instantiator's tag set are
|
|
|
1005 copied. (The default value of @code{nil} is a subset of all tag sets,
|
|
|
1006 so in this case no instantiators will be screened out.) If @var{exact-p}
|
|
|
1007 is non-@code{nil}, however, @var{tag-set} must be equal to an
|
|
|
1008 instantiator's tag set for the instantiator to be copied.
|
|
|
1009
|
|
|
1010 Optional argument @var{how-to-add} specifies what to do with existing
|
|
|
1011 specifications in @var{dest}. If nil, then whichever locales or locale
|
|
|
1012 types are copied will first be completely erased in @var{dest}.
|
|
|
1013 Otherwise, it is the same as in @code{add-spec-to-specifier}.
|
|
|
1014 @end defun
|
|
|
1015
|
|
|
1016 @defun remove-specifier specifier &optional locale tag-set exact-p
|
|
|
1017 This function removes specification(s) for @var{specifier}.
|
|
|
1018
|
|
|
1019 If @var{locale} is a particular locale (a buffer, window, frame, device,
|
|
|
1020 or the symbol @code{global}), the specification for that locale will be
|
|
|
1021 removed.
|
|
|
1022
|
|
|
1023 If instead, @var{locale} is a locale type (i.e. a symbol @code{buffer},
|
|
|
1024 @code{window}, @code{frame}, or @code{device}), the specifications for
|
|
|
1025 all locales of that type will be removed.
|
|
|
1026
|
|
|
1027 If @var{locale} is @code{nil} or the symbol @code{all}, all
|
|
|
1028 specifications will be removed.
|
|
|
1029
|
|
|
1030 @var{locale} can also be a list of locales, locale types, and/or
|
|
|
1031 @code{all}; this is equivalent to calling @code{remove-specifier} for
|
|
|
1032 each of the elements in the list.
|
|
|
1033
|
|
|
1034 Only instantiators where @var{tag-set} (a list of zero or more tags) is
|
|
|
1035 a subset of (or possibly equal to) the instantiator's tag set are
|
|
|
1036 removed. (The default value of @code{nil} is a subset of all tag sets,
|
|
|
1037 so in this case no instantiators will be screened out.) If @var{exact-p}
|
|
|
1038 is non-@code{nil}, however, @var{tag-set} must be equal to an
|
|
|
1039 instantiator's tag set for the instantiator to be removed.
|
|
|
1040 @end defun
|
|
|
1041
|
|
|
1042 @defun map-specifier specifier func &optional locale maparg
|
|
|
1043 This function applies @var{func} to the specification(s) for
|
|
|
1044 @var{locale} in @var{specifier}.
|
|
|
1045
|
|
|
1046 If @var{locale} is a locale, @var{func} will be called for that locale.
|
|
|
1047 If @var{locale} is a locale type, @var{func} will be mapped over all
|
|
|
1048 locales of that type. If @var{locale} is @code{nil} or the symbol
|
|
|
1049 @code{all}, @var{func} will be mapped over all locales in
|
|
|
1050 @var{specifier}.
|
|
|
1051
|
|
|
1052 @var{func} is called with four arguments: the @var{specifier}, the
|
|
|
1053 locale being mapped over, the inst-list for that locale, and the
|
|
|
1054 optional @var{maparg}. If any invocation of @var{func} returns
|
|
|
1055 non-@code{nil}, the mapping will stop and the returned value becomes the
|
|
|
1056 value returned from @code{map-specifier}. Otherwise,
|
|
|
1057 @code{map-specifier} returns @code{nil}.
|
|
|
1058 @end defun
|
|
|
1059
|
|
|
1060 @defun specifier-locale-type-from-locale locale
|
|
|
1061 Given a specifier @var{locale}, this function returns its type.
|
|
|
1062 @end defun
|
|
|
1063
|
