428
+ − 1 @c -*-texinfo-*-
+ − 2 @c This is part of the XEmacs Lisp Reference Manual.
+ − 3 @c Copyright (C) 1995, 1996 Ben Wing.
1135
+ − 4 @c Copyright (C) 2002 Free Software Foundation, Inc.
428
+ − 5 @c See the file lispref.texi for copying conditions.
+ − 6 @setfilename ../../info/specifiers.info
+ − 7 @node Specifiers, Faces and Window-System Objects, Extents, top
+ − 8 @chapter Specifiers
+ − 9 @cindex specifier
+ − 10
+ − 11 A specifier is an object used to keep track of a property whose value
1135
+ − 12 should vary according to @emph{display context}, a window, a frame, or
+ − 13 device. The value of many built-in properties, such as the font,
+ − 14 foreground, background, and such properties of a face and variables
+ − 15 such as @code{modeline-shadow-thickness} and
+ − 16 @code{top-toolbar-height}, is actually a specifier object. The
+ − 17 specifier object, in turn, is ``instanced'' in a particular situation
+ − 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.
+ − 31 * Specifier Instancing:: Instancing means obtaining the ``value'' of
+ − 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.
428
+ − 39 * Specifier Instancing Functions::
440
+ − 40 Functions to instance a specifier.
+ − 41 * Specifier Example:: Making all this stuff clearer.
+ − 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.
428
+ − 47 @end menu
+ − 48
+ − 49 @node Introduction to Specifiers
+ − 50 @section Introduction to Specifiers
+ − 51
1135
+ − 52 Perhaps the most useful way to explain specifiers is via an analogy.
+ − 53 Emacs Lisp programmers are used to @emph{buffer-local variables}
1138
+ − 54 @ref{Buffer-Local Variables}. For example, the variable
428
+ − 55 @code{modeline-format}, which controls the format of the modeline, can
+ − 56 have different values depending on the particular buffer being edited.
+ − 57 The variable has a default value which most modes will use, but a
1138
+ − 58 specialized package such as Calendar might change the variable so as to
+ − 59 tailor the modeline to its own purposes. Other variables are perhaps
+ − 60 best thought of as ``mode local,'' such as font-lock keywords, but they
+ − 61 are implemented as buffer locals.
428
+ − 62
+ − 63 Other properties (such as those that can be changed by the
+ − 64 @code{modify-frame-parameters} function, for example the color of the
+ − 65 text cursor) can have frame-local values, although it might also make
+ − 66 sense for them to have buffer-local values. In other cases, you might
+ − 67 want the property to vary depending on the particular window within the
+ − 68 frame that applies (e.g. the top or bottom window in a split frame), the
+ − 69 device type that that frame appears on (X or tty), etc. Perhaps you can
+ − 70 envision some more complicated scenario where you want a particular
+ − 71 value in a specified buffer, another value in all other buffers
+ − 72 displayed on a particular frame, another value in all other buffers
+ − 73 displayed in all other frames on any mono (two-color, e.g. black and
+ − 74 white only) displays, and a default value in all other circumstances.
+ − 75
1135
+ − 76 Specifiers generalize both buffer- and frame-local properties.
+ − 77 Specifiers vary according to the @emph{display} context. Font-lock
+ − 78 keywords in a buffer will be the same no matter which window the
+ − 79 buffer is displayed in, but windows on TTY devices will simply not be
+ − 80 capable of the flexibility that windows on modern GUI devices are.
+ − 81 Specifiers provide a way for the programmer to @emph{declare} that a
+ − 82 emphasized text should be italic on GUI devices and inverse video on
+ − 83 TTYs. They also provide a way for the programmer to declare
+ − 84 fallbacks, so that a color specified as ``chartreuse'' where possible
+ − 85 can fall back to ``yellow'' on devices where only ANSI (4-bit) color
+ − 86 is available. The complex calculations and device querying are
+ − 87 transparent to both user and programmer. You ask for what you want;
+ − 88 it's up to XEmacs to provide it, or a reasonable approximation.
+ − 89
+ − 90 We call such a declaration a @dfn{specification}. A @dfn{specification}
+ − 91 applies in a particular @dfn{locale}, which is a window, buffer, frame,
+ − 92 device, or the global locale. The value part of the specification is
+ − 93 called an @dfn{instantiator}. The process of determining the value in a
+ − 94 particular context, or @dfn{domain}, is called @dfn{instantiation} or
+ − 95 @dfn{instancing}. A domain is a window, frame, or device.
+ − 96
+ − 97 The difference between @dfn{locale} and @dfn{domain} is somewhat subtle.
+ − 98 You may think of a locale as a class of domains, which may span
+ − 99 different devices. Since the specification is abstract (a Lisp form),
+ − 100 you can state it without reference to a device. On the other hand, when
+ − 101 you instantiate a specification, you must know the type of the device.
+ − 102 It is useless to specify that ``blue mean italic'' on a monochrome
+ − 103 device. Thus instantiation requires specification of the device on
+ − 104 which it will be rendered.
+ − 105
+ − 106 Thus a @dfn{specifier} allows a great deal of flexibility in
+ − 107 controlling exactly what value a property has in which circumstances.
+ − 108 It is most commonly used for display properties, such as an image or
+ − 109 the foreground color of a face. As a simple example, you can specify
+ − 110 that the foreground of the default face be
428
+ − 111
+ − 112 @itemize @bullet
+ − 113 @item
+ − 114 blue for a particular buffer
+ − 115 @item
+ − 116 green for all other buffers
+ − 117 @end itemize
+ − 118
+ − 119 As a more complicated example, you could specify that the foreground of
+ − 120 the default face be
+ − 121
+ − 122 @itemize @bullet
+ − 123 @item
+ − 124 forest green for all buffers displayed in a particular Emacs window, or
+ − 125 green if the X server doesn't recognize the color @samp{forest green}
+ − 126 @item
+ − 127 blue for all buffers displayed in a particular frame
+ − 128 @item
+ − 129 red for all other buffers displayed on a color device
+ − 130 @item
+ − 131 white for all other buffers
+ − 132 @end itemize
+ − 133
1135
+ − 134 @node Simple Specifier Usage
+ − 135 @section Simple Specifier Usage
+ − 136 @cindex specifier examples
+ − 137 @cindex examples, specifier
+ − 138 @cindex adding a button to a toolbar
+ − 139 @cindex toolbar button, adding
+ − 140
+ − 141 A useful specifier application is adding a button to a toolbar. XEmacs
+ − 142 provides several toolbars, one along each edge of the frame. Normally
+ − 143 only one is used at a time, the default. The default toolbar is
+ − 144 actually a specifier object which is the value of @code{default-toolbar}.
+ − 145
+ − 146 The specification of a toolbar is simple: it is a list of buttons.
+ − 147 Each button is a vector with four elements: an icon, a command, the
+ − 148 enabled flag, and a help string. Let's retrieve the instance of the
+ − 149 toolbar you see in the selected frame.
+ − 150
+ − 151 @example
+ − 152 (specifier-instance default-toolbar)
+ − 153 @end example
+ − 154
+ − 155 The value returned is, as promised, a list of vectors. Now let's build
+ − 156 up a button, and add it to the toolbar. Our button will invoke the last
+ − 157 defined keyboard macro. This is an alternative to
+ − 158 @code{name-last-kbd-macro} for creating a persistent macro, rather than
+ − 159 an alias for @kbd{C-x e}.
+ − 160
+ − 161 A toolbar button icon can be quite sophisticated, with different images
+ − 162 for button up, button down, and disabled states, and a similar set with
+ − 163 captions. We'll use a very simple icon, but we have to jump through a
+ − 164 few non-obvious hoops designed to support the sophisticated applications.
+ − 165 The rest of the button descriptor is straightforward.
+ − 166
+ − 167 @example
+ − 168 (setq toolbar-my-kbd-macro-button
+ − 169 `[ (list (make-glyph "MyKbdMac"))
+ − 170 (lambda () (interactive) (execute-kbd-macro ,last-kbd-macro))
+ − 171 t
+ − 172 "Execute a previously defined keyboard macro." ])
+ − 173
+ − 174 (set-specifier default-toolbar
+ − 175 (cons toolbar-my-kbd-macro-button
+ − 176 (specifier-specs default-toolbar 'global))
+ − 177 'global)
+ − 178 @end example
+ − 179
+ − 180 To remove the button, just substitute the function @code{delete} for the
+ − 181 @code{cons} above.
+ − 182
+ − 183 What is the difference between @code{specifier-instance}, which we used
+ − 184 in the example of retrieving the toolbar descriptor, and
+ − 185 @code{specifier-specs}, which was used in the toolbar manipulating code?
+ − 186 @code{specifier-specs} retrieves a copy of the instantiator, which is
+ − 187 abstract and does not depend on context. @code{specifier-instance}, on
+ − 188 the other hand, actually instantiates the specification, and returns the
+ − 189 result for the given context. Another way to express this is:
+ − 190 @code{specifier-specs} takes a @emph{locale} as an argument, while
+ − 191 @code{specifier-instance} takes a @emph{domain}. The reason for
+ − 192 providing @code{specifier-instance} is that sometimes you wish to see
+ − 193 the object that XEmacs will actually use. @code{specifier-specs}, on
+ − 194 the other hand, shows you what the programmer (or user) requested. When
+ − 195 a program manipulates specifications, clearly it's the latter that is
+ − 196 desirable.
+ − 197
+ − 198 In the case of the toolbar descriptor, it turns out that these are the
+ − 199 same: the instancing process is trivial. However, many specifications
+ − 200 have non-trivial instancing. Compare the results of the following forms
+ − 201 on my system. (The @samp{(cdr (first ...))} form is due to my use of
+ − 202 Mule. On non-Mule XEmacsen, just use @code{specifier-specs}.)
+ − 203
+ − 204 @example
+ − 205 (cdr (first (specifier-specs (face-font 'default) 'global)))
+ − 206 => "-*--14-*jisx0208*-0"
+ − 207
+ − 208 (specifier-instance (face-font 'default))
+ − 209 #<font-instance "-*--14-*jisx0208*-0" on #<x-device on ":0.0" 0x970> 0xe0028b 0x176b>
+ − 210 @end example
+ − 211
+ − 212 In this case, @code{specifier-instance} returns an opaque object;
+ − 213 programs can't work on it, they can only pass it around. Worse, in some
+ − 214 environments the instantiation will fail, resulting in a different value
+ − 215 (when another instantiation succeeds), or worse yet, an error, if all
+ − 216 attempts to instance the specifier fail. @code{specifier-instance} is
+ − 217 context-dependent, even for the exact same specification.
+ − 218 @code{specifier-specs} is deterministic, and only depends on the
+ − 219 specifications.
+ − 220
+ − 221 Note that in the toolbar-changing code we operate in the global locale.
+ − 222 This means that narrower locales, if they have specifications, will
+ − 223 shadow our changes. (Specifier instancing does not merge
+ − 224 specifications. It selects the "highest-priority successful
+ − 225 specification" and instances that.)
+ − 226
+ − 227 In fact, in our example, it seems pretty likely that different buffers
+ − 228 @emph{should} have different buttons. (The icon can be the same, but
+ − 229 the keyboard macro you create in a Dired buffer is highly unlikely to be
+ − 230 useful in a LaTeX buffer!) Here's one way to implement this:
+ − 231
+ − 232 @example
+ − 233 (setq toolbar-my-kbd-macro-button
+ − 234 `[ (list (make-glyph "MyKbdMac"))
+ − 235 (lambda () (interactive) (execute-kbd-macro ,last-kbd-macro))
+ − 236 t
+ − 237 "Execute a previously defined keyboard macro." ])
+ − 238
+ − 239 (set-specifier default-toolbar
+ − 240 (cons toolbar-my-kbd-macro-button
+ − 241 (cond ((specifier-specs default-toolbar
+ − 242 (current-buffer)))
+ − 243 ((specifier-specs default-toolbar
+ − 244 'global)))
+ − 245 (current-buffer))
+ − 246 @end example
+ − 247
+ − 248 Finally, a cautionary note: the use of @code{specifier-specs} in the
+ − 249 code above is for expository purposes. Don't use it in production code.
+ − 250 In fact, the @code{set-specifier} form above is likely to fail
+ − 251 occasionally, because you can add many specifications for the same
+ − 252 locale.
+ − 253
+ − 254 In these cases, @code{specifier-specs} will return a list. A further
+ − 255 refinement is that a specification may be associated with a set of
+ − 256 @dfn{specifier tags}. If the list of specifier tags is non-nil, then
+ − 257 @code{specifier-specs} will return a cons of the tag set and the
+ − 258 instantiator. Evidently @code{specifier-specs} is a bit unreliable.
+ − 259 (For toolbars, the code above should work 99% of the time, because
+ − 260 toolbars are rarely changed. Since instantiation is trivial, multiple
+ − 261 specs are not useful---the first one always succeeds.)
+ − 262
+ − 263 In fact, @code{specifier-specs} is intended to be used to display specs
1138
+ − 264 to humans with a minimum of clutter. The robust way to access
+ − 265 specifications is via @code{specifier-spec-list}. @xref{Adding
+ − 266 Specifications}, for the definition of @dfn{spec-list}. @xref{Retrieving
+ − 267 Specifications}, for documentation of @code{specifier-specs} and
+ − 268 @code{specifier-spec-list}. To get the desired effect, replace the form
+ − 269 @code{(specifier-spec default-toolbar 'global)} with
1135
+ − 270
+ − 271 @example
+ − 272 (cdr (second (first (specifier-spec-list default-toolbar 'global))))
+ − 273 @end example
+ − 274
+ − 275 (It should be obvious why the example uses the lazy unreliable method!)
+ − 276
428
+ − 277 @node Specifiers In-Depth
+ − 278 @section In-Depth Overview of a Specifier
+ − 279 @cindex specification (in a specifier)
+ − 280 @cindex domain (in a specifier)
+ − 281 @cindex locale (in a specifier)
+ − 282 @cindex instantiator (in a specifier)
+ − 283 @cindex instancing (in a specifier)
+ − 284 @cindex instance (in a specifier)
+ − 285 @cindex inst-list (in a specifier)
+ − 286 @cindex inst-pair (in a specifier)
+ − 287 @cindex tag (in a specifier)
+ − 288 @cindex tag set (in a specifier)
+ − 289 @cindex specifier, specification
+ − 290 @cindex specifier, domain
+ − 291 @cindex specifier, locale
+ − 292 @cindex specifier, instantiator
+ − 293 @cindex specifier, instancing
+ − 294 @cindex specifier, instance
+ − 295 @cindex specifier, inst-list
+ − 296 @cindex specifier, inst-pair
+ − 297 @cindex specifier, tag
+ − 298 @cindex specifier, tag set
+ − 299
1135
+ − 300 Having variables vary according the editing context is very useful, and
+ − 301 the buffer is the natural ``atomic'' unit of editing context. In a GUI
+ − 302 environment, it can be similarly useful to have variables whose values
+ − 303 vary according to display context. The atomic unit of display context
+ − 304 is the Emacs window. Buffers are cleanly grouped by modes, but windows
+ − 305 are not so easily pigeonholed. On the one hand, a window displays a
+ − 306 buffer, and thus one possible hierarchy is window, buffer, mode. On the
+ − 307 other, a window is a component of a frame. This generates the window,
+ − 308 frame, device hierarchy. Finally, there are objects such as toolbars
+ − 309 whose properties are described by specifiers. These do not fit
+ − 310 naturally into either hierarchy. This problem is as yet not cleanly
+ − 311 solved.
+ − 312
+ − 313 Another potential source of conceptual confusion is the instantiation
+ − 314 process. Instantiating a buffer-local variable is simple: at any given
+ − 315 point in time there is a current buffer, and its local values are used
+ − 316 and set whenever the variable is accessed, unless the programmer goes to
+ − 317 some special effort (uses @code{default-value} and @code{set-default}.
+ − 318 However, a specifier object encapsulates a set of @dfn{specifications},
+ − 319 each of which says what its value should be if a particular condition
+ − 320 applies. Several such conditions might apply simultaneously in a given
+ − 321 window.
+ − 322
428
+ − 323 For example, one specification might be ``The value should be
+ − 324 darkseagreen2 on X devices'' another might be ``The value should be blue
1135
+ − 325 in the *Help* buffer''. So what do we do for "the *Help* buffer on an X
+ − 326 device"? The answer is simple: give each type of locale a priority and
+ − 327 check them in priority order, returning the first instantiator that
+ − 328 successfully instantiates a value.
+ − 329
428
+ − 330 Given a specifier, a logical question is ``What is its value in a
+ − 331 particular situation?'' This involves looking through the specifications
+ − 332 to see which ones apply to this particular situation, and perhaps
+ − 333 preferring one over another if more than one applies. In specifier
+ − 334 terminology, a ``particular situation'' is called a @dfn{domain}, and
+ − 335 determining its value in a particular domain is called @dfn{instancing}.
+ − 336 Most of the time, a domain is identified by a particular window. For
+ − 337 example, if the redisplay engine is drawing text in the default face in
+ − 338 a particular window, it retrieves the specifier for the foreground color
+ − 339 of the default face and @dfn{instances} it in the domain given by that
+ − 340 window; in other words, it asks the specifier, ``What is your value in
+ − 341 this window?''.
+ − 342
1135
+ − 343 Note that the redisplay example is in a sense canonical. That is,
+ − 344 specifiers are designed to present a uniform and @emph{efficient} API
+ − 345 to redisplay. It is the efficiency constraint that motivates the
+ − 346 introduction of specifier tags, and many restrictions on access (for
+ − 347 example, a buffer is not a domain, and you cannot instantiate a
+ − 348 specifier over a buffer).
+ − 349
428
+ − 350 More specifically, a specifier contains a set of @dfn{specifications},
+ − 351 each of which associates a @dfn{locale} (a window object, a buffer
+ − 352 object, a frame object, a device object, or the symbol @code{global})
+ − 353 with an @dfn{inst-list}, which is a list of one or more
+ − 354 @dfn{inst-pairs}. (For each possible locale, there can be at most one
+ − 355 specification containing that locale.) Each inst-pair is a cons of a
+ − 356 @dfn{tag set} (an unordered list of zero or more symbols, or @dfn{tags})
+ − 357 and an @dfn{instantiator} (the allowed form of this varies depending on
+ − 358 the type of specifier). In a given specification, there may be more
+ − 359 than one inst-pair with the same tag set; this is unlike for locales.
+ − 360
+ − 361 The tag set is used to restrict the sorts of devices over which the
+ − 362 instantiator is valid and to uniquely identify instantiators added by a
+ − 363 particular application, so that different applications can work on the
+ − 364 same specifier and not interfere with each other. Each tag can have a
+ − 365 @dfn{predicate} associated with it, which is a function of one argument
+ − 366 (a device) that specifies whether the tag matches that particular
+ − 367 device. (If a tag does not have a predicate, it matches all devices.)
+ − 368 All tags in a tag set must match a device for the associated inst-pair
+ − 369 to be instantiable over that device. (A null tag set is perfectly
1135
+ − 370 valid, and trivially matches all devices.)
428
+ − 371
1135
+ − 372 @c #### don't we have more device types now, gtk, ms-windows, mac-carbon?
428
+ − 373 The valid device types (normally @code{x}, @code{tty}, and
+ − 374 @code{stream}) and device classes (normally @code{color},
+ − 375 @code{grayscale}, and @code{mono}) can always be used as tags, and match
+ − 376 devices of the associated type or class (@pxref{Consoles and Devices}).
+ − 377 User-defined tags may be defined, with an optional predicate specified.
+ − 378 An application can create its own tag, use it to mark all its
+ − 379 instantiators, and be fairly confident that it will not interfere with
440
+ − 380 other applications that modify the same specifier---Functions that add
428
+ − 381 a specification to a specifier usually only overwrite existing
+ − 382 inst-pairs with the same tag set as was given, and a particular tag or
+ − 383 tag set can be specified when removing instantiators.
+ − 384
+ − 385 When a specifier is instanced in a domain, both the locale and the tag
+ − 386 set can be viewed as specifying necessary conditions that must apply in
+ − 387 that domain for an instantiator to be considered as a possible result of
+ − 388 the instancing. More specific locales always override more general
+ − 389 locales (thus, there is no particular ordering of the specifications in
+ − 390 a specifier); however, the tag sets are simply considered in the order
+ − 391 that the inst-pairs occur in the specification's inst-list.
+ − 392
+ − 393 Note also that the actual object that results from the instancing
+ − 394 (called an @dfn{instance object}) may not be the same as the instantiator
+ − 395 from which it was derived. For some specifier types (such as integer
+ − 396 specifiers and boolean specifiers), the instantiator will be returned
+ − 397 directly as the instance object. For other types, however, this
+ − 398 is not the case. For example, for font specifiers, the instantiator
+ − 399 is a font-description string and the instance object is a font-instance
+ − 400 object, which describes how the font is displayed on a particular device.
+ − 401 A font-instance object encapsulates such things as the actual font name
+ − 402 used to display the font on that device (a font-description string
+ − 403 under X is usually a wildcard specification that may resolve to
+ − 404 different font names, with possibly different foundries, widths, etc.,
+ − 405 on different devices), the extra properties of that font on that
+ − 406 device, etc. Furthermore, this conversion (called @dfn{instantiation})
440
+ − 407 might fail---a font or color might not exist on a particular device,
428
+ − 408 for example.
+ − 409
+ − 410 @node Specifier Instancing
+ − 411 @section How a Specifier Is Instanced
+ − 412 @cindex fallback (in a specifier)
+ − 413 @cindex specifier, fallback
+ − 414
+ − 415 Instancing of a specifier in a particular window domain proceeds as
+ − 416 follows:
+ − 417
+ − 418 @itemize @bullet
+ − 419 @item
+ − 420 First, XEmacs searches for a specification whose locale is the same as
+ − 421 the window. If that fails, the search is repeated, looking for a locale
+ − 422 that is the same as the window's buffer. If that fails, the search is
+ − 423 repeated using the window's frame, then using the device that frame is
+ − 424 on. Finally, the specification whose locale is the symbol @code{global}
+ − 425 (if there is such a specification) is considered.
+ − 426 @item
+ − 427 The inst-pairs contained in the specification that was found are
+ − 428 considered in their order in the inst-list, looking for one whose tag
+ − 429 set matches the device that is derived from the window domain. (The
+ − 430 tag set is an unordered list of zero or more tag symbols. For all
+ − 431 tags that have predicates associated with them, the predicate must
+ − 432 match the device.)
+ − 433 @item
+ − 434 If a matching tag set is found, the corresponding instantiator is passed
+ − 435 to the specifier's instantiation method, which is specific to the type
+ − 436 of the specifier. If it succeeds, the resulting instance object is
+ − 437 returned as the result of the instancing and the instancing is done.
+ − 438 Otherwise, the operation continues, looking for another matching
+ − 439 inst-pair in the current specification.
+ − 440 @item
+ − 441 When there are no more inst-pairs to be considered in the current
+ − 442 specification, the search starts over, looking for another specification
+ − 443 as in the first step above.
+ − 444 @item
+ − 445 If all specifications are exhausted and no instance object can be
+ − 446 derived, the instancing fails. (Actually, this is not completely true.
+ − 447 Some specifier objects for built-in properties have a @dfn{fallback}
+ − 448 value, which is either an inst-list or another specifier object, that is
+ − 449 consulted if the instancing is about to fail. If it is an inst-list,
+ − 450 the searching proceeds using the inst-pairs in that list. If it is a
+ − 451 specifier, the entire instancing starts over using that specifier
+ − 452 instead of the given one. Fallback values are set by the C code and
+ − 453 cannot be modified, except perhaps indirectly, using any Lisp functions.
+ − 454 The purpose of them is to supply some values to make sure that
+ − 455 instancing of built-in properties can't fail and to implement some basic
+ − 456 specifier inheritance, such as the fact that faces inherit their
+ − 457 properties from the @code{default} face.)
+ − 458 @end itemize
+ − 459
+ − 460 It is also possible to instance a specifier over a frame domain or
+ − 461 device domain instead of over a window domain. The C code, for example,
+ − 462 instances the @code{top-toolbar-height} variable over a frame domain in
+ − 463 order to determine the height of a frame's top toolbar. Instancing over
+ − 464 a frame or device is similar to instancing over a window except that
+ − 465 specifications for locales that cannot be derived from the domain are
+ − 466 ignored. Specifically, instancing over a frame looks first for frame
+ − 467 locales, then device locales, then the @code{global} locale. Instancing
+ − 468 over a device domain looks only for device locales and the @code{global}
+ − 469 locale.
+ − 470
+ − 471 @node Specifier Types
+ − 472 @section Specifier Types
+ − 473
+ − 474 There are various different types of specifiers. The type of a
+ − 475 specifier controls what sorts of instantiators are valid, how an
+ − 476 instantiator is instantiated, etc. Here is a list of built-in specifier
+ − 477 types:
+ − 478
+ − 479 @table @code
+ − 480 @item boolean
+ − 481 The valid instantiators are the symbols @code{t} and @code{nil}.
+ − 482 Instance objects are the same as instantiators so no special
+ − 483 instantiation function is needed.
+ − 484
+ − 485 @item integer
+ − 486 The valid instantiators are integers. Instance objects are the same as
+ − 487 instantiators so no special instantiation function is needed.
+ − 488 @code{modeline-shadow-thickness} is an example of an integer specifier
+ − 489 (negative thicknesses indicate that the shadow is drawn recessed instead
+ − 490 of raised).
+ − 491
+ − 492 @item natnum
+ − 493 The valid instantiators are natnums (non-negative integers). Instance
+ − 494 objects are the same as instantiators so no special instantiation
+ − 495 function is needed. Natnum specifiers are used for dimension variables
+ − 496 such as @code{top-toolbar-height}.
+ − 497
+ − 498 @item generic
+ − 499 All Lisp objects are valid instantiators. Instance objects are the same
+ − 500 as instantiators so no special instantiation function is needed.
+ − 501
+ − 502 @item font
+ − 503 The valid instantiators are strings describing fonts or vectors
+ − 504 indicating inheritance from the font of some face. Instance objects are
+ − 505 font-instance objects, which are specific to a particular device. The
+ − 506 instantiation method for font specifiers can fail, unlike for integer,
+ − 507 natnum, boolean, and generic specifiers.
+ − 508
+ − 509 @item color
+ − 510 The valid instantiators are strings describing colors or vectors
+ − 511 indicating inheritance from the foreground or background of some face.
+ − 512 Instance objects are color-instance objects, which are specific to a
+ − 513 particular device. The instantiation method for color specifiers can fail,
+ − 514 as for font specifiers.
+ − 515
+ − 516 @item image
+ − 517 Images are perhaps the most complicated type of built-in specifier. The
+ − 518 valid instantiators are strings (a filename, inline data for a pixmap,
+ − 519 or text to be displayed in a text glyph) or vectors describing inline
+ − 520 data of various sorts or indicating inheritance from the
+ − 521 background-pixmap property of some face. Instance objects are either
+ − 522 strings (for text images), image-instance objects (for pixmap images),
+ − 523 or subwindow objects (for subwindow images). The instantiation method
+ − 524 for image specifiers can fail, as for font and color specifiers.
+ − 525
+ − 526 @item face-boolean
+ − 527 The valid instantiators are the symbols @code{t} and @code{nil} and
+ − 528 vectors indicating inheritance from a boolean property of some face.
+ − 529 Specifiers of this sort are used for all of the built-in boolean
+ − 530 properties of faces. Instance objects are either the symbol @code{t}
+ − 531 or the symbol @code{nil}.
+ − 532
+ − 533 @item toolbar
+ − 534 The valid instantiators are toolbar descriptors, which are lists
+ − 535 of toolbar-button descriptors (each of which is a vector of two
+ − 536 or four elements). @xref{Toolbar}, for more information.
+ − 537 @end table
+ − 538
+ − 539 Color and font instance objects can also be used in turn as
+ − 540 instantiators for a new color or font instance object. Since these
+ − 541 instance objects are device-specific, the instantiator can be used
+ − 542 directly as the new instance object, but only if they are of the same
+ − 543 device. If the devices differ, the base color or font of the
+ − 544 instantiating object is effectively used instead as the instantiator.
+ − 545
+ − 546 @xref{Faces and Window-System Objects}, for more information on fonts,
+ − 547 colors, and face-boolean specifiers. @xref{Glyphs}, for more information
+ − 548 about image specifiers. @xref{Toolbar}, for more information on toolbar
+ − 549 specifiers.
+ − 550
+ − 551 @defun specifier-type specifier
+ − 552 This function returns the type of @var{specifier}. The returned value
+ − 553 will be a symbol: one of @code{integer}, @code{boolean}, etc., as
+ − 554 listed in the above table.
+ − 555 @end defun
+ − 556
+ − 557 Functions are also provided to query whether an object is a particular
+ − 558 kind of specifier:
+ − 559
+ − 560 @defun boolean-specifier-p object
+ − 561 This function returns non-@code{nil} if @var{object} is a boolean
+ − 562 specifier.
+ − 563 @end defun
+ − 564
+ − 565 @defun integer-specifier-p object
+ − 566 This function returns non-@code{nil} if @var{object} is an integer
+ − 567 specifier.
+ − 568 @end defun
+ − 569
+ − 570 @defun natnum-specifier-p object
+ − 571 This function returns non-@code{nil} if @var{object} is a natnum
+ − 572 specifier.
+ − 573 @end defun
+ − 574
+ − 575 @defun generic-specifier-p object
+ − 576 This function returns non-@code{nil} if @var{object} is a generic
+ − 577 specifier.
+ − 578 @end defun
+ − 579
+ − 580 @defun face-boolean-specifier-p object
+ − 581 This function returns non-@code{nil} if @var{object} is a face-boolean
+ − 582 specifier.
+ − 583 @end defun
+ − 584
+ − 585 @defun toolbar-specifier-p object
+ − 586 This function returns non-@code{nil} if @var{object} is a toolbar
+ − 587 specifier.
+ − 588 @end defun
+ − 589
+ − 590 @defun font-specifier-p object
+ − 591 This function returns non-@code{nil} if @var{object} is a font
+ − 592 specifier.
+ − 593 @end defun
+ − 594
+ − 595 @defun color-specifier-p object
+ − 596 This function returns non-@code{nil} if @var{object} is a color
+ − 597 specifier.
+ − 598 @end defun
+ − 599
+ − 600 @defun image-specifier-p object
+ − 601 This function returns non-@code{nil} if @var{object} is an image
+ − 602 specifier.
+ − 603 @end defun
+ − 604
+ − 605 @node Adding Specifications
+ − 606 @section Adding specifications to a Specifier
+ − 607
+ − 608 @defun add-spec-to-specifier specifier instantiator &optional locale tag-set how-to-add
+ − 609 This function adds a specification to @var{specifier}. The
+ − 610 specification maps from @var{locale} (which should be a window, buffer,
+ − 611 frame, device, or the symbol @code{global}, and defaults to
+ − 612 @code{global}) to @var{instantiator}, whose allowed values depend on the
+ − 613 type of the specifier. Optional argument @var{tag-set} limits the
+ − 614 instantiator to apply only to the specified tag set, which should be a
+ − 615 list of tags all of which must match the device being instantiated over
+ − 616 (tags are a device type, a device class, or tags defined with
+ − 617 @code{define-specifier-tag}). Specifying a single symbol for
+ − 618 @var{tag-set} is equivalent to specifying a one-element list containing
+ − 619 that symbol. Optional argument @var{how-to-add} specifies what to do if
+ − 620 there are already specifications in the specifier. It should be one of
+ − 621
+ − 622 @table @code
+ − 623 @item prepend
+ − 624 Put at the beginning of the current list of instantiators for @var{locale}.
+ − 625 @item append
+ − 626 Add to the end of the current list of instantiators for @var{locale}.
+ − 627 @item remove-tag-set-prepend
+ − 628 This is the default. Remove any existing instantiators whose tag set is
+ − 629 the same as @var{tag-set}; then put the new instantiator at the
+ − 630 beginning of the current list.
+ − 631 @item remove-tag-set-append
+ − 632 Remove any existing instantiators whose tag set is the same as
+ − 633 @var{tag-set}; then put the new instantiator at the end of the current
+ − 634 list.
+ − 635 @item remove-locale
+ − 636 Remove all previous instantiators for this locale before adding the new
+ − 637 spec.
+ − 638 @item remove-locale-type
+ − 639 Remove all specifications for all locales of the same type as
+ − 640 @var{locale} (this includes @var{locale} itself) before adding the new
+ − 641 spec.
+ − 642 @item remove-all
+ − 643 Remove all specifications from the specifier before adding the new spec.
+ − 644 @end table
+ − 645
+ − 646 @code{remove-tag-set-prepend} is the default.
+ − 647
+ − 648 You can retrieve the specifications for a particular locale or locale type
+ − 649 with the function @code{specifier-spec-list} or @code{specifier-specs}.
+ − 650 @end defun
+ − 651
+ − 652 @defun add-spec-list-to-specifier specifier spec-list &optional how-to-add
+ − 653 This function adds a @dfn{spec-list} (a list of specifications) to
+ − 654 @var{specifier}. The format of a spec-list is
+ − 655
+ − 656 @example
+ − 657 @code{((@var{locale} (@var{tag-set} . @var{instantiator}) ...) ...)}
+ − 658 @end example
+ − 659
+ − 660 where
+ − 661
+ − 662 @itemize @bullet
+ − 663 @item
+ − 664 @var{locale} := a window, a buffer, a frame, a device, or @code{global}
+ − 665 @item
+ − 666 @var{tag-set} := an unordered list of zero or more @var{tags}, each of
+ − 667 which is a symbol
+ − 668 @item
+ − 669 @var{tag} := a device class (@pxref{Consoles and Devices}), a device type,
+ − 670 or a tag defined with @code{define-specifier-tag}
+ − 671 @item
+ − 672 @var{instantiator} := format determined by the type of specifier
+ − 673 @end itemize
+ − 674
+ − 675 The pair @code{(@var{tag-set} . @var{instantiator})} is called an
+ − 676 @dfn{inst-pair}. A list of inst-pairs is called an @dfn{inst-list}.
+ − 677 The pair @code{(@var{locale} . @var{inst-list})} is called a
+ − 678 @dfn{specification}. A spec-list, then, can be viewed as a list of
+ − 679 specifications.
+ − 680
+ − 681 @var{how-to-add} specifies how to combine the new specifications with
+ − 682 the existing ones, and has the same semantics as for
+ − 683 @code{add-spec-to-specifier}.
+ − 684
+ − 685 In many circumstances, the higher-level function @code{set-specifier} is
+ − 686 more convenient and should be used instead.
+ − 687 @end defun
+ − 688
444
+ − 689 @defspec let-specifier specifier-list &rest body
428
+ − 690 This special form temporarily adds specifications to specifiers,
+ − 691 evaluates forms in @var{body} and restores the specifiers to their
+ − 692 previous states. The specifiers and their temporary specifications are
+ − 693 listed in @var{specifier-list}.
+ − 694
+ − 695 The format of @var{specifier-list} is
+ − 696
+ − 697 @example
+ − 698 ((@var{specifier} @var{value} &optional @var{locale} @var{tag-set} @var{how-to-add}) ...)
+ − 699 @end example
+ − 700
+ − 701 @var{specifier} is the specifier to be temporarily modified.
+ − 702 @var{value} is the instantiator to be temporarily added to specifier in
+ − 703 @var{locale}. @var{locale}, @var{tag-set} and @var{how-to-add} have the
+ − 704 same meaning as in @code{add-spec-to-specifier}.
+ − 705
+ − 706 This special form is implemented as a macro; the code resulting from
+ − 707 macro expansion will add specifications to specifiers using
+ − 708 @code{add-spec-to-specifier}. After forms in @var{body} are evaluated,
+ − 709 the temporary specifications are removed and old specifier spec-lists
+ − 710 are restored.
+ − 711
+ − 712 @var{locale}, @var{tag-set} and @var{how-to-add} may be omitted, and
+ − 713 default to @code{nil}. The value of the last form in @var{body} is
+ − 714 returned.
+ − 715
+ − 716 NOTE: If you want the specifier's instance to change in all
+ − 717 circumstances, use @code{(selected-window)} as the @var{locale}. If
+ − 718 @var{locale} is @code{nil} or omitted, it defaults to @code{global}.
+ − 719
+ − 720 The following example removes the 3D modeline effect in the currently
+ − 721 selected window for the duration of a second:
+ − 722
+ − 723 @example
+ − 724 (let-specifier ((modeline-shadow-thickness 0 (selected-window)))
+ − 725 (sit-for 1))
+ − 726 @end example
444
+ − 727 @end defspec
428
+ − 728
444
+ − 729 @defun set-specifier specifier value &optional locale tag-set how-to-add
428
+ − 730 This function adds some specifications to @var{specifier}. @var{value}
+ − 731 can be a single instantiator or tagged instantiator (added as a global
+ − 732 specification), a list of tagged and/or untagged instantiators (added as
+ − 733 a global specification), a cons of a locale and instantiator or locale
+ − 734 and instantiator list, a list of such conses, or nearly any other
+ − 735 reasonable form. More specifically, @var{value} can be anything
+ − 736 accepted by @code{canonicalize-spec-list}.
+ − 737
444
+ − 738 @var{locale}, @var{tag-set}, and @var{how-to-add} are the same as in
+ − 739 @code{add-spec-to-specifier}.
428
+ − 740
+ − 741 Note that @code{set-specifier} is exactly complementary to
+ − 742 @code{specifier-specs} except in the case where @var{specifier} has no
+ − 743 specs at all in it but @code{nil} is a valid instantiator (in that case,
+ − 744 @code{specifier-specs} will return @code{nil} (meaning no specs) and
+ − 745 @code{set-specifier} will interpret the @code{nil} as meaning ``I'm
+ − 746 adding a global instantiator and its value is @code{nil}''), or in
+ − 747 strange cases where there is an ambiguity between a spec-list and an
+ − 748 inst-list, etc. (The built-in specifier types are designed in such a way
+ − 749 as to avoid any such ambiguities.)
+ − 750
+ − 751 If you want to work with spec-lists, you should probably not use these
+ − 752 functions, but should use the lower-level functions
+ − 753 @code{specifier-spec-list} and @code{add-spec-list-to-specifier}. These
+ − 754 functions always work with fully-qualified spec-lists; thus, there is no
+ − 755 ambiguity.
+ − 756 @end defun
+ − 757
+ − 758 @defun canonicalize-inst-pair inst-pair specifier-type &optional noerror
+ − 759 This function canonicalizes the given @var{inst-pair}.
+ − 760
+ − 761 @var{specifier-type} specifies the type of specifier that this
+ − 762 @var{spec-list} will be used for.
+ − 763
+ − 764 Canonicalizing means converting to the full form for an inst-pair, i.e.
+ − 765 @code{(@var{tag-set} . @var{instantiator})}. A single, untagged
+ − 766 instantiator is given a tag set of @code{nil} (the empty set), and a
+ − 767 single tag is converted into a tag set consisting only of that tag.
+ − 768
+ − 769 If @var{noerror} is non-@code{nil}, signal an error if the inst-pair is
+ − 770 invalid; otherwise return @code{t}.
+ − 771 @end defun
+ − 772
+ − 773 @defun canonicalize-inst-list inst-list specifier-type &optional noerror
+ − 774 This function canonicalizes the given @var{inst-list} (a list of
+ − 775 inst-pairs).
+ − 776
+ − 777 @var{specifier-type} specifies the type of specifier that this @var{inst-list}
+ − 778 will be used for.
+ − 779
+ − 780 Canonicalizing means converting to the full form for an inst-list, i.e.
+ − 781 @code{((@var{tag-set} . @var{instantiator}) ...)}. This function
+ − 782 accepts a single inst-pair or any abbreviation thereof or a list of
+ − 783 (possibly abbreviated) inst-pairs. (See @code{canonicalize-inst-pair}.)
+ − 784
+ − 785 If @var{noerror} is non-@code{nil}, signal an error if the inst-list is
+ − 786 invalid; otherwise return @code{t}.
+ − 787 @end defun
+ − 788
+ − 789 @defun canonicalize-spec spec specifier-type &optional noerror
+ − 790 This function canonicalizes the given @var{spec} (a specification).
+ − 791
+ − 792 @var{specifier-type} specifies the type of specifier that this
+ − 793 @var{spec-list} will be used for.
+ − 794
+ − 795 Canonicalizing means converting to the full form for a spec, i.e.
+ − 796 @code{(@var{locale} (@var{tag-set} . @var{instantiator}) ...)}. This
+ − 797 function accepts a possibly abbreviated inst-list or a cons of a locale
+ − 798 and a possibly abbreviated inst-list. (See
+ − 799 @code{canonicalize-inst-list}.)
+ − 800
+ − 801 If @var{noerror} is @code{nil}, signal an error if the specification is
+ − 802 invalid; otherwise return @code{t}.
+ − 803 @end defun
+ − 804
+ − 805 @defun canonicalize-spec-list spec-list specifier-type &optional noerror
+ − 806 This function canonicalizes the given @var{spec-list} (a list of
+ − 807 specifications).
+ − 808
+ − 809 @var{specifier-type} specifies the type of specifier that this
+ − 810 @var{spec-list} will be used for.
+ − 811
+ − 812 Canonicalizing means converting to the full form for a spec-list, i.e.
+ − 813 @code{((@var{locale} (@var{tag-set} . @var{instantiator}) ...) ...)}.
+ − 814 This function accepts a possibly abbreviated specification or a list of
+ − 815 such things. (See @code{canonicalize-spec}.) This is the function used
+ − 816 to convert spec-lists accepted by @code{set-specifier} and such into a
+ − 817 form suitable for @code{add-spec-list-to-specifier}.
+ − 818
+ − 819 This function tries extremely hard to resolve any ambiguities,
+ − 820 and the built-in specifier types (font, image, toolbar, etc.) are
+ − 821 designed so that there won't be any ambiguities.
+ − 822
+ − 823 If @var{noerror} is @code{nil}, signal an error if the spec-list is
+ − 824 invalid; otherwise return @code{t}.
+ − 825 @end defun
+ − 826
+ − 827 @node Retrieving Specifications
+ − 828 @section Retrieving the Specifications from a Specifier
+ − 829
+ − 830 @defun specifier-spec-list specifier &optional locale tag-set exact-p
+ − 831 This function returns the spec-list of specifications for
+ − 832 @var{specifier} in @var{locale}.
+ − 833
+ − 834 If @var{locale} is a particular locale (a window, buffer, frame, device,
+ − 835 or the symbol @code{global}), a spec-list consisting of the
+ − 836 specification for that locale will be returned.
+ − 837
444
+ − 838 If @var{locale} is a locale type (i.e. one of the symbols @code{window},
428
+ − 839 @code{buffer}, @code{frame}, or @code{device}), a spec-list of the
+ − 840 specifications for all locales of that type will be returned.
+ − 841
+ − 842 If @var{locale} is @code{nil} or the symbol @code{all}, a spec-list of
+ − 843 all specifications in @var{specifier} will be returned.
+ − 844
+ − 845 @var{locale} can also be a list of locales, locale types, and/or
+ − 846 @code{all}; the result is as if @code{specifier-spec-list} were called
+ − 847 on each element of the list and the results concatenated together.
+ − 848
+ − 849 Only instantiators where @var{tag-set} (a list of zero or more tags) is
+ − 850 a subset of (or possibly equal to) the instantiator's tag set are
444
+ − 851 returned. (The default value of @code{nil} is a subset of all tag sets,
428
+ − 852 so in this case no instantiators will be screened out.) If @var{exact-p}
+ − 853 is non-@code{nil}, however, @var{tag-set} must be equal to an
+ − 854 instantiator's tag set for the instantiator to be returned.
+ − 855 @end defun
+ − 856
+ − 857 @defun specifier-specs specifier &optional locale tag-set exact-p
+ − 858 This function returns the specification(s) for @var{specifier} in
+ − 859 @var{locale}.
+ − 860
+ − 861 If @var{locale} is a single locale or is a list of one element
+ − 862 containing a single locale, then a ``short form'' of the instantiators
+ − 863 for that locale will be returned. Otherwise, this function is identical
+ − 864 to @code{specifier-spec-list}.
+ − 865
+ − 866 The ``short form'' is designed for readability and not for ease of use
+ − 867 in Lisp programs, and is as follows:
+ − 868
+ − 869 @enumerate
+ − 870 @item
+ − 871 If there is only one instantiator, then an inst-pair (i.e. cons of tag
+ − 872 and instantiator) will be returned; otherwise a list of inst-pairs will
+ − 873 be returned.
+ − 874 @item
+ − 875 For each inst-pair returned, if the instantiator's tag is @code{any},
+ − 876 the tag will be removed and the instantiator itself will be returned
+ − 877 instead of the inst-pair.
+ − 878 @item
+ − 879 If there is only one instantiator, its value is @code{nil}, and its tag
+ − 880 is @code{any}, a one-element list containing @code{nil} will be returned
+ − 881 rather than just @code{nil}, to distinguish this case from there being
+ − 882 no instantiators at all.
+ − 883 @end enumerate
+ − 884
+ − 885 @end defun
+ − 886
+ − 887 @defun specifier-fallback specifier
+ − 888 This function returns the fallback value for @var{specifier}. Fallback
+ − 889 values are provided by the C code for certain built-in specifiers to
+ − 890 make sure that instancing won't fail even if all specs are removed from
+ − 891 the specifier, or to implement simple inheritance behavior (e.g. this
+ − 892 method is used to ensure that faces other than @code{default} inherit
+ − 893 their attributes from @code{default}). By design, you cannot change the
+ − 894 fallback value, and specifiers created with @code{make-specifier} will
+ − 895 never have a fallback (although a similar, Lisp-accessible capability
+ − 896 may be provided in the future to allow for inheritance).
+ − 897
+ − 898 The fallback value will be an inst-list that is instanced like
+ − 899 any other inst-list, a specifier of the same type as @var{specifier}
+ − 900 (results in inheritance), or @code{nil} for no fallback.
+ − 901
+ − 902 When you instance a specifier, you can explicitly request that the
+ − 903 fallback not be consulted. (The C code does this, for example, when
+ − 904 merging faces.) See @code{specifier-instance}.
+ − 905 @end defun
+ − 906
+ − 907 @node Specifier Tag Functions
+ − 908 @section Working With Specifier Tags
+ − 909
+ − 910 A specifier tag set is an entity that is attached to an instantiator
+ − 911 and can be used to restrict the scope of that instantiator to a
+ − 912 particular device class or device type and/or to mark instantiators
+ − 913 added by a particular package so that they can be later removed.
+ − 914
442
+ − 915 A specifier tag set consists of a list of zero or more specifier tags,
428
+ − 916 each of which is a symbol that is recognized by XEmacs as a tag. (The
+ − 917 valid device types and device classes are always tags, as are any tags
+ − 918 defined by @code{define-specifier-tag}.) It is called a ``tag set'' (as
+ − 919 opposed to a list) because the order of the tags or the number of times
+ − 920 a particular tag occurs does not matter.
+ − 921
+ − 922 Each tag has a predicate associated with it, which specifies whether
+ − 923 that tag applies to a particular device. The tags which are device
+ − 924 types and classes match devices of that type or class. User-defined
+ − 925 tags can have any predicate, or none (meaning that all devices match).
+ − 926 When attempting to instance a specifier, a particular instantiator is
+ − 927 only considered if the device of the domain being instanced over matches
+ − 928 all tags in the tag set attached to that instantiator.
+ − 929
+ − 930 Most of the time, a tag set is not specified, and the instantiator gets
+ − 931 a null tag set, which matches all devices.
+ − 932
+ − 933 @defun valid-specifier-tag-p tag
+ − 934 This function returns non-@code{nil} if @var{tag} is a valid specifier
+ − 935 tag.
+ − 936 @end defun
+ − 937
+ − 938 @defun valid-specifier-tag-set-p tag-set
+ − 939 This function returns non-@code{nil} if @var{tag-set} is a valid
+ − 940 specifier tag set.
+ − 941 @end defun
+ − 942
+ − 943 @defun canonicalize-tag-set tag-set
+ − 944 This function canonicalizes the given tag set. Two canonicalized tag
+ − 945 sets can be compared with @code{equal} to see if they represent the same
+ − 946 tag set. (Specifically, canonicalizing involves sorting by symbol name
+ − 947 and removing duplicates.)
+ − 948 @end defun
+ − 949
+ − 950 @defun device-matches-specifier-tag-set-p device tag-set
+ − 951 This function returns non-@code{nil} if @var{device} matches specifier
+ − 952 tag set @var{tag-set}. This means that @var{device} matches each tag in
+ − 953 the tag set.
+ − 954 @end defun
+ − 955
+ − 956 @defun define-specifier-tag tag &optional predicate
+ − 957 This function defines a new specifier tag. If @var{predicate} is
+ − 958 specified, it should be a function of one argument (a device) that
+ − 959 specifies whether the tag matches that particular device. If
+ − 960 @var{predicate} is omitted, the tag matches all devices.
+ − 961
+ − 962 You can redefine an existing user-defined specifier tag. However, you
+ − 963 cannot redefine the built-in specifier tags (the device types and
+ − 964 classes) or the symbols @code{nil}, @code{t}, @code{all}, or
+ − 965 @code{global}.
+ − 966 @end defun
+ − 967
+ − 968 @defun device-matching-specifier-tag-list &optional device
+ − 969 This function returns a list of all specifier tags matching
+ − 970 @var{device}. @var{device} defaults to the selected device if omitted.
+ − 971 @end defun
+ − 972
+ − 973 @defun specifier-tag-list
+ − 974 This function returns a list of all currently-defined specifier tags.
+ − 975 This includes the built-in ones (the device types and classes).
+ − 976 @end defun
+ − 977
+ − 978 @defun specifier-tag-predicate tag
+ − 979 This function returns the predicate for the given specifier tag.
+ − 980 @end defun
+ − 981
+ − 982 @node Specifier Instancing Functions
+ − 983 @section Functions for Instancing a Specifier
+ − 984
+ − 985 @defun specifier-instance specifier &optional domain default no-fallback
+ − 986 This function instantiates @var{specifier} (return its value) in
+ − 987 @var{domain}. If no instance can be generated for this domain, return
+ − 988 @var{default}.
+ − 989
+ − 990 @var{domain} should be a window, frame, or device. Other values that
+ − 991 are legal as a locale (e.g. a buffer) are not valid as a domain because
+ − 992 they do not provide enough information to identify a particular device
+ − 993 (see @code{valid-specifier-domain-p}). @var{domain} defaults to the
+ − 994 selected window if omitted.
+ − 995
+ − 996 @dfn{Instantiating} a specifier in a particular domain means determining
+ − 997 the specifier's ``value'' in that domain. This is accomplished by
+ − 998 searching through the specifications in the specifier that correspond to
+ − 999 all locales that can be derived from the given domain, from specific to
+ − 1000 general. In most cases, the domain is an Emacs window. In that case
+ − 1001 specifications are searched for as follows:
+ − 1002
+ − 1003 @enumerate
+ − 1004 @item
+ − 1005 A specification whose locale is the window itself;
+ − 1006 @item
+ − 1007 A specification whose locale is the window's buffer;
+ − 1008 @item
+ − 1009 A specification whose locale is the window's frame;
+ − 1010 @item
+ − 1011 A specification whose locale is the window's frame's device;
+ − 1012 @item
+ − 1013 A specification whose locale is the symbol @code{global}.
+ − 1014 @end enumerate
+ − 1015
+ − 1016 If all of those fail, then the C-code-provided fallback value for this
+ − 1017 specifier is consulted (see @code{specifier-fallback}). If it is an
+ − 1018 inst-list, then this function attempts to instantiate that list just as
+ − 1019 when a specification is located in the first five steps above. If the
+ − 1020 fallback is a specifier, @code{specifier-instance} is called recursively
+ − 1021 on this specifier and the return value used. Note, however, that if the
+ − 1022 optional argument @var{no-fallback} is non-@code{nil}, the fallback
+ − 1023 value will not be consulted.
+ − 1024
+ − 1025 Note that there may be more than one specification matching a particular
+ − 1026 locale; all such specifications are considered before looking for any
+ − 1027 specifications for more general locales. Any particular specification
+ − 1028 that is found may be rejected because it is tagged to a particular
+ − 1029 device class (e.g. @code{color}) or device type (e.g. @code{x}) or both
+ − 1030 and the device for the given domain does not match this, or because the
+ − 1031 specification is not valid for the device of the given domain (e.g. the
+ − 1032 font or color name does not exist for this particular X server).
+ − 1033
+ − 1034 The returned value is dependent on the type of specifier. For example,
+ − 1035 for a font specifier (as returned by the @code{face-font} function), the
+ − 1036 returned value will be a font-instance object. For images, the returned
+ − 1037 value will be a string, pixmap, or subwindow.
+ − 1038 @end defun
+ − 1039
+ − 1040 @defun specifier-instance-from-inst-list specifier domain inst-list &optional default
+ − 1041 This function attempts to convert a particular inst-list into an
+ − 1042 instance. This attempts to instantiate @var{inst-list} in the given
+ − 1043 @var{domain}, as if @var{inst-list} existed in a specification in
+ − 1044 @var{specifier}. If the instantiation fails, @var{default} is returned.
+ − 1045 In most circumstances, you should not use this function; use
+ − 1046 @code{specifier-instance} instead.
+ − 1047 @end defun
+ − 1048
+ − 1049 @node Specifier Example
+ − 1050 @section Example of Specifier Usage
+ − 1051
+ − 1052 Now let us present an example to clarify the theoretical discussions we
+ − 1053 have been through. In this example, we will use the general specifier
+ − 1054 functions for clarity. Keep in mind that many types of specifiers, and
+ − 1055 some other types of objects that are associated with specifiers
+ − 1056 (e.g. faces), provide convenience functions making it easier to work
+ − 1057 with objects of that type.
+ − 1058
+ − 1059 Let us consider the background color of the default face. A specifier
+ − 1060 is used to specify how that color will appear in different domains.
+ − 1061 First, let's retrieve the specifier:
+ − 1062
+ − 1063 @example
+ − 1064 (setq sp (face-property 'default 'background))
+ − 1065 @result{} #<color-specifier 0x3da>
+ − 1066 @end example
+ − 1067
+ − 1068 @example
+ − 1069 (specifier-specs sp)
+ − 1070 @result{} ((#<buffer "device.c"> (nil . "forest green"))
+ − 1071 (#<window on "Makefile" 0x8a2b> (nil . "hot pink"))
+ − 1072 (#<x-frame "emacs" 0x4ac> (nil . "puke orange")
440
+ − 1073 (nil . "moccasin"))
428
+ − 1074 (#<x-frame "VM" 0x4ac> (nil . "magenta"))
440
+ − 1075 (global ((tty) . "cyan") (nil . "white"))
428
+ − 1076 )
+ − 1077 @end example
+ − 1078
+ − 1079 Then, say we want to determine what the background color of the default
+ − 1080 face is for the window currently displaying the buffer @samp{*scratch*}.
+ − 1081 We call
+ − 1082
+ − 1083 @example
+ − 1084 (get-buffer-window "*scratch*")
+ − 1085 @result{} #<window on "*scratch*" 0x4ad>
+ − 1086 (window-frame (get-buffer-window "*scratch*"))
+ − 1087 @result{} #<x-frame "emacs" 0x4ac>
+ − 1088 (specifier-instance sp (get-buffer-window "*scratch*"))
+ − 1089 @result{} #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x6309>
+ − 1090 @end example
+ − 1091
+ − 1092 Note that we passed a window to @code{specifier-instance}, not a buffer.
+ − 1093 We cannot pass a buffer because a buffer by itself does not provide enough
+ − 1094 information. The buffer might not be displayed anywhere at all, or
+ − 1095 could be displayed in many different frames on different devices.
+ − 1096
+ − 1097 The result is arrived at like this:
+ − 1098
+ − 1099 @enumerate
+ − 1100 @item
+ − 1101 First, we look for a specification matching the buffer displayed in the
440
+ − 1102 window, i.e. @samp{*scratch*}. There are none, so we proceed.
428
+ − 1103 @item
+ − 1104 Then, we look for a specification matching the window itself. Again, there
+ − 1105 are none.
+ − 1106 @item
+ − 1107 Then, we look for a specification matching the window's frame. The
+ − 1108 specification @code{(#<x-frame "emacs" 0x4ac> . "puke orange")} is
+ − 1109 found. We call the instantiation method for colors, passing it the
+ − 1110 locale we were searching over (i.e. the window, in this case) and the
+ − 1111 instantiator (@samp{"puke orange"}). However, the particular device
+ − 1112 which this window is on (let's say it's an X connection) doesn't
+ − 1113 recognize the color @samp{"puke orange"}, so the specification is
+ − 1114 rejected.
+ − 1115 @item
+ − 1116 So we continue looking for a specification matching the window's frame.
+ − 1117 We find @samp{(#<x-frame "emacs" 0x4ac> . "moccasin")}. Again, we
+ − 1118 call the instantiation method for colors. This time, the X server
+ − 1119 our window is on recognizes the color @samp{moccasin}, and so the
+ − 1120 instantiation method succeeds and returns a color instance.
+ − 1121 @end enumerate
+ − 1122
+ − 1123 @node Creating Specifiers
+ − 1124 @section Creating New Specifier Objects
+ − 1125
+ − 1126 @defun make-specifier type
+ − 1127 This function creates a new specifier.
+ − 1128
+ − 1129 A specifier is an object that can be used to keep track of a property
+ − 1130 whose value can be per-buffer, per-window, per-frame, or per-device,
+ − 1131 and can further be restricted to a particular device-type or device-class.
+ − 1132 Specifiers are used, for example, for the various built-in properties of a
+ − 1133 face; this allows a face to have different values in different frames,
444
+ − 1134 buffers, etc. For more information, see @code{specifier-instance},
+ − 1135 @code{specifier-specs}, and @code{add-spec-to-specifier}; or, for a detailed
428
+ − 1136 description of specifiers, including how they are instantiated over a
+ − 1137 particular domain (i.e. how their value in that domain is determined),
+ − 1138 see the chapter on specifiers in the XEmacs Lisp Reference Manual.
+ − 1139
+ − 1140 @var{type} specifies the particular type of specifier, and should be one
+ − 1141 of the symbols @code{generic}, @code{integer}, @code{natnum},
+ − 1142 @code{boolean}, @code{color}, @code{font}, @code{image},
+ − 1143 @code{face-boolean}, or @code{toolbar}.
+ − 1144
+ − 1145 For more information on particular types of specifiers, see the
442
+ − 1146 functions @code{make-generic-specifier}, @code{make-integer-specifier},
+ − 1147 @code{make-natnum-specifier}, @code{make-boolean-specifier},
+ − 1148 @code{make-color-specifier}, @code{make-font-specifier},
+ − 1149 @code{make-image-specifier}, @code{make-face-boolean-specifier}, and
+ − 1150 @code{make-toolbar-specifier}.
428
+ − 1151 @end defun
+ − 1152
+ − 1153 @defun make-specifier-and-init type spec-list &optional dont-canonicalize
+ − 1154 This function creates and initialize a new specifier.
+ − 1155
+ − 1156 This is a front-end onto @code{make-specifier} that allows you to create
+ − 1157 a specifier and add specs to it at the same time. @var{type} specifies
+ − 1158 the specifier type. @var{spec-list} supplies the specification(s) to be
+ − 1159 added to the specifier. Normally, almost any reasonable abbreviation of
+ − 1160 the full spec-list form is accepted, and is converted to the full form;
+ − 1161 however, if optional argument @var{dont-canonicalize} is non-@code{nil},
+ − 1162 this conversion is not performed, and the @var{spec-list} must already
+ − 1163 be in full form. See @code{canonicalize-spec-list}.
+ − 1164 @end defun
+ − 1165
442
+ − 1166 @defun make-integer-specifier spec-list
+ − 1167
+ − 1168 Return a new @code{integer} specifier object with the given
+ − 1169 specification list. @var{spec-list} can be a list of specifications
+ − 1170 (each of which is a cons of a locale and a list of instantiators), a
+ − 1171 single instantiator, or a list of instantiators.
+ − 1172
+ − 1173 Valid instantiators for integer specifiers are integers.
+ − 1174 @end defun
+ − 1175
+ − 1176 @defun make-boolean-specifier spec-list
+ − 1177
+ − 1178 Return a new @code{boolean} specifier object with the given
+ − 1179 specification list. @var{spec-list} can be a list of specifications
+ − 1180 (each of which is a cons of a locale and a list of instantiators), a
+ − 1181 single instantiator, or a list of instantiators.
+ − 1182
+ − 1183 Valid instantiators for boolean specifiers are @code{t} and @code{nil}.
+ − 1184 @end defun
+ − 1185
+ − 1186 @defun make-natnum-specifier spec-list
+ − 1187
+ − 1188 Return a new @code{natnum} specifier object with the given specification
+ − 1189 list. @var{spec-list} can be a list of specifications (each of which is
+ − 1190 a cons of a locale and a list of instantiators), a single instantiator,
+ − 1191 or a list of instantiators.
+ − 1192
+ − 1193 Valid instantiators for natnum specifiers are non-negative integers.
+ − 1194 @end defun
+ − 1195
+ − 1196 @defun make-generic-specifier spec-list
+ − 1197
+ − 1198 Return a new @code{generic} specifier object with the given
+ − 1199 specification list. @var{spec-list} can be a list of specifications
+ − 1200 (each of which is a cons of a locale and a list of instantiators), a
+ − 1201 single instantiator, or a list of instantiators.
+ − 1202
+ − 1203 Valid instantiators for generic specifiers are all Lisp values. They
+ − 1204 are returned back unchanged when a specifier is instantiated.
+ − 1205 @end defun
+ − 1206
+ − 1207 @defun make-display-table-specifier spec-list
+ − 1208
+ − 1209 Return a new @code{display-table} specifier object with the given spec
+ − 1210 list. @var{spec-list} can be a list of specifications (each of which is
+ − 1211 a cons of a locale and a list of instantiators), a single instantiator,
+ − 1212 or a list of instantiators.
+ − 1213
+ − 1214 Valid instantiators for display-table specifiers are described in detail
+ − 1215 in the doc string for @code{current-display-table} (@pxref{Active
+ − 1216 Display Table}).
+ − 1217 @end defun
+ − 1218
428
+ − 1219 @node Specifier Validation Functions
+ − 1220 @section Functions for Checking the Validity of Specifier Components
+ − 1221
+ − 1222 @defun valid-specifier-domain-p domain
+ − 1223 This function returns non-@code{nil} if @var{domain} is a valid
+ − 1224 specifier domain. A domain is used to instance a specifier
+ − 1225 (i.e. determine the specifier's value in that domain). Valid domains
+ − 1226 are a window, frame, or device. (@code{nil} is not valid.)
+ − 1227 @end defun
+ − 1228
+ − 1229 @defun valid-specifier-locale-p locale
+ − 1230 This function returns non-@code{nil} if @var{locale} is a valid
+ − 1231 specifier locale. Valid locales are a device, a frame, a window, a
+ − 1232 buffer, and @code{global}. (@code{nil} is not valid.)
+ − 1233 @end defun
+ − 1234
+ − 1235 @defun valid-specifier-locale-type-p locale-type
444
+ − 1236 Given a specifier @var{locale-type}, this function returns non-@code{nil} if it
428
+ − 1237 is valid. Valid locale types are the symbols @code{global},
+ − 1238 @code{device}, @code{frame}, @code{window}, and @code{buffer}. (Note,
+ − 1239 however, that in functions that accept either a locale or a locale type,
+ − 1240 @code{global} is considered an individual locale.)
+ − 1241 @end defun
+ − 1242
+ − 1243 @defun valid-specifier-type-p specifier-type
+ − 1244 Given a @var{specifier-type}, this function returns non-@code{nil} if it
+ − 1245 is valid. Valid types are @code{generic}, @code{integer},
+ − 1246 @code{boolean}, @code{color}, @code{font}, @code{image},
+ − 1247 @code{face-boolean}, and @code{toolbar}.
+ − 1248 @end defun
+ − 1249
+ − 1250 @defun valid-specifier-tag-p tag
+ − 1251 This function returns non-@code{nil} if @var{tag} is a valid specifier
+ − 1252 tag.
+ − 1253 @end defun
+ − 1254
+ − 1255 @defun valid-instantiator-p instantiator specifier-type
+ − 1256 This function returns non-@code{nil} if @var{instantiator} is valid for
+ − 1257 @var{specifier-type}.
+ − 1258 @end defun
+ − 1259
+ − 1260 @defun valid-inst-list-p inst-list type
+ − 1261 This function returns non-@code{nil} if @var{inst-list} is valid for
+ − 1262 specifier type @var{type}.
+ − 1263 @end defun
+ − 1264
+ − 1265 @defun valid-spec-list-p spec-list type
+ − 1266 This function returns non-@code{nil} if @var{spec-list} is valid for
+ − 1267 specifier type @var{type}.
+ − 1268 @end defun
+ − 1269
+ − 1270 @defun check-valid-instantiator instantiator specifier-type
+ − 1271 This function signals an error if @var{instantiator} is invalid for
+ − 1272 @var{specifier-type}.
+ − 1273 @end defun
+ − 1274
+ − 1275 @defun check-valid-inst-list inst-list type
+ − 1276 This function signals an error if @var{inst-list} is invalid for
+ − 1277 specifier type @var{type}.
+ − 1278 @end defun
+ − 1279
+ − 1280 @defun check-valid-spec-list spec-list type
+ − 1281 This function signals an error if @var{spec-list} is invalid for
+ − 1282 specifier type @var{type}.
+ − 1283 @end defun
+ − 1284
+ − 1285 @node Other Specification Functions
+ − 1286 @section Other Functions for Working with Specifications in a Specifier
+ − 1287
+ − 1288 @defun copy-specifier specifier &optional dest locale tag-set exact-p how-to-add
+ − 1289 This function copies @var{specifier} to @var{dest}, or creates a new one
+ − 1290 if @var{dest} is @code{nil}.
+ − 1291
+ − 1292 If @var{dest} is @code{nil} or omitted, a new specifier will be created
+ − 1293 and the specifications copied into it. Otherwise, the specifications
+ − 1294 will be copied into the existing specifier in @var{dest}.
+ − 1295
+ − 1296 If @var{locale} is @code{nil} or the symbol @code{all}, all
+ − 1297 specifications will be copied. If @var{locale} is a particular locale,
+ − 1298 the specification for that particular locale will be copied. If
+ − 1299 @var{locale} is a locale type, the specifications for all locales of
+ − 1300 that type will be copied. @var{locale} can also be a list of locales,
+ − 1301 locale types, and/or @code{all}; this is equivalent to calling
+ − 1302 @code{copy-specifier} for each of the elements of the list. See
+ − 1303 @code{specifier-spec-list} for more information about @var{locale}.
+ − 1304
+ − 1305 Only instantiators where @var{tag-set} (a list of zero or more tags) is
+ − 1306 a subset of (or possibly equal to) the instantiator's tag set are
+ − 1307 copied. (The default value of @code{nil} is a subset of all tag sets,
+ − 1308 so in this case no instantiators will be screened out.) If @var{exact-p}
+ − 1309 is non-@code{nil}, however, @var{tag-set} must be equal to an
+ − 1310 instantiator's tag set for the instantiator to be copied.
+ − 1311
+ − 1312 Optional argument @var{how-to-add} specifies what to do with existing
444
+ − 1313 specifications in @var{dest}. If @code{nil}, then whichever locales or locale
428
+ − 1314 types are copied will first be completely erased in @var{dest}.
+ − 1315 Otherwise, it is the same as in @code{add-spec-to-specifier}.
+ − 1316 @end defun
+ − 1317
+ − 1318 @defun remove-specifier specifier &optional locale tag-set exact-p
+ − 1319 This function removes specification(s) for @var{specifier}.
+ − 1320
+ − 1321 If @var{locale} is a particular locale (a buffer, window, frame, device,
+ − 1322 or the symbol @code{global}), the specification for that locale will be
+ − 1323 removed.
+ − 1324
+ − 1325 If instead, @var{locale} is a locale type (i.e. a symbol @code{buffer},
+ − 1326 @code{window}, @code{frame}, or @code{device}), the specifications for
+ − 1327 all locales of that type will be removed.
+ − 1328
+ − 1329 If @var{locale} is @code{nil} or the symbol @code{all}, all
+ − 1330 specifications will be removed.
+ − 1331
+ − 1332 @var{locale} can also be a list of locales, locale types, and/or
+ − 1333 @code{all}; this is equivalent to calling @code{remove-specifier} for
+ − 1334 each of the elements in the list.
+ − 1335
+ − 1336 Only instantiators where @var{tag-set} (a list of zero or more tags) is
+ − 1337 a subset of (or possibly equal to) the instantiator's tag set are
+ − 1338 removed. (The default value of @code{nil} is a subset of all tag sets,
+ − 1339 so in this case no instantiators will be screened out.) If @var{exact-p}
+ − 1340 is non-@code{nil}, however, @var{tag-set} must be equal to an
+ − 1341 instantiator's tag set for the instantiator to be removed.
+ − 1342 @end defun
+ − 1343
+ − 1344 @defun map-specifier specifier func &optional locale maparg
+ − 1345 This function applies @var{func} to the specification(s) for
+ − 1346 @var{locale} in @var{specifier}.
+ − 1347
+ − 1348 If @var{locale} is a locale, @var{func} will be called for that locale.
+ − 1349 If @var{locale} is a locale type, @var{func} will be mapped over all
+ − 1350 locales of that type. If @var{locale} is @code{nil} or the symbol
+ − 1351 @code{all}, @var{func} will be mapped over all locales in
+ − 1352 @var{specifier}.
+ − 1353
+ − 1354 @var{func} is called with four arguments: the @var{specifier}, the
+ − 1355 locale being mapped over, the inst-list for that locale, and the
+ − 1356 optional @var{maparg}. If any invocation of @var{func} returns
+ − 1357 non-@code{nil}, the mapping will stop and the returned value becomes the
+ − 1358 value returned from @code{map-specifier}. Otherwise,
+ − 1359 @code{map-specifier} returns @code{nil}.
+ − 1360 @end defun
+ − 1361
+ − 1362 @defun specifier-locale-type-from-locale locale
+ − 1363 Given a specifier @var{locale}, this function returns its type.
+ − 1364 @end defun