Mercurial > hg > xemacs-beta

comparison man/lispref/extents.texi @ 0:376386a54a3c r19-14

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r19-14
author cvs
date Mon, 13 Aug 2007 08:45:50 +0200
parents
children ac2d302a0011
comparison
equal deleted inserted replaced
-1:000000000000 0:376386a54a3c
1 @c -*-texinfo-*-
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
8 @chapter Extents
9 @cindex extent
10
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
15 extents in them.
16
17 @defun extentp object
18 This returns @code{t} if @var{object} is an extent.
19 @end defun
20
21 @menu
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.
34 @end menu
35
36 @node Intro to Extents
37 @section Introduction to Extents
38 @cindex extent priority
39 @cindex priority of an extent
40
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
46 string.
47
48 @emph{NOTE}: An alternative way to add properties to a buffer or
49 string is to use text properties. @xref{Text Properties}.
50
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.)
63
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
79 the list.
80
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}.
86
87 An extent can optionally have a @dfn{start-glyph} or @dfn{end-glyph}
88 (but not both at one time) associated with it. A start-glyph or
89 end-glyph is a pixmap or string that will be displayed either at the
90 start or end of an extent or in the margin of the line that the start
91 or end of the extent lies in, depending on the extent's layout policy.
92 Start-glyphs and end-glyphs are used to implement annotations, and you
93 should use the annotation API functions in preference to the
94 lower-level extent functions. For more information, @xref{Annotations}.
95
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}.
101
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}.
107
108 @node Creating and Modifying Extents
109 @section Creating and Modifying Extents
110
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}).
121 @end defun
122
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}.
129 @end defun
130
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
135 @code{nil}.
136 @end defun
137
138 @defun extent-live-p extent
139 This function returns @code{nil} if @var{extent} is deleted, and
140 @code{t} otherwise.
141 @end defun
142
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
150 @cindex extent order
151 @cindex order of extents
152
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}.
158
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.
166
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
169 sense.
170
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
186 as necessary.
187
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}).
191
192 @defun extent-start-position extent
193 This function returns the start position of @var{extent}.
194 @end defun
195
196 @defun extent-end-position extent
197 This function returns the end position of @var{extent}.
198 @end defun
199
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
204 @example
205 (- (extent-end-position @var{extent}) (extent-start-position @var{extent}))
206 @end example
207 @end defun
208
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}.
213
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.)
218
219 See documentation on @code{detach-extent} for a discussion of undo
220 recording.
221 @end defun
222
223 @node Finding Extents
224 @section Finding Extents
225 @cindex extents, locating
226
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}).
233
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
239 are returned.
240
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.
245
246 @var{flags} controls how end cases are treated. For a discussion of
247 this, and exactly what ``overlap'' means, see @code{map-extents}.
248 @end defun
249
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.
255
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.
265
266 @var{at-flag} controls how end cases are handled (i.e. what ``at''
267 really means), and should be one of:
268
269 @table @code
270 @item nil
271 @item after
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.
274 @item before
275 An extent is at @var{pos} if it covers the character before @var{pos}.
276 @item at
277 An extent is at @var{pos} if it overlaps or abuts @var{pos}. This
278 includes all zero-length extents at @var{pos}.
279 @end table
280
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
284 control.
285 @end defun
286
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}.
293
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.
298 @end defun
299
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.
304 @end defun
305
306 @node Mapping Over Extents
307 @section Mapping Over Extents
308 @cindex extents, mapping
309
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
316 Extents}).
317
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).
325
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}.
333
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.
339
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.
350
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
353 are:
354
355 @table @code
356 @item end-closed
357 The region's end is closed.
358
359 @item start-open
360 The region's start is open.
361
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
365 closedness.
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.
372
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.
379 @item end-in-region
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.
385
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.
389 @end table
390
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
393 be specified.
394
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
397 specified.
398
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.
403 @end defun
404
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}.
407
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 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}.
418 @end defun
419
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:
422
423 @itemize @bullet
424 @item
425 It only visits extents which start in the given region.
426 @item
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.
429 @end itemize
430
431 Thus, this function may be used to walk a tree of extents in a buffer:
432 @example
433 (defun walk-extents (buffer &optional ignore)
434 (map-extent-children 'walk-extents buffer))
435 @end example
436 @end defun
437
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.
441 @end defun
442
443 @node Extent Properties
444 @section Properties of Extents
445 @cindex extent property
446 @cindex property of an extent
447
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
459 on it.
460
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}.
465
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.
469 @end defun
470
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).
475 @end defun
476
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
481 stored.)
482 @end defun
483
484 The following table lists the properties with predefined meanings, along
485 with their allowable values.
486
487 @table @code
488 @item detached
489 (Boolean) Whether the extent is detached. Setting this is the same
490 as calling @code{detach-extent}. @xref{Detached Extents}.
491
492 @item destroyed
493 (Boolean) Whether the extent has been deleted. Setting this is the same
494 as calling @code{delete-extent}.
495
496 @item priority
497 (integer) The extent's redisplay priority. Defaults to 0. @xref{Intro
498 to Extents, priority}. This property can also be set with
499 @code{set-extent-priority} and accessed with @code{extent-priority}.
500
501 @item start-open
502 (Boolean) Whether the start position of the extent is open, meaning that
503 characters inserted at that position go outside of the extent.
504 @xref{Extent Endpoints}.
505
506 @item start-closed
507 (Boolean) Same as @code{start-open} but with the opposite sense. Setting
508 this property clears @code{start-open} and vice-versa.
509
510 @item end-open
511 (Boolean) Whether the end position of the extent is open, meaning that
512 characters inserted at that position go outside of the extent. This is
513 @code{t} by default.
514 @xref{Extent Endpoints}.
515
516 @item end-closed
517 (Boolean) Same as @code{end-open} but with the opposite sense. Setting
518 this property clears @code{end-open} and vice-versa.
519
520 @item read-only
521 (Boolean) Whether text within this extent will be unmodifiable.
522
523 @item face
524 (face, face name, list of faces or face names, or @code{nil}) The face
525 in which to display the extent's text. This property can also be set
526 with @code{set-extent-face} and accessed with @code{extent-face}.
527 Note that if a list of faces is specified, the faces are merged together,
528 with faces earlier in the list having priority over faces later in the
529 list.
530
531 @item mouse-face
532 (face, face name, list of faces or face names, or @code{nil}) The face
533 used to display the extent when the mouse moves over it. This property
534 can also be set with @code{set-extent-mouse-face} and accessed with
535 @code{extent-mouse-face}. Note that if a list of faces is specified,
536 the faces are merged together, with faces earlier in the list having
537 priority over faces later in the list. @xref{Extents and Events}.
538
539 @item pointer
540 (pointer glyph) The glyph used as the pointer when the mouse moves over
541 the extent. This takes precedence over the @code{text-pointer-glyph}
542 and @code{nontext-pointer-glyph} variables. If for any reason this
543 glyph is an invalid pointer, the standard glyphs will be used as
544 fallbacks. @xref{Mouse Pointer}
545
546 @item detachable
547 (Boolean) Whether this extent becomes detached when all of the text it
548 covers is deleted. This is @code{t} by default. @xref{Detached
549 Extents}.
550
551 @item duplicable
552 (Boolean) Whether this extent should be copied into strings, so that
553 kill, yank, and undo commands will restore or copy it. @xref{Duplicable
554 Extents}.
555
556 @item replicating
557 (Boolean) Meaningful only in conjunction with @code{duplicable}. If
558 set, actions that cause an extent to be copied from a buffer to a string
559 cause the original extent to be recorded in the copy (as the copied
560 extent's parent), so that when the extent is copied back into the
561 buffer, @code{eq}ness between the original extent and the re-inserted
562 extent is maintained whenever possible. @xref{Duplicable Extents}.
563
564 @item unique
565 (Boolean) Meaningful only in conjunction with @code{duplicable} and
566 @code{replicating}. When this is set, there may be only one instance of
567 this extent attached at a time. @xref{Duplicable Extents}.
568
569 @item invisible
570 (Boolean) If @code{t}, text under this extent will not be displayed --
571 it will look as if the text is not there at all.
572
573 @item keymap
574 (keymap or @code{nil}) This keymap is consulted for mouse clicks on this
575 extent or keypresses made while @code{point} is within the extent.
576 @xref{Extents and Events}.
577
578 @item copy-function
579 This is a hook that is run when a duplicable extent is about to be
580 copied from a buffer to a string (or the kill ring). @xref{Duplicable
581 Extents}.
582
583 @item paste-function
584 This is a hook that is run when a duplicable extent is about to be
585 copied from a string (or the kill ring) into a buffer. @xref{Duplicable
586 Extents}.
587
588 @item begin-glyph
589 (glyph or @code{nil}) This extent's begin glyph.
590 @xref{Annotations}.
591
592 @item end-glyph
593 (glyph or @code{nil}) This extent's end glyph.
594 @xref{Annotations}.
595
596 @item begin-glyph-layout
597 (@code{text}, @code{whitespace}, @code{inside-margin}, or
598 @code{outside-margin}) The layout policy for this extent's begin glyph.
599 Defaults to @code{text}. @xref{Annotations}.
600
601 @item end-glyph-layout
602 (@code{text}, @code{whitespace}, @code{inside-margin}, or
603 @code{outside-margin}) The layout policy for this extent's end glyph.
604 Defaults to @code{text}. @xref{Annotations}.
605 @end table
606
607 The following convenience functions are provided for accessing
608 particular properties of an extent.
609
610 @defun extent-face extent
611 This function returns the @code{face} property of @var{extent}. This
612 might also return a list of face names. Do not modify this list
613 directly! Instead, use @code{set-extent-face}.
614
615 Note that you can use @code{eq} to compare lists of faces as returned
616 by @code{extent-face}. In other words, if you set the face of two
617 different extents to two lists that are @code{equal} but not @code{eq},
618 then the return value of @code{extent-face} on the two extents will
619 return the identical list.
620 @end defun
621
622 @defun extent-mouse-face extent
623 This function returns the @code{mouse-face} property of @var{extent}.
624 This might also return a list of face names. Do not modify this list
625 directly! Instead, use @code{set-extent-mouse-face}.
626
627 Note that you can use @code{eq} to compare lists of faces as returned
628 by @code{extent-mouse-face}, just like for @code{extent-face}.
629 @end defun
630
631 @defun extent-priority extent
632 This function returns the @code{priority} property of @var{extent}.
633 @end defun
634
635 @defun extent-begin-glyph-layout extent
636 This function returns the @code{begin-glyph-layout} property of
637 @var{extent}, i.e. the layout policy associated with the @var{extent}'s
638 begin glyph.
639 @end defun
640
641 @defun extent-end-glyph-layout extent
642 This function returns the @code{end-glyph-layout} property of
643 @var{extent}, i.e. the layout policy associated with the @var{extent}'s
644 end glyph.
645 @end defun
646
647 @defun extent-begin-glyph extent
648 This function returns the @code{begin-glyph} property of @var{extent},
649 i.e. the glyph object displayed at the beginning of @var{extent}. If
650 there is none, @code{nil} is returned.
651 @end defun
652
653 @defun extent-end-glyph extent
654 This function returns the @code{end-glyph} property of @var{extent},
655 i.e. the glyph object displayed at the end of @var{extent}. If
656 there is none, @code{nil} is returned.
657 @end defun
658
659 The following convenience functions are provided for setting particular
660 properties of an extent.
661
662 @defun set-extent-priority extent pri
663 This function sets the @code{priority} property of @var{extent} to
664 @var{pri}.
665 @end defun
666
667 @defun set-extent-face extent face
668 This function sets the @code{face} property of @var{extent} to
669 @var{face}.
670 @end defun
671
672 @defun set-extent-mouse-face extent face
673 This function sets the @code{mouse-face} property of @var{extent} to
674 @var{face}.
675 @end defun
676
677 @defun set-extent-keymap extent keymap
678 This function sets the @code{keymap} property of @var{extent} to
679 @var{keymap}.
680 @end defun
681
682 @defun set-extent-begin-glyph-layout extent layout
683 This function sets the @code{begin-glyph-layout} property of
684 @var{extent} to @var{layout}.
685 @end defun
686
687 @defun set-extent-end-glyph-layout extent layout
688 This function sets the @code{end-glyph-layout} property of
689 @var{extent} to @var{layout}.
690 @end defun
691
692 @defun set-extent-begin-glyph extent begin-glyph &optional layout
693 This function sets the @code{begin-glyph} and @code{glyph-layout}
694 properties of @var{extent} to @var{begin-glyph} and @var{layout},
695 respectively. (@var{layout} defaults to @code{text} if not specified.)
696 @end defun
697
698 @defun set-extent-end-glyph extent end-glyph &optional layout
699 This function sets the @code{end-glyph} and @code{glyph-layout}
700 properties of @var{extent} to @var{end-glyph} and @var{layout},
701 respectively. (@var{layout} defaults to @code{text} if not specified.)
702 @end defun
703
704 @node Detached Extents
705 @section Detached Extents
706 @cindex detached extent
707
708 A detached extent is an extent that is not attached to a buffer or
709 string but can be re-inserted. Detached extents have a start position
710 and end position of @code{nil}. Extents can be explicitly detached
711 using @code{detach-extent}. An extent is also detached when all of its
712 characters are all killed by a deletion, if its @code{detachable}
713 property is set; if this property is not set, the extent becomes a
714 zero-length extent. (Zero-length extents with the @code{detachable}
715 property set behave specially. @xref{Extent Endpoints, zero-length
716 extents}.)
717
718 @defun detach-extent extent
719 This function detaches @var{extent} from its buffer or string. If
720 @var{extent} has the @code{duplicable} property, its detachment is
721 tracked by the undo mechanism. @xref{Duplicable Extents}.
722 @end defun
723
724 @defun extent-detached-p extent
725 This function returns @code{nil} if @var{extent} is detached, and
726 @code{t} otherwise.
727 @end defun
728
729 @defun copy-extent extent &optional object
730 This function makes a copy of @var{extent}. It is initially detached.
731 Optional argument @var{object} defaults to @var{extent}'s object
732 (normally a buffer or string, but could be @code{nil}).
733 @end defun
734
735 @defun insert-extent extent &optional start end no-hooks object
736 This function inserts @var{extent} from @var{start} to @var{end} in
737 @var{object} (a buffer or string). If @var{extent} is detached from a
738 different buffer or string, or in most cases when @var{extent} is
739 already attached, the extent will first be copied as if with
740 @code{copy-extent}. This function operates the same as if @code{insert}
741 were called on a string whose extent data calls for @var{extent} to be
742 inserted, except that if @var{no-hooks} is non-@code{nil},
743 @var{extent}'s @code{paste-function} will not be invoked.
744 @xref{Duplicable Extents}.
745 @end defun
746
747 @node Extent Parents
748 @section Extent Parents
749 @cindex extent parent
750 @cindex extent children
751 @cindex parent, of extent
752 @cindex children, of extent
753
754 An extent can have a parent extent set for it. If this is the case,
755 the extent derives all its properties from that extent and has no
756 properties of its own. The only ``properties'' that the extent keeps
757 are the buffer or string it refers to and the start and end points.
758 (More correctly, the extent's own properties are shadowed. If you
759 later change the extent to have no parent, its own properties will
760 become visible again.)
761
762 It is possible for an extent's parent to itself have a parent,
763 and so on. Through this, a whole tree of extents can be created,
764 all deriving their properties from one root extent. Note, however,
765 that you cannot create an inheritance loop -- this is explicitly
766 disallowed.
767
768 Parent extents are used to implement the ``replicating'' property
769 (@pxref{Duplicable Extents}) and extents over the modeline.
770
771 @defun set-extent-parent extent parent
772 This function sets the parent of @var{extent} to @var{parent}.
773 If @var{parent} is @code{nil}, the extent is set to have no parent.
774 @end defun
775
776 @defun extent-parent extent
777 This function return the parents (if any) of @var{extent}, or
778 @code{nil}.
779 @end defun
780
781 @defun extent-children extent
782 This function returns a list of the children (if any) of @var{extent}.
783 The children of an extent are all those extents whose parent is that
784 extent. This function does not recursively trace children of children.
785 @end defun
786
787 @defun extent-descendants extent
788 This function returns a list of all descendants of @var{extent},
789 including @var{extent}. This recursively applies @code{extent-children}
790 to any children of @var{extent}, until no more children can be found.
791 @end defun
792
793 @node Duplicable Extents
794 @section Duplicable Extents
795 @cindex duplicable extent
796 @cindex replicating extents
797 @cindex unique extents
798 @cindex extent replica
799 @cindex extent, duplicable
800 @cindex extent, replicating
801 @cindex extent, unique
802
803 If an extent has the @code{duplicable} property, it will be copied into
804 strings, so that kill, yank, and undo commands will restore or copy it.
805
806 If a duplicable extent also has the @code{replicating} property, the
807 extent itself is not actually copied; rather, a pointer to it is
808 stored, along with the start and end positions of the extent. (This
809 is done by making the copied extent a child of the original extent.
810 Formerly, this was done by creating a special object called an
811 @dfn{extent replica}. Extent replicas no longer exist, but all the
812 functionality is available in a cleaner and more general fashion
813 using the @code{replicating} property.) This means that, e.g.,
814 if you copy a replacting extent into the kill ring, then change the
815 properties of the extent, then paste the kill-ring text back into the
816 buffer, the newly-inserted extent will have the property changes you
817 just made to the original extent, and not the property values at the
818 time the text was copied into the kill ring.
819
820 Specifically:
821
822 @itemize @bullet
823 @item
824 When a string is created using @code{buffer-substring} or
825 @code{buffer-string}, any duplicable extents in the region corresponding
826 to the string will be copied into the string (@pxref{Buffer
827 Contents}). When the string in inserted into a buffer using
828 @code{insert}, @code{insert-before-markers}, @code{insert-buffer} or
829 @code{insert-buffer-substring}, the extents in the string will be copied
830 back into the buffer (@pxref{Insertion}). The extents in a string can,
831 of course, be retrieved explicitly using the standard extent primitives
832 over the string.
833
834 @item
835 Similarly, when text is copied or cut into the kill ring, any duplicable
836 extents will be remembered and reinserted later when the text is pasted
837 back into a buffer.
838
839 @item
840 If a duplicable extent has the @code{replicating} property, then when
841 it is copied into a string, the parent of the new extent is set to the
842 extent it was copied from.
843
844 @item
845 When an extent with the @code{replicating} property is copied from
846 a string back into a buffer:
847
848 @itemize @minus
849 @item
850 If the extent's parent was detached from this buffer, it is reattached
851 at the new range.
852
853 @item
854 If the extent's parent is attached to this buffer and is contiguous with
855 or overlaps the new range, it is simply extended to include that range.
856 Note that in this case the extent's @code{paste-function} is not called
857 (see below).
858
859 @item
860 If the extent's parent was detached from another buffer, it is copied
861 as if by @code{copy-extent} and attached at the new range.
862
863 @item
864 If the extent's parent is attached to another buffer, or is attached to
865 this buffer and does not overlap the new range, it is copied as if by
866 @code{copy-extent} and attached at the new range. However, if the
867 extent's parent has the @code{unique} property, this action is inhibited
868 and nothing happens.
869 @end itemize
870
871 @item
872 When @code{concat} is called on strings, the extents in the strings are
873 copied into the resulting string. If two or more replicating extents
874 with the same parent end up overlapping or abutting in the resulting
875 string, they are merged into a single extent.
876
877 @item
878 When @code{substring} is called on a string, the relevant extents
879 are copied into the resulting string.
880
881 @item
882 When a duplicable extent is detached by @code{detach-extent} or string
883 deletion, or inserted by @code{insert-extent} or string insertion, the
884 action is recorded by the undo mechanism so that it can be undone later.
885 Note that if an extent gets detached and then a later undo causes the
886 extent to get reinserted, the new extent will be `eq' to the original
887 extent if and only if the extent has the @code{replicating} property
888 set. This is the same as what happens when a string is cut and then
889 pasted back in.
890
891 @item
892 Extent motion, face changes, and attachment via @code{make-extent} are
893 not recorded by the undo mechanism. This means that extent changes
894 which are to be undo-able must be performed by character editing, or by
895 insertion and detachment of duplicable extents.
896
897 @item
898 A duplicable extent's @code{copy-function} property, if non-@code{nil},
899 should be a function, and will be run when a duplicable extent is about
900 to be copied from a buffer to a string (or the kill ring). It is called
901 with three arguments: the extent and the buffer positions within it
902 which are being copied. If this function returns @code{nil}, then the
903 extent will not be copied; otherwise it will.
904
905 @item
906 A duplicable extent's @code{paste-function} property, if non-@code{nil},
907 should be a function, and will be run when a duplicable extent is about
908 to be copied from a string (or the kill ring) into a buffer. It is
909 called with three arguments: the original extent and the buffer
910 positions which the copied extent will occupy. (This hook is run after
911 the corresponding text has already been inserted into the buffer.) Note
912 that the extent argument may be detached when this function is run. If
913 this function returns @code{nil}, no extent will be inserted.
914 Otherwise, there will be an extent covering the range in question.
915
916 Note: if the extent to be copied is already attached to the buffer and
917 overlaps the new range, the extent will simply be extended and the
918 @code{paste-function} will not be called.
919 @end itemize
920
921 @node Extents and Events
922 @section Interaction of Extents with Keyboard and Mouse Events
923
924 If an extent has the @code{mouse-face} property set, it will be
925 highlighted when the mouse passes over it. Highlighting is accomplished
926 by merging the extent's face with the face or faces specified by the
927 @code{mouse-face} property. The effect is as if a pseudo-extent with
928 the @code{mouse-face} face were inserted after the extent in the display
929 order (@pxref{Extent Endpoints}, display order).
930
931 @defvar mouse-highlight-priority
932 This variable holds the priority to use when merging in the highlighting
933 pseudo-extent. The default is 1000. This is purposely set very high
934 so that the highlighting pseudo-extent shows up even if there are other
935 extents with various priorities at the same location.
936 @end defvar
937
938 You can also explicitly cause an extent to be highlighted. Only one
939 extent at a time can be highlighted in this fashion, and any other
940 highlighted extent will be de-highlighted.
941
942 @defun highlight-extent extent &optional highlight-p
943 This function highlights (if @var{highlight-p} is non-@code{nil}) or
944 de-highlights (if @var{highlight-p} is @code{nil}) @var{extent}, if
945 @var{extent} has the @code{mouse-face} property. (Nothing happens if
946 @var{extent} does not have the @code{mouse-face} property.)
947 @end defun
948
949 @defun force-highlight-extent extent &optional highlight-p
950 This function is similar to @code{highlight-extent} but highlights
951 or de-highlights the extent regardless of whether it has the
952 @code{mouse-face} property.
953 @end defun
954
955 If an extent has a @code{keymap} property, this keymap will be
956 consulted for mouse clicks on the extent and keypresses made while
957 @code{point} is within the extent. The behavior of mouse clicks and
958 keystrokes not defined in the keymap is as normal for the buffer.
959
960 @node Atomic Extents
961 @section Atomic Extents
962 @cindex atomic extent
963
964 If the Lisp file @file{atomic-extents} is loaded, then the atomic
965 extent facility is available. An @dfn{atomic extent} is an extent for
966 which @code{point} cannot be positioned anywhere within it. This
967 ensures that when selecting text, either all or none of the extent is
968 selected.
969
970 To make an extent atomic, set its @code{atomic} property.