1 This is Info file ../../info/lispref.info, produced by Makeinfo version
2 1.68 from the input file lispref.texi.
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: Extents, Next: Specifiers, Prev: Abbrevs, Up: Top
58 An "extent" is a region of text (a start position and an end
59 position) that is displayed in a particular face and can have certain
60 other properties such as being read-only. Extents can overlap each
61 other. XEmacs efficiently handles buffers with large numbers of
64 - Function: extentp OBJECT
65 This returns `t' if OBJECT is an extent.
69 * Intro to Extents:: Extents are regions over a buffer or string.
70 * Creating and Modifying Extents::
71 Basic extent functions.
72 * Extent Endpoints:: Accessing and setting the bounds of an extent.
73 * Finding Extents:: Determining which extents are in an object.
74 * Mapping Over Extents:: More sophisticated functions for extent scanning.
75 * Extent Properties:: Extents have built-in and user-definable properties.
76 * Detached Extents:: Extents that are not in a buffer.
77 * Extent Parents:: Inheriting properties from another extent.
78 * Duplicable Extents:: Extents can be marked to be copied into strings.
79 * Extents and Events:: Extents can interact with the keyboard and mouse.
80 * Atomic Extents:: Treating a block of text as a single entity.
83 File: lispref.info, Node: Intro to Extents, Next: Creating and Modifying Extents, Up: Extents
85 Introduction to Extents
86 =======================
88 An extent is a region of text within a buffer or string that has
89 certain properties associated with it. The properties of an extent
90 primarily affect the way the text contained in the extent is displayed.
91 Extents can freely overlap each other in a buffer or string. Extents
92 are invisible to functions that merely examine the text of a buffer or
95 *Please note:* An alternative way to add properties to a buffer or
96 string is to use text properties. *Note Text Properties::.
98 An extent is logically a Lisp object consisting of a start position,
99 an end position, a buffer or string to which these positions refer, and
100 a property list. As text is inserted into a buffer, the start and end
101 positions of the extent are automatically adjusted as necessary to keep
102 the extent referring to the same text in the buffer. If text is
103 inserted at the boundary of an extent, the extent's `start-open' and
104 `end-open' properties control whether the text is included as part of
105 the extent. If the text bounded by an extent is deleted, the extent
106 becomes "detached"; its start and end positions are no longer
107 meaningful, but it maintains all its other properties and can later be
108 reinserted into a buffer. (None of these considerations apply to
109 strings, because text cannot be inserted into or deleted from a string.)
111 Each extent has a face or list of faces associated with it, which
112 controls the way in which the text bounded by the extent is displayed.
113 If an extent's face is `nil' or its properties are partially undefined,
114 the corresponding properties from the default face for the frame is
115 used. If two or more extents overlap, or if a list of more than one
116 face is specified for a particular extent, the corresponding faces are
117 merged to determine the text's displayed properties. Every extent has
118 a "priority" that determines which face takes precedence if the faces
119 conflict. (If two extents have the same priority, the one that comes
120 later in the display order takes precedence. *Note display order:
121 Extent Endpoints.) Higher-numbered priority values correspond to a
122 higher priority, and priority values can be negative. Every extent is
123 created with a priority of 0, but this can be changed with
124 `set-extent-priority'. Within a single extent with a list of faces,
125 faces earlier in the list have a higher priority than faces later in
128 Extents can be set to respond specially to key and mouse events
129 within the extent. An extent's `keymap' property controls the effect of
130 key and mouse strokes within the extent's text, and the `mouse-face'
131 property controls whether the extent is highlighted when the mouse moves
132 over it. *Note Extents and Events::.
134 An extent can optionally have a "begin-glyph" or "end-glyph"
135 associated with it. A begin-glyph or end-glyph is a pixmap or string
136 that will be displayed either at the start or end of an extent or in the
137 margin of the line that the start or end of the extent lies in,
138 depending on the extent's layout policy. Begin-glyphs and end-glyphs
139 are used to implement annotations, and you should use the annotation API
140 functions in preference to the lower-level extent functions. For more
141 information, *Note Annotations::.
143 If an extent has its `detachable' property set, it will become
144 "detached" (i.e. no longer in the buffer) when all its text its
145 deleted. Otherwise, it will simply shrink down to zero-length and sit
146 it the same place in the buffer. By default, the `detachable' property
147 is set on newly-created extents. *Note Detached Extents::.
149 If an extent has its `duplicable' property set, it will be
150 remembered when a string is created from text bounded by the extent.
151 When the string is re-inserted into a buffer, the extent will also be
152 re-inserted. This mechanism is used in the kill, yank, and undo
153 commands. *Note Duplicable Extents::.
156 File: lispref.info, Node: Creating and Modifying Extents, Next: Extent Endpoints, Prev: Intro to Extents, Up: Extents
158 Creating and Modifying Extents
159 ==============================
161 - Function: make-extent FROM TO &optional OBJECT
162 This function makes an extent for the range [FROM, TO) in OBJECT
163 (a buffer or string). OBJECT defaults to the current buffer.
164 Insertions at point TO will be outside of the extent; insertions
165 at FROM will be inside the extent, causing the extent to grow
166 (*note Extent Endpoints::.). This is the same way that markers
167 behave. The extent is initially detached if both FROM and TO are
168 `nil', and in this case OBJECT defaults to `nil', meaning the
169 extent is in no buffer or string (*note Detached Extents::.).
171 - Function: delete-extent EXTENT
172 This function removes EXTENT from its buffer and destroys it.
173 This does not modify the buffer's text, only its display
174 properties. The extent cannot be used thereafter. To remove an
175 extent in such a way that it can be re-inserted later, use
176 `detach-extent'. *Note Detached Extents::.
178 - Function: extent-object EXTENT
179 This function returns the buffer or string that EXTENT is in. If
180 the return value is `nil', this means that the extent is detached;
181 however, a detached extent will not necessarily return a value of
184 - Function: extent-live-p EXTENT
185 This function returns `nil' if EXTENT is deleted, and `t'
189 File: lispref.info, Node: Extent Endpoints, Next: Finding Extents, Prev: Creating and Modifying Extents, Up: Extents
194 Every extent has a start position and an end position, and logically
195 affects the characters between those positions. Normally the start and
196 end positions must both be valid positions in the extent's buffer or
197 string. However, both endpoints can be `nil', meaning the extent is
198 detached. *Note Detached Extents::.
200 Whether the extent overlaps its endpoints is governed by its
201 `start-open' and `end-open' properties. Insertion of a character at a
202 closed endpoint will expand the extent to include that character;
203 insertion at an open endpoint will not. Similarly, functions such as
204 `extent-at' that scan over all extents overlapping a particular
205 position will include extents with a closed endpoint at that position,
206 but not extents with an open endpoint.
208 Note that the `start-closed' and `end-closed' properties are
209 equivalent to `start-open' and `end-open' with the opposite sense.
211 Both endpoints can be equal, in which case the extent includes no
212 characters but still exists in the buffer or string. Zero-length
213 extents are used to represent annotations (*note Annotations::.) and can
214 be used as a more powerful form of a marker. Deletion of all the
215 characters in an extent may or may not result in a zero-length extent;
216 this depends on the `detachable' property (*note Detached Extents::.).
217 Insertion at the position of a zero-length extent expands the extent if
218 both endpoints are closed; goes before the extent if it has the
219 `start-open' property; and goes after the extent if it has the
220 `end-open' property. Zero-length extents with both the `start-open'
221 and `end-open' properties are treated as if their starting point were
222 closed. Deletion of a character on a side of a zero-length extent
223 whose corresponding endpoint is closed causes the extent to be detached
224 if its `detachable' property is set; if the corresponding endpoint is
225 open, the extent remains in the buffer, moving as necessary.
227 Extents are ordered within a buffer or string by increasing start
228 position, and then by decreasing end position (this is called the
231 - Function: extent-start-position EXTENT
232 This function returns the start position of EXTENT.
234 - Function: extent-end-position EXTENT
235 This function returns the end position of EXTENT.
237 - Function: extent-length EXTENT
238 This function returns the length of EXTENT in characters. If the
239 extent is detached, this returns `0'. If the extent is not
240 detached, this is equivalent to
241 (- (extent-end-position EXTENT) (extent-start-position EXTENT))
243 - Function: set-extent-endpoints EXTENT START END &optional
245 This function sets the start and end position of EXTENT to START
246 and END. If both are `nil', this is equivalent to `detach-extent'.
248 BUFFER-OR-STRING specifies the new buffer or string that the
249 extent should be in, and defaults to EXTENT's buffer or string.
250 (If `nil', and EXTENT is in no buffer and no string, it defaults
251 to the current buffer.)
253 See documentation on `detach-extent' for a discussion of undo
257 File: lispref.info, Node: Finding Extents, Next: Mapping Over Extents, Prev: Extent Endpoints, Up: Extents
262 The following functions provide a simple way of determining the
263 extents in a buffer or string. A number of more sophisticated
264 primitives for mapping over the extents in a range of a buffer or string
265 are also provided (*note Mapping Over Extents::.). When reading through
266 this section, keep in mind the way that extents are ordered (*note
267 Extent Endpoints::.).
269 - Function: extent-list &optional BUFFER-OR-STRING FROM TO FLAGS
270 This function returns a list of the extents in BUFFER-OR-STRING.
271 BUFFER-OR-STRING defaults to the current buffer if omitted. FROM
272 and TO can be used to limit the range over which extents are
273 returned; if omitted, all extents in the buffer or string are
276 More specifically, if a range is specified using FROM and TO, only
277 extents that overlap the range (i.e. begin or end inside of the
278 range) are included in the list. FROM and TO default to the
279 beginning and end of BUFFER-OR-STRING, respectively.
281 FLAGS controls how end cases are treated. For a discussion of
282 this, and exactly what "overlap" means, see `map-extents'.
284 Functions that create extents must be prepared for the possibility
285 that there are other extents in the same area, created by other
286 functions. To deal with this, functions typically mark their own
287 extents by setting a particular property on them. The following
288 function makes it easier to locate those extents.
290 - Function: extent-at POS &optional OBJECT PROPERTY BEFORE AT-FLAG
291 This function finds the "smallest" extent (i.e., the last one in
292 the display order) at (i.e., overlapping) POS in OBJECT (a buffer
293 or string) having PROPERTY set. OBJECT defaults to the current
294 buffer. PROPERTY defaults to `nil', meaning that any extent will
295 do. Returns `nil' if there is no matching extent at POS. If the
296 fourth argument BEFORE is not `nil', it must be an extent; any
297 returned extent will precede that extent. This feature allows
298 `extent-at' to be used by a loop over extents.
300 AT-FLAG controls how end cases are handled (i.e. what "at" really
301 means), and should be one of:
306 An extent is at POS if it covers the character after POS.
307 This is consistent with the way that text properties work.
310 An extent is at POS if it covers the character before POS.
313 An extent is at POS if it overlaps or abuts POS. This
314 includes all zero-length extents at POS.
316 Note that in all cases, the start-openness and end-openness of the
317 extents considered is ignored. If you want to pay attention to
318 those properties, you should use `map-extents', which gives you
321 The following low-level functions are provided for explicitly
322 traversing the extents in a buffer according to the display order.
323 These functions are mostly intended for debugging - in normal
324 operation, you should probably use `mapcar-extents' or `map-extents',
325 or loop using the BEFORE argument to `extent-at', rather than creating
326 a loop using `next-extent'.
328 - Function: next-extent EXTENT
329 Given an extent EXTENT, this function returns the next extent in
330 the buffer or string's display order. If EXTENT is a buffer or
331 string, this returns the first extent in the buffer or string.
333 - Function: previous-extent EXTENT
334 Given an extent EXTENT, this function returns the previous extent
335 in the buffer or string's display order. If EXTENT is a buffer or
336 string, this returns the last extent in the buffer or string.
339 File: lispref.info, Node: Mapping Over Extents, Next: Extent Properties, Prev: Finding Extents, Up: Extents
344 The most basic and general function for mapping over extents is
345 called `map-extents'. You should read through the definition of this
346 function to familiarize yourself with the concepts and optional
347 arguments involved. However, in practice you may find it more
348 convenient to use the function `mapcar-extents' or to create a loop
349 using the `before' argument to `extent-at' (*note Finding Extents::.).
351 - Function: map-extents FUNCTION &optional OBJECT FROM TO MAPARG FLAGS
353 This function maps FUNCTION over the extents which overlap a
354 region in OBJECT. OBJECT is normally a buffer or string but could
355 be an extent (see below). The region is normally bounded by
356 [FROM, TO) (i.e. the beginning of the region is closed and the end
357 of the region is open), but this can be changed with the FLAGS
358 argument (see below for a complete discussion).
360 FUNCTION is called with the arguments (extent, MAPARG). The
361 arguments OBJECT, FROM, TO, MAPARG, and FLAGS are all optional and
362 default to the current buffer, the beginning of OBJECT, the end of
363 OBJECT, NIL, and NIL, respectively. `map-extents' returns the
364 first non-`nil' result produced by FUNCTION, and no more calls to
365 FUNCTION are made after it returns non-`nil'.
367 If OBJECT is an extent, FROM and TO default to the extent's
368 endpoints, and the mapping omits that extent and its predecessors.
369 This feature supports restarting a loop based on `map-extents'.
370 Note: OBJECT must be attached to a buffer or string, and the
371 mapping is done over that buffer or string.
373 An extent overlaps the region if there is any point in the extent
374 that is also in the region. (For the purpose of overlap,
375 zero-length extents and regions are treated as closed on both ends
376 regardless of their endpoints' specified open/closedness.) Note
377 that the endpoints of an extent or region are considered to be in
378 that extent or region if and only if the corresponding end is
379 closed. For example, the extent [5,7] overlaps the region [2,5]
380 because 5 is in both the extent and the region. However, (5,7]
381 does not overlap [2,5] because 5 is not in the extent, and neither
382 [5,7] nor (5,7] overlaps the region [2,5) because 5 is not in the
385 The optional FLAGS can be a symbol or a list of one or more
386 symbols, modifying the behavior of `map-extents'. Allowed symbols
390 The region's end is closed.
393 The region's start is open.
396 Treat all extents as closed on both ends for the purpose of
397 determining whether they overlap the region, irrespective of
398 their actual open- or closedness.
401 Treat all extents as open on both ends.
403 `all-extents-closed-open'
404 Treat all extents as start-closed, end-open.
406 `all-extents-open-closed'
407 Treat all extents as start-open, end-closed.
410 In addition to the above conditions for extent overlap, the
411 extent's start position must lie within the specified region.
412 Note that, for this condition, open start positions are
413 treated as if 0.5 was added to the endpoint's value, and open
414 end positions are treated as if 0.5 was subtracted from the
418 The extent's end position must lie within the region.
420 `start-and-end-in-region'
421 Both the extent's start and end positions must lie within the
424 `start-or-end-in-region'
425 Either the extent's start or end position must lie within the
429 The condition specified by a `*-in-region' flag must *not*
430 hold for the extent to be considered.
432 At most one of `all-extents-closed', `all-extents-open',
433 `all-extents-closed-open', and `all-extents-open-closed' may be
436 At most one of `start-in-region', `end-in-region',
437 `start-and-end-in-region', and `start-or-end-in-region' may be
440 If optional arg PROPERTY is non-`nil', only extents with that
441 property set on them will be visited. If optional arg VALUE is
442 non-`nil', only extents whose value for that property is `eq' to
443 VALUE will be visited.
445 If you want to map over extents and accumulate a list of results,
446 the following function may be more convenient than `map-extents'.
448 - Function: mapcar-extents FUNCTION &optional PREDICATE
449 BUFFER-OR-STRING FROM TO FLAGS PROPERTY VALUE
450 This function applies FUNCTION to all extents which overlap a
451 region in BUFFER-OR-STRING. The region is delimited by FROM and
452 TO. FUNCTION is called with one argument, the extent. A list of
453 the values returned by FUNCTION is returned. An optional
454 PREDICATE may be used to further limit the extents over which
455 FUNCTION is mapped. The optional arguments FLAGS, PROPERTY, and
456 VALUE may also be used to control the extents passed to PREDICATE
457 or FUNCTION, and have the same meaning as in `map-extents'.
459 - Function: map-extent-children FUNCTION &optional OBJECT FROM TO
460 MAPARG FLAGS PROPERTY VALUE
461 This function is similar to `map-extents', but differs in that:
463 * It only visits extents which start in the given region.
465 * After visiting an extent E, it skips all other extents which
466 start inside E but end before E's end.
468 Thus, this function may be used to walk a tree of extents in a
470 (defun walk-extents (buffer &optional ignore)
471 (map-extent-children 'walk-extents buffer))
473 - Function: extent-in-region-p EXTENT &optional FROM TO FLAGS
474 This function returns T if `map-extents' would visit EXTENT if
475 called with the given arguments.
478 File: lispref.info, Node: Extent Properties, Next: Detached Extents, Prev: Mapping Over Extents, Up: Extents
480 Properties of Extents
481 =====================
483 Each extent has a property list associating property names with
484 values. Some property names have predefined meanings, and can usually
485 only assume particular values. Assigning other values to such a
486 property either cause the value to be converted into a legal value
487 (e.g., assigning anything but `nil' to a Boolean property will cause
488 the value of `t' to be assigned to the property) or will cause an
489 error. Property names without predefined meanings can be assigned any
490 value. An undefined property is equivalent to a property with a value
491 of `nil', or with a particular default value in the case of properties
492 with predefined meanings. Note that, when an extent is created, the
493 `end-open' and `detachable' properties are set on it.
495 If an extent has a parent, all of its properties actually derive
496 from that parent (or from the root ancestor if the parent in turn has a
497 parent), and setting a property of the extent actually sets that
498 property on the parent. *Note Extent Parents::.
500 - Function: extent-property EXTENT PROPERTY
501 This function returns the value of PROPERTY in EXTENT. If
502 PROPERTY is undefined, `nil' is returned.
504 - Function: extent-properties EXTENT
505 This function returns a list of all of EXTENT's properties that do
506 not have the value of `nil' (or the default value, for properties
507 with predefined meanings).
509 - Function: set-extent-property EXTENT PROPERTY VALUE
510 This function sets PROPERTY to VALUE in EXTENT. (If PROPERTY has a
511 predefined meaning, only certain values are allowed, and some
512 values may be converted to others before being stored.)
514 - Function: set-extent-properties EXTENT PLIST
515 Change some properties of EXTENT. PLIST is a property list. This
516 is useful to change many extent properties at once.
518 The following table lists the properties with predefined meanings,
519 along with their allowable values.
522 (Boolean) Whether the extent is detached. Setting this is the
523 same as calling `detach-extent'. *Note Detached Extents::.
526 (Boolean) Whether the extent has been deleted. Setting this is
527 the same as calling `delete-extent'.
530 (integer) The extent's redisplay priority. Defaults to 0. *Note
531 priority: Intro to Extents. This property can also be set with
532 `set-extent-priority' and accessed with `extent-priority'.
535 (Boolean) Whether the start position of the extent is open,
536 meaning that characters inserted at that position go outside of
537 the extent. *Note Extent Endpoints::.
540 (Boolean) Same as `start-open' but with the opposite sense.
541 Setting this property clears `start-open' and vice-versa.
544 (Boolean) Whether the end position of the extent is open, meaning
545 that characters inserted at that position go outside of the
546 extent. This is `t' by default. *Note Extent Endpoints::.
549 (Boolean) Same as `end-open' but with the opposite sense. Setting
550 this property clears `end-open' and vice-versa.
553 (Boolean) Whether text within this extent will be unmodifiable.
556 (face, face name, list of faces or face names, or `nil') The face
557 in which to display the extent's text. This property can also be
558 set with `set-extent-face' and accessed with `extent-face'. Note
559 that if a list of faces is specified, the faces are merged
560 together, with faces earlier in the list having priority over
561 faces later in the list.
564 (face, face name, list of faces or face names, or `nil') The face
565 used to display the extent when the mouse moves over it. This
566 property can also be set with `set-extent-mouse-face' and accessed
567 with `extent-mouse-face'. Note that if a list of faces is
568 specified, the faces are merged together, with faces earlier in
569 the list having priority over faces later in the list. *Note
570 Extents and Events::.
573 (pointer glyph) The glyph used as the pointer when the mouse
574 moves over the extent. This takes precedence over the
575 `text-pointer-glyph' and `nontext-pointer-glyph' variables. If
576 for any reason this glyph is an invalid pointer, the standard
577 glyphs will be used as fallbacks. *Note Mouse Pointer::.
580 (Boolean) Whether this extent becomes detached when all of the
581 text it covers is deleted. This is `t' by default. *Note
585 (Boolean) Whether this extent should be copied into strings, so
586 that kill, yank, and undo commands will restore or copy it. *Note
587 Duplicable Extents::.
590 (Boolean) Meaningful only in conjunction with `duplicable'. When
591 this is set, there may be only one instance of this extent
592 attached at a time. *Note Duplicable Extents::.
595 (Boolean) If `t', text under this extent will not be displayed -
596 it will look as if the text is not there at all.
599 (keymap or `nil') This keymap is consulted for mouse clicks on this
600 extent or keypresses made while `point' is within the extent.
601 *Note Extents and Events::.
604 This is a hook that is run when a duplicable extent is about to be
605 copied from a buffer to a string (or the kill ring). *Note
606 Duplicable Extents::.
609 This is a hook that is run when a duplicable extent is about to be
610 copied from a string (or the kill ring) into a buffer. *Note
611 Duplicable Extents::.
614 (glyph or `nil') This extent's begin glyph. *Note Annotations::.
617 (glyph or `nil') This extent's end glyph. *Note Annotations::.
620 (`text', `whitespace', `inside-margin', or `outside-margin') The
621 layout policy for this extent's begin glyph. Defaults to `text'.
625 (`text', `whitespace', `inside-margin', or `outside-margin') The
626 layout policy for this extent's end glyph. Defaults to `text'.
629 `initial-redisplay-function'
630 (any funcallable object) The function to be called the first time
631 (a part of) the extent is redisplayed. It will be called with the
632 extent as its argument.
634 This is used by `lazy-shot' to implement lazy font-locking. The
635 functionality is still experimental, and may change without further
638 The following convenience functions are provided for accessing
639 particular properties of an extent.
641 - Function: extent-face EXTENT
642 This function returns the `face' property of EXTENT. This might
643 also return a list of face names. Do not modify this list
644 directly! Instead, use `set-extent-face'.
646 Note that you can use `eq' to compare lists of faces as returned
647 by `extent-face'. In other words, if you set the face of two
648 different extents to two lists that are `equal' but not `eq', then
649 the return value of `extent-face' on the two extents will return
652 - Function: extent-mouse-face EXTENT
653 This function returns the `mouse-face' property of EXTENT. This
654 might also return a list of face names. Do not modify this list
655 directly! Instead, use `set-extent-mouse-face'.
657 Note that you can use `eq' to compare lists of faces as returned
658 by `extent-mouse-face', just like for `extent-face'.
660 - Function: extent-priority EXTENT
661 This function returns the `priority' property of EXTENT.
663 - Function: extent-keymap EXTENT
664 This function returns the `keymap' property of EXTENT.
666 - Function: extent-begin-glyph-layout EXTENT
667 This function returns the `begin-glyph-layout' property of EXTENT,
668 i.e. the layout policy associated with the EXTENT's begin glyph.
670 - Function: extent-end-glyph-layout EXTENT
671 This function returns the `end-glyph-layout' property of EXTENT,
672 i.e. the layout policy associated with the EXTENT's end glyph.
674 - Function: extent-begin-glyph EXTENT
675 This function returns the `begin-glyph' property of EXTENT, i.e.
676 the glyph object displayed at the beginning of EXTENT. If there
677 is none, `nil' is returned.
679 - Function: extent-end-glyph EXTENT
680 This function returns the `end-glyph' property of EXTENT, i.e. the
681 glyph object displayed at the end of EXTENT. If there is none,
684 The following convenience functions are provided for setting
685 particular properties of an extent.
687 - Function: set-extent-priority EXTENT PRI
688 This function sets the `priority' property of EXTENT to PRI.
690 - Function: set-extent-face EXTENT FACE
691 This function sets the `face' property of EXTENT to FACE.
693 - Function: set-extent-mouse-face EXTENT FACE
694 This function sets the `mouse-face' property of EXTENT to FACE.
696 - Function: set-extent-keymap EXTENT KEYMAP
697 This function sets the `keymap' property of EXTENT to KEYMAP.
698 KEYMAP must be either a keymap object, or `nil'.
700 - Function: set-extent-begin-glyph-layout EXTENT LAYOUT
701 This function sets the `begin-glyph-layout' property of EXTENT to
704 - Function: set-extent-end-glyph-layout EXTENT LAYOUT
705 This function sets the `end-glyph-layout' property of EXTENT to
708 - Function: set-extent-begin-glyph EXTENT BEGIN-GLYPH &optional LAYOUT
709 This function sets the `begin-glyph' and `glyph-layout' properties
710 of EXTENT to BEGIN-GLYPH and LAYOUT, respectively. (LAYOUT
711 defaults to `text' if not specified.)
713 - Function: set-extent-end-glyph EXTENT END-GLYPH &optional LAYOUT
714 This function sets the `end-glyph' and `glyph-layout' properties
715 of EXTENT to END-GLYPH and LAYOUT, respectively. (LAYOUT defaults
716 to `text' if not specified.)
718 - Function: set-extent-initial-redisplay-function EXTENT FUNCTION
719 This function sets the `initial-redisplay-function' property of the
723 File: lispref.info, Node: Detached Extents, Next: Extent Parents, Prev: Extent Properties, Up: Extents
728 A detached extent is an extent that is not attached to a buffer or
729 string but can be re-inserted. Detached extents have a start position
730 and end position of `nil'. Extents can be explicitly detached using
731 `detach-extent'. An extent is also detached when all of its characters
732 are all killed by a deletion, if its `detachable' property is set; if
733 this property is not set, the extent becomes a zero-length extent.
734 (Zero-length extents with the `detachable' property set behave
735 specially. *Note zero-length extents: Extent Endpoints.)
737 - Function: detach-extent EXTENT
738 This function detaches EXTENT from its buffer or string. If
739 EXTENT has the `duplicable' property, its detachment is tracked by
740 the undo mechanism. *Note Duplicable Extents::.
742 - Function: extent-detached-p EXTENT
743 This function returns `nil' if EXTENT is detached, and `t'
746 - Function: copy-extent EXTENT &optional OBJECT
747 This function makes a copy of EXTENT. It is initially detached.
748 Optional argument OBJECT defaults to EXTENT's object (normally a
749 buffer or string, but could be `nil').
751 - Function: insert-extent EXTENT &optional START END NO-HOOKS OBJECT
752 This function inserts EXTENT from START to END in OBJECT (a buffer
753 or string). If EXTENT is detached from a different buffer or
754 string, or in most cases when EXTENT is already attached, the
755 extent will first be copied as if with `copy-extent'. This
756 function operates the same as if `insert' were called on a string
757 whose extent data calls for EXTENT to be inserted, except that if
758 NO-HOOKS is non-`nil', EXTENT's `paste-function' will not be
759 invoked. *Note Duplicable Extents::.
762 File: lispref.info, Node: Extent Parents, Next: Duplicable Extents, Prev: Detached Extents, Up: Extents
767 An extent can have a parent extent set for it. If this is the case,
768 the extent derives all its properties from that extent and has no
769 properties of its own. The only "properties" that the extent keeps are
770 the buffer or string it refers to and the start and end points. (More
771 correctly, the extent's own properties are shadowed. If you later
772 change the extent to have no parent, its own properties will become
775 It is possible for an extent's parent to itself have a parent, and
776 so on. Through this, a whole tree of extents can be created, all
777 deriving their properties from one root extent. Note, however, that
778 you cannot create an inheritance loop - this is explicitly disallowed.
780 Parent extents are used to implement the extents over the modeline.
782 - Function: set-extent-parent EXTENT PARENT
783 This function sets the parent of EXTENT to PARENT. If PARENT is
784 `nil', the extent is set to have no parent.
786 - Function: extent-parent EXTENT
787 This function return the parents (if any) of EXTENT, or `nil'.
789 - Function: extent-children EXTENT
790 This function returns a list of the children (if any) of EXTENT.
791 The children of an extent are all those extents whose parent is
792 that extent. This function does not recursively trace children of
795 - Function: extent-descendants EXTENT
796 This function returns a list of all descendants of EXTENT,
797 including EXTENT. This recursively applies `extent-children' to
798 any children of EXTENT, until no more children can be found.
801 File: lispref.info, Node: Duplicable Extents, Next: Extents and Events, Prev: Extent Parents, Up: Extents
806 If an extent has the `duplicable' property, it will be copied into
807 strings, so that kill, yank, and undo commands will restore or copy it.
811 * When a string is created using `buffer-substring' or
812 `buffer-string', any duplicable extents in the region corresponding
813 to the string will be copied into the string (*note Buffer
814 Contents::.). When the string in inserted into a buffer using
815 `insert', `insert-before-markers', `insert-buffer' or
816 `insert-buffer-substring', the extents in the string will be copied
817 back into the buffer (*note Insertion::.). The extents in a
818 string can, of course, be retrieved explicitly using the standard
819 extent primitives over the string.
821 * Similarly, when text is copied or cut into the kill ring, any
822 duplicable extents will be remembered and reinserted later when
823 the text is pasted back into a buffer.
825 * When `concat' is called on strings, the extents in the strings are
826 copied into the resulting string.
828 * When `substring' is called on a string, the relevant extents are
829 copied into the resulting string.
831 * When a duplicable extent is detached by `detach-extent' or string
832 deletion, or inserted by `insert-extent' or string insertion, the
833 action is recorded by the undo mechanism so that it can be undone
834 later. Note that if an extent gets detached and then a later undo
835 causes the extent to get reinserted, the new extent will not be
836 `eq' to the original extent.
838 * Extent motion, face changes, and attachment via `make-extent' are
839 not recorded by the undo mechanism. This means that extent changes
840 which are to be undo-able must be performed by character editing,
841 or by insertion and detachment of duplicable extents.
843 * A duplicable extent's `copy-function' property, if non-`nil',
844 should be a function, and will be run when a duplicable extent is
845 about to be copied from a buffer to a string (or the kill ring).
846 It is called with three arguments: the extent and the buffer
847 positions within it which are being copied. If this function
848 returns `nil', then the extent will not be copied; otherwise it
851 * A duplicable extent's `paste-function' property, if non-`nil',
852 should be a function, and will be run when a duplicable extent is
853 about to be copied from a string (or the kill ring) into a buffer.
854 It is called with three arguments: the original extent and the
855 buffer positions which the copied extent will occupy. (This hook
856 is run after the corresponding text has already been inserted into
857 the buffer.) Note that the extent argument may be detached when
858 this function is run. If this function returns `nil', no extent
859 will be inserted. Otherwise, there will be an extent covering the
862 Note: if the extent to be copied is already attached to the buffer
863 and overlaps the new range, the extent will simply be extended and
864 the `paste-function' will not be called.
867 File: lispref.info, Node: Extents and Events, Next: Atomic Extents, Prev: Duplicable Extents, Up: Extents
869 Interaction of Extents with Keyboard and Mouse Events
870 =====================================================
872 If an extent has the `mouse-face' property set, it will be
873 highlighted when the mouse passes over it. Highlighting is accomplished
874 by merging the extent's face with the face or faces specified by the
875 `mouse-face' property. The effect is as if a pseudo-extent with the
876 `mouse-face' face were inserted after the extent in the display order
877 (*note Extent Endpoints::., display order).
879 - Variable: mouse-highlight-priority
880 This variable holds the priority to use when merging in the
881 highlighting pseudo-extent. The default is 1000. This is
882 purposely set very high so that the highlighting pseudo-extent
883 shows up even if there are other extents with various priorities
884 at the same location.
886 You can also explicitly cause an extent to be highlighted. Only one
887 extent at a time can be highlighted in this fashion, and any other
888 highlighted extent will be de-highlighted.
890 - Function: highlight-extent EXTENT &optional HIGHLIGHT-P
891 This function highlights (if HIGHLIGHT-P is non-`nil') or
892 de-highlights (if HIGHLIGHT-P is `nil') EXTENT, if EXTENT has the
893 `mouse-face' property. (Nothing happens if EXTENT does not have
894 the `mouse-face' property.)
896 - Function: force-highlight-extent EXTENT &optional HIGHLIGHT-P
897 This function is similar to `highlight-extent' but highlights or
898 de-highlights the extent regardless of whether it has the
899 `mouse-face' property.
901 If an extent has a `keymap' property, this keymap will be consulted
902 for mouse clicks on the extent and keypresses made while `point' is
903 within the extent. The behavior of mouse clicks and keystrokes not
904 defined in the keymap is as normal for the buffer.
907 File: lispref.info, Node: Atomic Extents, Prev: Extents and Events, Up: Extents
912 If the Lisp file `atomic-extents' is loaded, then the atomic extent
913 facility is available. An "atomic extent" is an extent for which
914 `point' cannot be positioned anywhere within it. This ensures that
915 when selecting text, either all or none of the extent is selected.
917 To make an extent atomic, set its `atomic' property.
920 File: lispref.info, Node: Specifiers, Next: Faces and Window-System Objects, Prev: Extents, Up: Top
925 A specifier is an object used to keep track of a property whose value
926 may vary depending on the particular situation (e.g. particular buffer
927 displayed in a particular window) that it is used in. The value of many
928 built-in properties, such as the font, foreground, background, and such
929 properties of a face and variables such as `modeline-shadow-thickness'
930 and `top-toolbar-height', is actually a specifier object. The
931 specifier object, in turn, is "instanced" in a particular situation to
932 yield the real value of the property in that situation.
934 - Function: specifierp OBJECT
935 This function returns non-`nil' if OBJECT is a specifier.
939 * Introduction to Specifiers:: Specifiers provide a clean way for
940 display and other properties to vary
941 (under user control) in a wide variety
943 * Specifiers In-Depth:: Gory details about specifier innards.
944 * Specifier Instancing:: Instancing means obtaining the "value" of
945 a specifier in a particular context.
946 * Specifier Types:: Specifiers come in different flavors.
947 * Adding Specifications:: Specifications control a specifier's "value"
948 by giving conditions under which a
949 particular value is valid.
950 * Retrieving Specifications:: Querying a specifier's specifications.
951 * Specifier Tag Functions:: Working with specifier tags.
952 * Specifier Instancing Functions::
953 Functions to instance a specifier.
954 * Specifier Example:: Making all this stuff clearer.
955 * Creating Specifiers:: Creating specifiers for your own use.
956 * Specifier Validation Functions::
957 Validating the components of a specifier.
958 * Other Specification Functions::
959 Other ways of working with specifications.
962 File: lispref.info, Node: Introduction to Specifiers, Next: Specifiers In-Depth, Up: Specifiers
964 Introduction to Specifiers
965 ==========================
967 Sometimes you may want the value of a property to vary depending on
968 the context the property is used in. A simple example of this in XEmacs
969 is buffer-local variables. For example, the variable
970 `modeline-format', which controls the format of the modeline, can have
971 different values depending on the particular buffer being edited. The
972 variable has a default value which most modes will use, but a
973 specialized package such as Calendar might change the variable so as to
974 tailor the modeline to its own purposes.
976 Other properties (such as those that can be changed by the
977 `modify-frame-parameters' function, for example the color of the text
978 cursor) can have frame-local values, although it might also make sense
979 for them to have buffer-local values. In other cases, you might want
980 the property to vary depending on the particular window within the
981 frame that applies (e.g. the top or bottom window in a split frame), the
982 device type that that frame appears on (X or tty), etc. Perhaps you can
983 envision some more complicated scenario where you want a particular
984 value in a specified buffer, another value in all other buffers
985 displayed on a particular frame, another value in all other buffers
986 displayed in all other frames on any mono (two-color, e.g. black and
987 white only) displays, and a default value in all other circumstances.
989 A "specifier" is a generalization of this, allowing a great deal of
990 flexibility in controlling exactly what value a property has in which
991 circumstances. It is most commonly used for display properties, such as
992 an image or the foreground color of a face. As a simple example, you
993 can specify that the foreground of the default face be
995 * blue for a particular buffer
997 * green for all other buffers
999 As a more complicated example, you could specify that the foreground
1000 of the default face be
1002 * forest green for all buffers displayed in a particular Emacs
1003 window, or green if the X server doesn't recognize the color
1006 * blue for all buffers displayed in a particular frame
1008 * red for all other buffers displayed on a color device
1010 * white for all other buffers
1013 File: lispref.info, Node: Specifiers In-Depth, Next: Specifier Instancing, Prev: Introduction to Specifiers, Up: Specifiers
1015 In-Depth Overview of a Specifier
1016 ================================
1018 A specifier object encapsulates a set of "specifications", each of
1019 which says what its value should be if a particular condition applies.
1020 For example, one specification might be "The value should be
1021 darkseagreen2 on X devices" another might be "The value should be blue
1022 in the *Help* buffer". In specifier terminology, these conditions are
1023 called "locales" and the values are called "instantiators". Given a
1024 specifier, a logical question is "What is its value in a particular
1025 situation?" This involves looking through the specifications to see
1026 which ones apply to this particular situation, and perhaps preferring
1027 one over another if more than one applies. In specifier terminology, a
1028 "particular situation" is called a "domain", and determining its value
1029 in a particular domain is called "instancing". Most of the time, a
1030 domain is identified by a particular window. For example, if the
1031 redisplay engine is drawing text in the default face in a particular
1032 window, it retrieves the specifier for the foreground color of the
1033 default face and "instances" it in the domain given by that window; in
1034 other words, it asks the specifier, "What is your value in this
1037 More specifically, a specifier contains a set of "specifications",
1038 each of which associates a "locale" (a window object, a buffer object,
1039 a frame object, a device object, or the symbol `global') with an
1040 "inst-list", which is a list of one or more "inst-pairs". (For each
1041 possible locale, there can be at most one specification containing that
1042 locale.) Each inst-pair is a cons of a "tag set" (an unordered list of
1043 zero or more symbols, or "tags") and an "instantiator" (the allowed
1044 form of this varies depending on the type of specifier). In a given
1045 specification, there may be more than one inst-pair with the same tag
1046 set; this is unlike for locales.
1048 The tag set is used to restrict the sorts of devices over which the
1049 instantiator is valid and to uniquely identify instantiators added by a
1050 particular application, so that different applications can work on the
1051 same specifier and not interfere with each other. Each tag can have a
1052 "predicate" associated with it, which is a function of one argument (a
1053 device) that specifies whether the tag matches that particular device.
1054 (If a tag does not have a predicate, it matches all devices.) All tags
1055 in a tag set must match a device for the associated inst-pair to be
1056 instantiable over that device. (A null tag set is perfectly valid.)
1058 The valid device types (normally `x', `tty', and `stream') and
1059 device classes (normally `color', `grayscale', and `mono') can always
1060 be used as tags, and match devices of the associated type or class
1061 (*note Consoles and Devices::.). User-defined tags may be defined,
1062 with an optional predicate specified. An application can create its
1063 own tag, use it to mark all its instantiators, and be fairly confident
1064 that it will not interfere with other applications that modify the same
1065 specifier - Functions that add a specification to a specifier usually
1066 only overwrite existing inst-pairs with the same tag set as was given,
1067 and a particular tag or tag set can be specified when removing
1070 When a specifier is instanced in a domain, both the locale and the
1071 tag set can be viewed as specifying necessary conditions that must
1072 apply in that domain for an instantiator to be considered as a possible
1073 result of the instancing. More specific locales always override more
1074 general locales (thus, there is no particular ordering of the
1075 specifications in a specifier); however, the tag sets are simply
1076 considered in the order that the inst-pairs occur in the
1077 specification's inst-list.
1079 Note also that the actual object that results from the instancing
1080 (called an "instance object") may not be the same as the instantiator
1081 from which it was derived. For some specifier types (such as integer
1082 specifiers and boolean specifiers), the instantiator will be returned
1083 directly as the instance object. For other types, however, this is not
1084 the case. For example, for font specifiers, the instantiator is a
1085 font-description string and the instance object is a font-instance
1086 object, which describes how the font is displayed on a particular
1087 device. A font-instance object encapsulates such things as the actual
1088 font name used to display the font on that device (a font-description
1089 string under X is usually a wildcard specification that may resolve to
1090 different font names, with possibly different foundries, widths, etc.,
1091 on different devices), the extra properties of that font on that
1092 device, etc. Furthermore, this conversion (called "instantiation")
1093 might fail - a font or color might not exist on a particular device,
projects / chise / xemacs-chise.git.1 / blob