|
428
|
1 @c -*-texinfo-*-
|
|
|
2 @c This is part of the XEmacs Lisp Reference Manual.
|
|
|
3 @c Copyright (C) 1995, 1996 Ben Wing.
|
|
1882
|
4 @c Copyright (C) 2002, 2004 Free Software Foundation, Inc.
|
|
428
|
5 @c See the file lispref.texi for copying conditions.
|
|
|
6 @setfilename ../../info/specifiers.info
|
|
|
7 @node Specifiers, Faces and Window-System Objects, Extents, top
|
|
|
8 @chapter Specifiers
|
|
|
9 @cindex specifier
|
|
|
10
|
|
|
11 A specifier is an object used to keep track of a property whose value
|
|
1135
|
12 should vary according to @emph{display context}, a window, a frame, or
|
|
3674
|
13 device, or a Mule character set. The value of many built-in properties,
|
|
|
14 such as the font, foreground, background, and such properties of a face
|
|
|
15 and variables such as @code{modeline-shadow-thickness} and
|
|
1135
|
16 @code{top-toolbar-height}, is actually a specifier object. The
|
|
2953
|
17 specifier object, in turn, is ``instantiated'' in a particular situation
|
|
1135
|
18 to yield the real value of the property in the current context.
|
|
428
|
19
|
|
|
20 @defun specifierp object
|
|
|
21 This function returns non-@code{nil} if @var{object} is a specifier.
|
|
|
22 @end defun
|
|
|
23
|
|
|
24 @menu
|
|
440
|
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.
|
|
1135
|
29 * Simple Specifier Usage:: Getting started with specifiers.
|
|
440
|
30 * Specifiers In-Depth:: Gory details about specifier innards.
|
|
2953
|
31 * Specifier Instantiation:: Instantiation means obtaining the ``value'' of
|
|
440
|
32 a specifier in a particular context.
|
|
|
33 * Specifier Types:: Specifiers come in different flavors.
|
|
|
34 * Adding Specifications:: Specifications control a specifier's ``value''
|
|
|
35 by giving conditions under which a
|
|
|
36 particular value is valid.
|
|
|
37 * Retrieving Specifications:: Querying a specifier's specifications.
|
|
|
38 * Specifier Tag Functions:: Working with specifier tags.
|
|
2953
|
39 * Specifier Instantiation Functions::
|
|
|
40 Functions to instantiate a specifier.
|
|
1869
|
41 * Specifier Examples:: Making all this stuff clearer.
|
|
440
|
42 * Creating Specifiers:: Creating specifiers for your own use.
|
|
428
|
43 * Specifier Validation Functions::
|
|
440
|
44 Validating the components of a specifier.
|
|
428
|
45 * Other Specification Functions::
|
|
440
|
46 Other ways of working with specifications.
|
|
2028
|
47 * Specifier Compatibility Notes::
|
|
|
48 Backward compatibility and GNU Emacs.
|
|
428
|
49 @end menu
|
|
|
50
|
|
|
51 @node Introduction to Specifiers
|
|
|
52 @section Introduction to Specifiers
|
|
|
53
|
|
1135
|
54 Perhaps the most useful way to explain specifiers is via an analogy.
|
|
|
55 Emacs Lisp programmers are used to @emph{buffer-local variables}
|
|
1138
|
56 @ref{Buffer-Local Variables}. For example, the variable
|
|
428
|
57 @code{modeline-format}, which controls the format of the modeline, can
|
|
|
58 have different values depending on the particular buffer being edited.
|
|
|
59 The variable has a default value which most modes will use, but a
|
|
1138
|
60 specialized package such as Calendar might change the variable so as to
|
|
|
61 tailor the modeline to its own purposes. Other variables are perhaps
|
|
|
62 best thought of as ``mode local,'' such as font-lock keywords, but they
|
|
|
63 are implemented as buffer locals.
|
|
428
|
64
|
|
|
65 Other properties (such as those that can be changed by the
|
|
|
66 @code{modify-frame-parameters} function, for example the color of the
|
|
|
67 text cursor) can have frame-local values, although it might also make
|
|
|
68 sense for them to have buffer-local values. In other cases, you might
|
|
|
69 want the property to vary depending on the particular window within the
|
|
|
70 frame that applies (e.g. the top or bottom window in a split frame), the
|
|
|
71 device type that that frame appears on (X or tty), etc. Perhaps you can
|
|
|
72 envision some more complicated scenario where you want a particular
|
|
|
73 value in a specified buffer, another value in all other buffers
|
|
|
74 displayed on a particular frame, another value in all other buffers
|
|
|
75 displayed in all other frames on any mono (two-color, e.g. black and
|
|
|
76 white only) displays, and a default value in all other circumstances.
|
|
|
77
|
|
1135
|
78 Specifiers generalize both buffer- and frame-local properties.
|
|
|
79 Specifiers vary according to the @emph{display} context. Font-lock
|
|
|
80 keywords in a buffer will be the same no matter which window the
|
|
|
81 buffer is displayed in, but windows on TTY devices will simply not be
|
|
|
82 capable of the flexibility that windows on modern GUI devices are.
|
|
1875
|
83 Specifiers provide a way for the programmer to @emph{declare} that an
|
|
1135
|
84 emphasized text should be italic on GUI devices and inverse video on
|
|
|
85 TTYs. They also provide a way for the programmer to declare
|
|
|
86 fallbacks, so that a color specified as ``chartreuse'' where possible
|
|
|
87 can fall back to ``yellow'' on devices where only ANSI (4-bit) color
|
|
|
88 is available. The complex calculations and device querying are
|
|
|
89 transparent to both user and programmer. You ask for what you want;
|
|
|
90 it's up to XEmacs to provide it, or a reasonable approximation.
|
|
|
91
|
|
2953
|
92 We call such a declaration a @dfn{specification}. A
|
|
|
93 @dfn{specification} applies in a particular @dfn{locale}, which is a
|
|
|
94 window, buffer, frame, device, or the global locale. The value part
|
|
|
95 of the specification is called an @dfn{instantiator}. The process of
|
|
|
96 determining the value in a particular context, or @dfn{domain}, is
|
|
|
97 called @dfn{instantiation}. A domain is a window, frame, or device.
|
|
1135
|
98
|
|
|
99 The difference between @dfn{locale} and @dfn{domain} is somewhat subtle.
|
|
|
100 You may think of a locale as a class of domains, which may span
|
|
|
101 different devices. Since the specification is abstract (a Lisp form),
|
|
|
102 you can state it without reference to a device. On the other hand, when
|
|
|
103 you instantiate a specification, you must know the type of the device.
|
|
1875
|
104 It is useless to specify that ``blue means emphasis'' on a monochrome
|
|
1135
|
105 device. Thus instantiation requires specification of the device on
|
|
|
106 which it will be rendered.
|
|
|
107
|
|
|
108 Thus a @dfn{specifier} allows a great deal of flexibility in
|
|
|
109 controlling exactly what value a property has in which circumstances.
|
|
1875
|
110 Specifiers are most commonly used for display properties, such as an image or
|
|
1135
|
111 the foreground color of a face. As a simple example, you can specify
|
|
|
112 that the foreground of the default face be
|
|
428
|
113
|
|
|
114 @itemize @bullet
|
|
|
115 @item
|
|
|
116 blue for a particular buffer
|
|
|
117 @item
|
|
|
118 green for all other buffers
|
|
|
119 @end itemize
|
|
|
120
|
|
|
121 As a more complicated example, you could specify that the foreground of
|
|
|
122 the default face be
|
|
|
123
|
|
|
124 @itemize @bullet
|
|
|
125 @item
|
|
|
126 forest green for all buffers displayed in a particular Emacs window, or
|
|
|
127 green if the X server doesn't recognize the color @samp{forest green}
|
|
|
128 @item
|
|
|
129 blue for all buffers displayed in a particular frame
|
|
|
130 @item
|
|
|
131 red for all other buffers displayed on a color device
|
|
|
132 @item
|
|
|
133 white for all other buffers
|
|
|
134 @end itemize
|
|
|
135
|
|
1135
|
136 @node Simple Specifier Usage
|
|
|
137 @section Simple Specifier Usage
|
|
|
138 @cindex specifier examples
|
|
|
139 @cindex examples, specifier
|
|
|
140 @cindex adding a button to a toolbar
|
|
|
141 @cindex toolbar button, adding
|
|
|
142
|
|
|
143 A useful specifier application is adding a button to a toolbar. XEmacs
|
|
|
144 provides several toolbars, one along each edge of the frame. Normally
|
|
|
145 only one is used at a time, the default. The default toolbar is
|
|
1875
|
146 actually a specifier object which is the value of
|
|
|
147 @code{default-toolbar}. @xref{Toolbar Intro}.
|
|
1135
|
148
|
|
|
149 The specification of a toolbar is simple: it is a list of buttons.
|
|
|
150 Each button is a vector with four elements: an icon, a command, the
|
|
|
151 enabled flag, and a help string. Let's retrieve the instance of the
|
|
|
152 toolbar you see in the selected frame.
|
|
|
153
|
|
|
154 @example
|
|
|
155 (specifier-instance default-toolbar)
|
|
|
156 @end example
|
|
|
157
|
|
|
158 The value returned is, as promised, a list of vectors. Now let's build
|
|
|
159 up a button, and add it to the toolbar. Our button will invoke the last
|
|
|
160 defined keyboard macro. This is an alternative to
|
|
|
161 @code{name-last-kbd-macro} for creating a persistent macro, rather than
|
|
|
162 an alias for @kbd{C-x e}.
|
|
|
163
|
|
|
164 A toolbar button icon can be quite sophisticated, with different images
|
|
|
165 for button up, button down, and disabled states, and a similar set with
|
|
|
166 captions. We'll use a very simple icon, but we have to jump through a
|
|
|
167 few non-obvious hoops designed to support the sophisticated applications.
|
|
|
168 The rest of the button descriptor is straightforward.
|
|
|
169
|
|
|
170 @example
|
|
|
171 (setq toolbar-my-kbd-macro-button
|
|
|
172 `[ (list (make-glyph "MyKbdMac"))
|
|
|
173 (lambda () (interactive) (execute-kbd-macro ,last-kbd-macro))
|
|
|
174 t
|
|
|
175 "Execute a previously defined keyboard macro." ])
|
|
|
176
|
|
|
177 (set-specifier default-toolbar
|
|
|
178 (cons toolbar-my-kbd-macro-button
|
|
|
179 (specifier-specs default-toolbar 'global))
|
|
|
180 'global)
|
|
|
181 @end example
|
|
|
182
|
|
|
183 To remove the button, just substitute the function @code{delete} for the
|
|
|
184 @code{cons} above.
|
|
|
185
|
|
|
186 What is the difference between @code{specifier-instance}, which we used
|
|
|
187 in the example of retrieving the toolbar descriptor, and
|
|
|
188 @code{specifier-specs}, which was used in the toolbar manipulating code?
|
|
|
189 @code{specifier-specs} retrieves a copy of the instantiator, which is
|
|
|
190 abstract and does not depend on context. @code{specifier-instance}, on
|
|
|
191 the other hand, actually instantiates the specification, and returns the
|
|
|
192 result for the given context. Another way to express this is:
|
|
|
193 @code{specifier-specs} takes a @emph{locale} as an argument, while
|
|
|
194 @code{specifier-instance} takes a @emph{domain}. The reason for
|
|
|
195 providing @code{specifier-instance} is that sometimes you wish to see
|
|
|
196 the object that XEmacs will actually use. @code{specifier-specs}, on
|
|
|
197 the other hand, shows you what the programmer (or user) requested. When
|
|
|
198 a program manipulates specifications, clearly it's the latter that is
|
|
|
199 desirable.
|
|
|
200
|
|
|
201 In the case of the toolbar descriptor, it turns out that these are the
|
|
2953
|
202 same: the instantiation process is trivial. However, many specifications
|
|
|
203 have non-trivial instantiation. Compare the results of the following forms
|
|
1135
|
204 on my system. (The @samp{(cdr (first ...))} form is due to my use of
|
|
|
205 Mule. On non-Mule XEmacsen, just use @code{specifier-specs}.)
|
|
|
206
|
|
|
207 @example
|
|
|
208 (cdr (first (specifier-specs (face-font 'default) 'global)))
|
|
|
209 => "-*--14-*jisx0208*-0"
|
|
|
210
|
|
|
211 (specifier-instance (face-font 'default))
|
|
|
212 #<font-instance "-*--14-*jisx0208*-0" on #<x-device on ":0.0" 0x970> 0xe0028b 0x176b>
|
|
|
213 @end example
|
|
|
214
|
|
|
215 In this case, @code{specifier-instance} returns an opaque object;
|
|
3674
|
216 Lisp programs can't work on it, they can only pass it around. Worse, in some
|
|
1135
|
217 environments the instantiation will fail, resulting in a different value
|
|
|
218 (when another instantiation succeeds), or worse yet, an error, if all
|
|
2953
|
219 attempts to instantiate the specifier fail. @code{specifier-instance} is
|
|
1135
|
220 context-dependent, even for the exact same specification.
|
|
|
221 @code{specifier-specs} is deterministic, and only depends on the
|
|
|
222 specifications.
|
|
|
223
|
|
|
224 Note that in the toolbar-changing code we operate in the global locale.
|
|
|
225 This means that narrower locales, if they have specifications, will
|
|
2953
|
226 shadow our changes. (Specifier instantiation does not merge
|
|
1135
|
227 specifications. It selects the "highest-priority successful
|
|
2953
|
228 specification" and instantiates that.)
|
|
1135
|
229
|
|
|
230 In fact, in our example, it seems pretty likely that different buffers
|
|
|
231 @emph{should} have different buttons. (The icon can be the same, but
|
|
|
232 the keyboard macro you create in a Dired buffer is highly unlikely to be
|
|
|
233 useful in a LaTeX buffer!) Here's one way to implement this:
|
|
|
234
|
|
|
235 @example
|
|
|
236 (setq toolbar-my-kbd-macro-button
|
|
|
237 `[ (list (make-glyph "MyKbdMac"))
|
|
|
238 (lambda () (interactive) (execute-kbd-macro ,last-kbd-macro))
|
|
|
239 t
|
|
|
240 "Execute a previously defined keyboard macro." ])
|
|
|
241
|
|
|
242 (set-specifier default-toolbar
|
|
|
243 (cons toolbar-my-kbd-macro-button
|
|
|
244 (cond ((specifier-specs default-toolbar
|
|
|
245 (current-buffer)))
|
|
|
246 ((specifier-specs default-toolbar
|
|
|
247 'global)))
|
|
|
248 (current-buffer))
|
|
|
249 @end example
|
|
|
250
|
|
|
251 Finally, a cautionary note: the use of @code{specifier-specs} in the
|
|
|
252 code above is for expository purposes. Don't use it in production code.
|
|
|
253 In fact, the @code{set-specifier} form above is likely to fail
|
|
|
254 occasionally, because you can add many specifications for the same
|
|
|
255 locale.
|
|
|
256
|
|
|
257 In these cases, @code{specifier-specs} will return a list. A further
|
|
|
258 refinement is that a specification may be associated with a set of
|
|
|
259 @dfn{specifier tags}. If the list of specifier tags is non-nil, then
|
|
|
260 @code{specifier-specs} will return a cons of the tag set and the
|
|
|
261 instantiator. Evidently @code{specifier-specs} is a bit unreliable.
|
|
|
262 (For toolbars, the code above should work 99% of the time, because
|
|
|
263 toolbars are rarely changed. Since instantiation is trivial, multiple
|
|
|
264 specs are not useful---the first one always succeeds.)
|
|
|
265
|
|
|
266 In fact, @code{specifier-specs} is intended to be used to display specs
|
|
1138
|
267 to humans with a minimum of clutter. The robust way to access
|
|
|
268 specifications is via @code{specifier-spec-list}. @xref{Adding
|
|
|
269 Specifications}, for the definition of @dfn{spec-list}. @xref{Retrieving
|
|
|
270 Specifications}, for documentation of @code{specifier-specs} and
|
|
|
271 @code{specifier-spec-list}. To get the desired effect, replace the form
|
|
|
272 @code{(specifier-spec default-toolbar 'global)} with
|
|
1135
|
273
|
|
|
274 @example
|
|
|
275 (cdr (second (first (specifier-spec-list default-toolbar 'global))))
|
|
|
276 @end example
|
|
|
277
|
|
|
278 (It should be obvious why the example uses the lazy unreliable method!)
|
|
|
279
|
|
428
|
280 @node Specifiers In-Depth
|
|
|
281 @section In-Depth Overview of a Specifier
|
|
|
282 @cindex specification (in a specifier)
|
|
|
283 @cindex domain (in a specifier)
|
|
|
284 @cindex locale (in a specifier)
|
|
|
285 @cindex instantiator (in a specifier)
|
|
2953
|
286 @cindex instantiation (in a specifier)
|
|
428
|
287 @cindex instance (in a specifier)
|
|
|
288 @cindex inst-list (in a specifier)
|
|
|
289 @cindex inst-pair (in a specifier)
|
|
|
290 @cindex tag (in a specifier)
|
|
|
291 @cindex tag set (in a specifier)
|
|
|
292 @cindex specifier, specification
|
|
|
293 @cindex specifier, domain
|
|
|
294 @cindex specifier, locale
|
|
|
295 @cindex specifier, instantiator
|
|
2953
|
296 @cindex specifier, instantiation
|
|
428
|
297 @cindex specifier, instance
|
|
|
298 @cindex specifier, inst-list
|
|
|
299 @cindex specifier, inst-pair
|
|
|
300 @cindex specifier, tag
|
|
|
301 @cindex specifier, tag set
|
|
|
302
|
|
1135
|
303 Having variables vary according the editing context is very useful, and
|
|
|
304 the buffer is the natural ``atomic'' unit of editing context. In a GUI
|
|
|
305 environment, it can be similarly useful to have variables whose values
|
|
|
306 vary according to display context. The atomic unit of display context
|
|
|
307 is the Emacs window. Buffers are cleanly grouped by modes, but windows
|
|
|
308 are not so easily pigeonholed. On the one hand, a window displays a
|
|
|
309 buffer, and thus one possible hierarchy is window, buffer, mode. On the
|
|
|
310 other, a window is a component of a frame. This generates the window,
|
|
|
311 frame, device hierarchy. Finally, there are objects such as toolbars
|
|
|
312 whose properties are described by specifiers. These do not fit
|
|
|
313 naturally into either hierarchy. This problem is as yet not cleanly
|
|
|
314 solved.
|
|
|
315
|
|
|
316 Another potential source of conceptual confusion is the instantiation
|
|
|
317 process. Instantiating a buffer-local variable is simple: at any given
|
|
|
318 point in time there is a current buffer, and its local values are used
|
|
|
319 and set whenever the variable is accessed, unless the programmer goes to
|
|
|
320 some special effort (uses @code{default-value} and @code{set-default}.
|
|
|
321 However, a specifier object encapsulates a set of @dfn{specifications},
|
|
|
322 each of which says what its value should be if a particular condition
|
|
|
323 applies. Several such conditions might apply simultaneously in a given
|
|
|
324 window.
|
|
|
325
|
|
428
|
326 For example, one specification might be ``The value should be
|
|
|
327 darkseagreen2 on X devices'' another might be ``The value should be blue
|
|
1135
|
328 in the *Help* buffer''. So what do we do for "the *Help* buffer on an X
|
|
|
329 device"? The answer is simple: give each type of locale a priority and
|
|
|
330 check them in priority order, returning the first instantiator that
|
|
|
331 successfully instantiates a value.
|
|
|
332
|
|
428
|
333 Given a specifier, a logical question is ``What is its value in a
|
|
|
334 particular situation?'' This involves looking through the specifications
|
|
|
335 to see which ones apply to this particular situation, and perhaps
|
|
|
336 preferring one over another if more than one applies. In specifier
|
|
|
337 terminology, a ``particular situation'' is called a @dfn{domain}, and
|
|
2953
|
338 determining its value in a particular domain is called @dfn{instantiation}.
|
|
428
|
339 Most of the time, a domain is identified by a particular window. For
|
|
|
340 example, if the redisplay engine is drawing text in the default face in
|
|
|
341 a particular window, it retrieves the specifier for the foreground color
|
|
2953
|
342 of the default face and @dfn{instantiates} it in the domain given by that
|
|
428
|
343 window; in other words, it asks the specifier, ``What is your value in
|
|
|
344 this window?''.
|
|
|
345
|
|
1135
|
346 Note that the redisplay example is in a sense canonical. That is,
|
|
|
347 specifiers are designed to present a uniform and @emph{efficient} API
|
|
|
348 to redisplay. It is the efficiency constraint that motivates the
|
|
|
349 introduction of specifier tags, and many restrictions on access (for
|
|
|
350 example, a buffer is not a domain, and you cannot instantiate a
|
|
|
351 specifier over a buffer).
|
|
|
352
|
|
428
|
353 More specifically, a specifier contains a set of @dfn{specifications},
|
|
|
354 each of which associates a @dfn{locale} (a window object, a buffer
|
|
|
355 object, a frame object, a device object, or the symbol @code{global})
|
|
|
356 with an @dfn{inst-list}, which is a list of one or more
|
|
|
357 @dfn{inst-pairs}. (For each possible locale, there can be at most one
|
|
|
358 specification containing that locale.) Each inst-pair is a cons of a
|
|
|
359 @dfn{tag set} (an unordered list of zero or more symbols, or @dfn{tags})
|
|
|
360 and an @dfn{instantiator} (the allowed form of this varies depending on
|
|
|
361 the type of specifier). In a given specification, there may be more
|
|
|
362 than one inst-pair with the same tag set; this is unlike for locales.
|
|
|
363
|
|
3674
|
364 The tag set is used to restrict the sorts of devices and character sets
|
|
|
365 over which the instantiator is valid and to uniquely identify
|
|
|
366 instantiators added by a particular application, so that different
|
|
|
367 applications can work on the same specifier and not interfere with each
|
|
|
368 other.
|
|
|
369
|
|
|
370 Each tag can have a @dfn{device-predicate} associated with it, which is
|
|
|
371 a function of one argument (a device) that specifies whether the tag
|
|
|
372 matches that particular device. (If a tag does not have a predicate, it
|
|
|
373 matches all devices.) All tags in a tag set must match a device for the
|
|
|
374 associated inst-pair to be instantiable over that device. (A null tag
|
|
|
375 set is perfectly valid, and trivially matches all devices.)
|
|
|
376
|
|
|
377 Each tag can also have a @dfn{charset-predicate} associated with it;
|
|
|
378 this is a function that takes one charset argument, and specifies
|
|
|
379 whether that tag matches that particular charset. When instantiating a
|
|
|
380 face over a given domain with a given charset, the
|
|
|
381 @code{charset-predicate} attribute of a tag is consulted@footnote{Not
|
|
|
382 quite the case; the result of the functions are pre-calculated and
|
|
|
383 cached whenever @code{define-specifier-tag} or @code{make-charset} is
|
|
|
384 called.} to decide whether this inst-pair matches the charset. If the
|
|
|
385 @code{charset-predicate} function of a tag is unspecified, that tag
|
|
|
386 defaults to matching all charsets.
|
|
428
|
387
|
|
3674
|
388 When @code{charset-predicate}s are being taken into account, the
|
|
|
389 matching process becomes two-stage. The first stage pays attention to
|
|
|
390 the charset predicates and the device predicates; only if there is no
|
|
|
391 match does the second stage take place, in which charset predicates are
|
|
|
392 ignored, and only the device predicates are relevant.
|
|
|
393
|
|
|
394 The valid device types in a build (normally @code{x}, @code{tty},
|
|
|
395 @code{stream}, @code{mswindows}, @code{msprinter}, and possibly
|
|
|
396 @code{carbon}) and device classes (normally @code{color},
|
|
|
397 @code{grayscale}, and @code{mono}) can always be used as tags, and match
|
|
|
398 devices of the associated type or class (@pxref{Consoles and Devices}).
|
|
|
399 There are also built-in tags related to font instantiation and
|
|
|
400 translation to Unicode; they are identical to the symbols used with
|
|
|
401 @code{specifier-matching-instance}, see the documentation of that
|
|
|
402 function for their names.
|
|
|
403
|
|
|
404 User-defined tags may be defined, with optional device and charset
|
|
|
405 predicates specified. An application can create its own tag, use it to
|
|
|
406 mark all its instantiators, and be fairly confident that it will not
|
|
|
407 interfere with other applications that modify the same
|
|
|
408 specifier---functions that add a specification to a specifier usually
|
|
|
409 only overwrite existing inst-pairs with the same tag set as was given,
|
|
|
410 and a particular tag or tag set can be specified when removing
|
|
|
411 instantiators.
|
|
428
|
412
|
|
2953
|
413 When a specifier is instantiated in a domain, both the locale and the tag
|
|
428
|
414 set can be viewed as specifying necessary conditions that must apply in
|
|
|
415 that domain for an instantiator to be considered as a possible result of
|
|
2953
|
416 the instantiation. More specific locales always override more general
|
|
428
|
417 locales (thus, there is no particular ordering of the specifications in
|
|
|
418 a specifier); however, the tag sets are simply considered in the order
|
|
|
419 that the inst-pairs occur in the specification's inst-list.
|
|
|
420
|
|
2953
|
421 Note also that the actual object that results from the instantiation
|
|
428
|
422 (called an @dfn{instance object}) may not be the same as the instantiator
|
|
|
423 from which it was derived. For some specifier types (such as integer
|
|
|
424 specifiers and boolean specifiers), the instantiator will be returned
|
|
|
425 directly as the instance object. For other types, however, this
|
|
|
426 is not the case. For example, for font specifiers, the instantiator
|
|
|
427 is a font-description string and the instance object is a font-instance
|
|
|
428 object, which describes how the font is displayed on a particular device.
|
|
|
429 A font-instance object encapsulates such things as the actual font name
|
|
|
430 used to display the font on that device (a font-description string
|
|
|
431 under X is usually a wildcard specification that may resolve to
|
|
|
432 different font names, with possibly different foundries, widths, etc.,
|
|
|
433 on different devices), the extra properties of that font on that
|
|
|
434 device, etc. Furthermore, this conversion (called @dfn{instantiation})
|
|
440
|
435 might fail---a font or color might not exist on a particular device,
|
|
428
|
436 for example.
|
|
|
437
|
|
2953
|
438 @node Specifier Instantiation
|
|
|
439 @section How a Specifier Is Instantiated
|
|
428
|
440 @cindex fallback (in a specifier)
|
|
|
441 @cindex specifier, fallback
|
|
|
442
|
|
2953
|
443 Instantiation of a specifier in a particular window domain proceeds as
|
|
428
|
444 follows:
|
|
|
445
|
|
|
446 @itemize @bullet
|
|
|
447 @item
|
|
|
448 First, XEmacs searches for a specification whose locale is the same as
|
|
|
449 the window. If that fails, the search is repeated, looking for a locale
|
|
|
450 that is the same as the window's buffer. If that fails, the search is
|
|
|
451 repeated using the window's frame, then using the device that frame is
|
|
|
452 on. Finally, the specification whose locale is the symbol @code{global}
|
|
|
453 (if there is such a specification) is considered.
|
|
|
454 @item
|
|
|
455 The inst-pairs contained in the specification that was found are
|
|
|
456 considered in their order in the inst-list, looking for one whose tag
|
|
|
457 set matches the device that is derived from the window domain. (The
|
|
|
458 tag set is an unordered list of zero or more tag symbols. For all
|
|
|
459 tags that have predicates associated with them, the predicate must
|
|
|
460 match the device.)
|
|
|
461 @item
|
|
|
462 If a matching tag set is found, the corresponding instantiator is passed
|
|
|
463 to the specifier's instantiation method, which is specific to the type
|
|
|
464 of the specifier. If it succeeds, the resulting instance object is
|
|
2953
|
465 returned as the result of the instantiation and the instantiation is done.
|
|
428
|
466 Otherwise, the operation continues, looking for another matching
|
|
|
467 inst-pair in the current specification.
|
|
|
468 @item
|
|
|
469 When there are no more inst-pairs to be considered in the current
|
|
|
470 specification, the search starts over, looking for another specification
|
|
|
471 as in the first step above.
|
|
|
472 @item
|
|
|
473 If all specifications are exhausted and no instance object can be
|
|
2953
|
474 derived, the instantiation fails. (Actually, this is not completely true.
|
|
428
|
475 Some specifier objects for built-in properties have a @dfn{fallback}
|
|
|
476 value, which is either an inst-list or another specifier object, that is
|
|
2953
|
477 consulted if the instantiation is about to fail. If it is an inst-list,
|
|
428
|
478 the searching proceeds using the inst-pairs in that list. If it is a
|
|
2953
|
479 specifier, the entire instantiation starts over using that specifier
|
|
428
|
480 instead of the given one. Fallback values are set by the C code and
|
|
|
481 cannot be modified, except perhaps indirectly, using any Lisp functions.
|
|
|
482 The purpose of them is to supply some values to make sure that
|
|
2953
|
483 instantiation of built-in properties can't fail and to implement some basic
|
|
428
|
484 specifier inheritance, such as the fact that faces inherit their
|
|
|
485 properties from the @code{default} face.)
|
|
|
486 @end itemize
|
|
|
487
|
|
2953
|
488 It is also possible to instantiate a specifier over a frame domain or
|
|
428
|
489 device domain instead of over a window domain. The C code, for example,
|
|
2953
|
490 instantiates the @code{top-toolbar-height} variable over a frame domain in
|
|
|
491 order to determine the height of a frame's top toolbar. Instantiation over
|
|
|
492 a frame or device is similar to instantiation over a window except that
|
|
428
|
493 specifications for locales that cannot be derived from the domain are
|
|
2953
|
494 ignored. Specifically, instantiation over a frame looks first for frame
|
|
|
495 locales, then device locales, then the @code{global} locale. Instantiation
|
|
428
|
496 over a device domain looks only for device locales and the @code{global}
|
|
|
497 locale.
|
|
|
498
|
|
2953
|
499 Note that specifiers are instantiated on @emph{every} redisplay. (This is
|
|
2141
|
500 the concept; of course the implementation keeps track of changes and
|
|
2953
|
501 doesn't reinstantiate unchanged specifiers.) That means that changes in
|
|
2141
|
502 specifiers controlling appearance are reflected immediately in the UI.
|
|
2953
|
503 Also, since specifiers are instantiated completely, removing a
|
|
2141
|
504 specification can be just as effective as adding one.
|
|
|
505
|
|
|
506 @emph{E.g.}, Giacomo Boffi wanted a modeline that indicates whether the
|
|
|
507 frame containing it is selected or not. The first proposed implementation
|
|
|
508 is natural in a world of ``local'' variables. The later implementations
|
|
|
509 apply the power of specifiers.
|
|
|
510
|
|
|
511 (The copyright notice and permission statement below apply to the code in
|
|
|
512 example format, up to the ``@code{;;; end of neon-modeline.el}''
|
|
|
513 comment.)
|
|
|
514
|
|
|
515 @example
|
|
|
516 ;;; neon-modeline.el
|
|
|
517
|
|
|
518 ;; Copyright (c) 2004 Stephen J. Turnbull <stephen@@xemacs.org>
|
|
|
519
|
|
|
520 ;; Based on a suggestion by Giacomo Boffi
|
|
|
521
|
|
|
522 ;; This code may be used and redistributed under the GNU GPL, v.2 or any
|
|
|
523 ;; later version as published by the FSF, or under the license used for
|
|
|
524 ;; XEmacs Texinfo manuals, at your option.
|
|
|
525 @end example
|
|
|
526
|
|
|
527 A few customizations:
|
|
|
528
|
|
|
529 @example
|
|
|
530 ;; Placate the specifier and Customize gods.
|
|
|
531
|
|
|
532 (unless (valid-specifier-tag-p 'modeline-background)
|
|
|
533 (define-specifier-tag 'modeline-background))
|
|
|
534
|
|
|
535 (defgroup lisp-demos nil "Demos for Lisp programming techniques.")
|
|
|
536
|
|
|
537 (defgroup neon-modeline nil "Neon modeline identifies selected frame."
|
|
|
538 :group 'lisp-demos)
|
|
|
539
|
|
|
540 (defcustom neon-modeline-selected-background "LemonChiffon"
|
|
|
541 "Background color for modeline in selected frames."
|
|
|
542 :type 'color
|
|
|
543 :group 'neon-modeline)
|
|
|
544
|
|
|
545 (defcustom neon-modeline-deselected-background "Wheat"
|
|
|
546 "Background color for modeline in unselected frames."
|
|
|
547 :type 'color
|
|
|
548 :group 'neon-modeline)
|
|
|
549
|
|
|
550 @end example
|
|
|
551
|
|
|
552 Our first try uses three functions, a setup and two hook functions.
|
|
|
553 Separate hooks are defined for entry into a frame and exit from it.
|
|
|
554 Since we're using hooks, it's a fairly natural approach: we operate on
|
|
|
555 the background on each event corresponding to an appearance change we
|
|
|
556 want to make. This doesn't depend on the specifier API, ``frame-local''
|
|
|
557 variables would serve as well.
|
|
|
558
|
|
|
559 @example
|
|
|
560 (defun select-modeline ()
|
|
|
561 (set-face-background 'modeline neon-modeline-selected-background
|
|
|
562 (selected-frame)))
|
|
|
563
|
|
|
564 (defun deselect-modeline ()
|
|
|
565 (set-face-background 'modeline neon-modeline-deselected-background
|
|
|
566 (selected-frame)))
|
|
|
567 @end example
|
|
|
568
|
|
|
569 Note that the initialization removes no specifications, and therefore is
|
|
|
570 not idempotent. Cruft will accumulate in the specifier if the
|
|
|
571 @samp{-setup} function is called repeatedly. This shouldn't cause a
|
|
|
572 performance problem; specifiers are quite efficient for their purpose.
|
|
|
573 But it's ugly, and wastes a small amount of space.
|
|
|
574
|
|
|
575 @example
|
|
|
576 (defun neon-modeline-setup ()
|
|
|
577 (interactive)
|
|
|
578 (set-face-background 'modeline neon-modeline-deselected-background)
|
|
|
579 ;; Add the distinguished background on pointer entry to the frame;
|
|
|
580 (add-hook 'select-frame-hook 'select-modeline)
|
|
|
581 ;; restore the ordinary background on pointer exit from the frame.
|
|
|
582 (add-hook 'deselect-frame-hook 'deselect-modeline)
|
|
|
583 @end example
|
|
|
584
|
|
|
585 This approach causes a decided flicker on Boffi's platform, because the
|
|
|
586 two hook functions are executed in response to separate GUI events.
|
|
|
587
|
|
|
588 The following code should be an improvement. First, the hook function.
|
|
|
589
|
|
|
590 @example
|
|
|
591 (defun neon-modeline-reselect ()
|
|
|
592 (set-face-background 'modeline neon-modeline-deselected-background
|
|
|
593 (selected-frame) '(modeline-background)
|
|
|
594 'remove-locale-type))
|
|
|
595 @end example
|
|
|
596
|
|
|
597 Only one event triggers the configuration change, which should reduce
|
|
|
598 flicker. Because this is implemented as a specifier, we can use the
|
|
|
599 specifier API to reset all frame-local specifications (the
|
|
|
600 @code{remove-locale-type} argument). This leaves the @code{global}
|
|
|
601 specification alone, but removes all existing frame-local
|
|
|
602 specifications. Then it adds the selected-frame background
|
|
|
603 specification for the newly selected frame. @emph{I.e.}, this
|
|
|
604 effectively implements a ``move specification from frame to frame''
|
|
|
605 operation.
|
|
|
606
|
|
|
607 Why does it give the desired result? By ensuring that only one frame
|
|
|
608 has the selected-frame modeline background. Frame-local specifications
|
|
|
609 have precedence over global ones, so when the modeline background is
|
|
|
610 instantiated in the selected frame, it matches the specification set up
|
|
|
611 for it and gets the right color. On the other hand, in any other frame,
|
|
|
612 it does not match the selected frame, so it falls through the
|
|
|
613 frame-local specifications and picks up the global specification. Again
|
|
|
614 we get the desired color, in this case for unselected frames.
|
|
|
615
|
|
|
616 Here the @code{modeline-background} tag is simply good practice
|
|
|
617 (identifying an application's specifications allows it to avoid
|
|
|
618 interfering with other applications, and other well-behaved applications
|
|
|
619 and Customize should not munge specifications with our tag on them).
|
|
|
620 However, an alternative implementation of this functionality would be
|
|
|
621
|
|
|
622 @example
|
|
|
623 (defun neon-modeline-reselect-2 ()
|
|
|
624 (set-face-background 'modeline neon-modeline-deselected-background
|
|
|
625 (selected-frame) '(modeline-background)
|
|
|
626 'remove-tag-set-prepend))
|
|
|
627 @end example
|
|
|
628
|
|
|
629 @code{neon-modeline-reselect} may be a preferable implementation here, if we
|
|
|
630 really want only one frame to have a local specification. The
|
|
|
631 @code{neon-modeline-reselect-2} style would be useful if we had groups of
|
|
|
632 frames which have @emph{different} modeline backgrounds when deselected.
|
|
|
633
|
|
|
634 Here's the initialization function, with different semantics from above.
|
|
|
635 Note that it is destructive, unless the user saves off the state of the
|
|
|
636 modeline face before invoking the function. This is only a problem if
|
|
|
637 you remove specifications and expect the older ones to persist. In this
|
|
|
638 example it should not be an issue. We use the customizations defined
|
|
|
639 above.
|
|
|
640
|
|
|
641 @example
|
|
|
642 (defun neon-modeline-modified-setup ()
|
|
|
643 (interactive)
|
|
|
644 (set-face-background 'modeline neon-modeline-selected-background
|
|
|
645 'global nil 'remove-all)
|
|
|
646 (add-hook 'select-frame-hook 'neon-modeline-reselect)
|
|
|
647
|
|
|
648 ;;; end of neon-modeline.el
|
|
|
649 @end example
|
|
|
650
|
|
|
651 Note the use of @code{'remove-all} to clear out stale specifications.
|
|
|
652 Thus it will be idempotent.
|
|
|
653
|
|
|
654
|
|
428
|
655 @node Specifier Types
|
|
|
656 @section Specifier Types
|
|
|
657
|
|
|
658 There are various different types of specifiers. The type of a
|
|
|
659 specifier controls what sorts of instantiators are valid, how an
|
|
|
660 instantiator is instantiated, etc. Here is a list of built-in specifier
|
|
|
661 types:
|
|
|
662
|
|
|
663 @table @code
|
|
|
664 @item boolean
|
|
|
665 The valid instantiators are the symbols @code{t} and @code{nil}.
|
|
|
666 Instance objects are the same as instantiators so no special
|
|
|
667 instantiation function is needed.
|
|
|
668
|
|
|
669 @item integer
|
|
|
670 The valid instantiators are integers. Instance objects are the same as
|
|
|
671 instantiators so no special instantiation function is needed.
|
|
|
672 @code{modeline-shadow-thickness} is an example of an integer specifier
|
|
|
673 (negative thicknesses indicate that the shadow is drawn recessed instead
|
|
|
674 of raised).
|
|
|
675
|
|
|
676 @item natnum
|
|
|
677 The valid instantiators are natnums (non-negative integers). Instance
|
|
|
678 objects are the same as instantiators so no special instantiation
|
|
|
679 function is needed. Natnum specifiers are used for dimension variables
|
|
|
680 such as @code{top-toolbar-height}.
|
|
|
681
|
|
|
682 @item generic
|
|
|
683 All Lisp objects are valid instantiators. Instance objects are the same
|
|
|
684 as instantiators so no special instantiation function is needed.
|
|
|
685
|
|
|
686 @item font
|
|
|
687 The valid instantiators are strings describing fonts or vectors
|
|
|
688 indicating inheritance from the font of some face. Instance objects are
|
|
|
689 font-instance objects, which are specific to a particular device. The
|
|
|
690 instantiation method for font specifiers can fail, unlike for integer,
|
|
|
691 natnum, boolean, and generic specifiers.
|
|
|
692
|
|
|
693 @item color
|
|
|
694 The valid instantiators are strings describing colors or vectors
|
|
|
695 indicating inheritance from the foreground or background of some face.
|
|
|
696 Instance objects are color-instance objects, which are specific to a
|
|
|
697 particular device. The instantiation method for color specifiers can fail,
|
|
|
698 as for font specifiers.
|
|
|
699
|
|
|
700 @item image
|
|
|
701 Images are perhaps the most complicated type of built-in specifier. The
|
|
|
702 valid instantiators are strings (a filename, inline data for a pixmap,
|
|
|
703 or text to be displayed in a text glyph) or vectors describing inline
|
|
|
704 data of various sorts or indicating inheritance from the
|
|
|
705 background-pixmap property of some face. Instance objects are either
|
|
|
706 strings (for text images), image-instance objects (for pixmap images),
|
|
|
707 or subwindow objects (for subwindow images). The instantiation method
|
|
|
708 for image specifiers can fail, as for font and color specifiers.
|
|
|
709
|
|
|
710 @item face-boolean
|
|
|
711 The valid instantiators are the symbols @code{t} and @code{nil} and
|
|
|
712 vectors indicating inheritance from a boolean property of some face.
|
|
|
713 Specifiers of this sort are used for all of the built-in boolean
|
|
|
714 properties of faces. Instance objects are either the symbol @code{t}
|
|
|
715 or the symbol @code{nil}.
|
|
|
716
|
|
|
717 @item toolbar
|
|
|
718 The valid instantiators are toolbar descriptors, which are lists
|
|
|
719 of toolbar-button descriptors (each of which is a vector of two
|
|
|
720 or four elements). @xref{Toolbar}, for more information.
|
|
|
721 @end table
|
|
|
722
|
|
|
723 Color and font instance objects can also be used in turn as
|
|
|
724 instantiators for a new color or font instance object. Since these
|
|
|
725 instance objects are device-specific, the instantiator can be used
|
|
|
726 directly as the new instance object, but only if they are of the same
|
|
|
727 device. If the devices differ, the base color or font of the
|
|
|
728 instantiating object is effectively used instead as the instantiator.
|
|
|
729
|
|
|
730 @xref{Faces and Window-System Objects}, for more information on fonts,
|
|
|
731 colors, and face-boolean specifiers. @xref{Glyphs}, for more information
|
|
|
732 about image specifiers. @xref{Toolbar}, for more information on toolbar
|
|
|
733 specifiers.
|
|
|
734
|
|
|
735 @defun specifier-type specifier
|
|
|
736 This function returns the type of @var{specifier}. The returned value
|
|
|
737 will be a symbol: one of @code{integer}, @code{boolean}, etc., as
|
|
|
738 listed in the above table.
|
|
|
739 @end defun
|
|
|
740
|
|
|
741 Functions are also provided to query whether an object is a particular
|
|
|
742 kind of specifier:
|
|
|
743
|
|
|
744 @defun boolean-specifier-p object
|
|
|
745 This function returns non-@code{nil} if @var{object} is a boolean
|
|
|
746 specifier.
|
|
|
747 @end defun
|
|
|
748
|
|
|
749 @defun integer-specifier-p object
|
|
|
750 This function returns non-@code{nil} if @var{object} is an integer
|
|
|
751 specifier.
|
|
|
752 @end defun
|
|
|
753
|
|
|
754 @defun natnum-specifier-p object
|
|
|
755 This function returns non-@code{nil} if @var{object} is a natnum
|
|
|
756 specifier.
|
|
|
757 @end defun
|
|
|
758
|
|
|
759 @defun generic-specifier-p object
|
|
|
760 This function returns non-@code{nil} if @var{object} is a generic
|
|
|
761 specifier.
|
|
|
762 @end defun
|
|
|
763
|
|
|
764 @defun face-boolean-specifier-p object
|
|
|
765 This function returns non-@code{nil} if @var{object} is a face-boolean
|
|
|
766 specifier.
|
|
|
767 @end defun
|
|
|
768
|
|
|
769 @defun toolbar-specifier-p object
|
|
|
770 This function returns non-@code{nil} if @var{object} is a toolbar
|
|
|
771 specifier.
|
|
|
772 @end defun
|
|
|
773
|
|
|
774 @defun font-specifier-p object
|
|
|
775 This function returns non-@code{nil} if @var{object} is a font
|
|
|
776 specifier.
|
|
|
777 @end defun
|
|
|
778
|
|
|
779 @defun color-specifier-p object
|
|
|
780 This function returns non-@code{nil} if @var{object} is a color
|
|
|
781 specifier.
|
|
|
782 @end defun
|
|
|
783
|
|
|
784 @defun image-specifier-p object
|
|
|
785 This function returns non-@code{nil} if @var{object} is an image
|
|
|
786 specifier.
|
|
|
787 @end defun
|
|
|
788
|
|
|
789 @node Adding Specifications
|
|
|
790 @section Adding specifications to a Specifier
|
|
|
791
|
|
|
792 @defun add-spec-to-specifier specifier instantiator &optional locale tag-set how-to-add
|
|
|
793 This function adds a specification to @var{specifier}. The
|
|
|
794 specification maps from @var{locale} (which should be a window, buffer,
|
|
|
795 frame, device, or the symbol @code{global}, and defaults to
|
|
|
796 @code{global}) to @var{instantiator}, whose allowed values depend on the
|
|
|
797 type of the specifier. Optional argument @var{tag-set} limits the
|
|
|
798 instantiator to apply only to the specified tag set, which should be a
|
|
|
799 list of tags all of which must match the device being instantiated over
|
|
|
800 (tags are a device type, a device class, or tags defined with
|
|
|
801 @code{define-specifier-tag}). Specifying a single symbol for
|
|
|
802 @var{tag-set} is equivalent to specifying a one-element list containing
|
|
|
803 that symbol. Optional argument @var{how-to-add} specifies what to do if
|
|
|
804 there are already specifications in the specifier. It should be one of
|
|
|
805
|
|
|
806 @table @code
|
|
|
807 @item prepend
|
|
|
808 Put at the beginning of the current list of instantiators for @var{locale}.
|
|
|
809 @item append
|
|
|
810 Add to the end of the current list of instantiators for @var{locale}.
|
|
|
811 @item remove-tag-set-prepend
|
|
|
812 This is the default. Remove any existing instantiators whose tag set is
|
|
|
813 the same as @var{tag-set}; then put the new instantiator at the
|
|
|
814 beginning of the current list.
|
|
|
815 @item remove-tag-set-append
|
|
|
816 Remove any existing instantiators whose tag set is the same as
|
|
|
817 @var{tag-set}; then put the new instantiator at the end of the current
|
|
|
818 list.
|
|
|
819 @item remove-locale
|
|
|
820 Remove all previous instantiators for this locale before adding the new
|
|
|
821 spec.
|
|
|
822 @item remove-locale-type
|
|
|
823 Remove all specifications for all locales of the same type as
|
|
|
824 @var{locale} (this includes @var{locale} itself) before adding the new
|
|
|
825 spec.
|
|
|
826 @item remove-all
|
|
|
827 Remove all specifications from the specifier before adding the new spec.
|
|
|
828 @end table
|
|
|
829
|
|
|
830 @code{remove-tag-set-prepend} is the default.
|
|
|
831
|
|
|
832 You can retrieve the specifications for a particular locale or locale type
|
|
|
833 with the function @code{specifier-spec-list} or @code{specifier-specs}.
|
|
|
834 @end defun
|
|
|
835
|
|
|
836 @defun add-spec-list-to-specifier specifier spec-list &optional how-to-add
|
|
|
837 This function adds a @dfn{spec-list} (a list of specifications) to
|
|
|
838 @var{specifier}. The format of a spec-list is
|
|
|
839
|
|
|
840 @example
|
|
|
841 @code{((@var{locale} (@var{tag-set} . @var{instantiator}) ...) ...)}
|
|
|
842 @end example
|
|
|
843
|
|
|
844 where
|
|
|
845
|
|
|
846 @itemize @bullet
|
|
|
847 @item
|
|
|
848 @var{locale} := a window, a buffer, a frame, a device, or @code{global}
|
|
|
849 @item
|
|
|
850 @var{tag-set} := an unordered list of zero or more @var{tags}, each of
|
|
|
851 which is a symbol
|
|
|
852 @item
|
|
|
853 @var{tag} := a device class (@pxref{Consoles and Devices}), a device type,
|
|
|
854 or a tag defined with @code{define-specifier-tag}
|
|
|
855 @item
|
|
|
856 @var{instantiator} := format determined by the type of specifier
|
|
|
857 @end itemize
|
|
|
858
|
|
|
859 The pair @code{(@var{tag-set} . @var{instantiator})} is called an
|
|
|
860 @dfn{inst-pair}. A list of inst-pairs is called an @dfn{inst-list}.
|
|
|
861 The pair @code{(@var{locale} . @var{inst-list})} is called a
|
|
|
862 @dfn{specification}. A spec-list, then, can be viewed as a list of
|
|
|
863 specifications.
|
|
|
864
|
|
|
865 @var{how-to-add} specifies how to combine the new specifications with
|
|
|
866 the existing ones, and has the same semantics as for
|
|
|
867 @code{add-spec-to-specifier}.
|
|
|
868
|
|
1875
|
869 The higher-level function @code{set-specifier} is often
|
|
|
870 more convenient because it allows abbreviations of spec-lists to be used
|
|
|
871 instead of the heavily nested canonical syntax. However, one should
|
|
|
872 take great care in using them with specifiers types which can have lists
|
|
|
873 as instantiators, such as toolbar specifiers and generic specifiers. In
|
|
|
874 those cases it's probably best to use @code{add-spec-to-specifier} or
|
|
|
875 @code{add-spec-list-to-specifier}.
|
|
428
|
876 @end defun
|
|
|
877
|
|
444
|
878 @defspec let-specifier specifier-list &rest body
|
|
428
|
879 This special form temporarily adds specifications to specifiers,
|
|
|
880 evaluates forms in @var{body} and restores the specifiers to their
|
|
|
881 previous states. The specifiers and their temporary specifications are
|
|
|
882 listed in @var{specifier-list}.
|
|
|
883
|
|
|
884 The format of @var{specifier-list} is
|
|
|
885
|
|
|
886 @example
|
|
|
887 ((@var{specifier} @var{value} &optional @var{locale} @var{tag-set} @var{how-to-add}) ...)
|
|
|
888 @end example
|
|
|
889
|
|
|
890 @var{specifier} is the specifier to be temporarily modified.
|
|
|
891 @var{value} is the instantiator to be temporarily added to specifier in
|
|
|
892 @var{locale}. @var{locale}, @var{tag-set} and @var{how-to-add} have the
|
|
|
893 same meaning as in @code{add-spec-to-specifier}.
|
|
|
894
|
|
|
895 This special form is implemented as a macro; the code resulting from
|
|
|
896 macro expansion will add specifications to specifiers using
|
|
|
897 @code{add-spec-to-specifier}. After forms in @var{body} are evaluated,
|
|
|
898 the temporary specifications are removed and old specifier spec-lists
|
|
|
899 are restored.
|
|
|
900
|
|
|
901 @var{locale}, @var{tag-set} and @var{how-to-add} may be omitted, and
|
|
|
902 default to @code{nil}. The value of the last form in @var{body} is
|
|
|
903 returned.
|
|
|
904
|
|
|
905 NOTE: If you want the specifier's instance to change in all
|
|
|
906 circumstances, use @code{(selected-window)} as the @var{locale}. If
|
|
|
907 @var{locale} is @code{nil} or omitted, it defaults to @code{global}.
|
|
|
908
|
|
|
909 The following example removes the 3D modeline effect in the currently
|
|
|
910 selected window for the duration of a second:
|
|
|
911
|
|
|
912 @example
|
|
|
913 (let-specifier ((modeline-shadow-thickness 0 (selected-window)))
|
|
|
914 (sit-for 1))
|
|
|
915 @end example
|
|
444
|
916 @end defspec
|
|
428
|
917
|
|
444
|
918 @defun set-specifier specifier value &optional locale tag-set how-to-add
|
|
428
|
919 This function adds some specifications to @var{specifier}. @var{value}
|
|
|
920 can be a single instantiator or tagged instantiator (added as a global
|
|
|
921 specification), a list of tagged and/or untagged instantiators (added as
|
|
|
922 a global specification), a cons of a locale and instantiator or locale
|
|
|
923 and instantiator list, a list of such conses, or nearly any other
|
|
|
924 reasonable form. More specifically, @var{value} can be anything
|
|
1875
|
925 accepted by @code{canonicalize-spec-list} (described below).
|
|
428
|
926
|
|
444
|
927 @var{locale}, @var{tag-set}, and @var{how-to-add} are the same as in
|
|
|
928 @code{add-spec-to-specifier}.
|
|
428
|
929
|
|
|
930 Note that @code{set-specifier} is exactly complementary to
|
|
|
931 @code{specifier-specs} except in the case where @var{specifier} has no
|
|
|
932 specs at all in it but @code{nil} is a valid instantiator (in that case,
|
|
|
933 @code{specifier-specs} will return @code{nil} (meaning no specs) and
|
|
|
934 @code{set-specifier} will interpret the @code{nil} as meaning ``I'm
|
|
|
935 adding a global instantiator and its value is @code{nil}''), or in
|
|
|
936 strange cases where there is an ambiguity between a spec-list and an
|
|
|
937 inst-list, etc. (The built-in specifier types are designed in such a way
|
|
1875
|
938 as to avoid any such ambiguities.) For robust code,
|
|
|
939 @code{set-specifier} should probably be avoided for specifier types
|
|
|
940 which accept lists as instantiators (currently toolbar specifiers and
|
|
|
941 generic specifiers).
|
|
428
|
942
|
|
|
943 If you want to work with spec-lists, you should probably not use these
|
|
|
944 functions, but should use the lower-level functions
|
|
|
945 @code{specifier-spec-list} and @code{add-spec-list-to-specifier}. These
|
|
|
946 functions always work with fully-qualified spec-lists; thus, there is no
|
|
|
947 ambiguity.
|
|
|
948 @end defun
|
|
|
949
|
|
|
950 @defun canonicalize-inst-pair inst-pair specifier-type &optional noerror
|
|
|
951 This function canonicalizes the given @var{inst-pair}.
|
|
|
952
|
|
|
953 @var{specifier-type} specifies the type of specifier that this
|
|
|
954 @var{spec-list} will be used for.
|
|
|
955
|
|
|
956 Canonicalizing means converting to the full form for an inst-pair, i.e.
|
|
|
957 @code{(@var{tag-set} . @var{instantiator})}. A single, untagged
|
|
|
958 instantiator is given a tag set of @code{nil} (the empty set), and a
|
|
|
959 single tag is converted into a tag set consisting only of that tag.
|
|
|
960
|
|
|
961 If @var{noerror} is non-@code{nil}, signal an error if the inst-pair is
|
|
|
962 invalid; otherwise return @code{t}.
|
|
|
963 @end defun
|
|
|
964
|
|
|
965 @defun canonicalize-inst-list inst-list specifier-type &optional noerror
|
|
|
966 This function canonicalizes the given @var{inst-list} (a list of
|
|
|
967 inst-pairs).
|
|
|
968
|
|
|
969 @var{specifier-type} specifies the type of specifier that this @var{inst-list}
|
|
|
970 will be used for.
|
|
|
971
|
|
|
972 Canonicalizing means converting to the full form for an inst-list, i.e.
|
|
|
973 @code{((@var{tag-set} . @var{instantiator}) ...)}. This function
|
|
|
974 accepts a single inst-pair or any abbreviation thereof or a list of
|
|
|
975 (possibly abbreviated) inst-pairs. (See @code{canonicalize-inst-pair}.)
|
|
|
976
|
|
|
977 If @var{noerror} is non-@code{nil}, signal an error if the inst-list is
|
|
|
978 invalid; otherwise return @code{t}.
|
|
|
979 @end defun
|
|
|
980
|
|
|
981 @defun canonicalize-spec spec specifier-type &optional noerror
|
|
|
982 This function canonicalizes the given @var{spec} (a specification).
|
|
|
983
|
|
|
984 @var{specifier-type} specifies the type of specifier that this
|
|
|
985 @var{spec-list} will be used for.
|
|
|
986
|
|
|
987 Canonicalizing means converting to the full form for a spec, i.e.
|
|
|
988 @code{(@var{locale} (@var{tag-set} . @var{instantiator}) ...)}. This
|
|
|
989 function accepts a possibly abbreviated inst-list or a cons of a locale
|
|
|
990 and a possibly abbreviated inst-list. (See
|
|
|
991 @code{canonicalize-inst-list}.)
|
|
|
992
|
|
|
993 If @var{noerror} is @code{nil}, signal an error if the specification is
|
|
|
994 invalid; otherwise return @code{t}.
|
|
|
995 @end defun
|
|
|
996
|
|
|
997 @defun canonicalize-spec-list spec-list specifier-type &optional noerror
|
|
|
998 This function canonicalizes the given @var{spec-list} (a list of
|
|
|
999 specifications).
|
|
|
1000
|
|
|
1001 @var{specifier-type} specifies the type of specifier that this
|
|
|
1002 @var{spec-list} will be used for.
|
|
|
1003
|
|
1875
|
1004 If @var{noerror} is @code{nil}, signal an error if the spec-list is
|
|
|
1005 invalid; otherwise return @code{t} for an invalid spec-list. (Note that
|
|
|
1006 this cannot be confused with a canonical spec-list.)
|
|
|
1007
|
|
428
|
1008 Canonicalizing means converting to the full form for a spec-list, i.e.
|
|
|
1009 @code{((@var{locale} (@var{tag-set} . @var{instantiator}) ...) ...)}.
|
|
|
1010 This function accepts a possibly abbreviated specification or a list of
|
|
|
1011 such things. (See @code{canonicalize-spec}.) This is the function used
|
|
|
1012 to convert spec-lists accepted by @code{set-specifier} and such into a
|
|
|
1013 form suitable for @code{add-spec-list-to-specifier}.
|
|
|
1014
|
|
|
1015 This function tries extremely hard to resolve any ambiguities,
|
|
|
1016 and the built-in specifier types (font, image, toolbar, etc.) are
|
|
|
1017 designed so that there won't be any ambiguities.
|
|
|
1018
|
|
1875
|
1019 The canonicalization algorithm is as follows:
|
|
|
1020
|
|
|
1021 @enumerate
|
|
|
1022 @item
|
|
|
1023 Attempt to parse @var{spec-list} as a single, possibly abbreviated,
|
|
|
1024 specification.
|
|
|
1025 @item
|
|
|
1026 If that fails, attempt to parse @var{spec-list} as a list of (abbreviated)
|
|
|
1027 specifications.
|
|
|
1028 @item
|
|
|
1029 If that fails, @var{spec-list} is invalid.
|
|
|
1030 @end enumerate
|
|
|
1031
|
|
|
1032 A possibly abbreviated specification @var{spec} is parsed by
|
|
|
1033
|
|
|
1034 @enumerate
|
|
|
1035 @item
|
|
|
1036 Attempt to parse @var{spec} as a possibly abbreviated inst-list.
|
|
|
1037 @item
|
|
|
1038 If that fails, attempt to parse @var{spec} as a cons of a locale and an
|
|
|
1039 (abbreviated) inst-list.
|
|
|
1040 @item
|
|
|
1041 If that fails, @var{spec} is invalid.
|
|
|
1042 @end enumerate
|
|
|
1043
|
|
|
1044 A possibly abbreviated inst-list @var{inst-list} is parsed by
|
|
|
1045
|
|
|
1046 @enumerate
|
|
|
1047 @item
|
|
|
1048 Attempt to parse @var{inst-list} as a possibly abbreviated inst-pair.
|
|
|
1049 @item
|
|
|
1050 If that fails, attempt to parse @var{inst-list} as a list of (abbreviated)
|
|
|
1051 inst-pairs.
|
|
|
1052 @item
|
|
|
1053 If that fails, @var{inst-list} is invalid.
|
|
|
1054 @end enumerate
|
|
|
1055
|
|
|
1056 A possibly abbreviated inst-pair @var{inst-pair} is parsed by
|
|
|
1057
|
|
|
1058 @enumerate
|
|
|
1059 @item
|
|
|
1060 Check if @var{inst-pair} is @code{valid-instantiator-p}.
|
|
|
1061 @item
|
|
|
1062 If not, check if @var{inst-pair} is a cons of something that is a tag, ie,
|
|
|
1063 @code{valid-specifier-tag-p}, and something that is @code{valid-instantiator-p}.
|
|
|
1064 @item
|
|
|
1065 If not, check if @var{inst-pair} is a cons of a list of tags and something that
|
|
|
1066 is @code{valid-instantiator-p}.
|
|
|
1067 @item
|
|
|
1068 Otherwise, @var{inst-pair} is invalid.
|
|
|
1069 @end enumerate
|
|
|
1070
|
|
|
1071 In summary, this function generally prefers more abbreviated forms.
|
|
428
|
1072 @end defun
|
|
|
1073
|
|
|
1074 @node Retrieving Specifications
|
|
|
1075 @section Retrieving the Specifications from a Specifier
|
|
|
1076
|
|
|
1077 @defun specifier-spec-list specifier &optional locale tag-set exact-p
|
|
|
1078 This function returns the spec-list of specifications for
|
|
|
1079 @var{specifier} in @var{locale}.
|
|
|
1080
|
|
|
1081 If @var{locale} is a particular locale (a window, buffer, frame, device,
|
|
|
1082 or the symbol @code{global}), a spec-list consisting of the
|
|
|
1083 specification for that locale will be returned.
|
|
|
1084
|
|
444
|
1085 If @var{locale} is a locale type (i.e. one of the symbols @code{window},
|
|
428
|
1086 @code{buffer}, @code{frame}, or @code{device}), a spec-list of the
|
|
|
1087 specifications for all locales of that type will be returned.
|
|
|
1088
|
|
|
1089 If @var{locale} is @code{nil} or the symbol @code{all}, a spec-list of
|
|
|
1090 all specifications in @var{specifier} will be returned.
|
|
|
1091
|
|
|
1092 @var{locale} can also be a list of locales, locale types, and/or
|
|
|
1093 @code{all}; the result is as if @code{specifier-spec-list} were called
|
|
|
1094 on each element of the list and the results concatenated together.
|
|
|
1095
|
|
|
1096 Only instantiators where @var{tag-set} (a list of zero or more tags) is
|
|
|
1097 a subset of (or possibly equal to) the instantiator's tag set are
|
|
444
|
1098 returned. (The default value of @code{nil} is a subset of all tag sets,
|
|
428
|
1099 so in this case no instantiators will be screened out.) If @var{exact-p}
|
|
|
1100 is non-@code{nil}, however, @var{tag-set} must be equal to an
|
|
|
1101 instantiator's tag set for the instantiator to be returned.
|
|
|
1102 @end defun
|
|
|
1103
|
|
|
1104 @defun specifier-specs specifier &optional locale tag-set exact-p
|
|
|
1105 This function returns the specification(s) for @var{specifier} in
|
|
|
1106 @var{locale}.
|
|
|
1107
|
|
|
1108 If @var{locale} is a single locale or is a list of one element
|
|
|
1109 containing a single locale, then a ``short form'' of the instantiators
|
|
|
1110 for that locale will be returned. Otherwise, this function is identical
|
|
|
1111 to @code{specifier-spec-list}.
|
|
|
1112
|
|
|
1113 The ``short form'' is designed for readability and not for ease of use
|
|
|
1114 in Lisp programs, and is as follows:
|
|
|
1115
|
|
|
1116 @enumerate
|
|
|
1117 @item
|
|
|
1118 If there is only one instantiator, then an inst-pair (i.e. cons of tag
|
|
|
1119 and instantiator) will be returned; otherwise a list of inst-pairs will
|
|
|
1120 be returned.
|
|
|
1121 @item
|
|
|
1122 For each inst-pair returned, if the instantiator's tag is @code{any},
|
|
|
1123 the tag will be removed and the instantiator itself will be returned
|
|
|
1124 instead of the inst-pair.
|
|
|
1125 @item
|
|
|
1126 If there is only one instantiator, its value is @code{nil}, and its tag
|
|
|
1127 is @code{any}, a one-element list containing @code{nil} will be returned
|
|
|
1128 rather than just @code{nil}, to distinguish this case from there being
|
|
|
1129 no instantiators at all.
|
|
|
1130 @end enumerate
|
|
|
1131
|
|
|
1132 @end defun
|
|
|
1133
|
|
|
1134 @defun specifier-fallback specifier
|
|
|
1135 This function returns the fallback value for @var{specifier}. Fallback
|
|
|
1136 values are provided by the C code for certain built-in specifiers to
|
|
2953
|
1137 make sure that instantiation won't fail even if all specs are removed from
|
|
428
|
1138 the specifier, or to implement simple inheritance behavior (e.g. this
|
|
|
1139 method is used to ensure that faces other than @code{default} inherit
|
|
|
1140 their attributes from @code{default}). By design, you cannot change the
|
|
|
1141 fallback value, and specifiers created with @code{make-specifier} will
|
|
|
1142 never have a fallback (although a similar, Lisp-accessible capability
|
|
|
1143 may be provided in the future to allow for inheritance).
|
|
|
1144
|
|
2953
|
1145 The fallback value will be an inst-list that is instantiated like
|
|
428
|
1146 any other inst-list, a specifier of the same type as @var{specifier}
|
|
|
1147 (results in inheritance), or @code{nil} for no fallback.
|
|
|
1148
|
|
2953
|
1149 When you instantiate a specifier, you can explicitly request that the
|
|
428
|
1150 fallback not be consulted. (The C code does this, for example, when
|
|
|
1151 merging faces.) See @code{specifier-instance}.
|
|
|
1152 @end defun
|
|
|
1153
|
|
|
1154 @node Specifier Tag Functions
|
|
|
1155 @section Working With Specifier Tags
|
|
|
1156
|
|
|
1157 A specifier tag set is an entity that is attached to an instantiator
|
|
|
1158 and can be used to restrict the scope of that instantiator to a
|
|
|
1159 particular device class or device type and/or to mark instantiators
|
|
|
1160 added by a particular package so that they can be later removed.
|
|
|
1161
|
|
442
|
1162 A specifier tag set consists of a list of zero or more specifier tags,
|
|
428
|
1163 each of which is a symbol that is recognized by XEmacs as a tag. (The
|
|
|
1164 valid device types and device classes are always tags, as are any tags
|
|
|
1165 defined by @code{define-specifier-tag}.) It is called a ``tag set'' (as
|
|
|
1166 opposed to a list) because the order of the tags or the number of times
|
|
|
1167 a particular tag occurs does not matter.
|
|
|
1168
|
|
3674
|
1169 Each tag has a device predicate associated with it, which specifies whether
|
|
428
|
1170 that tag applies to a particular device. The tags which are device
|
|
|
1171 types and classes match devices of that type or class. User-defined
|
|
3674
|
1172 tags can have any device predicate, or none (meaning that all devices match).
|
|
2953
|
1173 When attempting to instantiate a specifier, a particular instantiator is
|
|
|
1174 only considered if the device of the domain being instantiated over matches
|
|
428
|
1175 all tags in the tag set attached to that instantiator.
|
|
|
1176
|
|
3674
|
1177 Each tag can also have a charset predicate, specifying whether that tag
|
|
|
1178 applies to a particular charset. There are a few tags with predefined
|
|
|
1179 charset predicates created to allow sensible fallbacks in the face
|
|
|
1180 code---see the output of @code{(specifier-fallback (face-font
|
|
|
1181 'default))} for these.
|
|
|
1182
|
|
428
|
1183 Most of the time, a tag set is not specified, and the instantiator gets
|
|
3674
|
1184 a null tag set, which matches all devices and all character sets (when
|
|
|
1185 possible; fonts with an inappropriate repertoire will not match, for
|
|
|
1186 example).
|
|
428
|
1187
|
|
|
1188 @defun valid-specifier-tag-p tag
|
|
|
1189 This function returns non-@code{nil} if @var{tag} is a valid specifier
|
|
|
1190 tag.
|
|
|
1191 @end defun
|
|
|
1192
|
|
|
1193 @defun valid-specifier-tag-set-p tag-set
|
|
|
1194 This function returns non-@code{nil} if @var{tag-set} is a valid
|
|
|
1195 specifier tag set.
|
|
|
1196 @end defun
|
|
|
1197
|
|
|
1198 @defun canonicalize-tag-set tag-set
|
|
|
1199 This function canonicalizes the given tag set. Two canonicalized tag
|
|
|
1200 sets can be compared with @code{equal} to see if they represent the same
|
|
|
1201 tag set. (Specifically, canonicalizing involves sorting by symbol name
|
|
|
1202 and removing duplicates.)
|
|
|
1203 @end defun
|
|
|
1204
|
|
|
1205 @defun device-matches-specifier-tag-set-p device tag-set
|
|
|
1206 This function returns non-@code{nil} if @var{device} matches specifier
|
|
|
1207 tag set @var{tag-set}. This means that @var{device} matches each tag in
|
|
|
1208 the tag set.
|
|
|
1209 @end defun
|
|
|
1210
|
|
3674
|
1211 @defun define-specifier-tag tag &optional device-predicate charset-predicate
|
|
|
1212 This function defines a new specifier tag. If @var{device-predicate} is
|
|
428
|
1213 specified, it should be a function of one argument (a device) that
|
|
|
1214 specifies whether the tag matches that particular device. If
|
|
3674
|
1215 @var{device-predicate} is omitted, the tag matches all devices.
|
|
|
1216
|
|
|
1217 If @var{charset-predicate} is specified, it should be a function taking
|
|
|
1218 one character set argument that specifies whether the tag matches that
|
|
|
1219 particular character set.
|
|
428
|
1220
|
|
|
1221 You can redefine an existing user-defined specifier tag. However, you
|
|
|
1222 cannot redefine the built-in specifier tags (the device types and
|
|
|
1223 classes) or the symbols @code{nil}, @code{t}, @code{all}, or
|
|
|
1224 @code{global}.
|
|
|
1225 @end defun
|
|
|
1226
|
|
|
1227 @defun device-matching-specifier-tag-list &optional device
|
|
|
1228 This function returns a list of all specifier tags matching
|
|
|
1229 @var{device}. @var{device} defaults to the selected device if omitted.
|
|
|
1230 @end defun
|
|
|
1231
|
|
|
1232 @defun specifier-tag-list
|
|
|
1233 This function returns a list of all currently-defined specifier tags.
|
|
|
1234 This includes the built-in ones (the device types and classes).
|
|
|
1235 @end defun
|
|
|
1236
|
|
3674
|
1237 @defun specifier-tag-device-predicate tag
|
|
|
1238 This function returns the device predicate for the given specifier tag.
|
|
|
1239 @end defun
|
|
|
1240
|
|
|
1241 @defun specifier-tag-charset-predicate tag
|
|
|
1242 This function returns the charset predicate for the given specifier tag.
|
|
428
|
1243 @end defun
|
|
|
1244
|
|
2953
|
1245 @node Specifier Instantiation Functions
|
|
|
1246 @section Functions for Instantiating a Specifier
|
|
428
|
1247
|
|
|
1248 @defun specifier-instance specifier &optional domain default no-fallback
|
|
1882
|
1249 This function instantiates @var{specifier} (returns its value) in
|
|
428
|
1250 @var{domain}. If no instance can be generated for this domain, return
|
|
|
1251 @var{default}.
|
|
|
1252
|
|
|
1253 @var{domain} should be a window, frame, or device. Other values that
|
|
|
1254 are legal as a locale (e.g. a buffer) are not valid as a domain because
|
|
|
1255 they do not provide enough information to identify a particular device
|
|
|
1256 (see @code{valid-specifier-domain-p}). @var{domain} defaults to the
|
|
|
1257 selected window if omitted.
|
|
|
1258
|
|
|
1259 @dfn{Instantiating} a specifier in a particular domain means determining
|
|
|
1260 the specifier's ``value'' in that domain. This is accomplished by
|
|
|
1261 searching through the specifications in the specifier that correspond to
|
|
|
1262 all locales that can be derived from the given domain, from specific to
|
|
|
1263 general. In most cases, the domain is an Emacs window. In that case
|
|
|
1264 specifications are searched for as follows:
|
|
|
1265
|
|
|
1266 @enumerate
|
|
|
1267 @item
|
|
|
1268 A specification whose locale is the window itself;
|
|
|
1269 @item
|
|
|
1270 A specification whose locale is the window's buffer;
|
|
|
1271 @item
|
|
|
1272 A specification whose locale is the window's frame;
|
|
|
1273 @item
|
|
|
1274 A specification whose locale is the window's frame's device;
|
|
|
1275 @item
|
|
|
1276 A specification whose locale is the symbol @code{global}.
|
|
|
1277 @end enumerate
|
|
|
1278
|
|
|
1279 If all of those fail, then the C-code-provided fallback value for this
|
|
|
1280 specifier is consulted (see @code{specifier-fallback}). If it is an
|
|
|
1281 inst-list, then this function attempts to instantiate that list just as
|
|
|
1282 when a specification is located in the first five steps above. If the
|
|
|
1283 fallback is a specifier, @code{specifier-instance} is called recursively
|
|
|
1284 on this specifier and the return value used. Note, however, that if the
|
|
|
1285 optional argument @var{no-fallback} is non-@code{nil}, the fallback
|
|
|
1286 value will not be consulted.
|
|
|
1287
|
|
|
1288 Note that there may be more than one specification matching a particular
|
|
|
1289 locale; all such specifications are considered before looking for any
|
|
|
1290 specifications for more general locales. Any particular specification
|
|
|
1291 that is found may be rejected because it is tagged to a particular
|
|
|
1292 device class (e.g. @code{color}) or device type (e.g. @code{x}) or both
|
|
|
1293 and the device for the given domain does not match this, or because the
|
|
|
1294 specification is not valid for the device of the given domain (e.g. the
|
|
|
1295 font or color name does not exist for this particular X server).
|
|
|
1296
|
|
|
1297 The returned value is dependent on the type of specifier. For example,
|
|
|
1298 for a font specifier (as returned by the @code{face-font} function), the
|
|
|
1299 returned value will be a font-instance object. For images, the returned
|
|
|
1300 value will be a string, pixmap, or subwindow.
|
|
|
1301 @end defun
|
|
|
1302
|
|
1875
|
1303 @defun specifier-matching-instance specifier matchspec &optional domain default no-fallback
|
|
1882
|
1304 This function returns an instance for @var{specifier} in @var{domain}
|
|
1875
|
1305 that matches @var{matchspec}. If no instance can be generated for
|
|
2028
|
1306 @var{domain}, return @var{default}. @xref{Specifier Compatibility Notes}.
|
|
1875
|
1307
|
|
|
1308 This function is identical to @code{specifier-instance} except that a
|
|
|
1309 specification will only be considered if it matches @var{matchspec}.
|
|
|
1310 The definition of ``match,'' and allowed values for @var{matchspec}, are
|
|
|
1311 dependent on the particular type of specifier. Here are some examples:
|
|
|
1312
|
|
|
1313 @itemize
|
|
|
1314 @item
|
|
|
1315 For chartable (e.g. display table) specifiers, @var{matchspec} should be a
|
|
|
1316 character, and the specification (a chartable) must give a value for
|
|
|
1317 that character in order to be considered. This allows you to specify,
|
|
1877
|
1318 @emph{e.g.}, a buffer-local display table that only gives values for particular
|
|
1875
|
1319 characters. All other characters are handled as if the buffer-local
|
|
|
1320 display table is not there. (Chartable specifiers are not yet
|
|
|
1321 implemented.)
|
|
1877
|
1322 @item
|
|
1875
|
1323 For font specifiers, @var{matchspec} should be a list (@var{charset}
|
|
3674
|
1324 . @var{stage}). On X11 the specification (a font string) should, for
|
|
|
1325 clarity, have a registry that matches the charset's registry, but the
|
|
|
1326 redisplay code will specify the XLFD CHARSET_REGISTRY and
|
|
|
1327 CHARSET_ENCODING fields itself. This makes minimal sense without Mule
|
|
|
1328 support. @var{stage} can be one of the symbols @code{'initial} and
|
|
|
1329 @code{'final}; on X11, @code{'initial} means ``search for fonts using
|
|
|
1330 the charset registry of this charset'' and @code{'final} means ``search
|
|
|
1331 for fonts using `iso10646-1' as their charset registries, with the
|
|
|
1332 expectation that characters will be translated to Unicode at
|
|
|
1333 redisplay.'' Their meanings are similar on MS Windows, with the
|
|
|
1334 difference that the actual repertoire of the font is checked when
|
|
|
1335 deciding if a matchspec with @code{'final} matches.
|
|
|
1336
|
|
|
1337 For example, the following code emulates what redisplay does when
|
|
|
1338 deciding what font to use for ethiopic with the default face (ignoring,
|
|
|
1339 for the moment, fallbacks):
|
|
|
1340 @example
|
|
|
1341 (or
|
|
|
1342 (specifier-matching-instance (face-font 'default)
|
|
|
1343 (cons 'ethiopic 'initial))
|
|
|
1344 (specifier-matching-instance (face-font 'default)
|
|
|
1345 (cons 'ethiopic 'final)))
|
|
|
1346 @end example
|
|
1878
|
1347 @end itemize
|
|
1875
|
1348 @end defun
|
|
|
1349
|
|
428
|
1350 @defun specifier-instance-from-inst-list specifier domain inst-list &optional default
|
|
|
1351 This function attempts to convert a particular inst-list into an
|
|
|
1352 instance. This attempts to instantiate @var{inst-list} in the given
|
|
|
1353 @var{domain}, as if @var{inst-list} existed in a specification in
|
|
|
1354 @var{specifier}. If the instantiation fails, @var{default} is returned.
|
|
|
1355 In most circumstances, you should not use this function; use
|
|
|
1356 @code{specifier-instance} instead.
|
|
|
1357 @end defun
|
|
|
1358
|
|
1869
|
1359 @node Specifier Examples
|
|
|
1360 @section Examples of Specifier Usage
|
|
428
|
1361
|
|
|
1362 Now let us present an example to clarify the theoretical discussions we
|
|
|
1363 have been through. In this example, we will use the general specifier
|
|
|
1364 functions for clarity. Keep in mind that many types of specifiers, and
|
|
|
1365 some other types of objects that are associated with specifiers
|
|
|
1366 (e.g. faces), provide convenience functions making it easier to work
|
|
|
1367 with objects of that type.
|
|
|
1368
|
|
|
1369 Let us consider the background color of the default face. A specifier
|
|
|
1370 is used to specify how that color will appear in different domains.
|
|
|
1371 First, let's retrieve the specifier:
|
|
|
1372
|
|
|
1373 @example
|
|
|
1374 (setq sp (face-property 'default 'background))
|
|
|
1375 @result{} #<color-specifier 0x3da>
|
|
|
1376 @end example
|
|
|
1377
|
|
|
1378 @example
|
|
|
1379 (specifier-specs sp)
|
|
|
1380 @result{} ((#<buffer "device.c"> (nil . "forest green"))
|
|
|
1381 (#<window on "Makefile" 0x8a2b> (nil . "hot pink"))
|
|
|
1382 (#<x-frame "emacs" 0x4ac> (nil . "puke orange")
|
|
440
|
1383 (nil . "moccasin"))
|
|
428
|
1384 (#<x-frame "VM" 0x4ac> (nil . "magenta"))
|
|
440
|
1385 (global ((tty) . "cyan") (nil . "white"))
|
|
428
|
1386 )
|
|
|
1387 @end example
|
|
|
1388
|
|
|
1389 Then, say we want to determine what the background color of the default
|
|
|
1390 face is for the window currently displaying the buffer @samp{*scratch*}.
|
|
|
1391 We call
|
|
|
1392
|
|
|
1393 @example
|
|
|
1394 (get-buffer-window "*scratch*")
|
|
|
1395 @result{} #<window on "*scratch*" 0x4ad>
|
|
|
1396 (window-frame (get-buffer-window "*scratch*"))
|
|
|
1397 @result{} #<x-frame "emacs" 0x4ac>
|
|
|
1398 (specifier-instance sp (get-buffer-window "*scratch*"))
|
|
|
1399 @result{} #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x6309>
|
|
|
1400 @end example
|
|
|
1401
|
|
|
1402 Note that we passed a window to @code{specifier-instance}, not a buffer.
|
|
|
1403 We cannot pass a buffer because a buffer by itself does not provide enough
|
|
|
1404 information. The buffer might not be displayed anywhere at all, or
|
|
|
1405 could be displayed in many different frames on different devices.
|
|
|
1406
|
|
|
1407 The result is arrived at like this:
|
|
|
1408
|
|
|
1409 @enumerate
|
|
|
1410 @item
|
|
|
1411 First, we look for a specification matching the buffer displayed in the
|
|
440
|
1412 window, i.e. @samp{*scratch*}. There are none, so we proceed.
|
|
428
|
1413 @item
|
|
|
1414 Then, we look for a specification matching the window itself. Again, there
|
|
|
1415 are none.
|
|
|
1416 @item
|
|
|
1417 Then, we look for a specification matching the window's frame. The
|
|
|
1418 specification @code{(#<x-frame "emacs" 0x4ac> . "puke orange")} is
|
|
|
1419 found. We call the instantiation method for colors, passing it the
|
|
|
1420 locale we were searching over (i.e. the window, in this case) and the
|
|
|
1421 instantiator (@samp{"puke orange"}). However, the particular device
|
|
|
1422 which this window is on (let's say it's an X connection) doesn't
|
|
|
1423 recognize the color @samp{"puke orange"}, so the specification is
|
|
|
1424 rejected.
|
|
|
1425 @item
|
|
|
1426 So we continue looking for a specification matching the window's frame.
|
|
|
1427 We find @samp{(#<x-frame "emacs" 0x4ac> . "moccasin")}. Again, we
|
|
|
1428 call the instantiation method for colors. This time, the X server
|
|
|
1429 our window is on recognizes the color @samp{moccasin}, and so the
|
|
|
1430 instantiation method succeeds and returns a color instance.
|
|
|
1431 @end enumerate
|
|
|
1432
|
|
1869
|
1433 Here's another example, which implements something like GNU Emacs's
|
|
|
1434 ``frame-local'' variables.
|
|
|
1435
|
|
|
1436 @example
|
|
|
1437 ;; Implementation
|
|
|
1438
|
|
|
1439 ;; There are probably better ways to write this macro
|
|
|
1440 ;; Heaven help you if VAR is a buffer-local; you will become very
|
|
|
1441 ;; confused. Probably should error on that.
|
|
|
1442 (defmacro define-frame-local-variable (var)
|
|
|
1443 "Make the unbound symbol VAR become a frame-local variable."
|
|
|
1444 (let ((val (if (boundp var) (symbol-value var) nil)))
|
|
|
1445 `(progn
|
|
|
1446 (setq ,var (make-specifier 'generic))
|
|
|
1447 (add-spec-to-specifier ,var ',val 'global))))
|
|
|
1448
|
|
|
1449 ;; I'm not real happy about this terminology, how can `setq' be a defun?
|
|
|
1450 ;; But `frame-set' would have people writing "(frame-set 'foo value)".
|
|
|
1451 (defun frame-setq (var value &optional frame)
|
|
|
1452 "Set the local value of VAR to VALUE in FRAME.
|
|
|
1453
|
|
|
1454 FRAME defaults to the selected frame."
|
|
|
1455 (and frame (not (framep frame))
|
|
|
1456 (error 'invalid-argument "FRAME must be a frame", frame))
|
|
|
1457 (add-spec-to-specifier var value (or frame (selected-frame))))
|
|
|
1458
|
|
|
1459 (defun frame-value (var &optional frame)
|
|
|
1460 "Get the local value of VAR in FRAME.
|
|
|
1461
|
|
|
1462 FRAME defaults to the selected frame."
|
|
|
1463 (and frame (not (framep frame))
|
|
|
1464 (error 'invalid-argument "FRAME must be a frame", frame))
|
|
|
1465 ;; this is not just a map from frames to values; it also falls back
|
|
|
1466 ;; to the global value
|
|
|
1467 (specifier-instance var (or frame (selected-frame))))
|
|
|
1468
|
|
|
1469 ;; for completeness
|
|
|
1470 (defun frame-set-default (var value)
|
|
|
1471 "Set the default value of frame-local variable VAR to VALUE."
|
|
|
1472 (add-spec-to-specifier var value 'global))
|
|
|
1473
|
|
|
1474 (defun frame-get-default (var)
|
|
|
1475 "Get the default value of frame-local variable VAR."
|
|
|
1476 (car (specifier-specs var 'global)))
|
|
|
1477 @end example
|
|
|
1478
|
|
|
1479 Now you can execute the above definitions (eg, with @code{eval-last-sexp})
|
|
|
1480 and switch to @file{*scratch*} to play. Things will work differently if
|
|
|
1481 you already have a variable named @code{foo}.
|
|
|
1482
|
|
|
1483 @example
|
|
|
1484 ;; Usage
|
|
|
1485
|
|
|
1486 foo
|
|
|
1487 @error{} Symbol's value as variable is void: foo
|
|
|
1488
|
|
|
1489 (define-frame-local-variable foo)
|
|
|
1490 @result{} nil
|
|
|
1491
|
|
|
1492 ;; the value of foo is a specifier, which is an opaque object;
|
|
|
1493 ;; you must use accessor functions to get values
|
|
|
1494
|
|
|
1495 foo
|
|
|
1496 @result{} #<generic-specifier global=(nil) 0x4f5cb>
|
|
|
1497
|
|
|
1498 ;; since no frame-local value is set, the global value (which is the
|
|
|
1499 ;; constant `nil') is returned
|
|
|
1500 (frame-value foo)
|
|
|
1501 @result{} nil
|
|
|
1502
|
|
|
1503 ;; get the default explicitly
|
|
|
1504 (frame-get-default foo)
|
|
|
1505 @result{} nil
|
|
|
1506
|
|
|
1507 ;; get the whole specification list
|
|
|
1508 (specifier-specs foo 'global)
|
|
|
1509 @result{} (nil)
|
|
|
1510
|
|
|
1511 ;; give foo a frame-local value
|
|
|
1512
|
|
|
1513 (frame-setq foo 'bar)
|
|
|
1514 @result{} nil
|
|
|
1515
|
|
|
1516 ;; access foo in several ways
|
|
|
1517
|
|
|
1518 ;; Note that the print function for this kind of specifier only
|
|
|
1519 ;; gives you the global setting. To get the full list of specs for
|
|
|
1520 ;; debugging or study purposes, you must use specifier-specs or
|
|
|
1521 ;; specifier-spec-list.
|
|
|
1522 foo
|
|
|
1523 @result{} #<generic-specifier global=(nil) 0x4f5cb>
|
|
|
1524
|
|
|
1525 ;; get the whole specification list
|
|
|
1526 (specifier-specs foo)
|
|
|
1527 @result{} ((#<x-frame "Message" 0x1bd66> (nil . bar)) (global (nil)))
|
|
|
1528
|
|
|
1529 ;; get the frame-local value
|
|
|
1530 (frame-value foo)
|
|
|
1531 @result{} bar
|
|
|
1532
|
|
|
1533 ;; get the default explicitly
|
|
|
1534 (frame-get-default foo)
|
|
|
1535 @result{} nil
|
|
|
1536
|
|
|
1537 ;; Switch to another frame and evaluate:
|
|
|
1538 ;; C-x 5 o M-: (frame-setq foo 'baz) RET M-: (frame-value foo) RET
|
|
|
1539 @result{} baz
|
|
|
1540
|
|
|
1541 ;; Switch back.
|
|
|
1542 ;; C-x 5 o
|
|
|
1543 (specifier-specs foo)
|
|
|
1544 @result{} ((#<x-frame "emacs" 0x28ec> (nil . baz))
|
|
|
1545 (#<x-frame "Message" 0x1bd66> (nil . bar))
|
|
|
1546 (global (nil)))
|
|
|
1547
|
|
|
1548 (frame-value foo)
|
|
|
1549 @result{} bar
|
|
|
1550
|
|
|
1551 (frame-get-default foo)
|
|
|
1552 @result{} nil
|
|
|
1553 @end example
|
|
|
1554
|
|
|
1555 Note that since specifiers generalize both frame-local and buffer-local
|
|
|
1556 variables in a sensible way, XEmacs is not likely to put a high priority
|
|
2028
|
1557 on implementing frame-local variables @ref{Specifier Compatibility Notes}.
|
|
1869
|
1558
|
|
|
1559
|
|
428
|
1560 @node Creating Specifiers
|
|
|
1561 @section Creating New Specifier Objects
|
|
|
1562
|
|
|
1563 @defun make-specifier type
|
|
|
1564 This function creates a new specifier.
|
|
|
1565
|
|
|
1566 A specifier is an object that can be used to keep track of a property
|
|
|
1567 whose value can be per-buffer, per-window, per-frame, or per-device,
|
|
|
1568 and can further be restricted to a particular device-type or device-class.
|
|
|
1569 Specifiers are used, for example, for the various built-in properties of a
|
|
|
1570 face; this allows a face to have different values in different frames,
|
|
444
|
1571 buffers, etc. For more information, see @code{specifier-instance},
|
|
|
1572 @code{specifier-specs}, and @code{add-spec-to-specifier}; or, for a detailed
|
|
428
|
1573 description of specifiers, including how they are instantiated over a
|
|
|
1574 particular domain (i.e. how their value in that domain is determined),
|
|
|
1575 see the chapter on specifiers in the XEmacs Lisp Reference Manual.
|
|
|
1576
|
|
|
1577 @var{type} specifies the particular type of specifier, and should be one
|
|
|
1578 of the symbols @code{generic}, @code{integer}, @code{natnum},
|
|
|
1579 @code{boolean}, @code{color}, @code{font}, @code{image},
|
|
|
1580 @code{face-boolean}, or @code{toolbar}.
|
|
|
1581
|
|
|
1582 For more information on particular types of specifiers, see the
|
|
442
|
1583 functions @code{make-generic-specifier}, @code{make-integer-specifier},
|
|
|
1584 @code{make-natnum-specifier}, @code{make-boolean-specifier},
|
|
|
1585 @code{make-color-specifier}, @code{make-font-specifier},
|
|
|
1586 @code{make-image-specifier}, @code{make-face-boolean-specifier}, and
|
|
|
1587 @code{make-toolbar-specifier}.
|
|
428
|
1588 @end defun
|
|
|
1589
|
|
|
1590 @defun make-specifier-and-init type spec-list &optional dont-canonicalize
|
|
1875
|
1591 This function creates and initializes a new specifier.
|
|
428
|
1592
|
|
1875
|
1593 This is a convenience API combining @code{make-specifier} and
|
|
|
1594 @code{set-specifier} that allows you to create
|
|
428
|
1595 a specifier and add specs to it at the same time. @var{type} specifies
|
|
1875
|
1596 the specifier type. Allowed types are as for @code{make-specifier}.
|
|
|
1597
|
|
|
1598 @var{spec-list} supplies the specification(s) to be
|
|
|
1599 added to the specifier. Any abbreviation of
|
|
|
1600 the full spec-list form accepted by @code{canonicalize-spec-list} may
|
|
|
1601 be used.
|
|
|
1602 However, if the optional argument @var{dont-canonicalize} is non-@code{nil},
|
|
|
1603 canonicalization is not performed, and the @var{spec-list} must already
|
|
|
1604 be in full form.
|
|
428
|
1605 @end defun
|
|
|
1606
|
|
442
|
1607 @defun make-integer-specifier spec-list
|
|
|
1608
|
|
|
1609 Return a new @code{integer} specifier object with the given
|
|
|
1610 specification list. @var{spec-list} can be a list of specifications
|
|
|
1611 (each of which is a cons of a locale and a list of instantiators), a
|
|
|
1612 single instantiator, or a list of instantiators.
|
|
|
1613
|
|
|
1614 Valid instantiators for integer specifiers are integers.
|
|
|
1615 @end defun
|
|
|
1616
|
|
|
1617 @defun make-boolean-specifier spec-list
|
|
|
1618
|
|
|
1619 Return a new @code{boolean} specifier object with the given
|
|
|
1620 specification list. @var{spec-list} can be a list of specifications
|
|
|
1621 (each of which is a cons of a locale and a list of instantiators), a
|
|
|
1622 single instantiator, or a list of instantiators.
|
|
|
1623
|
|
|
1624 Valid instantiators for boolean specifiers are @code{t} and @code{nil}.
|
|
|
1625 @end defun
|
|
|
1626
|
|
|
1627 @defun make-natnum-specifier spec-list
|
|
|
1628
|
|
|
1629 Return a new @code{natnum} specifier object with the given specification
|
|
|
1630 list. @var{spec-list} can be a list of specifications (each of which is
|
|
|
1631 a cons of a locale and a list of instantiators), a single instantiator,
|
|
|
1632 or a list of instantiators.
|
|
|
1633
|
|
|
1634 Valid instantiators for natnum specifiers are non-negative integers.
|
|
|
1635 @end defun
|
|
|
1636
|
|
|
1637 @defun make-generic-specifier spec-list
|
|
|
1638
|
|
|
1639 Return a new @code{generic} specifier object with the given
|
|
|
1640 specification list. @var{spec-list} can be a list of specifications
|
|
|
1641 (each of which is a cons of a locale and a list of instantiators), a
|
|
|
1642 single instantiator, or a list of instantiators.
|
|
|
1643
|
|
|
1644 Valid instantiators for generic specifiers are all Lisp values. They
|
|
|
1645 are returned back unchanged when a specifier is instantiated.
|
|
|
1646 @end defun
|
|
|
1647
|
|
|
1648 @defun make-display-table-specifier spec-list
|
|
|
1649
|
|
|
1650 Return a new @code{display-table} specifier object with the given spec
|
|
|
1651 list. @var{spec-list} can be a list of specifications (each of which is
|
|
|
1652 a cons of a locale and a list of instantiators), a single instantiator,
|
|
|
1653 or a list of instantiators.
|
|
|
1654
|
|
|
1655 Valid instantiators for display-table specifiers are described in detail
|
|
|
1656 in the doc string for @code{current-display-table} (@pxref{Active
|
|
|
1657 Display Table}).
|
|
|
1658 @end defun
|
|
|
1659
|
|
428
|
1660 @node Specifier Validation Functions
|
|
|
1661 @section Functions for Checking the Validity of Specifier Components
|
|
|
1662
|
|
|
1663 @defun valid-specifier-domain-p domain
|
|
|
1664 This function returns non-@code{nil} if @var{domain} is a valid
|
|
2953
|
1665 specifier domain. A domain is used to instantiate a specifier
|
|
428
|
1666 (i.e. determine the specifier's value in that domain). Valid domains
|
|
|
1667 are a window, frame, or device. (@code{nil} is not valid.)
|
|
|
1668 @end defun
|
|
|
1669
|
|
|
1670 @defun valid-specifier-locale-p locale
|
|
|
1671 This function returns non-@code{nil} if @var{locale} is a valid
|
|
|
1672 specifier locale. Valid locales are a device, a frame, a window, a
|
|
|
1673 buffer, and @code{global}. (@code{nil} is not valid.)
|
|
|
1674 @end defun
|
|
|
1675
|
|
|
1676 @defun valid-specifier-locale-type-p locale-type
|
|
444
|
1677 Given a specifier @var{locale-type}, this function returns non-@code{nil} if it
|
|
428
|
1678 is valid. Valid locale types are the symbols @code{global},
|
|
|
1679 @code{device}, @code{frame}, @code{window}, and @code{buffer}. (Note,
|
|
|
1680 however, that in functions that accept either a locale or a locale type,
|
|
|
1681 @code{global} is considered an individual locale.)
|
|
|
1682 @end defun
|
|
|
1683
|
|
|
1684 @defun valid-specifier-type-p specifier-type
|
|
|
1685 Given a @var{specifier-type}, this function returns non-@code{nil} if it
|
|
|
1686 is valid. Valid types are @code{generic}, @code{integer},
|
|
|
1687 @code{boolean}, @code{color}, @code{font}, @code{image},
|
|
|
1688 @code{face-boolean}, and @code{toolbar}.
|
|
|
1689 @end defun
|
|
|
1690
|
|
|
1691 @defun valid-specifier-tag-p tag
|
|
|
1692 This function returns non-@code{nil} if @var{tag} is a valid specifier
|
|
|
1693 tag.
|
|
|
1694 @end defun
|
|
|
1695
|
|
|
1696 @defun valid-instantiator-p instantiator specifier-type
|
|
|
1697 This function returns non-@code{nil} if @var{instantiator} is valid for
|
|
|
1698 @var{specifier-type}.
|
|
|
1699 @end defun
|
|
|
1700
|
|
|
1701 @defun valid-inst-list-p inst-list type
|
|
|
1702 This function returns non-@code{nil} if @var{inst-list} is valid for
|
|
|
1703 specifier type @var{type}.
|
|
|
1704 @end defun
|
|
|
1705
|
|
|
1706 @defun valid-spec-list-p spec-list type
|
|
|
1707 This function returns non-@code{nil} if @var{spec-list} is valid for
|
|
|
1708 specifier type @var{type}.
|
|
|
1709 @end defun
|
|
|
1710
|
|
|
1711 @defun check-valid-instantiator instantiator specifier-type
|
|
|
1712 This function signals an error if @var{instantiator} is invalid for
|
|
|
1713 @var{specifier-type}.
|
|
|
1714 @end defun
|
|
|
1715
|
|
|
1716 @defun check-valid-inst-list inst-list type
|
|
|
1717 This function signals an error if @var{inst-list} is invalid for
|
|
|
1718 specifier type @var{type}.
|
|
|
1719 @end defun
|
|
|
1720
|
|
|
1721 @defun check-valid-spec-list spec-list type
|
|
|
1722 This function signals an error if @var{spec-list} is invalid for
|
|
|
1723 specifier type @var{type}.
|
|
|
1724 @end defun
|
|
|
1725
|
|
|
1726 @node Other Specification Functions
|
|
|
1727 @section Other Functions for Working with Specifications in a Specifier
|
|
|
1728
|
|
|
1729 @defun copy-specifier specifier &optional dest locale tag-set exact-p how-to-add
|
|
|
1730 This function copies @var{specifier} to @var{dest}, or creates a new one
|
|
|
1731 if @var{dest} is @code{nil}.
|
|
|
1732
|
|
|
1733 If @var{dest} is @code{nil} or omitted, a new specifier will be created
|
|
|
1734 and the specifications copied into it. Otherwise, the specifications
|
|
|
1735 will be copied into the existing specifier in @var{dest}.
|
|
|
1736
|
|
|
1737 If @var{locale} is @code{nil} or the symbol @code{all}, all
|
|
|
1738 specifications will be copied. If @var{locale} is a particular locale,
|
|
|
1739 the specification for that particular locale will be copied. If
|
|
|
1740 @var{locale} is a locale type, the specifications for all locales of
|
|
|
1741 that type will be copied. @var{locale} can also be a list of locales,
|
|
|
1742 locale types, and/or @code{all}; this is equivalent to calling
|
|
|
1743 @code{copy-specifier} for each of the elements of the list. See
|
|
|
1744 @code{specifier-spec-list} for more information about @var{locale}.
|
|
|
1745
|
|
|
1746 Only instantiators where @var{tag-set} (a list of zero or more tags) is
|
|
|
1747 a subset of (or possibly equal to) the instantiator's tag set are
|
|
|
1748 copied. (The default value of @code{nil} is a subset of all tag sets,
|
|
|
1749 so in this case no instantiators will be screened out.) If @var{exact-p}
|
|
|
1750 is non-@code{nil}, however, @var{tag-set} must be equal to an
|
|
|
1751 instantiator's tag set for the instantiator to be copied.
|
|
|
1752
|
|
|
1753 Optional argument @var{how-to-add} specifies what to do with existing
|
|
444
|
1754 specifications in @var{dest}. If @code{nil}, then whichever locales or locale
|
|
428
|
1755 types are copied will first be completely erased in @var{dest}.
|
|
|
1756 Otherwise, it is the same as in @code{add-spec-to-specifier}.
|
|
|
1757 @end defun
|
|
|
1758
|
|
|
1759 @defun remove-specifier specifier &optional locale tag-set exact-p
|
|
|
1760 This function removes specification(s) for @var{specifier}.
|
|
|
1761
|
|
|
1762 If @var{locale} is a particular locale (a buffer, window, frame, device,
|
|
|
1763 or the symbol @code{global}), the specification for that locale will be
|
|
|
1764 removed.
|
|
|
1765
|
|
|
1766 If instead, @var{locale} is a locale type (i.e. a symbol @code{buffer},
|
|
|
1767 @code{window}, @code{frame}, or @code{device}), the specifications for
|
|
|
1768 all locales of that type will be removed.
|
|
|
1769
|
|
|
1770 If @var{locale} is @code{nil} or the symbol @code{all}, all
|
|
|
1771 specifications will be removed.
|
|
|
1772
|
|
|
1773 @var{locale} can also be a list of locales, locale types, and/or
|
|
|
1774 @code{all}; this is equivalent to calling @code{remove-specifier} for
|
|
|
1775 each of the elements in the list.
|
|
|
1776
|
|
|
1777 Only instantiators where @var{tag-set} (a list of zero or more tags) is
|
|
|
1778 a subset of (or possibly equal to) the instantiator's tag set are
|
|
|
1779 removed. (The default value of @code{nil} is a subset of all tag sets,
|
|
|
1780 so in this case no instantiators will be screened out.) If @var{exact-p}
|
|
|
1781 is non-@code{nil}, however, @var{tag-set} must be equal to an
|
|
|
1782 instantiator's tag set for the instantiator to be removed.
|
|
|
1783 @end defun
|
|
|
1784
|
|
|
1785 @defun map-specifier specifier func &optional locale maparg
|
|
|
1786 This function applies @var{func} to the specification(s) for
|
|
|
1787 @var{locale} in @var{specifier}.
|
|
|
1788
|
|
1875
|
1789 If optional @var{locale} is a locale, @var{func} will be called for that
|
|
|
1790 locale.
|
|
428
|
1791 If @var{locale} is a locale type, @var{func} will be mapped over all
|
|
|
1792 locales of that type. If @var{locale} is @code{nil} or the symbol
|
|
|
1793 @code{all}, @var{func} will be mapped over all locales in
|
|
|
1794 @var{specifier}.
|
|
|
1795
|
|
1875
|
1796 Optional @var{ms-tag-set} and @var{ms-exact-p} are as in
|
|
|
1797 @code{specifier-spec-list'}.
|
|
|
1798 Optional @var{ms-maparg} will be passed to @var{ms-func}.
|
|
|
1799
|
|
428
|
1800 @var{func} is called with four arguments: the @var{specifier}, the
|
|
|
1801 locale being mapped over, the inst-list for that locale, and the
|
|
|
1802 optional @var{maparg}. If any invocation of @var{func} returns
|
|
|
1803 non-@code{nil}, the mapping will stop and the returned value becomes the
|
|
|
1804 value returned from @code{map-specifier}. Otherwise,
|
|
|
1805 @code{map-specifier} returns @code{nil}.
|
|
|
1806 @end defun
|
|
|
1807
|
|
|
1808 @defun specifier-locale-type-from-locale locale
|
|
|
1809 Given a specifier @var{locale}, this function returns its type.
|
|
|
1810 @end defun
|
|
2028
|
1811
|
|
|
1812 @node Specifier Compatibility Notes
|
|
|
1813 @section Specifier Compatibility Notes
|
|
|
1814
|
|
|
1815 This node describes compatibility issues in the use of specifiers known
|
|
|
1816 as of 2004-01-22.
|
|
|
1817 @c I considered basing the main text on 21.4, but then future
|
|
|
1818 @c maintenance of this documentation would be a pain.
|
|
|
1819 The main text refers to XEmacs 21.5.16.
|
|
|
1820
|
|
|
1821 Effort will be made to describe changes in the API or semantics between
|
|
|
1822 XEmacs versions accurately. Any inaccuracy or missing information about
|
|
|
1823 backward and forward compatibility is a bug, and we greatly appreciate
|
|
|
1824 your reports, whether you can provide a patch or not.
|
|
|
1825
|
|
|
1826 A change is reported as @dfn{changed} when we believe that the new or
|
|
|
1827 changed API will cause old code to malfunction. When old code is
|
|
|
1828 believed to be upward compatible with the changed API, the change is
|
|
|
1829 reported as @dfn{added}.
|
|
|
1830
|
|
|
1831 We would like to also describe compatibility with GNU Emacs, but this is
|
|
|
1832 not so high a priority. Inaccuracies or omissions will be addressed at
|
|
|
1833 the priority of a feature request, and as such processing will be
|
|
|
1834 greatly expedited if you can provide a patch.
|
|
|
1835 @c #### xref here to bug reporting and patch submissions
|
|
|
1836
|
|
|
1837 @c #### write and xref a file on compatibility policy
|
|
|
1838
|
|
|
1839 @subsection Compatibility with GNU Emacs
|
|
|
1840
|
|
|
1841 Specifiers are not used in GNU Emacs. If your program depends on
|
|
|
1842 specifers, you will probably have to rewrite the functionality
|
|
|
1843 completely for GNU Emacs. If you wish to maximize portability, you
|
|
|
1844 should plan to encapsulate use of specifiers.
|
|
|
1845
|
|
|
1846 GNU Emacs provides two features for context-sensitive variables,
|
|
|
1847 buffer-local variables and frame-local variables. XEmacs implements
|
|
|
1848 buffer-local variables 100%-compatibly with GNU Emacs. If buffer-local
|
|
|
1849 variables will server your purpose and portability is a major concern,
|
|
|
1850 consider using them instead of specifiers.
|
|
|
1851
|
|
|
1852 XEmacs does not implement frame-local variables at all. In this case
|
|
|
1853 specifiers must be used to provide equivalent functionality.
|
|
|
1854
|
|
|
1855 It is not clear whether XEmacs will provide this feature in the future.
|
|
|
1856 @c Thanks to Jerry James for the following explanation. He is not
|
|
|
1857 @c responsible for its use here, Stephen Turnbull is.
|
|
|
1858 In fact, some core XEmacs developers think that both frame-local
|
|
|
1859 variables and buffer-local variables are evil, because the declaration
|
|
|
1860 is both global and invisible. That is, you cannot tell whether a
|
|
|
1861 variable is ``normal,'' buffer-local, or frame-local just by looking at
|
|
|
1862 it. So if you have namespace management problems, and some other Lisp
|
|
|
1863 package happens to use a variable name that you already declared frame-
|
|
|
1864 or buffer-local, weird stuff happens, and it is extremely hard to track
|
|
|
1865 down.
|
|
|
1866 @c #### Direct comments to xemacs-design?
|
|
|
1867
|
|
|
1868 @subsection Backwards Compatibility with XEmacs 21.4
|
|
|
1869
|
|
|
1870 Sorry, I'm unwilling to find out exactly when these changes were made.
|
|
|
1871
|
|
|
1872 Changed by 21.5.16: the second argument of
|
|
|
1873 @code{specifier-matching-instance} is now a cons of a charset and a
|
|
|
1874 boolean value. Previously it was a charset or a symbol (a name of a
|
|
|
1875 charset). It was not documented in Info.
|
|
|
1876
|
|
|
1877 Changed by 21.5.16: the specifier-specific error symbols
|
|
|
1878 @code{specifier_syntax_error}, @code{specifier_argument_error}, and
|
|
|
1879 @code{specifier_change_error} were removed. (This probably only
|
|
|
1880 affected internal code.)
|
|
|
1881
|
|
|
1882 Added by 21.5.16: @code{map-specifier} got two new arguments,
|
|
|
1883 @code{ms-tag-set} and @code{ms-exact-p}.
|
|
|
1884
|
|
|
1885 Added by 21.5.16: when skipping instantiators, XEmacs warns at level
|
|
|
1886 `debug'.
|
|
|
1887
|
|
|
1888 Added by 21.5.16: new convenience APIs:
|
|
|
1889 @code{instance-to-instantiator},
|
|
|
1890 @code{device-type-matches-spec},
|
|
|
1891 @code{add-tag-to-inst-list},
|
|
|
1892 @code{derive-domain-from-locale},
|
|
|
1893 @code{derive-device-type-from-tag-set},
|
|
|
1894 @code{derive-device-type-from-locale-and-tag-set}, and
|
|
|
1895 @code{derive-specifier-specs-from-locale}.
|
