1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Extent Properties, Next: Detached Extents, Prev: Mapping Over Extents, Up: Extents
58 Each extent has a property list associating property names with
59 values. Some property names have predefined meanings, and can usually
60 only assume particular values. Assigning other values to such a
61 property either cause the value to be converted into a legal value
62 (e.g., assigning anything but `nil' to a Boolean property will cause
63 the value of `t' to be assigned to the property) or will cause an
64 error. Property names without predefined meanings can be assigned any
65 value. An undefined property is equivalent to a property with a value
66 of `nil', or with a particular default value in the case of properties
67 with predefined meanings. Note that, when an extent is created, the
68 `end-open' and `detachable' properties are set on it.
70 If an extent has a parent, all of its properties actually derive
71 from that parent (or from the root ancestor if the parent in turn has a
72 parent), and setting a property of the extent actually sets that
73 property on the parent. *Note Extent Parents::.
75 - Function: extent-property extent property
76 This function returns the value of PROPERTY in EXTENT. If
77 PROPERTY is undefined, `nil' is returned.
79 - Function: extent-properties extent
80 This function returns a list of all of EXTENT's properties that do
81 not have the value of `nil' (or the default value, for properties
82 with predefined meanings).
84 - Function: set-extent-property extent property value
85 This function sets PROPERTY to VALUE in EXTENT. (If PROPERTY has a
86 predefined meaning, only certain values are allowed, and some
87 values may be converted to others before being stored.)
89 - Function: set-extent-properties extent plist
90 Change some properties of EXTENT. PLIST is a property list. This
91 is useful to change many extent properties at once.
93 The following table lists the properties with predefined meanings,
94 along with their allowable values.
97 (Boolean) Whether the extent is detached. Setting this is the
98 same as calling `detach-extent'. *Note Detached Extents::.
101 (Boolean) Whether the extent has been deleted. Setting this is
102 the same as calling `delete-extent'.
105 (integer) The extent's redisplay priority. Defaults to 0. *Note
106 priority: Intro to Extents. This property can also be set with
107 `set-extent-priority' and accessed with `extent-priority'.
110 (Boolean) Whether the start position of the extent is open,
111 meaning that characters inserted at that position go outside of
112 the extent. *Note Extent Endpoints::.
115 (Boolean) Same as `start-open' but with the opposite sense.
116 Setting this property clears `start-open' and vice-versa.
119 (Boolean) Whether the end position of the extent is open, meaning
120 that characters inserted at that position go outside of the
121 extent. This is `t' by default. *Note Extent Endpoints::.
124 (Boolean) Same as `end-open' but with the opposite sense. Setting
125 this property clears `end-open' and vice-versa.
128 (Boolean) Whether text within this extent will be unmodifiable.
131 (face, face name, list of faces or face names, or `nil') The face
132 in which to display the extent's text. This property can also be
133 set with `set-extent-face' and accessed with `extent-face'. Note
134 that if a list of faces is specified, the faces are merged
135 together, with faces earlier in the list having priority over
136 faces later in the list.
139 (face, face name, list of faces or face names, or `nil') The face
140 used to display the extent when the mouse moves over it. This
141 property can also be set with `set-extent-mouse-face' and accessed
142 with `extent-mouse-face'. Note that if a list of faces is
143 specified, the faces are merged together, with faces earlier in
144 the list having priority over faces later in the list. *Note
145 Extents and Events::.
148 (pointer glyph) The glyph used as the pointer when the mouse
149 moves over the extent. This takes precedence over the
150 `text-pointer-glyph' and `nontext-pointer-glyph' variables. If
151 for any reason this glyph is an invalid pointer, the standard
152 glyphs will be used as fallbacks. *Note Mouse Pointer::.
155 (Boolean) Whether this extent becomes detached when all of the
156 text it covers is deleted. This is `t' by default. *Note
160 (Boolean) Whether this extent should be copied into strings, so
161 that kill, yank, and undo commands will restore or copy it. *Note
162 Duplicable Extents::.
165 (Boolean) Meaningful only in conjunction with `duplicable'. When
166 this is set, there may be only one instance of this extent
167 attached at a time. *Note Duplicable Extents::.
170 (Boolean) If `t', text under this extent will not be displayed -
171 it will look as if the text is not there at all.
174 (keymap or `nil') This keymap is consulted for mouse clicks on this
175 extent or keypresses made while `point' is within the extent.
176 *Note Extents and Events::.
179 This is a hook that is run when a duplicable extent is about to be
180 copied from a buffer to a string (or the kill ring). *Note
181 Duplicable Extents::.
184 This is a hook that is run when a duplicable extent is about to be
185 copied from a string (or the kill ring) into a buffer. *Note
186 Duplicable Extents::.
189 (glyph or `nil') This extent's begin glyph. *Note Annotations::.
192 (glyph or `nil') This extent's end glyph. *Note Annotations::.
195 (`text', `whitespace', `inside-margin', or `outside-margin') The
196 layout policy for this extent's begin glyph. Defaults to `text'.
200 (`text', `whitespace', `inside-margin', or `outside-margin') The
201 layout policy for this extent's end glyph. Defaults to `text'.
204 `initial-redisplay-function'
205 (any funcallable object) The function to be called the first time
206 (a part of) the extent is redisplayed. It will be called with the
207 extent as its argument.
209 This is used by `lazy-shot' to implement lazy font-locking. The
210 functionality is still experimental, and may change without further
213 The following convenience functions are provided for accessing
214 particular properties of an extent.
216 - Function: extent-face extent
217 This function returns the `face' property of EXTENT. This might
218 also return a list of face names. Do not modify this list
219 directly! Instead, use `set-extent-face'.
221 Note that you can use `eq' to compare lists of faces as returned
222 by `extent-face'. In other words, if you set the face of two
223 different extents to two lists that are `equal' but not `eq', then
224 the return value of `extent-face' on the two extents will return
227 - Function: extent-mouse-face extent
228 This function returns the `mouse-face' property of EXTENT. This
229 might also return a list of face names. Do not modify this list
230 directly! Instead, use `set-extent-mouse-face'.
232 Note that you can use `eq' to compare lists of faces as returned
233 by `extent-mouse-face', just like for `extent-face'.
235 - Function: extent-priority extent
236 This function returns the `priority' property of EXTENT.
238 - Function: extent-keymap extent
239 This function returns the `keymap' property of EXTENT.
241 - Function: extent-begin-glyph-layout extent
242 This function returns the `begin-glyph-layout' property of EXTENT,
243 i.e. the layout policy associated with the EXTENT's begin glyph.
245 - Function: extent-end-glyph-layout extent
246 This function returns the `end-glyph-layout' property of EXTENT,
247 i.e. the layout policy associated with the EXTENT's end glyph.
249 - Function: extent-begin-glyph extent
250 This function returns the `begin-glyph' property of EXTENT, i.e.
251 the glyph object displayed at the beginning of EXTENT. If there
252 is none, `nil' is returned.
254 - Function: extent-end-glyph extent
255 This function returns the `end-glyph' property of EXTENT, i.e. the
256 glyph object displayed at the end of EXTENT. If there is none,
259 The following convenience functions are provided for setting
260 particular properties of an extent.
262 - Function: set-extent-priority extent pri
263 This function sets the `priority' property of EXTENT to PRI.
265 - Function: set-extent-face extent face
266 This function sets the `face' property of EXTENT to FACE.
268 - Function: set-extent-mouse-face extent face
269 This function sets the `mouse-face' property of EXTENT to FACE.
271 - Function: set-extent-keymap extent keymap
272 This function sets the `keymap' property of EXTENT to KEYMAP.
273 KEYMAP must be either a keymap object, or `nil'.
275 - Function: set-extent-begin-glyph-layout extent layout
276 This function sets the `begin-glyph-layout' property of EXTENT to
279 - Function: set-extent-end-glyph-layout extent layout
280 This function sets the `end-glyph-layout' property of EXTENT to
283 - Function: set-extent-begin-glyph extent begin-glyph &optional layout
284 This function sets the `begin-glyph' and `glyph-layout' properties
285 of EXTENT to BEGIN-GLYPH and LAYOUT, respectively. (LAYOUT
286 defaults to `text' if not specified.)
288 - Function: set-extent-end-glyph extent end-glyph &optional layout
289 This function sets the `end-glyph' and `glyph-layout' properties
290 of EXTENT to END-GLYPH and LAYOUT, respectively. (LAYOUT defaults
291 to `text' if not specified.)
293 - Function: set-extent-initial-redisplay-function extent function
294 This function sets the `initial-redisplay-function' property of the
298 File: lispref.info, Node: Detached Extents, Next: Extent Parents, Prev: Extent Properties, Up: Extents
303 A detached extent is an extent that is not attached to a buffer or
304 string but can be re-inserted. Detached extents have a start position
305 and end position of `nil'. Extents can be explicitly detached using
306 `detach-extent'. An extent is also detached when all of its characters
307 are all killed by a deletion, if its `detachable' property is set; if
308 this property is not set, the extent becomes a zero-length extent.
309 (Zero-length extents with the `detachable' property set behave
310 specially. *Note zero-length extents: Extent Endpoints.)
312 - Function: detach-extent extent
313 This function detaches EXTENT from its buffer or string. If
314 EXTENT has the `duplicable' property, its detachment is tracked by
315 the undo mechanism. *Note Duplicable Extents::.
317 - Function: extent-detached-p extent
318 This function returns `nil' if EXTENT is detached, and `t'
321 - Function: copy-extent extent &optional object
322 This function makes a copy of EXTENT. It is initially detached.
323 Optional argument OBJECT defaults to EXTENT's object (normally a
324 buffer or string, but could be `nil').
326 - Function: insert-extent extent &optional start end no-hooks object
327 This function inserts EXTENT from START to END in OBJECT (a buffer
328 or string). If EXTENT is detached from a different buffer or
329 string, or in most cases when EXTENT is already attached, the
330 extent will first be copied as if with `copy-extent'. This
331 function operates the same as if `insert' were called on a string
332 whose extent data calls for EXTENT to be inserted, except that if
333 NO-HOOKS is non-`nil', EXTENT's `paste-function' will not be
334 invoked. *Note Duplicable Extents::.
337 File: lispref.info, Node: Extent Parents, Next: Duplicable Extents, Prev: Detached Extents, Up: Extents
342 An extent can have a parent extent set for it. If this is the case,
343 the extent derives all its properties from that extent and has no
344 properties of its own. The only "properties" that the extent keeps are
345 the buffer or string it refers to and the start and end points. (More
346 correctly, the extent's own properties are shadowed. If you later
347 change the extent to have no parent, its own properties will become
350 It is possible for an extent's parent to itself have a parent, and
351 so on. Through this, a whole tree of extents can be created, all
352 deriving their properties from one root extent. Note, however, that
353 you cannot create an inheritance loop--this is explicitly disallowed.
355 Parent extents are used to implement the extents over the modeline.
357 - Function: set-extent-parent extent parent
358 This function sets the parent of EXTENT to PARENT. If PARENT is
359 `nil', the extent is set to have no parent.
361 - Function: extent-parent extent
362 This function return the parents (if any) of EXTENT, or `nil'.
364 - Function: extent-children extent
365 This function returns a list of the children (if any) of EXTENT.
366 The children of an extent are all those extents whose parent is
367 that extent. This function does not recursively trace children of
370 - Function: extent-descendants extent
371 This function returns a list of all descendants of EXTENT,
372 including EXTENT. This recursively applies `extent-children' to
373 any children of EXTENT, until no more children can be found.
376 File: lispref.info, Node: Duplicable Extents, Next: Extents and Events, Prev: Extent Parents, Up: Extents
381 If an extent has the `duplicable' property, it will be copied into
382 strings, so that kill, yank, and undo commands will restore or copy it.
386 * When a string is created using `buffer-substring' or
387 `buffer-string', any duplicable extents in the region corresponding
388 to the string will be copied into the string (*note Buffer
389 Contents::). When the string in inserted into a buffer using
390 `insert', `insert-before-markers', `insert-buffer' or
391 `insert-buffer-substring', the extents in the string will be copied
392 back into the buffer (*note Insertion::). The extents in a string
393 can, of course, be retrieved explicitly using the standard extent
394 primitives over the string.
396 * Similarly, when text is copied or cut into the kill ring, any
397 duplicable extents will be remembered and reinserted later when
398 the text is pasted back into a buffer.
400 * When `concat' is called on strings, the extents in the strings are
401 copied into the resulting string.
403 * When `substring' is called on a string, the relevant extents are
404 copied into the resulting string.
406 * When a duplicable extent is detached by `detach-extent' or string
407 deletion, or inserted by `insert-extent' or string insertion, the
408 action is recorded by the undo mechanism so that it can be undone
409 later. Note that if an extent gets detached and then a later undo
410 causes the extent to get reinserted, the new extent will not be
411 `eq' to the original extent.
413 * Extent motion, face changes, and attachment via `make-extent' are
414 not recorded by the undo mechanism. This means that extent changes
415 which are to be undo-able must be performed by character editing,
416 or by insertion and detachment of duplicable extents.
418 * A duplicable extent's `copy-function' property, if non-`nil',
419 should be a function, and will be run when a duplicable extent is
420 about to be copied from a buffer to a string (or the kill ring).
421 It is called with three arguments: the extent and the buffer
422 positions within it which are being copied. If this function
423 returns `nil', then the extent will not be copied; otherwise it
426 * A duplicable extent's `paste-function' property, if non-`nil',
427 should be a function, and will be run when a duplicable extent is
428 about to be copied from a string (or the kill ring) into a buffer.
429 It is called with three arguments: the original extent and the
430 buffer positions which the copied extent will occupy. (This hook
431 is run after the corresponding text has already been inserted into
432 the buffer.) Note that the extent argument may be detached when
433 this function is run. If this function returns `nil', no extent
434 will be inserted. Otherwise, there will be an extent covering the
437 Note: if the extent to be copied is already attached to the buffer
438 and overlaps the new range, the extent will simply be extended and
439 the `paste-function' will not be called.
442 File: lispref.info, Node: Extents and Events, Next: Atomic Extents, Prev: Duplicable Extents, Up: Extents
444 Interaction of Extents with Keyboard and Mouse Events
445 =====================================================
447 If an extent has the `mouse-face' property set, it will be
448 highlighted when the mouse passes over it. Highlighting is accomplished
449 by merging the extent's face with the face or faces specified by the
450 `mouse-face' property. The effect is as if a pseudo-extent with the
451 `mouse-face' face were inserted after the extent in the display order
452 (*note Extent Endpoints::, display order).
454 - Variable: mouse-highlight-priority
455 This variable holds the priority to use when merging in the
456 highlighting pseudo-extent. The default is 1000. This is
457 purposely set very high so that the highlighting pseudo-extent
458 shows up even if there are other extents with various priorities
459 at the same location.
461 You can also explicitly cause an extent to be highlighted. Only one
462 extent at a time can be highlighted in this fashion, and any other
463 highlighted extent will be de-highlighted.
465 - Function: highlight-extent extent &optional highlight-p
466 This function highlights (if HIGHLIGHT-P is non-`nil') or
467 de-highlights (if HIGHLIGHT-P is `nil') EXTENT, if EXTENT has the
468 `mouse-face' property. (Nothing happens if EXTENT does not have
469 the `mouse-face' property.)
471 - Function: force-highlight-extent extent &optional highlight-p
472 This function is similar to `highlight-extent' but highlights or
473 de-highlights the extent regardless of whether it has the
474 `mouse-face' property.
476 If an extent has a `keymap' property, this keymap will be consulted
477 for mouse clicks on the extent and keypresses made while `point' is
478 within the extent. The behavior of mouse clicks and keystrokes not
479 defined in the keymap is as normal for the buffer.
482 File: lispref.info, Node: Atomic Extents, Prev: Extents and Events, Up: Extents
487 If the Lisp file `atomic-extents' is loaded, then the atomic extent
488 facility is available. An "atomic extent" is an extent for which
489 `point' cannot be positioned anywhere within it. This ensures that
490 when selecting text, either all or none of the extent is selected.
492 To make an extent atomic, set its `atomic' property.
495 File: lispref.info, Node: Specifiers, Next: Faces and Window-System Objects, Prev: Extents, Up: Top
500 A specifier is an object used to keep track of a property whose value
501 may vary depending on the particular situation (e.g. particular buffer
502 displayed in a particular window) that it is used in. The value of many
503 built-in properties, such as the font, foreground, background, and such
504 properties of a face and variables such as `modeline-shadow-thickness'
505 and `top-toolbar-height', is actually a specifier object. The
506 specifier object, in turn, is "instanced" in a particular situation to
507 yield the real value of the property in that situation.
509 - Function: specifierp object
510 This function returns non-`nil' if OBJECT is a specifier.
514 * Introduction to Specifiers:: Specifiers provide a clean way for
515 display and other properties to vary
516 (under user control) in a wide variety
518 * Specifiers In-Depth:: Gory details about specifier innards.
519 * Specifier Instancing:: Instancing means obtaining the ``value'' of
520 a specifier in a particular context.
521 * Specifier Types:: Specifiers come in different flavors.
522 * Adding Specifications:: Specifications control a specifier's ``value''
523 by giving conditions under which a
524 particular value is valid.
525 * Retrieving Specifications:: Querying a specifier's specifications.
526 * Specifier Tag Functions:: Working with specifier tags.
527 * Specifier Instancing Functions::
528 Functions to instance a specifier.
529 * Specifier Example:: Making all this stuff clearer.
530 * Creating Specifiers:: Creating specifiers for your own use.
531 * Specifier Validation Functions::
532 Validating the components of a specifier.
533 * Other Specification Functions::
534 Other ways of working with specifications.
537 File: lispref.info, Node: Introduction to Specifiers, Next: Specifiers In-Depth, Up: Specifiers
539 Introduction to Specifiers
540 ==========================
542 Sometimes you may want the value of a property to vary depending on
543 the context the property is used in. A simple example of this in XEmacs
544 is buffer-local variables. For example, the variable
545 `modeline-format', which controls the format of the modeline, can have
546 different values depending on the particular buffer being edited. The
547 variable has a default value which most modes will use, but a
548 specialized package such as Calendar might change the variable so as to
549 tailor the modeline to its own purposes.
551 Other properties (such as those that can be changed by the
552 `modify-frame-parameters' function, for example the color of the text
553 cursor) can have frame-local values, although it might also make sense
554 for them to have buffer-local values. In other cases, you might want
555 the property to vary depending on the particular window within the
556 frame that applies (e.g. the top or bottom window in a split frame), the
557 device type that that frame appears on (X or tty), etc. Perhaps you can
558 envision some more complicated scenario where you want a particular
559 value in a specified buffer, another value in all other buffers
560 displayed on a particular frame, another value in all other buffers
561 displayed in all other frames on any mono (two-color, e.g. black and
562 white only) displays, and a default value in all other circumstances.
564 A "specifier" is a generalization of this, allowing a great deal of
565 flexibility in controlling exactly what value a property has in which
566 circumstances. It is most commonly used for display properties, such as
567 an image or the foreground color of a face. As a simple example, you
568 can specify that the foreground of the default face be
570 * blue for a particular buffer
572 * green for all other buffers
574 As a more complicated example, you could specify that the foreground
575 of the default face be
577 * forest green for all buffers displayed in a particular Emacs
578 window, or green if the X server doesn't recognize the color
581 * blue for all buffers displayed in a particular frame
583 * red for all other buffers displayed on a color device
585 * white for all other buffers
588 File: lispref.info, Node: Specifiers In-Depth, Next: Specifier Instancing, Prev: Introduction to Specifiers, Up: Specifiers
590 In-Depth Overview of a Specifier
591 ================================
593 A specifier object encapsulates a set of "specifications", each of
594 which says what its value should be if a particular condition applies.
595 For example, one specification might be "The value should be
596 darkseagreen2 on X devices" another might be "The value should be blue
597 in the *Help* buffer". In specifier terminology, these conditions are
598 called "locales" and the values are called "instantiators". Given a
599 specifier, a logical question is "What is its value in a particular
600 situation?" This involves looking through the specifications to see
601 which ones apply to this particular situation, and perhaps preferring
602 one over another if more than one applies. In specifier terminology, a
603 "particular situation" is called a "domain", and determining its value
604 in a particular domain is called "instancing". Most of the time, a
605 domain is identified by a particular window. For example, if the
606 redisplay engine is drawing text in the default face in a particular
607 window, it retrieves the specifier for the foreground color of the
608 default face and "instances" it in the domain given by that window; in
609 other words, it asks the specifier, "What is your value in this
612 More specifically, a specifier contains a set of "specifications",
613 each of which associates a "locale" (a window object, a buffer object,
614 a frame object, a device object, or the symbol `global') with an
615 "inst-list", which is a list of one or more "inst-pairs". (For each
616 possible locale, there can be at most one specification containing that
617 locale.) Each inst-pair is a cons of a "tag set" (an unordered list of
618 zero or more symbols, or "tags") and an "instantiator" (the allowed
619 form of this varies depending on the type of specifier). In a given
620 specification, there may be more than one inst-pair with the same tag
621 set; this is unlike for locales.
623 The tag set is used to restrict the sorts of devices over which the
624 instantiator is valid and to uniquely identify instantiators added by a
625 particular application, so that different applications can work on the
626 same specifier and not interfere with each other. Each tag can have a
627 "predicate" associated with it, which is a function of one argument (a
628 device) that specifies whether the tag matches that particular device.
629 (If a tag does not have a predicate, it matches all devices.) All tags
630 in a tag set must match a device for the associated inst-pair to be
631 instantiable over that device. (A null tag set is perfectly valid.)
633 The valid device types (normally `x', `tty', and `stream') and
634 device classes (normally `color', `grayscale', and `mono') can always
635 be used as tags, and match devices of the associated type or class
636 (*note Consoles and Devices::). User-defined tags may be defined, with
637 an optional predicate specified. An application can create its own
638 tag, use it to mark all its instantiators, and be fairly confident that
639 it will not interfere with other applications that modify the same
640 specifier--Functions that add a specification to a specifier usually
641 only overwrite existing inst-pairs with the same tag set as was given,
642 and a particular tag or tag set can be specified when removing
645 When a specifier is instanced in a domain, both the locale and the
646 tag set can be viewed as specifying necessary conditions that must
647 apply in that domain for an instantiator to be considered as a possible
648 result of the instancing. More specific locales always override more
649 general locales (thus, there is no particular ordering of the
650 specifications in a specifier); however, the tag sets are simply
651 considered in the order that the inst-pairs occur in the
652 specification's inst-list.
654 Note also that the actual object that results from the instancing
655 (called an "instance object") may not be the same as the instantiator
656 from which it was derived. For some specifier types (such as integer
657 specifiers and boolean specifiers), the instantiator will be returned
658 directly as the instance object. For other types, however, this is not
659 the case. For example, for font specifiers, the instantiator is a
660 font-description string and the instance object is a font-instance
661 object, which describes how the font is displayed on a particular
662 device. A font-instance object encapsulates such things as the actual
663 font name used to display the font on that device (a font-description
664 string under X is usually a wildcard specification that may resolve to
665 different font names, with possibly different foundries, widths, etc.,
666 on different devices), the extra properties of that font on that
667 device, etc. Furthermore, this conversion (called "instantiation")
668 might fail--a font or color might not exist on a particular device, for
672 File: lispref.info, Node: Specifier Instancing, Next: Specifier Types, Prev: Specifiers In-Depth, Up: Specifiers
674 How a Specifier Is Instanced
675 ============================
677 Instancing of a specifier in a particular window domain proceeds as
680 * First, XEmacs searches for a specification whose locale is the
681 same as the window. If that fails, the search is repeated,
682 looking for a locale that is the same as the window's buffer. If
683 that fails, the search is repeated using the window's frame, then
684 using the device that frame is on. Finally, the specification
685 whose locale is the symbol `global' (if there is such a
686 specification) is considered.
688 * The inst-pairs contained in the specification that was found are
689 considered in their order in the inst-list, looking for one whose
690 tag set matches the device that is derived from the window domain.
691 (The tag set is an unordered list of zero or more tag symbols.
692 For all tags that have predicates associated with them, the
693 predicate must match the device.)
695 * If a matching tag set is found, the corresponding instantiator is
696 passed to the specifier's instantiation method, which is specific
697 to the type of the specifier. If it succeeds, the resulting
698 instance object is returned as the result of the instancing and
699 the instancing is done. Otherwise, the operation continues,
700 looking for another matching inst-pair in the current
703 * When there are no more inst-pairs to be considered in the current
704 specification, the search starts over, looking for another
705 specification as in the first step above.
707 * If all specifications are exhausted and no instance object can be
708 derived, the instancing fails. (Actually, this is not completely
709 true. Some specifier objects for built-in properties have a
710 "fallback" value, which is either an inst-list or another
711 specifier object, that is consulted if the instancing is about to
712 fail. If it is an inst-list, the searching proceeds using the
713 inst-pairs in that list. If it is a specifier, the entire
714 instancing starts over using that specifier instead of the given
715 one. Fallback values are set by the C code and cannot be
716 modified, except perhaps indirectly, using any Lisp functions.
717 The purpose of them is to supply some values to make sure that
718 instancing of built-in properties can't fail and to implement some
719 basic specifier inheritance, such as the fact that faces inherit
720 their properties from the `default' face.)
722 It is also possible to instance a specifier over a frame domain or
723 device domain instead of over a window domain. The C code, for example,
724 instances the `top-toolbar-height' variable over a frame domain in
725 order to determine the height of a frame's top toolbar. Instancing over
726 a frame or device is similar to instancing over a window except that
727 specifications for locales that cannot be derived from the domain are
728 ignored. Specifically, instancing over a frame looks first for frame
729 locales, then device locales, then the `global' locale. Instancing
730 over a device domain looks only for device locales and the `global'
734 File: lispref.info, Node: Specifier Types, Next: Adding Specifications, Prev: Specifier Instancing, Up: Specifiers
739 There are various different types of specifiers. The type of a
740 specifier controls what sorts of instantiators are valid, how an
741 instantiator is instantiated, etc. Here is a list of built-in specifier
745 The valid instantiators are the symbols `t' and `nil'. Instance
746 objects are the same as instantiators so no special instantiation
750 The valid instantiators are integers. Instance objects are the
751 same as instantiators so no special instantiation function is
752 needed. `modeline-shadow-thickness' is an example of an integer
753 specifier (negative thicknesses indicate that the shadow is drawn
754 recessed instead of raised).
757 The valid instantiators are natnums (non-negative integers).
758 Instance objects are the same as instantiators so no special
759 instantiation function is needed. Natnum specifiers are used for
760 dimension variables such as `top-toolbar-height'.
763 All Lisp objects are valid instantiators. Instance objects are
764 the same as instantiators so no special instantiation function is
768 The valid instantiators are strings describing fonts or vectors
769 indicating inheritance from the font of some face. Instance
770 objects are font-instance objects, which are specific to a
771 particular device. The instantiation method for font specifiers
772 can fail, unlike for integer, natnum, boolean, and generic
776 The valid instantiators are strings describing colors or vectors
777 indicating inheritance from the foreground or background of some
778 face. Instance objects are color-instance objects, which are
779 specific to a particular device. The instantiation method for
780 color specifiers can fail, as for font specifiers.
783 Images are perhaps the most complicated type of built-in
784 specifier. The valid instantiators are strings (a filename,
785 inline data for a pixmap, or text to be displayed in a text glyph)
786 or vectors describing inline data of various sorts or indicating
787 inheritance from the background-pixmap property of some face.
788 Instance objects are either strings (for text images),
789 image-instance objects (for pixmap images), or subwindow objects
790 (for subwindow images). The instantiation method for image
791 specifiers can fail, as for font and color specifiers.
794 The valid instantiators are the symbols `t' and `nil' and vectors
795 indicating inheritance from a boolean property of some face.
796 Specifiers of this sort are used for all of the built-in boolean
797 properties of faces. Instance objects are either the symbol `t'
801 The valid instantiators are toolbar descriptors, which are lists
802 of toolbar-button descriptors (each of which is a vector of two or
803 four elements). *Note Toolbar::, for more information.
805 Color and font instance objects can also be used in turn as
806 instantiators for a new color or font instance object. Since these
807 instance objects are device-specific, the instantiator can be used
808 directly as the new instance object, but only if they are of the same
809 device. If the devices differ, the base color or font of the
810 instantiating object is effectively used instead as the instantiator.
812 *Note Faces and Window-System Objects::, for more information on
813 fonts, colors, and face-boolean specifiers. *Note Glyphs::, for more
814 information about image specifiers. *Note Toolbar::, for more
815 information on toolbar specifiers.
817 - Function: specifier-type specifier
818 This function returns the type of SPECIFIER. The returned value
819 will be a symbol: one of `integer', `boolean', etc., as listed in
822 Functions are also provided to query whether an object is a
823 particular kind of specifier:
825 - Function: boolean-specifier-p object
826 This function returns non-`nil' if OBJECT is a boolean specifier.
828 - Function: integer-specifier-p object
829 This function returns non-`nil' if OBJECT is an integer specifier.
831 - Function: natnum-specifier-p object
832 This function returns non-`nil' if OBJECT is a natnum specifier.
834 - Function: generic-specifier-p object
835 This function returns non-`nil' if OBJECT is a generic specifier.
837 - Function: face-boolean-specifier-p object
838 This function returns non-`nil' if OBJECT is a face-boolean
841 - Function: toolbar-specifier-p object
842 This function returns non-`nil' if OBJECT is a toolbar specifier.
844 - Function: font-specifier-p object
845 This function returns non-`nil' if OBJECT is a font specifier.
847 - Function: color-specifier-p object
848 This function returns non-`nil' if OBJECT is a color specifier.
850 - Function: image-specifier-p object
851 This function returns non-`nil' if OBJECT is an image specifier.
854 File: lispref.info, Node: Adding Specifications, Next: Retrieving Specifications, Prev: Specifier Types, Up: Specifiers
856 Adding specifications to a Specifier
857 ====================================
859 - Function: add-spec-to-specifier specifier instantiator &optional
860 locale tag-set how-to-add
861 This function adds a specification to SPECIFIER. The
862 specification maps from LOCALE (which should be a window, buffer,
863 frame, device, or the symbol `global', and defaults to `global')
864 to INSTANTIATOR, whose allowed values depend on the type of the
865 specifier. Optional argument TAG-SET limits the instantiator to
866 apply only to the specified tag set, which should be a list of
867 tags all of which must match the device being instantiated over
868 (tags are a device type, a device class, or tags defined with
869 `define-specifier-tag'). Specifying a single symbol for TAG-SET
870 is equivalent to specifying a one-element list containing that
871 symbol. Optional argument HOW-TO-ADD specifies what to do if
872 there are already specifications in the specifier. It should be
876 Put at the beginning of the current list of instantiators for
880 Add to the end of the current list of instantiators for
883 `remove-tag-set-prepend'
884 This is the default. Remove any existing instantiators whose
885 tag set is the same as TAG-SET; then put the new instantiator
886 at the beginning of the current list.
888 `remove-tag-set-append'
889 Remove any existing instantiators whose tag set is the same as
890 TAG-SET; then put the new instantiator at the end of the
894 Remove all previous instantiators for this locale before
898 Remove all specifications for all locales of the same type as
899 LOCALE (this includes LOCALE itself) before adding the new
903 Remove all specifications from the specifier before adding
906 `remove-tag-set-prepend' is the default.
908 You can retrieve the specifications for a particular locale or
909 locale type with the function `specifier-spec-list' or
912 - Function: add-spec-list-to-specifier specifier spec-list &optional
914 This function adds a "spec-list" (a list of specifications) to
915 SPECIFIER. The format of a spec-list is
917 `((LOCALE (TAG-SET . INSTANTIATOR) ...) ...)'
921 * LOCALE := a window, a buffer, a frame, a device, or `global'
923 * TAG-SET := an unordered list of zero or more TAGS, each of
926 * TAG := a device class (*note Consoles and Devices::), a
927 device type, or a tag defined with `define-specifier-tag'
929 * INSTANTIATOR := format determined by the type of specifier
931 The pair `(TAG-SET . INSTANTIATOR)' is called an "inst-pair". A
932 list of inst-pairs is called an "inst-list". The pair `(LOCALE .
933 INST-LIST)' is called a "specification". A spec-list, then, can
934 be viewed as a list of specifications.
936 HOW-TO-ADD specifies how to combine the new specifications with
937 the existing ones, and has the same semantics as for
938 `add-spec-to-specifier'.
940 In many circumstances, the higher-level function `set-specifier' is
941 more convenient and should be used instead.
943 - Macro: let-specifier specifier-list &rest body
944 This special form temporarily adds specifications to specifiers,
945 evaluates forms in BODY and restores the specifiers to their
946 previous states. The specifiers and their temporary
947 specifications are listed in SPECIFIER-LIST.
949 The format of SPECIFIER-LIST is
951 ((SPECIFIER VALUE &optional LOCALE TAG-SET HOW-TO-ADD) ...)
953 SPECIFIER is the specifier to be temporarily modified. VALUE is
954 the instantiator to be temporarily added to specifier in LOCALE.
955 LOCALE, TAG-SET and HOW-TO-ADD have the same meaning as in
956 `add-spec-to-specifier'.
958 This special form is implemented as a macro; the code resulting
959 from macro expansion will add specifications to specifiers using
960 `add-spec-to-specifier'. After forms in BODY are evaluated, the
961 temporary specifications are removed and old specifier spec-lists
964 LOCALE, TAG-SET and HOW-TO-ADD may be omitted, and default to
965 `nil'. The value of the last form in BODY is returned.
967 NOTE: If you want the specifier's instance to change in all
968 circumstances, use `(selected-window)' as the LOCALE. If LOCALE
969 is `nil' or omitted, it defaults to `global'.
971 The following example removes the 3D modeline effect in the
972 currently selected window for the duration of a second:
974 (let-specifier ((modeline-shadow-thickness 0 (selected-window)))
977 - Function: set-specifier specifier value &optional how-to-add
978 This function adds some specifications to SPECIFIER. VALUE can be
979 a single instantiator or tagged instantiator (added as a global
980 specification), a list of tagged and/or untagged instantiators
981 (added as a global specification), a cons of a locale and
982 instantiator or locale and instantiator list, a list of such
983 conses, or nearly any other reasonable form. More specifically,
984 VALUE can be anything accepted by `canonicalize-spec-list'.
986 HOW-TO-ADD is the same as in `add-spec-to-specifier'.
988 Note that `set-specifier' is exactly complementary to
989 `specifier-specs' except in the case where SPECIFIER has no specs
990 at all in it but `nil' is a valid instantiator (in that case,
991 `specifier-specs' will return `nil' (meaning no specs) and
992 `set-specifier' will interpret the `nil' as meaning "I'm adding a
993 global instantiator and its value is `nil'"), or in strange cases
994 where there is an ambiguity between a spec-list and an inst-list,
995 etc. (The built-in specifier types are designed in such a way as
996 to avoid any such ambiguities.)
998 If you want to work with spec-lists, you should probably not use
999 these functions, but should use the lower-level functions
1000 `specifier-spec-list' and `add-spec-list-to-specifier'. These
1001 functions always work with fully-qualified spec-lists; thus, there
1004 - Function: canonicalize-inst-pair inst-pair specifier-type &optional
1006 This function canonicalizes the given INST-PAIR.
1008 SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST
1011 Canonicalizing means converting to the full form for an inst-pair,
1012 i.e. `(TAG-SET . INSTANTIATOR)'. A single, untagged instantiator
1013 is given a tag set of `nil' (the empty set), and a single tag is
1014 converted into a tag set consisting only of that tag.
1016 If NOERROR is non-`nil', signal an error if the inst-pair is
1017 invalid; otherwise return `t'.
1019 - Function: canonicalize-inst-list inst-list specifier-type &optional
1021 This function canonicalizes the given INST-LIST (a list of
1024 SPECIFIER-TYPE specifies the type of specifier that this INST-LIST
1027 Canonicalizing means converting to the full form for an inst-list,
1028 i.e. `((TAG-SET . INSTANTIATOR) ...)'. This function accepts a
1029 single inst-pair or any abbreviation thereof or a list of
1030 (possibly abbreviated) inst-pairs. (See `canonicalize-inst-pair'.)
1032 If NOERROR is non-`nil', signal an error if the inst-list is
1033 invalid; otherwise return `t'.
1035 - Function: canonicalize-spec spec specifier-type &optional noerror
1036 This function canonicalizes the given SPEC (a specification).
1038 SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST
1041 Canonicalizing means converting to the full form for a spec, i.e.
1042 `(LOCALE (TAG-SET . INSTANTIATOR) ...)'. This function accepts a
1043 possibly abbreviated inst-list or a cons of a locale and a
1044 possibly abbreviated inst-list. (See `canonicalize-inst-list'.)
1046 If NOERROR is `nil', signal an error if the specification is
1047 invalid; otherwise return `t'.
1049 - Function: canonicalize-spec-list spec-list specifier-type &optional
1051 This function canonicalizes the given SPEC-LIST (a list of
1054 SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST
1057 Canonicalizing means converting to the full form for a spec-list,
1058 i.e. `((LOCALE (TAG-SET . INSTANTIATOR) ...) ...)'. This
1059 function accepts a possibly abbreviated specification or a list of
1060 such things. (See `canonicalize-spec'.) This is the function used
1061 to convert spec-lists accepted by `set-specifier' and such into a
1062 form suitable for `add-spec-list-to-specifier'.
1064 This function tries extremely hard to resolve any ambiguities, and
1065 the built-in specifier types (font, image, toolbar, etc.) are
1066 designed so that there won't be any ambiguities.
1068 If NOERROR is `nil', signal an error if the spec-list is invalid;
1069 otherwise return `t'.
projects / chise / xemacs-chise.git / blob