2 @c This is part of the XEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
4 @c Copyright (C) 1996 Ben Wing.
5 @c See the file lispref.texi for copying conditions.
6 @setfilename ../../info/extents.info
7 @node Extents, Specifiers, Abbrevs, top
11 An @dfn{extent} is a region of text (a start position and an end
12 position) that is displayed in a particular face and can have certain
13 other properties such as being read-only. Extents can overlap each
14 other. XEmacs efficiently handles buffers with large numbers of
18 This returns @code{t} if @var{object} is an extent.
22 * Intro to Extents:: Extents are regions over a buffer or string.
23 * Creating and Modifying Extents::
24 Basic extent functions.
25 * Extent Endpoints:: Accessing and setting the bounds of an extent.
26 * Finding Extents:: Determining which extents are in an object.
27 * Mapping Over Extents:: More sophisticated functions for extent scanning.
28 * Extent Properties:: Extents have built-in and user-definable properties.
29 * Detached Extents:: Extents that are not in a buffer.
30 * Extent Parents:: Inheriting properties from another extent.
31 * Duplicable Extents:: Extents can be marked to be copied into strings.
32 * Extents and Events:: Extents can interact with the keyboard and mouse.
33 * Atomic Extents:: Treating a block of text as a single entity.
36 @node Intro to Extents
37 @section Introduction to Extents
38 @cindex extent priority
39 @cindex priority of an extent
41 An extent is a region of text within a buffer or string that has
42 certain properties associated with it. The properties of an extent
43 primarily affect the way the text contained in the extent is displayed.
44 Extents can freely overlap each other in a buffer or string. Extents
45 are invisible to functions that merely examine the text of a buffer or
48 @emph{Please note:} An alternative way to add properties to a buffer or
49 string is to use text properties. @xref{Text Properties}.
51 An extent is logically a Lisp object consisting of a start position,
52 an end position, a buffer or string to which these positions refer, and
53 a property list. As text is inserted into a buffer, the start and end
54 positions of the extent are automatically adjusted as necessary to keep
55 the extent referring to the same text in the buffer. If text is
56 inserted at the boundary of an extent, the extent's @code{start-open}
57 and @code{end-open} properties control whether the text is included as
58 part of the extent. If the text bounded by an extent is deleted, the
59 extent becomes @dfn{detached}; its start and end positions are no longer
60 meaningful, but it maintains all its other properties and can later be
61 reinserted into a buffer. (None of these considerations apply to strings,
62 because text cannot be inserted into or deleted from a string.)
64 Each extent has a face or list of faces associated with it, which
65 controls the way in which the text bounded by the extent is displayed.
66 If an extent's face is @code{nil} or its properties are partially
67 undefined, the corresponding properties from the default face for the
68 frame is used. If two or more extents overlap, or if a list of more
69 than one face is specified for a particular extent, the corresponding
70 faces are merged to determine the text's displayed properties. Every
71 extent has a @dfn{priority} that determines which face takes precedence
72 if the faces conflict. (If two extents have the same priority, the one
73 that comes later in the display order takes precedence. @xref{Extent
74 Endpoints, display order}.) Higher-numbered priority values correspond
75 to a higher priority, and priority values can be negative. Every extent
76 is created with a priority of 0, but this can be changed with
77 @code{set-extent-priority}. Within a single extent with a list of faces,
78 faces earlier in the list have a higher priority than faces later in
81 Extents can be set to respond specially to key and mouse events within
82 the extent. An extent's @code{keymap} property controls the effect of
83 key and mouse strokes within the extent's text, and the @code{mouse-face}
84 property controls whether the extent is highlighted when the mouse moves
85 over it. @xref{Extents and Events}.
87 An extent can optionally have a @dfn{begin-glyph} or @dfn{end-glyph}
88 associated with it. A begin-glyph or end-glyph is a pixmap or string
89 that will be displayed either at the start or end of an extent or in the
90 margin of the line that the start or end of the extent lies in,
91 depending on the extent's layout policy. Begin-glyphs and end-glyphs
92 are used to implement annotations, and you should use the annotation API
93 functions in preference to the lower-level extent functions. For more
94 information, @xref{Annotations}.
96 If an extent has its @code{detachable} property set, it will become
97 @dfn{detached} (i.e. no longer in the buffer) when all its text its
98 deleted. Otherwise, it will simply shrink down to zero-length and
99 sit it the same place in the buffer. By default, the @code{detachable}
100 property is set on newly-created extents. @xref{Detached Extents}.
102 If an extent has its @code{duplicable} property set, it will be
103 remembered when a string is created from text bounded by the extent.
104 When the string is re-inserted into a buffer, the extent will also
105 be re-inserted. This mechanism is used in the kill, yank, and undo
106 commands. @xref{Duplicable Extents}.
108 @node Creating and Modifying Extents
109 @section Creating and Modifying Extents
111 @defun make-extent from to &optional object
112 This function makes an extent for the range [@var{from}, @var{to}) in
113 @var{object} (a buffer or string). @var{object} defaults to the current
114 buffer. Insertions at point @var{to} will be outside of the extent;
115 insertions at @var{from} will be inside the extent, causing the extent
116 to grow (@pxref{Extent Endpoints}). This is the same way that markers
117 behave. The extent is initially detached if both @var{from} and
118 @var{to} are @code{nil}, and in this case @var{object} defaults to
119 @code{nil}, meaning the extent is in no buffer or string
120 (@pxref{Detached Extents}).
123 @defun delete-extent extent
124 This function removes @var{extent} from its buffer and destroys it.
125 This does not modify the buffer's text, only its display properties.
126 The extent cannot be used thereafter. To remove an extent in such
127 a way that it can be re-inserted later, use @code{detach-extent}.
128 @xref{Detached Extents}.
131 @defun extent-object extent
132 This function returns the buffer or string that @var{extent} is in. If
133 the return value is @code{nil}, this means that the extent is detached;
134 however, a detached extent will not necessarily return a value of
138 @defun extent-live-p extent
139 This function returns @code{nil} if @var{extent} is deleted, and
143 @node Extent Endpoints
144 @section Extent Endpoints
145 @cindex extent endpoint
146 @cindex extent start position
147 @cindex extent end position
148 @cindex zero-length extent
149 @cindex display order
151 @cindex order of extents
153 Every extent has a start position and an end position, and logically
154 affects the characters between those positions. Normally the start and
155 end positions must both be valid positions in the extent's buffer or
156 string. However, both endpoints can be @code{nil}, meaning the extent
157 is detached. @xref{Detached Extents}.
159 Whether the extent overlaps its endpoints is governed by its
160 @code{start-open} and @code{end-open} properties. Insertion of a
161 character at a closed endpoint will expand the extent to include that
162 character; insertion at an open endpoint will not. Similarly, functions
163 such as @code{extent-at} that scan over all extents overlapping a
164 particular position will include extents with a closed endpoint at that
165 position, but not extents with an open endpoint.
167 Note that the @code{start-closed} and @code{end-closed} properties are
168 equivalent to @code{start-open} and @code{end-open} with the opposite
171 Both endpoints can be equal, in which case the extent includes no
172 characters but still exists in the buffer or string. Zero-length
173 extents are used to represent annotations (@pxref{Annotations}) and can
174 be used as a more powerful form of a marker. Deletion of all the
175 characters in an extent may or may not result in a zero-length extent;
176 this depends on the @code{detachable} property (@pxref{Detached
177 Extents}). Insertion at the position of a zero-length extent expands
178 the extent if both endpoints are closed; goes before the extent if it
179 has the @code{start-open} property; and goes after the extent if it has
180 the @code{end-open} property. Zero-length extents with both the
181 @code{start-open} and @code{end-open} properties are treated as if their
182 starting point were closed. Deletion of a character on a side of a
183 zero-length extent whose corresponding endpoint is closed causes the
184 extent to be detached if its @code{detachable} property is set; if the
185 corresponding endpoint is open, the extent remains in the buffer, moving
188 Extents are ordered within a buffer or string by increasing start
189 position, and then by decreasing end position (this is called the
190 @dfn{display order}).
192 @defun extent-start-position extent
193 This function returns the start position of @var{extent}.
196 @defun extent-end-position extent
197 This function returns the end position of @var{extent}.
200 @defun extent-length extent
201 This function returns the length of @var{extent} in characters. If
202 the extent is detached, this returns @code{0}. If the extent is not
203 detached, this is equivalent to
205 (- (extent-end-position @var{extent}) (extent-start-position @var{extent}))
209 @defun set-extent-endpoints extent start end &optional buffer-or-string
210 This function sets the start and end position of @var{extent} to
211 @var{start} and @var{end}. If both are @code{nil}, this is equivalent
212 to @code{detach-extent}.
214 @var{buffer-or-string} specifies the new buffer or string that the
215 extent should be in, and defaults to @var{extent}'s buffer or
216 string. (If @code{nil}, and @var{extent} is in no buffer and no string,
217 it defaults to the current buffer.)
219 See documentation on @code{detach-extent} for a discussion of undo
223 @node Finding Extents
224 @section Finding Extents
225 @cindex extents, locating
227 The following functions provide a simple way of determining the
228 extents in a buffer or string. A number of more sophisticated
229 primitives for mapping over the extents in a range of a buffer or string
230 are also provided (@pxref{Mapping Over Extents}). When reading through
231 this section, keep in mind the way that extents are ordered
232 (@pxref{Extent Endpoints}).
234 @defun extent-list &optional buffer-or-string from to flags
235 This function returns a list of the extents in @var{buffer-or-string}.
236 @var{buffer-or-string} defaults to the current buffer if omitted.
237 @var{from} and @var{to} can be used to limit the range over which
238 extents are returned; if omitted, all extents in the buffer or string
241 More specifically, if a range is specified using @var{from} and
242 @var{to}, only extents that overlap the range (i.e. begin or end inside
243 of the range) are included in the list. @var{from} and @var{to} default
244 to the beginning and end of @var{buffer-or-string}, respectively.
246 @var{flags} controls how end cases are treated. For a discussion of
247 this, and exactly what ``overlap'' means, see @code{map-extents}.
250 Functions that create extents must be prepared for the possibility
251 that there are other extents in the same area, created by other
252 functions. To deal with this, functions typically mark their own
253 extents by setting a particular property on them. The following
254 function makes it easier to locate those extents.
256 @defun extent-at pos &optional object property before at-flag
257 This function finds the ``smallest'' extent (i.e., the last one in the
258 display order) at (i.e., overlapping) @var{pos} in @var{object} (a
259 buffer or string) having @var{property} set. @var{object} defaults to
260 the current buffer. @var{property} defaults to @code{nil}, meaning that
261 any extent will do. Returns @code{nil} if there is no matching extent
262 at @var{pos}. If the fourth argument @var{before} is not @code{nil}, it
263 must be an extent; any returned extent will precede that extent. This
264 feature allows @code{extent-at} to be used by a loop over extents.
266 @var{at-flag} controls how end cases are handled (i.e. what ``at''
267 really means), and should be one of:
272 An extent is at @var{pos} if it covers the character after @var{pos}.
273 This is consistent with the way that text properties work.
275 An extent is at @var{pos} if it covers the character before @var{pos}.
277 An extent is at @var{pos} if it overlaps or abuts @var{pos}. This
278 includes all zero-length extents at @var{pos}.
281 Note that in all cases, the start-openness and end-openness of the
282 extents considered is ignored. If you want to pay attention to those
283 properties, you should use @code{map-extents}, which gives you more
287 The following low-level functions are provided for explicitly
288 traversing the extents in a buffer according to the display order.
289 These functions are mostly intended for debugging -- in normal
290 operation, you should probably use @code{mapcar-extents} or
291 @code{map-extents}, or loop using the @var{before} argument to
292 @code{extent-at}, rather than creating a loop using @code{next-extent}.
294 @defun next-extent extent
295 Given an extent @var{extent}, this function returns the next extent in
296 the buffer or string's display order. If @var{extent} is a buffer or
297 string, this returns the first extent in the buffer or string.
300 @defun previous-extent extent
301 Given an extent @var{extent}, this function returns the previous extent
302 in the buffer or string's display order. If @var{extent} is a buffer or
303 string, this returns the last extent in the buffer or string.
306 @node Mapping Over Extents
307 @section Mapping Over Extents
308 @cindex extents, mapping
310 The most basic and general function for mapping over extents is called
311 @code{map-extents}. You should read through the definition of this
312 function to familiarize yourself with the concepts and optional
313 arguments involved. However, in practice you may find it more
314 convenient to use the function @code{mapcar-extents} or to create a loop
315 using the @code{before} argument to @code{extent-at} (@pxref{Finding
318 @defun map-extents function &optional object from to maparg flags property value
319 This function maps @var{function} over the extents which overlap a
320 region in @var{object}. @var{object} is normally a buffer or string but
321 could be an extent (see below). The region is normally bounded by
322 [@var{from}, @var{to}) (i.e. the beginning of the region is closed and
323 the end of the region is open), but this can be changed with the
324 @var{flags} argument (see below for a complete discussion).
326 @var{function} is called with the arguments (extent, @var{maparg}).
327 The arguments @var{object}, @var{from}, @var{to}, @var{maparg}, and
328 @var{flags} are all optional and default to the current buffer, the
329 beginning of @var{object}, the end of @var{object}, @var{nil}, and
330 @var{nil}, respectively. @code{map-extents} returns the first
331 non-@code{nil} result produced by @var{function}, and no more calls to
332 @var{function} are made after it returns non-@code{nil}.
334 If @var{object} is an extent, @var{from} and @var{to} default to the
335 extent's endpoints, and the mapping omits that extent and its
336 predecessors. This feature supports restarting a loop based on
337 @code{map-extents}. Note: @var{object} must be attached to a buffer or
338 string, and the mapping is done over that buffer or string.
340 An extent overlaps the region if there is any point in the extent that
341 is also in the region. (For the purpose of overlap, zero-length extents
342 and regions are treated as closed on both ends regardless of their
343 endpoints' specified open/closedness.) Note that the endpoints of an
344 extent or region are considered to be in that extent or region if and
345 only if the corresponding end is closed. For example, the extent [5,7]
346 overlaps the region [2,5] because 5 is in both the extent and the
347 region. However, (5,7] does not overlap [2,5] because 5 is not in the
348 extent, and neither [5,7] nor (5,7] overlaps the region [2,5) because 5
349 is not in the region.
351 The optional @var{flags} can be a symbol or a list of one or more
352 symbols, modifying the behavior of @code{map-extents}. Allowed symbols
357 The region's end is closed.
360 The region's start is open.
362 @item all-extents-closed
363 Treat all extents as closed on both ends for the purpose of determining
364 whether they overlap the region, irrespective of their actual open- or
366 @item all-extents-open
367 Treat all extents as open on both ends.
368 @item all-extents-closed-open
369 Treat all extents as start-closed, end-open.
370 @item all-extents-open-closed
371 Treat all extents as start-open, end-closed.
373 @item start-in-region
374 In addition to the above conditions for extent overlap, the extent's
375 start position must lie within the specified region. Note that, for
376 this condition, open start positions are treated as if 0.5 was added to
377 the endpoint's value, and open end positions are treated as if 0.5 was
378 subtracted from the endpoint's value.
380 The extent's end position must lie within the region.
381 @item start-and-end-in-region
382 Both the extent's start and end positions must lie within the region.
383 @item start-or-end-in-region
384 Either the extent's start or end position must lie within the region.
386 @item negate-in-region
387 The condition specified by a @code{*-in-region} flag must @emph{not}
388 hold for the extent to be considered.
391 At most one of @code{all-extents-closed}, @code{all-extents-open},
392 @code{all-extents-closed-open}, and @code{all-extents-open-closed} may
395 At most one of @code{start-in-region}, @code{end-in-region},
396 @code{start-and-end-in-region}, and @code{start-or-end-in-region} may be
399 If optional arg @var{property} is non-@code{nil}, only extents with
400 that property set on them will be visited. If optional arg @var{value}
401 is non-@code{nil}, only extents whose value for that property is
402 @code{eq} to @var{value} will be visited.
405 If you want to map over extents and accumulate a list of results,
406 the following function may be more convenient than @code{map-extents}.
408 @defun mapcar-extents function &optional predicate buffer-or-string from to flags property value
409 This function applies @var{function} to all extents which overlap a
410 region in @var{buffer-or-string}. The region is delimited by
411 @var{from} and @var{to}. @var{function} is called with one argument,
412 the extent. A list of the values returned by @var{function} is
413 returned. An optional @var{predicate} may be used to further limit the
414 extents over which @var{function} is mapped. The optional arguments
415 @var{flags}, @var{property}, and @var{value} may also be used to control
416 the extents passed to @var{predicate} or @var{function}, and have the
417 same meaning as in @code{map-extents}.
420 @defun map-extent-children function &optional object from to maparg flags property value
421 This function is similar to @code{map-extents}, but differs in that:
425 It only visits extents which start in the given region.
427 After visiting an extent @var{e}, it skips all other extents which start
428 inside @var{e} but end before @var{e}'s end.
431 Thus, this function may be used to walk a tree of extents in a buffer:
433 (defun walk-extents (buffer &optional ignore)
434 (map-extent-children 'walk-extents buffer))
438 @defun extent-in-region-p extent &optional from to flags
439 This function returns @var{t} if @code{map-extents} would visit
440 @var{extent} if called with the given arguments.
443 @node Extent Properties
444 @section Properties of Extents
445 @cindex extent property
446 @cindex property of an extent
448 Each extent has a property list associating property names with
449 values. Some property names have predefined meanings, and can usually
450 only assume particular values. Assigning other values to such a
451 property either cause the value to be converted into a legal value
452 (e.g., assigning anything but @code{nil} to a Boolean property will
453 cause the value of @code{t} to be assigned to the property) or will
454 cause an error. Property names without predefined meanings can be
455 assigned any value. An undefined property is equivalent to a property
456 with a value of @code{nil}, or with a particular default value in the
457 case of properties with predefined meanings. Note that, when an extent
458 is created, the @code{end-open} and @code{detachable} properties are set
461 If an extent has a parent, all of its properties actually derive
462 from that parent (or from the root ancestor if the parent in turn
463 has a parent), and setting a property of the extent actually sets
464 that property on the parent. @xref{Extent Parents}.
466 @defun extent-property extent property
467 This function returns the value of @var{property} in @var{extent}. If
468 @var{property} is undefined, @code{nil} is returned.
471 @defun extent-properties extent
472 This function returns a list of all of @var{extent}'s properties that do
473 not have the value of @code{nil} (or the default value, for properties
474 with predefined meanings).
477 @defun set-extent-property extent property value
478 This function sets @var{property} to @var{value} in @var{extent}. (If
479 @var{property} has a predefined meaning, only certain values are
480 allowed, and some values may be converted to others before being
484 @defun set-extent-properties extent plist
485 Change some properties of @var{extent}. @var{plist} is a property
486 list. This is useful to change many extent properties at once.
489 The following table lists the properties with predefined meanings, along
490 with their allowable values.
494 (Boolean) Whether the extent is detached. Setting this is the same
495 as calling @code{detach-extent}. @xref{Detached Extents}.
498 (Boolean) Whether the extent has been deleted. Setting this is the same
499 as calling @code{delete-extent}.
502 (integer) The extent's redisplay priority. Defaults to 0. @xref{Intro
503 to Extents, priority}. This property can also be set with
504 @code{set-extent-priority} and accessed with @code{extent-priority}.
507 (Boolean) Whether the start position of the extent is open, meaning that
508 characters inserted at that position go outside of the extent.
509 @xref{Extent Endpoints}.
512 (Boolean) Same as @code{start-open} but with the opposite sense. Setting
513 this property clears @code{start-open} and vice-versa.
516 (Boolean) Whether the end position of the extent is open, meaning that
517 characters inserted at that position go outside of the extent. This is
519 @xref{Extent Endpoints}.
522 (Boolean) Same as @code{end-open} but with the opposite sense. Setting
523 this property clears @code{end-open} and vice-versa.
526 (Boolean) Whether text within this extent will be unmodifiable.
529 (face, face name, list of faces or face names, or @code{nil}) The face
530 in which to display the extent's text. This property can also be set
531 with @code{set-extent-face} and accessed with @code{extent-face}.
532 Note that if a list of faces is specified, the faces are merged together,
533 with faces earlier in the list having priority over faces later in the
537 (face, face name, list of faces or face names, or @code{nil}) The face
538 used to display the extent when the mouse moves over it. This property
539 can also be set with @code{set-extent-mouse-face} and accessed with
540 @code{extent-mouse-face}. Note that if a list of faces is specified,
541 the faces are merged together, with faces earlier in the list having
542 priority over faces later in the list. @xref{Extents and Events}.
545 (pointer glyph) The glyph used as the pointer when the mouse moves over
546 the extent. This takes precedence over the @code{text-pointer-glyph}
547 and @code{nontext-pointer-glyph} variables. If for any reason this
548 glyph is an invalid pointer, the standard glyphs will be used as
549 fallbacks. @xref{Mouse Pointer}.
552 (Boolean) Whether this extent becomes detached when all of the text it
553 covers is deleted. This is @code{t} by default. @xref{Detached
557 (Boolean) Whether this extent should be copied into strings, so that
558 kill, yank, and undo commands will restore or copy it. @xref{Duplicable
562 (Boolean) Meaningful only in conjunction with @code{duplicable}.
563 When this is set, there may be only one instance of
564 this extent attached at a time. @xref{Duplicable Extents}.
567 (Boolean) If @code{t}, text under this extent will not be displayed --
568 it will look as if the text is not there at all.
571 (keymap or @code{nil}) This keymap is consulted for mouse clicks on this
572 extent or keypresses made while @code{point} is within the extent.
573 @xref{Extents and Events}.
576 This is a hook that is run when a duplicable extent is about to be
577 copied from a buffer to a string (or the kill ring). @xref{Duplicable
581 This is a hook that is run when a duplicable extent is about to be
582 copied from a string (or the kill ring) into a buffer. @xref{Duplicable
586 (glyph or @code{nil}) This extent's begin glyph.
590 (glyph or @code{nil}) This extent's end glyph.
593 @item begin-glyph-layout
594 (@code{text}, @code{whitespace}, @code{inside-margin}, or
595 @code{outside-margin}) The layout policy for this extent's begin glyph.
596 Defaults to @code{text}. @xref{Annotations}.
598 @item end-glyph-layout
599 (@code{text}, @code{whitespace}, @code{inside-margin}, or
600 @code{outside-margin}) The layout policy for this extent's end glyph.
601 Defaults to @code{text}. @xref{Annotations}.
603 @item initial-redisplay-function
604 (any funcallable object) The function to be called the first time (a
605 part of) the extent is redisplayed. It will be called with the extent
608 This is used by @code{lazy-shot} to implement lazy font-locking. The
609 functionality is still experimental, and may change without further
613 The following convenience functions are provided for accessing
614 particular properties of an extent.
616 @defun extent-face extent
617 This function returns the @code{face} property of @var{extent}. This
618 might also return a list of face names. Do not modify this list
619 directly! Instead, use @code{set-extent-face}.
621 Note that you can use @code{eq} to compare lists of faces as returned
622 by @code{extent-face}. In other words, if you set the face of two
623 different extents to two lists that are @code{equal} but not @code{eq},
624 then the return value of @code{extent-face} on the two extents will
625 return the identical list.
628 @defun extent-mouse-face extent
629 This function returns the @code{mouse-face} property of @var{extent}.
630 This might also return a list of face names. Do not modify this list
631 directly! Instead, use @code{set-extent-mouse-face}.
633 Note that you can use @code{eq} to compare lists of faces as returned
634 by @code{extent-mouse-face}, just like for @code{extent-face}.
637 @defun extent-priority extent
638 This function returns the @code{priority} property of @var{extent}.
641 @defun extent-keymap extent
642 This function returns the @code{keymap} property of @var{extent}.
645 @defun extent-begin-glyph-layout extent
646 This function returns the @code{begin-glyph-layout} property of
647 @var{extent}, i.e. the layout policy associated with the @var{extent}'s
651 @defun extent-end-glyph-layout extent
652 This function returns the @code{end-glyph-layout} property of
653 @var{extent}, i.e. the layout policy associated with the @var{extent}'s
657 @defun extent-begin-glyph extent
658 This function returns the @code{begin-glyph} property of @var{extent},
659 i.e. the glyph object displayed at the beginning of @var{extent}. If
660 there is none, @code{nil} is returned.
663 @defun extent-end-glyph extent
664 This function returns the @code{end-glyph} property of @var{extent},
665 i.e. the glyph object displayed at the end of @var{extent}. If
666 there is none, @code{nil} is returned.
669 The following convenience functions are provided for setting particular
670 properties of an extent.
672 @defun set-extent-priority extent pri
673 This function sets the @code{priority} property of @var{extent} to
677 @defun set-extent-face extent face
678 This function sets the @code{face} property of @var{extent} to
682 @defun set-extent-mouse-face extent face
683 This function sets the @code{mouse-face} property of @var{extent} to
687 @defun set-extent-keymap extent keymap
688 This function sets the @code{keymap} property of @var{extent} to
689 @var{keymap}. @var{keymap} must be either a keymap object, or
693 @defun set-extent-begin-glyph-layout extent layout
694 This function sets the @code{begin-glyph-layout} property of
695 @var{extent} to @var{layout}.
698 @defun set-extent-end-glyph-layout extent layout
699 This function sets the @code{end-glyph-layout} property of
700 @var{extent} to @var{layout}.
703 @defun set-extent-begin-glyph extent begin-glyph &optional layout
704 This function sets the @code{begin-glyph} and @code{glyph-layout}
705 properties of @var{extent} to @var{begin-glyph} and @var{layout},
706 respectively. (@var{layout} defaults to @code{text} if not specified.)
709 @defun set-extent-end-glyph extent end-glyph &optional layout
710 This function sets the @code{end-glyph} and @code{glyph-layout}
711 properties of @var{extent} to @var{end-glyph} and @var{layout},
712 respectively. (@var{layout} defaults to @code{text} if not specified.)
715 @defun set-extent-initial-redisplay-function extent function
716 This function sets the @code{initial-redisplay-function} property of the
717 extent to @var{function}.
720 @node Detached Extents
721 @section Detached Extents
722 @cindex detached extent
724 A detached extent is an extent that is not attached to a buffer or
725 string but can be re-inserted. Detached extents have a start position
726 and end position of @code{nil}. Extents can be explicitly detached
727 using @code{detach-extent}. An extent is also detached when all of its
728 characters are all killed by a deletion, if its @code{detachable}
729 property is set; if this property is not set, the extent becomes a
730 zero-length extent. (Zero-length extents with the @code{detachable}
731 property set behave specially. @xref{Extent Endpoints, zero-length
734 @defun detach-extent extent
735 This function detaches @var{extent} from its buffer or string. If
736 @var{extent} has the @code{duplicable} property, its detachment is
737 tracked by the undo mechanism. @xref{Duplicable Extents}.
740 @defun extent-detached-p extent
741 This function returns @code{nil} if @var{extent} is detached, and
745 @defun copy-extent extent &optional object
746 This function makes a copy of @var{extent}. It is initially detached.
747 Optional argument @var{object} defaults to @var{extent}'s object
748 (normally a buffer or string, but could be @code{nil}).
751 @defun insert-extent extent &optional start end no-hooks object
752 This function inserts @var{extent} from @var{start} to @var{end} in
753 @var{object} (a buffer or string). If @var{extent} is detached from a
754 different buffer or string, or in most cases when @var{extent} is
755 already attached, the extent will first be copied as if with
756 @code{copy-extent}. This function operates the same as if @code{insert}
757 were called on a string whose extent data calls for @var{extent} to be
758 inserted, except that if @var{no-hooks} is non-@code{nil},
759 @var{extent}'s @code{paste-function} will not be invoked.
760 @xref{Duplicable Extents}.
764 @section Extent Parents
765 @cindex extent parent
766 @cindex extent children
767 @cindex parent, of extent
768 @cindex children, of extent
770 An extent can have a parent extent set for it. If this is the case,
771 the extent derives all its properties from that extent and has no
772 properties of its own. The only ``properties'' that the extent keeps
773 are the buffer or string it refers to and the start and end points.
774 (More correctly, the extent's own properties are shadowed. If you
775 later change the extent to have no parent, its own properties will
776 become visible again.)
778 It is possible for an extent's parent to itself have a parent,
779 and so on. Through this, a whole tree of extents can be created,
780 all deriving their properties from one root extent. Note, however,
781 that you cannot create an inheritance loop -- this is explicitly
784 Parent extents are used to implement the extents over the modeline.
786 @defun set-extent-parent extent parent
787 This function sets the parent of @var{extent} to @var{parent}.
788 If @var{parent} is @code{nil}, the extent is set to have no parent.
791 @defun extent-parent extent
792 This function return the parents (if any) of @var{extent}, or
796 @defun extent-children extent
797 This function returns a list of the children (if any) of @var{extent}.
798 The children of an extent are all those extents whose parent is that
799 extent. This function does not recursively trace children of children.
802 @defun extent-descendants extent
803 This function returns a list of all descendants of @var{extent},
804 including @var{extent}. This recursively applies @code{extent-children}
805 to any children of @var{extent}, until no more children can be found.
808 @node Duplicable Extents
809 @section Duplicable Extents
810 @cindex duplicable extent
811 @cindex unique extents
812 @cindex extent replica
813 @cindex extent, duplicable
814 @cindex extent, unique
816 If an extent has the @code{duplicable} property, it will be copied into
817 strings, so that kill, yank, and undo commands will restore or copy it.
823 When a string is created using @code{buffer-substring} or
824 @code{buffer-string}, any duplicable extents in the region corresponding
825 to the string will be copied into the string (@pxref{Buffer
826 Contents}). When the string in inserted into a buffer using
827 @code{insert}, @code{insert-before-markers}, @code{insert-buffer} or
828 @code{insert-buffer-substring}, the extents in the string will be copied
829 back into the buffer (@pxref{Insertion}). The extents in a string can,
830 of course, be retrieved explicitly using the standard extent primitives
834 Similarly, when text is copied or cut into the kill ring, any duplicable
835 extents will be remembered and reinserted later when the text is pasted
839 When @code{concat} is called on strings, the extents in the strings are
840 copied into the resulting string.
843 When @code{substring} is called on a string, the relevant extents
844 are copied into the resulting string.
847 When a duplicable extent is detached by @code{detach-extent} or string
848 deletion, or inserted by @code{insert-extent} or string insertion, the
849 action is recorded by the undo mechanism so that it can be undone later.
850 Note that if an extent gets detached and then a later undo causes the
851 extent to get reinserted, the new extent will not be `eq' to the original
855 Extent motion, face changes, and attachment via @code{make-extent} are
856 not recorded by the undo mechanism. This means that extent changes
857 which are to be undo-able must be performed by character editing, or by
858 insertion and detachment of duplicable extents.
861 A duplicable extent's @code{copy-function} property, if non-@code{nil},
862 should be a function, and will be run when a duplicable extent is about
863 to be copied from a buffer to a string (or the kill ring). It is called
864 with three arguments: the extent and the buffer positions within it
865 which are being copied. If this function returns @code{nil}, then the
866 extent will not be copied; otherwise it will.
869 A duplicable extent's @code{paste-function} property, if non-@code{nil},
870 should be a function, and will be run when a duplicable extent is about
871 to be copied from a string (or the kill ring) into a buffer. It is
872 called with three arguments: the original extent and the buffer
873 positions which the copied extent will occupy. (This hook is run after
874 the corresponding text has already been inserted into the buffer.) Note
875 that the extent argument may be detached when this function is run. If
876 this function returns @code{nil}, no extent will be inserted.
877 Otherwise, there will be an extent covering the range in question.
879 Note: if the extent to be copied is already attached to the buffer and
880 overlaps the new range, the extent will simply be extended and the
881 @code{paste-function} will not be called.
884 @node Extents and Events
885 @section Interaction of Extents with Keyboard and Mouse Events
887 If an extent has the @code{mouse-face} property set, it will be
888 highlighted when the mouse passes over it. Highlighting is accomplished
889 by merging the extent's face with the face or faces specified by the
890 @code{mouse-face} property. The effect is as if a pseudo-extent with
891 the @code{mouse-face} face were inserted after the extent in the display
892 order (@pxref{Extent Endpoints}, display order).
894 @defvar mouse-highlight-priority
895 This variable holds the priority to use when merging in the highlighting
896 pseudo-extent. The default is 1000. This is purposely set very high
897 so that the highlighting pseudo-extent shows up even if there are other
898 extents with various priorities at the same location.
901 You can also explicitly cause an extent to be highlighted. Only one
902 extent at a time can be highlighted in this fashion, and any other
903 highlighted extent will be de-highlighted.
905 @defun highlight-extent extent &optional highlight-p
906 This function highlights (if @var{highlight-p} is non-@code{nil}) or
907 de-highlights (if @var{highlight-p} is @code{nil}) @var{extent}, if
908 @var{extent} has the @code{mouse-face} property. (Nothing happens if
909 @var{extent} does not have the @code{mouse-face} property.)
912 @defun force-highlight-extent extent &optional highlight-p
913 This function is similar to @code{highlight-extent} but highlights
914 or de-highlights the extent regardless of whether it has the
915 @code{mouse-face} property.
918 If an extent has a @code{keymap} property, this keymap will be
919 consulted for mouse clicks on the extent and keypresses made while
920 @code{point} is within the extent. The behavior of mouse clicks and
921 keystrokes not defined in the keymap is as normal for the buffer.
924 @section Atomic Extents
925 @cindex atomic extent
927 If the Lisp file @file{atomic-extents} is loaded, then the atomic
928 extent facility is available. An @dfn{atomic extent} is an extent for
929 which @code{point} cannot be positioned anywhere within it. This
930 ensures that when selecting text, either all or none of the extent is
933 To make an extent atomic, set its @code{atomic} property.