Mercurial > hg > xemacs-beta
annotate man/lispref/specifiers.texi @ 5880:44ba043ceada
Fix a small typo
| author | Vin Shelton <acs@xemacs.org> |
|---|---|
| date | Sat, 28 Mar 2015 16:03:33 -0400 |
| parents | 9fae6227ede5 |
| children |
| rev | line source |
|---|---|
| 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5547
diff
changeset
|
7 @node Specifiers, Faces and Window-System Objects, Extents, Top |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5547
diff
changeset
|
51 @node Introduction to Specifiers, Simple Specifier Usage, Specifiers, Specifiers |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5547
diff
changeset
|
136 @node Simple Specifier Usage, Specifiers In-Depth, Introduction to Specifiers, Specifiers |
| 1135 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5547
diff
changeset
|
280 @node Specifiers In-Depth, Specifier Instantiation, Simple Specifier Usage, Specifiers |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5547
diff
changeset
|
438 @node Specifier Instantiation, Specifier Types, Specifiers In-Depth, Specifiers |
| 2953 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5547
diff
changeset
|
655 @node Specifier Types, Adding Specifications, Specifier Instantiation, Specifiers |
| 428 | 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 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5547
diff
changeset
|
789 @node Adding Specifications, Retrieving Specifications, Specifier Types, Specifiers |
| 428 | 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 | |
|
5547
a46c5c8d6564
Avoid calling various macros "special operators" in the manuals.
Aidan Kehoe <kehoea@parhasard.net>
parents:
5361
diff
changeset
|
878 @defmac let-specifier specifier-list &rest body |
|
4905
755ae5b97edb
Change "special form" to "special operator" in our sources.
Aidan Kehoe <kehoea@parhasard.net>
parents:
3674
diff
changeset
|
879 This macro temporarily adds specifications to specifiers, |
| 428 | 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 | |
|
4905
755ae5b97edb
Change "special form" to "special operator" in our sources.
Aidan Kehoe <kehoea@parhasard.net>
parents:
3674
diff
changeset
|
895 The code resulting from macro expansion will add specifications to |
|
755ae5b97edb
Change "special form" to "special operator" in our sources.
Aidan Kehoe <kehoea@parhasard.net>
parents:
3674
diff
changeset
|
896 specifiers using @code{add-spec-to-specifier}. After forms in |
|
755ae5b97edb
Change "special form" to "special operator" in our sources.
Aidan Kehoe <kehoea@parhasard.net>
parents:
3674
diff
changeset
|
897 @var{body} are evaluated, the temporary specifications are removed and |
|
755ae5b97edb
Change "special form" to "special operator" in our sources.
Aidan Kehoe <kehoea@parhasard.net>
parents:
3674
diff
changeset
|
898 old specifier spec-lists are restored. |
| 428 | 899 |
| 900 @var{locale}, @var{tag-set} and @var{how-to-add} may be omitted, and | |
| 901 default to @code{nil}. The value of the last form in @var{body} is | |
| 902 returned. | |
| 903 | |
| 904 NOTE: If you want the specifier's instance to change in all | |
| 905 circumstances, use @code{(selected-window)} as the @var{locale}. If | |
| 906 @var{locale} is @code{nil} or omitted, it defaults to @code{global}. | |
| 907 | |
| 908 The following example removes the 3D modeline effect in the currently | |
| 909 selected window for the duration of a second: | |
| 910 | |
| 911 @example | |
| 912 (let-specifier ((modeline-shadow-thickness 0 (selected-window))) | |
| 913 (sit-for 1)) | |
| 914 @end example | |
|
5547
a46c5c8d6564
Avoid calling various macros "special operators" in the manuals.
Aidan Kehoe <kehoea@parhasard.net>
parents:
5361
diff
changeset
|
915 @end defmac |
| 428 | 916 |
| 444 | 917 @defun set-specifier specifier value &optional locale tag-set how-to-add |
| 428 | 918 This function adds some specifications to @var{specifier}. @var{value} |
| 919 can be a single instantiator or tagged instantiator (added as a global | |
| 920 specification), a list of tagged and/or untagged instantiators (added as | |
| 921 a global specification), a cons of a locale and instantiator or locale | |
| 922 and instantiator list, a list of such conses, or nearly any other | |
| 923 reasonable form. More specifically, @var{value} can be anything | |
| 1875 | 924 accepted by @code{canonicalize-spec-list} (described below). |
| 428 | 925 |
| 444 | 926 @var{locale}, @var{tag-set}, and @var{how-to-add} are the same as in |
| 927 @code{add-spec-to-specifier}. | |
| 428 | 928 |
| 929 Note that @code{set-specifier} is exactly complementary to | |
| 930 @code{specifier-specs} except in the case where @var{specifier} has no | |
| 931 specs at all in it but @code{nil} is a valid instantiator (in that case, | |
| 932 @code{specifier-specs} will return @code{nil} (meaning no specs) and | |
| 933 @code{set-specifier} will interpret the @code{nil} as meaning ``I'm | |
| 934 adding a global instantiator and its value is @code{nil}''), or in | |
| 935 strange cases where there is an ambiguity between a spec-list and an | |
| 936 inst-list, etc. (The built-in specifier types are designed in such a way | |
| 1875 | 937 as to avoid any such ambiguities.) For robust code, |
| 938 @code{set-specifier} should probably be avoided for specifier types | |
| 939 which accept lists as instantiators (currently toolbar specifiers and | |
| 940 generic specifiers). | |
| 428 | 941 |
| 942 If you want to work with spec-lists, you should probably not use these | |
| 943 functions, but should use the lower-level functions | |
| 944 @code{specifier-spec-list} and @code{add-spec-list-to-specifier}. These | |
| 945 functions always work with fully-qualified spec-lists; thus, there is no | |
| 946 ambiguity. | |
| 947 @end defun | |
| 948 | |
| 949 @defun canonicalize-inst-pair inst-pair specifier-type &optional noerror | |
| 950 This function canonicalizes the given @var{inst-pair}. | |
| 951 | |
| 952 @var{specifier-type} specifies the type of specifier that this | |
| 953 @var{spec-list} will be used for. | |
| 954 | |
| 955 Canonicalizing means converting to the full form for an inst-pair, i.e. | |
| 956 @code{(@var{tag-set} . @var{instantiator})}. A single, untagged | |
| 957 instantiator is given a tag set of @code{nil} (the empty set), and a | |
| 958 single tag is converted into a tag set consisting only of that tag. | |
| 959 | |
| 960 If @var{noerror} is non-@code{nil}, signal an error if the inst-pair is | |
| 961 invalid; otherwise return @code{t}. | |
| 962 @end defun | |
| 963 | |
| 964 @defun canonicalize-inst-list inst-list specifier-type &optional noerror | |
| 965 This function canonicalizes the given @var{inst-list} (a list of | |
| 966 inst-pairs). | |
| 967 | |
| 968 @var{specifier-type} specifies the type of specifier that this @var{inst-list} | |
| 969 will be used for. | |
| 970 | |
| 971 Canonicalizing means converting to the full form for an inst-list, i.e. | |
| 972 @code{((@var{tag-set} . @var{instantiator}) ...)}. This function | |
| 973 accepts a single inst-pair or any abbreviation thereof or a list of | |
| 974 (possibly abbreviated) inst-pairs. (See @code{canonicalize-inst-pair}.) | |
| 975 | |
| 976 If @var{noerror} is non-@code{nil}, signal an error if the inst-list is | |
| 977 invalid; otherwise return @code{t}. | |
| 978 @end defun | |
| 979 | |
| 980 @defun canonicalize-spec spec specifier-type &optional noerror | |
| 981 This function canonicalizes the given @var{spec} (a specification). | |
| 982 | |
| 983 @var{specifier-type} specifies the type of specifier that this | |
| 984 @var{spec-list} will be used for. | |
| 985 | |
| 986 Canonicalizing means converting to the full form for a spec, i.e. | |
| 987 @code{(@var{locale} (@var{tag-set} . @var{instantiator}) ...)}. This | |
| 988 function accepts a possibly abbreviated inst-list or a cons of a locale | |
| 989 and a possibly abbreviated inst-list. (See | |
| 990 @code{canonicalize-inst-list}.) | |
| 991 | |
| 992 If @var{noerror} is @code{nil}, signal an error if the specification is | |
| 993 invalid; otherwise return @code{t}. | |
| 994 @end defun | |
| 995 | |
| 996 @defun canonicalize-spec-list spec-list specifier-type &optional noerror | |
| 997 This function canonicalizes the given @var{spec-list} (a list of | |
| 998 specifications). | |
| 999 | |
| 1000 @var{specifier-type} specifies the type of specifier that this | |
| 1001 @var{spec-list} will be used for. | |
| 1002 | |
| 1875 | 1003 If @var{noerror} is @code{nil}, signal an error if the spec-list is |
| 1004 invalid; otherwise return @code{t} for an invalid spec-list. (Note that | |
| 1005 this cannot be confused with a canonical spec-list.) | |
| 1006 | |
| 428 | 1007 Canonicalizing means converting to the full form for a spec-list, i.e. |
| 1008 @code{((@var{locale} (@var{tag-set} . @var{instantiator}) ...) ...)}. | |
| 1009 This function accepts a possibly abbreviated specification or a list of | |
| 1010 such things. (See @code{canonicalize-spec}.) This is the function used | |
| 1011 to convert spec-lists accepted by @code{set-specifier} and such into a | |
| 1012 form suitable for @code{add-spec-list-to-specifier}. | |
| 1013 | |
| 1014 This function tries extremely hard to resolve any ambiguities, | |
| 1015 and the built-in specifier types (font, image, toolbar, etc.) are | |
| 1016 designed so that there won't be any ambiguities. | |
| 1017 | |
| 1875 | 1018 The canonicalization algorithm is as follows: |
| 1019 | |
| 1020 @enumerate | |
| 1021 @item | |
| 1022 Attempt to parse @var{spec-list} as a single, possibly abbreviated, | |
| 1023 specification. | |
| 1024 @item | |
| 1025 If that fails, attempt to parse @var{spec-list} as a list of (abbreviated) | |
| 1026 specifications. | |
| 1027 @item | |
| 1028 If that fails, @var{spec-list} is invalid. | |
| 1029 @end enumerate | |
| 1030 | |
| 1031 A possibly abbreviated specification @var{spec} is parsed by | |
| 1032 | |
| 1033 @enumerate | |
| 1034 @item | |
| 1035 Attempt to parse @var{spec} as a possibly abbreviated inst-list. | |
| 1036 @item | |
| 1037 If that fails, attempt to parse @var{spec} as a cons of a locale and an | |
| 1038 (abbreviated) inst-list. | |
| 1039 @item | |
| 1040 If that fails, @var{spec} is invalid. | |
| 1041 @end enumerate | |
| 1042 | |
| 1043 A possibly abbreviated inst-list @var{inst-list} is parsed by | |
| 1044 | |
| 1045 @enumerate | |
| 1046 @item | |
| 1047 Attempt to parse @var{inst-list} as a possibly abbreviated inst-pair. | |
| 1048 @item | |
| 1049 If that fails, attempt to parse @var{inst-list} as a list of (abbreviated) | |
| 1050 inst-pairs. | |
| 1051 @item | |
| 1052 If that fails, @var{inst-list} is invalid. | |
| 1053 @end enumerate | |
| 1054 | |
| 1055 A possibly abbreviated inst-pair @var{inst-pair} is parsed by | |
| 1056 | |
| 1057 @enumerate | |
| 1058 @item | |
| 1059 Check if @var{inst-pair} is @code{valid-instantiator-p}. | |
| 1060 @item | |
| 1061 If not, check if @var{inst-pair} is a cons of something that is a tag, ie, | |
| 1062 @code{valid-specifier-tag-p}, and something that is @code{valid-instantiator-p}. | |
| 1063 @item | |
| 1064 If not, check if @var{inst-pair} is a cons of a list of tags and something that | |
| 1065 is @code{valid-instantiator-p}. | |
| 1066 @item | |
| 1067 Otherwise, @var{inst-pair} is invalid. | |
| 1068 @end enumerate | |
| 1069 | |
| 1070 In summary, this function generally prefers more abbreviated forms. | |
| 428 | 1071 @end defun |
| 1072 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5547
diff
changeset
|
1073 @node Retrieving Specifications, Specifier Tag Functions, Adding Specifications, Specifiers |
| 428 | 1074 @section Retrieving the Specifications from a Specifier |
| 1075 | |
| 1076 @defun specifier-spec-list specifier &optional locale tag-set exact-p | |
| 1077 This function returns the spec-list of specifications for | |
| 1078 @var{specifier} in @var{locale}. | |
| 1079 | |
| 1080 If @var{locale} is a particular locale (a window, buffer, frame, device, | |
| 1081 or the symbol @code{global}), a spec-list consisting of the | |
| 1082 specification for that locale will be returned. | |
| 1083 | |
| 444 | 1084 If @var{locale} is a locale type (i.e. one of the symbols @code{window}, |
| 428 | 1085 @code{buffer}, @code{frame}, or @code{device}), a spec-list of the |
| 1086 specifications for all locales of that type will be returned. | |
| 1087 | |
| 1088 If @var{locale} is @code{nil} or the symbol @code{all}, a spec-list of | |
| 1089 all specifications in @var{specifier} will be returned. | |
| 1090 | |
| 1091 @var{locale} can also be a list of locales, locale types, and/or | |
| 1092 @code{all}; the result is as if @code{specifier-spec-list} were called | |
| 1093 on each element of the list and the results concatenated together. | |
| 1094 | |
| 1095 Only instantiators where @var{tag-set} (a list of zero or more tags) is | |
| 1096 a subset of (or possibly equal to) the instantiator's tag set are | |
| 444 | 1097 returned. (The default value of @code{nil} is a subset of all tag sets, |
| 428 | 1098 so in this case no instantiators will be screened out.) If @var{exact-p} |
| 1099 is non-@code{nil}, however, @var{tag-set} must be equal to an | |
| 1100 instantiator's tag set for the instantiator to be returned. | |
| 1101 @end defun | |
| 1102 | |
| 1103 @defun specifier-specs specifier &optional locale tag-set exact-p | |
| 1104 This function returns the specification(s) for @var{specifier} in | |
| 1105 @var{locale}. | |
| 1106 | |
| 1107 If @var{locale} is a single locale or is a list of one element | |
| 1108 containing a single locale, then a ``short form'' of the instantiators | |
| 1109 for that locale will be returned. Otherwise, this function is identical | |
| 1110 to @code{specifier-spec-list}. | |
| 1111 | |
| 1112 The ``short form'' is designed for readability and not for ease of use | |
| 1113 in Lisp programs, and is as follows: | |
| 1114 | |
| 1115 @enumerate | |
| 1116 @item | |
| 1117 If there is only one instantiator, then an inst-pair (i.e. cons of tag | |
| 1118 and instantiator) will be returned; otherwise a list of inst-pairs will | |
| 1119 be returned. | |
| 1120 @item | |
| 1121 For each inst-pair returned, if the instantiator's tag is @code{any}, | |
| 1122 the tag will be removed and the instantiator itself will be returned | |
| 1123 instead of the inst-pair. | |
| 1124 @item | |
| 1125 If there is only one instantiator, its value is @code{nil}, and its tag | |
| 1126 is @code{any}, a one-element list containing @code{nil} will be returned | |
| 1127 rather than just @code{nil}, to distinguish this case from there being | |
| 1128 no instantiators at all. | |
| 1129 @end enumerate | |
| 1130 | |
| 1131 @end defun | |
| 1132 | |
| 1133 @defun specifier-fallback specifier | |
| 1134 This function returns the fallback value for @var{specifier}. Fallback | |
| 1135 values are provided by the C code for certain built-in specifiers to | |
| 2953 | 1136 make sure that instantiation won't fail even if all specs are removed from |
| 428 | 1137 the specifier, or to implement simple inheritance behavior (e.g. this |
| 1138 method is used to ensure that faces other than @code{default} inherit | |
| 1139 their attributes from @code{default}). By design, you cannot change the | |
| 1140 fallback value, and specifiers created with @code{make-specifier} will | |
| 1141 never have a fallback (although a similar, Lisp-accessible capability | |
| 1142 may be provided in the future to allow for inheritance). | |
| 1143 | |
| 2953 | 1144 The fallback value will be an inst-list that is instantiated like |
| 428 | 1145 any other inst-list, a specifier of the same type as @var{specifier} |
| 1146 (results in inheritance), or @code{nil} for no fallback. | |
| 1147 | |
| 2953 | 1148 When you instantiate a specifier, you can explicitly request that the |
| 428 | 1149 fallback not be consulted. (The C code does this, for example, when |
| 1150 merging faces.) See @code{specifier-instance}. | |
| 1151 @end defun | |
| 1152 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5547
diff
changeset
|
1153 @node Specifier Tag Functions, Specifier Instantiation Functions, Retrieving Specifications, Specifiers |
| 428 | 1154 @section Working With Specifier Tags |
| 1155 | |
| 1156 A specifier tag set is an entity that is attached to an instantiator | |
| 1157 and can be used to restrict the scope of that instantiator to a | |
| 1158 particular device class or device type and/or to mark instantiators | |
| 1159 added by a particular package so that they can be later removed. | |
| 1160 | |
| 442 | 1161 A specifier tag set consists of a list of zero or more specifier tags, |
| 428 | 1162 each of which is a symbol that is recognized by XEmacs as a tag. (The |
| 1163 valid device types and device classes are always tags, as are any tags | |
| 1164 defined by @code{define-specifier-tag}.) It is called a ``tag set'' (as | |
| 1165 opposed to a list) because the order of the tags or the number of times | |
| 1166 a particular tag occurs does not matter. | |
| 1167 | |
| 3674 | 1168 Each tag has a device predicate associated with it, which specifies whether |
| 428 | 1169 that tag applies to a particular device. The tags which are device |
| 1170 types and classes match devices of that type or class. User-defined | |
| 3674 | 1171 tags can have any device predicate, or none (meaning that all devices match). |
| 2953 | 1172 When attempting to instantiate a specifier, a particular instantiator is |
| 1173 only considered if the device of the domain being instantiated over matches | |
| 428 | 1174 all tags in the tag set attached to that instantiator. |
| 1175 | |
| 3674 | 1176 Each tag can also have a charset predicate, specifying whether that tag |
| 1177 applies to a particular charset. There are a few tags with predefined | |
| 1178 charset predicates created to allow sensible fallbacks in the face | |
| 1179 code---see the output of @code{(specifier-fallback (face-font | |
| 1180 'default))} for these. | |
| 1181 | |
| 428 | 1182 Most of the time, a tag set is not specified, and the instantiator gets |
| 3674 | 1183 a null tag set, which matches all devices and all character sets (when |
| 1184 possible; fonts with an inappropriate repertoire will not match, for | |
| 1185 example). | |
| 428 | 1186 |
| 1187 @defun valid-specifier-tag-p tag | |
| 1188 This function returns non-@code{nil} if @var{tag} is a valid specifier | |
| 1189 tag. | |
| 1190 @end defun | |
| 1191 | |
| 1192 @defun valid-specifier-tag-set-p tag-set | |
| 1193 This function returns non-@code{nil} if @var{tag-set} is a valid | |
| 1194 specifier tag set. | |
| 1195 @end defun | |
| 1196 | |
| 1197 @defun canonicalize-tag-set tag-set | |
| 1198 This function canonicalizes the given tag set. Two canonicalized tag | |
| 1199 sets can be compared with @code{equal} to see if they represent the same | |
| 1200 tag set. (Specifically, canonicalizing involves sorting by symbol name | |
| 1201 and removing duplicates.) | |
| 1202 @end defun | |
| 1203 | |
| 1204 @defun device-matches-specifier-tag-set-p device tag-set | |
| 1205 This function returns non-@code{nil} if @var{device} matches specifier | |
| 1206 tag set @var{tag-set}. This means that @var{device} matches each tag in | |
| 1207 the tag set. | |
| 1208 @end defun | |
| 1209 | |
| 3674 | 1210 @defun define-specifier-tag tag &optional device-predicate charset-predicate |
| 1211 This function defines a new specifier tag. If @var{device-predicate} is | |
| 428 | 1212 specified, it should be a function of one argument (a device) that |
| 1213 specifies whether the tag matches that particular device. If | |
| 3674 | 1214 @var{device-predicate} is omitted, the tag matches all devices. |
| 1215 | |
| 1216 If @var{charset-predicate} is specified, it should be a function taking | |
| 1217 one character set argument that specifies whether the tag matches that | |
| 1218 particular character set. | |
| 428 | 1219 |
| 1220 You can redefine an existing user-defined specifier tag. However, you | |
| 1221 cannot redefine the built-in specifier tags (the device types and | |
| 1222 classes) or the symbols @code{nil}, @code{t}, @code{all}, or | |
| 1223 @code{global}. | |
| 1224 @end defun | |
| 1225 | |
| 1226 @defun device-matching-specifier-tag-list &optional device | |
| 1227 This function returns a list of all specifier tags matching | |
| 1228 @var{device}. @var{device} defaults to the selected device if omitted. | |
| 1229 @end defun | |
| 1230 | |
| 1231 @defun specifier-tag-list | |
| 1232 This function returns a list of all currently-defined specifier tags. | |
| 1233 This includes the built-in ones (the device types and classes). | |
| 1234 @end defun | |
| 1235 | |
| 3674 | 1236 @defun specifier-tag-device-predicate tag |
| 1237 This function returns the device predicate for the given specifier tag. | |
| 1238 @end defun | |
| 1239 | |
| 1240 @defun specifier-tag-charset-predicate tag | |
| 1241 This function returns the charset predicate for the given specifier tag. | |
| 428 | 1242 @end defun |
| 1243 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5547
diff
changeset
|
1244 @node Specifier Instantiation Functions, Specifier Examples, Specifier Tag Functions, Specifiers |
| 2953 | 1245 @section Functions for Instantiating a Specifier |
| 428 | 1246 |
| 1247 @defun specifier-instance specifier &optional domain default no-fallback | |
| 1882 | 1248 This function instantiates @var{specifier} (returns its value) in |
| 428 | 1249 @var{domain}. If no instance can be generated for this domain, return |
| 1250 @var{default}. | |
| 1251 | |
| 1252 @var{domain} should be a window, frame, or device. Other values that | |
| 1253 are legal as a locale (e.g. a buffer) are not valid as a domain because | |
| 1254 they do not provide enough information to identify a particular device | |
| 1255 (see @code{valid-specifier-domain-p}). @var{domain} defaults to the | |
| 1256 selected window if omitted. | |
| 1257 | |
| 1258 @dfn{Instantiating} a specifier in a particular domain means determining | |
| 1259 the specifier's ``value'' in that domain. This is accomplished by | |
| 1260 searching through the specifications in the specifier that correspond to | |
| 1261 all locales that can be derived from the given domain, from specific to | |
| 1262 general. In most cases, the domain is an Emacs window. In that case | |
| 1263 specifications are searched for as follows: | |
| 1264 | |
| 1265 @enumerate | |
| 1266 @item | |
| 1267 A specification whose locale is the window itself; | |
| 1268 @item | |
| 1269 A specification whose locale is the window's buffer; | |
| 1270 @item | |
| 1271 A specification whose locale is the window's frame; | |
| 1272 @item | |
| 1273 A specification whose locale is the window's frame's device; | |
| 1274 @item | |
| 1275 A specification whose locale is the symbol @code{global}. | |
| 1276 @end enumerate | |
| 1277 | |
| 1278 If all of those fail, then the C-code-provided fallback value for this | |
| 1279 specifier is consulted (see @code{specifier-fallback}). If it is an | |
| 1280 inst-list, then this function attempts to instantiate that list just as | |
| 1281 when a specification is located in the first five steps above. If the | |
| 1282 fallback is a specifier, @code{specifier-instance} is called recursively | |
| 1283 on this specifier and the return value used. Note, however, that if the | |
| 1284 optional argument @var{no-fallback} is non-@code{nil}, the fallback | |
| 1285 value will not be consulted. | |
| 1286 | |
| 1287 Note that there may be more than one specification matching a particular | |
| 1288 locale; all such specifications are considered before looking for any | |
| 1289 specifications for more general locales. Any particular specification | |
| 1290 that is found may be rejected because it is tagged to a particular | |
| 1291 device class (e.g. @code{color}) or device type (e.g. @code{x}) or both | |
| 1292 and the device for the given domain does not match this, or because the | |
| 1293 specification is not valid for the device of the given domain (e.g. the | |
| 1294 font or color name does not exist for this particular X server). | |
| 1295 | |
| 1296 The returned value is dependent on the type of specifier. For example, | |
| 1297 for a font specifier (as returned by the @code{face-font} function), the | |
| 1298 returned value will be a font-instance object. For images, the returned | |
| 1299 value will be a string, pixmap, or subwindow. | |
| 1300 @end defun | |
| 1301 | |
| 1875 | 1302 @defun specifier-matching-instance specifier matchspec &optional domain default no-fallback |
| 1882 | 1303 This function returns an instance for @var{specifier} in @var{domain} |
| 1875 | 1304 that matches @var{matchspec}. If no instance can be generated for |
| 2028 | 1305 @var{domain}, return @var{default}. @xref{Specifier Compatibility Notes}. |
| 1875 | 1306 |
| 1307 This function is identical to @code{specifier-instance} except that a | |
| 1308 specification will only be considered if it matches @var{matchspec}. | |
| 1309 The definition of ``match,'' and allowed values for @var{matchspec}, are | |
| 1310 dependent on the particular type of specifier. Here are some examples: | |
| 1311 | |
| 1312 @itemize | |
| 1313 @item | |
| 1314 For chartable (e.g. display table) specifiers, @var{matchspec} should be a | |
| 1315 character, and the specification (a chartable) must give a value for | |
| 1316 that character in order to be considered. This allows you to specify, | |
| 1877 | 1317 @emph{e.g.}, a buffer-local display table that only gives values for particular |
| 1875 | 1318 characters. All other characters are handled as if the buffer-local |
| 1319 display table is not there. (Chartable specifiers are not yet | |
| 1320 implemented.) | |
| 1877 | 1321 @item |
| 1875 | 1322 For font specifiers, @var{matchspec} should be a list (@var{charset} |
| 3674 | 1323 . @var{stage}). On X11 the specification (a font string) should, for |
| 1324 clarity, have a registry that matches the charset's registry, but the | |
| 1325 redisplay code will specify the XLFD CHARSET_REGISTRY and | |
| 1326 CHARSET_ENCODING fields itself. This makes minimal sense without Mule | |
| 1327 support. @var{stage} can be one of the symbols @code{'initial} and | |
| 1328 @code{'final}; on X11, @code{'initial} means ``search for fonts using | |
| 1329 the charset registry of this charset'' and @code{'final} means ``search | |
| 1330 for fonts using `iso10646-1' as their charset registries, with the | |
| 1331 expectation that characters will be translated to Unicode at | |
| 1332 redisplay.'' Their meanings are similar on MS Windows, with the | |
| 1333 difference that the actual repertoire of the font is checked when | |
| 1334 deciding if a matchspec with @code{'final} matches. | |
| 1335 | |
| 1336 For example, the following code emulates what redisplay does when | |
| 1337 deciding what font to use for ethiopic with the default face (ignoring, | |
| 1338 for the moment, fallbacks): | |
| 1339 @example | |
| 1340 (or | |
| 1341 (specifier-matching-instance (face-font 'default) | |
| 1342 (cons 'ethiopic 'initial)) | |
| 1343 (specifier-matching-instance (face-font 'default) | |
| 1344 (cons 'ethiopic 'final))) | |
| 1345 @end example | |
| 1878 | 1346 @end itemize |
| 1875 | 1347 @end defun |
| 1348 | |
| 428 | 1349 @defun specifier-instance-from-inst-list specifier domain inst-list &optional default |
| 1350 This function attempts to convert a particular inst-list into an | |
| 1351 instance. This attempts to instantiate @var{inst-list} in the given | |
| 1352 @var{domain}, as if @var{inst-list} existed in a specification in | |
| 1353 @var{specifier}. If the instantiation fails, @var{default} is returned. | |
| 1354 In most circumstances, you should not use this function; use | |
| 1355 @code{specifier-instance} instead. | |
| 1356 @end defun | |
| 1357 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5547
diff
changeset
|
1358 @node Specifier Examples, Creating Specifiers, Specifier Instantiation Functions, Specifiers |
| 1869 | 1359 @section Examples of Specifier Usage |
| 428 | 1360 |
| 1361 Now let us present an example to clarify the theoretical discussions we | |
| 1362 have been through. In this example, we will use the general specifier | |
| 1363 functions for clarity. Keep in mind that many types of specifiers, and | |
| 1364 some other types of objects that are associated with specifiers | |
| 1365 (e.g. faces), provide convenience functions making it easier to work | |
| 1366 with objects of that type. | |
| 1367 | |
| 1368 Let us consider the background color of the default face. A specifier | |
| 1369 is used to specify how that color will appear in different domains. | |
| 1370 First, let's retrieve the specifier: | |
| 1371 | |
| 1372 @example | |
| 1373 (setq sp (face-property 'default 'background)) | |
| 1374 @result{} #<color-specifier 0x3da> | |
| 1375 @end example | |
| 1376 | |
| 1377 @example | |
| 1378 (specifier-specs sp) | |
| 1379 @result{} ((#<buffer "device.c"> (nil . "forest green")) | |
| 1380 (#<window on "Makefile" 0x8a2b> (nil . "hot pink")) | |
| 1381 (#<x-frame "emacs" 0x4ac> (nil . "puke orange") | |
| 440 | 1382 (nil . "moccasin")) |
| 428 | 1383 (#<x-frame "VM" 0x4ac> (nil . "magenta")) |
| 440 | 1384 (global ((tty) . "cyan") (nil . "white")) |
| 428 | 1385 ) |
| 1386 @end example | |
| 1387 | |
| 1388 Then, say we want to determine what the background color of the default | |
| 1389 face is for the window currently displaying the buffer @samp{*scratch*}. | |
| 1390 We call | |
| 1391 | |
| 1392 @example | |
| 1393 (get-buffer-window "*scratch*") | |
| 1394 @result{} #<window on "*scratch*" 0x4ad> | |
| 1395 (window-frame (get-buffer-window "*scratch*")) | |
| 1396 @result{} #<x-frame "emacs" 0x4ac> | |
| 1397 (specifier-instance sp (get-buffer-window "*scratch*")) | |
| 1398 @result{} #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x6309> | |
| 1399 @end example | |
| 1400 | |
| 1401 Note that we passed a window to @code{specifier-instance}, not a buffer. | |
| 1402 We cannot pass a buffer because a buffer by itself does not provide enough | |
| 1403 information. The buffer might not be displayed anywhere at all, or | |
| 1404 could be displayed in many different frames on different devices. | |
| 1405 | |
| 1406 The result is arrived at like this: | |
| 1407 | |
| 1408 @enumerate | |
| 1409 @item | |
| 1410 First, we look for a specification matching the buffer displayed in the | |
| 440 | 1411 window, i.e. @samp{*scratch*}. There are none, so we proceed. |
| 428 | 1412 @item |
| 1413 Then, we look for a specification matching the window itself. Again, there | |
| 1414 are none. | |
| 1415 @item | |
| 1416 Then, we look for a specification matching the window's frame. The | |
| 1417 specification @code{(#<x-frame "emacs" 0x4ac> . "puke orange")} is | |
| 1418 found. We call the instantiation method for colors, passing it the | |
| 1419 locale we were searching over (i.e. the window, in this case) and the | |
| 1420 instantiator (@samp{"puke orange"}). However, the particular device | |
| 1421 which this window is on (let's say it's an X connection) doesn't | |
| 1422 recognize the color @samp{"puke orange"}, so the specification is | |
| 1423 rejected. | |
| 1424 @item | |
| 1425 So we continue looking for a specification matching the window's frame. | |
| 1426 We find @samp{(#<x-frame "emacs" 0x4ac> . "moccasin")}. Again, we | |
| 1427 call the instantiation method for colors. This time, the X server | |
| 1428 our window is on recognizes the color @samp{moccasin}, and so the | |
| 1429 instantiation method succeeds and returns a color instance. | |
| 1430 @end enumerate | |
| 1431 | |
| 1869 | 1432 Here's another example, which implements something like GNU Emacs's |
| 1433 ``frame-local'' variables. | |
| 1434 | |
| 1435 @example | |
| 1436 ;; Implementation | |
| 1437 | |
| 1438 ;; There are probably better ways to write this macro | |
| 1439 ;; Heaven help you if VAR is a buffer-local; you will become very | |
| 1440 ;; confused. Probably should error on that. | |
| 1441 (defmacro define-frame-local-variable (var) | |
| 1442 "Make the unbound symbol VAR become a frame-local variable." | |
| 1443 (let ((val (if (boundp var) (symbol-value var) nil))) | |
| 1444 `(progn | |
| 1445 (setq ,var (make-specifier 'generic)) | |
| 1446 (add-spec-to-specifier ,var ',val 'global)))) | |
| 1447 | |
| 1448 ;; I'm not real happy about this terminology, how can `setq' be a defun? | |
| 1449 ;; But `frame-set' would have people writing "(frame-set 'foo value)". | |
| 1450 (defun frame-setq (var value &optional frame) | |
| 1451 "Set the local value of VAR to VALUE in FRAME. | |
| 1452 | |
| 1453 FRAME defaults to the selected frame." | |
| 1454 (and frame (not (framep frame)) | |
| 1455 (error 'invalid-argument "FRAME must be a frame", frame)) | |
| 1456 (add-spec-to-specifier var value (or frame (selected-frame)))) | |
| 1457 | |
| 1458 (defun frame-value (var &optional frame) | |
| 1459 "Get the local value of VAR in FRAME. | |
| 1460 | |
| 1461 FRAME defaults to the selected frame." | |
| 1462 (and frame (not (framep frame)) | |
| 1463 (error 'invalid-argument "FRAME must be a frame", frame)) | |
| 1464 ;; this is not just a map from frames to values; it also falls back | |
| 1465 ;; to the global value | |
| 1466 (specifier-instance var (or frame (selected-frame)))) | |
| 1467 | |
| 1468 ;; for completeness | |
| 1469 (defun frame-set-default (var value) | |
| 1470 "Set the default value of frame-local variable VAR to VALUE." | |
| 1471 (add-spec-to-specifier var value 'global)) | |
| 1472 | |
| 1473 (defun frame-get-default (var) | |
| 1474 "Get the default value of frame-local variable VAR." | |
| 1475 (car (specifier-specs var 'global))) | |
| 1476 @end example | |
| 1477 | |
| 1478 Now you can execute the above definitions (eg, with @code{eval-last-sexp}) | |
| 1479 and switch to @file{*scratch*} to play. Things will work differently if | |
| 1480 you already have a variable named @code{foo}. | |
| 1481 | |
| 1482 @example | |
| 1483 ;; Usage | |
| 1484 | |
| 1485 foo | |
| 1486 @error{} Symbol's value as variable is void: foo | |
| 1487 | |
| 1488 (define-frame-local-variable foo) | |
| 1489 @result{} nil | |
| 1490 | |
| 1491 ;; the value of foo is a specifier, which is an opaque object; | |
| 1492 ;; you must use accessor functions to get values | |
| 1493 | |
| 1494 foo | |
| 1495 @result{} #<generic-specifier global=(nil) 0x4f5cb> | |
| 1496 | |
| 1497 ;; since no frame-local value is set, the global value (which is the | |
| 1498 ;; constant `nil') is returned | |
| 1499 (frame-value foo) | |
| 1500 @result{} nil | |
| 1501 | |
| 1502 ;; get the default explicitly | |
| 1503 (frame-get-default foo) | |
| 1504 @result{} nil | |
| 1505 | |
| 1506 ;; get the whole specification list | |
| 1507 (specifier-specs foo 'global) | |
| 1508 @result{} (nil) | |
| 1509 | |
| 1510 ;; give foo a frame-local value | |
| 1511 | |
| 1512 (frame-setq foo 'bar) | |
| 1513 @result{} nil | |
| 1514 | |
| 1515 ;; access foo in several ways | |
| 1516 | |
| 1517 ;; Note that the print function for this kind of specifier only | |
| 1518 ;; gives you the global setting. To get the full list of specs for | |
| 1519 ;; debugging or study purposes, you must use specifier-specs or | |
| 1520 ;; specifier-spec-list. | |
| 1521 foo | |
| 1522 @result{} #<generic-specifier global=(nil) 0x4f5cb> | |
| 1523 | |
| 1524 ;; get the whole specification list | |
| 1525 (specifier-specs foo) | |
| 1526 @result{} ((#<x-frame "Message" 0x1bd66> (nil . bar)) (global (nil))) | |
| 1527 | |
| 1528 ;; get the frame-local value | |
| 1529 (frame-value foo) | |
| 1530 @result{} bar | |
| 1531 | |
| 1532 ;; get the default explicitly | |
| 1533 (frame-get-default foo) | |
| 1534 @result{} nil | |
| 1535 | |
| 1536 ;; Switch to another frame and evaluate: | |
| 1537 ;; C-x 5 o M-: (frame-setq foo 'baz) RET M-: (frame-value foo) RET | |
| 1538 @result{} baz | |
| 1539 | |
| 1540 ;; Switch back. | |
| 1541 ;; C-x 5 o | |
| 1542 (specifier-specs foo) | |
| 1543 @result{} ((#<x-frame "emacs" 0x28ec> (nil . baz)) | |
| 1544 (#<x-frame "Message" 0x1bd66> (nil . bar)) | |
| 1545 (global (nil))) | |
| 1546 | |
| 1547 (frame-value foo) | |
| 1548 @result{} bar | |
| 1549 | |
| 1550 (frame-get-default foo) | |
| 1551 @result{} nil | |
| 1552 @end example | |
| 1553 | |
| 1554 Note that since specifiers generalize both frame-local and buffer-local | |
| 1555 variables in a sensible way, XEmacs is not likely to put a high priority | |
| 2028 | 1556 on implementing frame-local variables @ref{Specifier Compatibility Notes}. |
| 1869 | 1557 |
| 1558 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5547
diff
changeset
|
1559 @node Creating Specifiers, Specifier Validation Functions, Specifier Examples, Specifiers |
| 428 | 1560 @section Creating New Specifier Objects |
| 1561 | |
| 1562 @defun make-specifier type | |
| 1563 This function creates a new specifier. | |
| 1564 | |
| 1565 A specifier is an object that can be used to keep track of a property | |
| 1566 whose value can be per-buffer, per-window, per-frame, or per-device, | |
| 1567 and can further be restricted to a particular device-type or device-class. | |
| 1568 Specifiers are used, for example, for the various built-in properties of a | |
| 1569 face; this allows a face to have different values in different frames, | |
| 444 | 1570 buffers, etc. For more information, see @code{specifier-instance}, |
| 1571 @code{specifier-specs}, and @code{add-spec-to-specifier}; or, for a detailed | |
| 428 | 1572 description of specifiers, including how they are instantiated over a |
| 1573 particular domain (i.e. how their value in that domain is determined), | |
| 1574 see the chapter on specifiers in the XEmacs Lisp Reference Manual. | |
| 1575 | |
| 1576 @var{type} specifies the particular type of specifier, and should be one | |
| 1577 of the symbols @code{generic}, @code{integer}, @code{natnum}, | |
| 1578 @code{boolean}, @code{color}, @code{font}, @code{image}, | |
| 1579 @code{face-boolean}, or @code{toolbar}. | |
| 1580 | |
| 1581 For more information on particular types of specifiers, see the | |
| 442 | 1582 functions @code{make-generic-specifier}, @code{make-integer-specifier}, |
| 1583 @code{make-natnum-specifier}, @code{make-boolean-specifier}, | |
| 1584 @code{make-color-specifier}, @code{make-font-specifier}, | |
| 1585 @code{make-image-specifier}, @code{make-face-boolean-specifier}, and | |
| 1586 @code{make-toolbar-specifier}. | |
| 428 | 1587 @end defun |
| 1588 | |
| 1589 @defun make-specifier-and-init type spec-list &optional dont-canonicalize | |
| 1875 | 1590 This function creates and initializes a new specifier. |
| 428 | 1591 |
| 1875 | 1592 This is a convenience API combining @code{make-specifier} and |
| 1593 @code{set-specifier} that allows you to create | |
| 428 | 1594 a specifier and add specs to it at the same time. @var{type} specifies |
| 1875 | 1595 the specifier type. Allowed types are as for @code{make-specifier}. |
| 1596 | |
| 1597 @var{spec-list} supplies the specification(s) to be | |
| 1598 added to the specifier. Any abbreviation of | |
| 1599 the full spec-list form accepted by @code{canonicalize-spec-list} may | |
| 1600 be used. | |
| 1601 However, if the optional argument @var{dont-canonicalize} is non-@code{nil}, | |
| 1602 canonicalization is not performed, and the @var{spec-list} must already | |
| 1603 be in full form. | |
| 428 | 1604 @end defun |
| 1605 | |
| 442 | 1606 @defun make-integer-specifier spec-list |
| 1607 | |
| 1608 Return a new @code{integer} specifier object with the given | |
| 1609 specification list. @var{spec-list} can be a list of specifications | |
| 1610 (each of which is a cons of a locale and a list of instantiators), a | |
| 1611 single instantiator, or a list of instantiators. | |
| 1612 | |
| 1613 Valid instantiators for integer specifiers are integers. | |
| 1614 @end defun | |
| 1615 | |
| 1616 @defun make-boolean-specifier spec-list | |
| 1617 | |
| 1618 Return a new @code{boolean} specifier object with the given | |
| 1619 specification list. @var{spec-list} can be a list of specifications | |
| 1620 (each of which is a cons of a locale and a list of instantiators), a | |
| 1621 single instantiator, or a list of instantiators. | |
| 1622 | |
| 1623 Valid instantiators for boolean specifiers are @code{t} and @code{nil}. | |
| 1624 @end defun | |
| 1625 | |
| 1626 @defun make-natnum-specifier spec-list | |
| 1627 | |
| 1628 Return a new @code{natnum} specifier object with the given specification | |
| 1629 list. @var{spec-list} can be a list of specifications (each of which is | |
| 1630 a cons of a locale and a list of instantiators), a single instantiator, | |
| 1631 or a list of instantiators. | |
| 1632 | |
| 1633 Valid instantiators for natnum specifiers are non-negative integers. | |
| 1634 @end defun | |
| 1635 | |
| 1636 @defun make-generic-specifier spec-list | |
| 1637 | |
| 1638 Return a new @code{generic} specifier object with the given | |
| 1639 specification list. @var{spec-list} can be a list of specifications | |
| 1640 (each of which is a cons of a locale and a list of instantiators), a | |
| 1641 single instantiator, or a list of instantiators. | |
| 1642 | |
| 1643 Valid instantiators for generic specifiers are all Lisp values. They | |
| 1644 are returned back unchanged when a specifier is instantiated. | |
| 1645 @end defun | |
| 1646 | |
| 1647 @defun make-display-table-specifier spec-list | |
| 1648 | |
| 1649 Return a new @code{display-table} specifier object with the given spec | |
| 1650 list. @var{spec-list} can be a list of specifications (each of which is | |
| 1651 a cons of a locale and a list of instantiators), a single instantiator, | |
| 1652 or a list of instantiators. | |
| 1653 | |
| 1654 Valid instantiators for display-table specifiers are described in detail | |
| 1655 in the doc string for @code{current-display-table} (@pxref{Active | |
| 1656 Display Table}). | |
| 1657 @end defun | |
| 1658 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5547
diff
changeset
|
1659 @node Specifier Validation Functions, Other Specification Functions, Creating Specifiers, Specifiers |
| 428 | 1660 @section Functions for Checking the Validity of Specifier Components |
| 1661 | |
| 1662 @defun valid-specifier-domain-p domain | |
| 1663 This function returns non-@code{nil} if @var{domain} is a valid | |
| 2953 | 1664 specifier domain. A domain is used to instantiate a specifier |
| 428 | 1665 (i.e. determine the specifier's value in that domain). Valid domains |
| 1666 are a window, frame, or device. (@code{nil} is not valid.) | |
| 1667 @end defun | |
| 1668 | |
| 1669 @defun valid-specifier-locale-p locale | |
| 1670 This function returns non-@code{nil} if @var{locale} is a valid | |
| 1671 specifier locale. Valid locales are a device, a frame, a window, a | |
| 1672 buffer, and @code{global}. (@code{nil} is not valid.) | |
| 1673 @end defun | |
| 1674 | |
| 1675 @defun valid-specifier-locale-type-p locale-type | |
| 444 | 1676 Given a specifier @var{locale-type}, this function returns non-@code{nil} if it |
| 428 | 1677 is valid. Valid locale types are the symbols @code{global}, |
| 1678 @code{device}, @code{frame}, @code{window}, and @code{buffer}. (Note, | |
| 1679 however, that in functions that accept either a locale or a locale type, | |
| 1680 @code{global} is considered an individual locale.) | |
| 1681 @end defun | |
| 1682 | |
| 1683 @defun valid-specifier-type-p specifier-type | |
| 1684 Given a @var{specifier-type}, this function returns non-@code{nil} if it | |
| 1685 is valid. Valid types are @code{generic}, @code{integer}, | |
| 1686 @code{boolean}, @code{color}, @code{font}, @code{image}, | |
| 1687 @code{face-boolean}, and @code{toolbar}. | |
| 1688 @end defun | |
| 1689 | |
| 1690 @defun valid-specifier-tag-p tag | |
| 1691 This function returns non-@code{nil} if @var{tag} is a valid specifier | |
| 1692 tag. | |
| 1693 @end defun | |
| 1694 | |
| 1695 @defun valid-instantiator-p instantiator specifier-type | |
| 1696 This function returns non-@code{nil} if @var{instantiator} is valid for | |
| 1697 @var{specifier-type}. | |
| 1698 @end defun | |
| 1699 | |
| 1700 @defun valid-inst-list-p inst-list type | |
| 1701 This function returns non-@code{nil} if @var{inst-list} is valid for | |
| 1702 specifier type @var{type}. | |
| 1703 @end defun | |
| 1704 | |
| 1705 @defun valid-spec-list-p spec-list type | |
| 1706 This function returns non-@code{nil} if @var{spec-list} is valid for | |
| 1707 specifier type @var{type}. | |
| 1708 @end defun | |
| 1709 | |
| 1710 @defun check-valid-instantiator instantiator specifier-type | |
| 1711 This function signals an error if @var{instantiator} is invalid for | |
| 1712 @var{specifier-type}. | |
| 1713 @end defun | |
| 1714 | |
| 1715 @defun check-valid-inst-list inst-list type | |
| 1716 This function signals an error if @var{inst-list} is invalid for | |
| 1717 specifier type @var{type}. | |
| 1718 @end defun | |
| 1719 | |
| 1720 @defun check-valid-spec-list spec-list type | |
| 1721 This function signals an error if @var{spec-list} is invalid for | |
| 1722 specifier type @var{type}. | |
| 1723 @end defun | |
| 1724 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5547
diff
changeset
|
1725 @node Other Specification Functions, Specifier Compatibility Notes, Specifier Validation Functions, Specifiers |
| 428 | 1726 @section Other Functions for Working with Specifications in a Specifier |
| 1727 | |
| 1728 @defun copy-specifier specifier &optional dest locale tag-set exact-p how-to-add | |
| 1729 This function copies @var{specifier} to @var{dest}, or creates a new one | |
| 1730 if @var{dest} is @code{nil}. | |
| 1731 | |
| 1732 If @var{dest} is @code{nil} or omitted, a new specifier will be created | |
| 1733 and the specifications copied into it. Otherwise, the specifications | |
| 1734 will be copied into the existing specifier in @var{dest}. | |
| 1735 | |
| 1736 If @var{locale} is @code{nil} or the symbol @code{all}, all | |
| 1737 specifications will be copied. If @var{locale} is a particular locale, | |
| 1738 the specification for that particular locale will be copied. If | |
| 1739 @var{locale} is a locale type, the specifications for all locales of | |
| 1740 that type will be copied. @var{locale} can also be a list of locales, | |
| 1741 locale types, and/or @code{all}; this is equivalent to calling | |
| 1742 @code{copy-specifier} for each of the elements of the list. See | |
| 1743 @code{specifier-spec-list} for more information about @var{locale}. | |
| 1744 | |
| 1745 Only instantiators where @var{tag-set} (a list of zero or more tags) is | |
| 1746 a subset of (or possibly equal to) the instantiator's tag set are | |
| 1747 copied. (The default value of @code{nil} is a subset of all tag sets, | |
| 1748 so in this case no instantiators will be screened out.) If @var{exact-p} | |
| 1749 is non-@code{nil}, however, @var{tag-set} must be equal to an | |
| 1750 instantiator's tag set for the instantiator to be copied. | |
| 1751 | |
| 1752 Optional argument @var{how-to-add} specifies what to do with existing | |
| 444 | 1753 specifications in @var{dest}. If @code{nil}, then whichever locales or locale |
| 428 | 1754 types are copied will first be completely erased in @var{dest}. |
| 1755 Otherwise, it is the same as in @code{add-spec-to-specifier}. | |
| 1756 @end defun | |
| 1757 | |
| 1758 @defun remove-specifier specifier &optional locale tag-set exact-p | |
| 1759 This function removes specification(s) for @var{specifier}. | |
| 1760 | |
| 1761 If @var{locale} is a particular locale (a buffer, window, frame, device, | |
| 1762 or the symbol @code{global}), the specification for that locale will be | |
| 1763 removed. | |
| 1764 | |
| 1765 If instead, @var{locale} is a locale type (i.e. a symbol @code{buffer}, | |
| 1766 @code{window}, @code{frame}, or @code{device}), the specifications for | |
| 1767 all locales of that type will be removed. | |
| 1768 | |
| 1769 If @var{locale} is @code{nil} or the symbol @code{all}, all | |
| 1770 specifications will be removed. | |
| 1771 | |
| 1772 @var{locale} can also be a list of locales, locale types, and/or | |
| 1773 @code{all}; this is equivalent to calling @code{remove-specifier} for | |
| 1774 each of the elements in the list. | |
| 1775 | |
| 1776 Only instantiators where @var{tag-set} (a list of zero or more tags) is | |
| 1777 a subset of (or possibly equal to) the instantiator's tag set are | |
| 1778 removed. (The default value of @code{nil} is a subset of all tag sets, | |
| 1779 so in this case no instantiators will be screened out.) If @var{exact-p} | |
| 1780 is non-@code{nil}, however, @var{tag-set} must be equal to an | |
| 1781 instantiator's tag set for the instantiator to be removed. | |
| 1782 @end defun | |
| 1783 | |
| 1784 @defun map-specifier specifier func &optional locale maparg | |
| 1785 This function applies @var{func} to the specification(s) for | |
| 1786 @var{locale} in @var{specifier}. | |
| 1787 | |
| 1875 | 1788 If optional @var{locale} is a locale, @var{func} will be called for that |
| 1789 locale. | |
| 428 | 1790 If @var{locale} is a locale type, @var{func} will be mapped over all |
| 1791 locales of that type. If @var{locale} is @code{nil} or the symbol | |
| 1792 @code{all}, @var{func} will be mapped over all locales in | |
| 1793 @var{specifier}. | |
| 1794 | |
| 1875 | 1795 Optional @var{ms-tag-set} and @var{ms-exact-p} are as in |
| 1796 @code{specifier-spec-list'}. | |
| 1797 Optional @var{ms-maparg} will be passed to @var{ms-func}. | |
| 1798 | |
| 428 | 1799 @var{func} is called with four arguments: the @var{specifier}, the |
| 1800 locale being mapped over, the inst-list for that locale, and the | |
| 1801 optional @var{maparg}. If any invocation of @var{func} returns | |
| 1802 non-@code{nil}, the mapping will stop and the returned value becomes the | |
| 1803 value returned from @code{map-specifier}. Otherwise, | |
| 1804 @code{map-specifier} returns @code{nil}. | |
| 1805 @end defun | |
| 1806 | |
| 1807 @defun specifier-locale-type-from-locale locale | |
| 1808 Given a specifier @var{locale}, this function returns its type. | |
| 1809 @end defun | |
| 2028 | 1810 |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5547
diff
changeset
|
1811 @node Specifier Compatibility Notes, , Other Specification Functions, Specifiers |
| 2028 | 1812 @section Specifier Compatibility Notes |
| 1813 | |
| 1814 This node describes compatibility issues in the use of specifiers known | |
| 1815 as of 2004-01-22. | |
| 1816 @c I considered basing the main text on 21.4, but then future | |
| 1817 @c maintenance of this documentation would be a pain. | |
| 1818 The main text refers to XEmacs 21.5.16. | |
| 1819 | |
| 1820 Effort will be made to describe changes in the API or semantics between | |
| 1821 XEmacs versions accurately. Any inaccuracy or missing information about | |
| 1822 backward and forward compatibility is a bug, and we greatly appreciate | |
| 1823 your reports, whether you can provide a patch or not. | |
| 1824 | |
| 1825 A change is reported as @dfn{changed} when we believe that the new or | |
| 1826 changed API will cause old code to malfunction. When old code is | |
| 1827 believed to be upward compatible with the changed API, the change is | |
| 1828 reported as @dfn{added}. | |
| 1829 | |
| 1830 We would like to also describe compatibility with GNU Emacs, but this is | |
| 1831 not so high a priority. Inaccuracies or omissions will be addressed at | |
| 1832 the priority of a feature request, and as such processing will be | |
| 1833 greatly expedited if you can provide a patch. | |
| 1834 @c #### xref here to bug reporting and patch submissions | |
| 1835 | |
| 1836 @c #### write and xref a file on compatibility policy | |
| 1837 | |
| 1838 @subsection Compatibility with GNU Emacs | |
| 1839 | |
| 1840 Specifiers are not used in GNU Emacs. If your program depends on | |
| 1841 specifers, you will probably have to rewrite the functionality | |
| 1842 completely for GNU Emacs. If you wish to maximize portability, you | |
| 1843 should plan to encapsulate use of specifiers. | |
| 1844 | |
| 1845 GNU Emacs provides two features for context-sensitive variables, | |
| 1846 buffer-local variables and frame-local variables. XEmacs implements | |
| 1847 buffer-local variables 100%-compatibly with GNU Emacs. If buffer-local | |
| 1848 variables will server your purpose and portability is a major concern, | |
| 1849 consider using them instead of specifiers. | |
| 1850 | |
| 1851 XEmacs does not implement frame-local variables at all. In this case | |
| 1852 specifiers must be used to provide equivalent functionality. | |
| 1853 | |
| 1854 It is not clear whether XEmacs will provide this feature in the future. | |
| 1855 @c Thanks to Jerry James for the following explanation. He is not | |
| 1856 @c responsible for its use here, Stephen Turnbull is. | |
| 1857 In fact, some core XEmacs developers think that both frame-local | |
| 1858 variables and buffer-local variables are evil, because the declaration | |
| 1859 is both global and invisible. That is, you cannot tell whether a | |
| 1860 variable is ``normal,'' buffer-local, or frame-local just by looking at | |
| 1861 it. So if you have namespace management problems, and some other Lisp | |
| 1862 package happens to use a variable name that you already declared frame- | |
| 1863 or buffer-local, weird stuff happens, and it is extremely hard to track | |
| 1864 down. | |
| 1865 @c #### Direct comments to xemacs-design? | |
| 1866 | |
| 1867 @subsection Backwards Compatibility with XEmacs 21.4 | |
| 1868 | |
| 1869 Sorry, I'm unwilling to find out exactly when these changes were made. | |
| 1870 | |
| 1871 Changed by 21.5.16: the second argument of | |
| 1872 @code{specifier-matching-instance} is now a cons of a charset and a | |
| 1873 boolean value. Previously it was a charset or a symbol (a name of a | |
| 1874 charset). It was not documented in Info. | |
| 1875 | |
| 1876 Changed by 21.5.16: the specifier-specific error symbols | |
| 1877 @code{specifier_syntax_error}, @code{specifier_argument_error}, and | |
| 1878 @code{specifier_change_error} were removed. (This probably only | |
| 1879 affected internal code.) | |
| 1880 | |
| 1881 Added by 21.5.16: @code{map-specifier} got two new arguments, | |
| 1882 @code{ms-tag-set} and @code{ms-exact-p}. | |
| 1883 | |
| 1884 Added by 21.5.16: when skipping instantiators, XEmacs warns at level | |
| 1885 `debug'. | |
| 1886 | |
| 1887 Added by 21.5.16: new convenience APIs: | |
| 1888 @code{instance-to-instantiator}, | |
| 1889 @code{device-type-matches-spec}, | |
| 1890 @code{add-tag-to-inst-list}, | |
| 1891 @code{derive-domain-from-locale}, | |
| 1892 @code{derive-device-type-from-tag-set}, | |
| 1893 @code{derive-device-type-from-locale-and-tag-set}, and | |
| 1894 @code{derive-specifier-specs-from-locale}. |