|
428
|
1 @c -*-texinfo-*-
|
|
|
2 @c This is part of the XEmacs Lisp Reference Manual.
|
|
444
|
3 @c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
|
|
428
|
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{Please 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{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}.
|
|
|
95
|
|
|
96 If an extent has its @code{detachable} property set, it will become
|
|
442
|
97 @dfn{detached} (i.e. no longer in the buffer) when all its text is
|
|
428
|
98 deleted. Otherwise, it will simply shrink down to zero-length and
|
|
442
|
99 sit in the same place in the buffer. By default, the @code{detachable}
|
|
428
|
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
|
|
444
|
111 @defun make-extent from to &optional buffer-or-string
|
|
428
|
112 This function makes an extent for the range [@var{from}, @var{to}) in
|
|
444
|
113 @var{buffer-or-string} (a buffer or string). @var{buffer-or-string}
|
|
|
114 defaults to the current buffer. Insertions at point @var{to} will be
|
|
|
115 outside of the extent; insertions at @var{from} will be inside the
|
|
|
116 extent, causing the extent to grow (@pxref{Extent Endpoints}). This is
|
|
|
117 the same way that markers behave. The extent is initially detached if
|
|
|
118 both @var{from} and @var{to} are @code{nil}, and in this case
|
|
|
119 @var{buffer-or-string} defaults to @code{nil}, meaning the extent is in
|
|
|
120 no buffer or string (@pxref{Detached Extents}).
|
|
428
|
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
|
|
444
|
138 @defun extent-live-p object
|
|
|
139 This function returns @code{t} if @var{object} is an extent that has not
|
|
|
140 been deleted, and @code{nil} otherwise.
|
|
428
|
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
|
|
444
|
234 @defun extent-list &optional buffer-or-string from to flags property value
|
|
428
|
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}.
|
|
444
|
248
|
|
|
249 The optional arguments @var{property} and @var{value} can be used to
|
|
|
250 further restrict which extents are returned. They have the same meaning
|
|
|
251 as for @code{map-extents}.
|
|
|
252
|
|
|
253 If you want to map a function over the extents in a buffer or string,
|
|
|
254 consider using @code{map-extents} or @code{mapcar-extents} instead.
|
|
|
255
|
|
|
256 See also the function @code{extents-at}.
|
|
428
|
257 @end defun
|
|
|
258
|
|
|
259 Functions that create extents must be prepared for the possibility
|
|
444
|
260 that there are other extents in the same area, created by other
|
|
428
|
261 functions. To deal with this, functions typically mark their own
|
|
|
262 extents by setting a particular property on them. The following
|
|
|
263 function makes it easier to locate those extents.
|
|
|
264
|
|
|
265 @defun extent-at pos &optional object property before at-flag
|
|
|
266 This function finds the ``smallest'' extent (i.e., the last one in the
|
|
|
267 display order) at (i.e., overlapping) @var{pos} in @var{object} (a
|
|
|
268 buffer or string) having @var{property} set. @var{object} defaults to
|
|
|
269 the current buffer. @var{property} defaults to @code{nil}, meaning that
|
|
|
270 any extent will do. Returns @code{nil} if there is no matching extent
|
|
|
271 at @var{pos}. If the fourth argument @var{before} is not @code{nil}, it
|
|
|
272 must be an extent; any returned extent will precede that extent. This
|
|
|
273 feature allows @code{extent-at} to be used by a loop over extents.
|
|
|
274
|
|
|
275 @var{at-flag} controls how end cases are handled (i.e. what ``at''
|
|
|
276 really means), and should be one of:
|
|
|
277
|
|
|
278 @table @code
|
|
|
279 @item nil
|
|
|
280 @item after
|
|
|
281 An extent is at @var{pos} if it covers the character after @var{pos}.
|
|
|
282 This is consistent with the way that text properties work.
|
|
|
283 @item before
|
|
|
284 An extent is at @var{pos} if it covers the character before @var{pos}.
|
|
|
285 @item at
|
|
|
286 An extent is at @var{pos} if it overlaps or abuts @var{pos}. This
|
|
|
287 includes all zero-length extents at @var{pos}.
|
|
|
288 @end table
|
|
|
289
|
|
|
290 Note that in all cases, the start-openness and end-openness of the
|
|
|
291 extents considered is ignored. If you want to pay attention to those
|
|
|
292 properties, you should use @code{map-extents}, which gives you more
|
|
|
293 control.
|
|
|
294 @end defun
|
|
|
295
|
|
|
296 The following low-level functions are provided for explicitly
|
|
|
297 traversing the extents in a buffer according to the display order.
|
|
440
|
298 These functions are mostly intended for debugging---in normal
|
|
428
|
299 operation, you should probably use @code{mapcar-extents} or
|
|
|
300 @code{map-extents}, or loop using the @var{before} argument to
|
|
|
301 @code{extent-at}, rather than creating a loop using @code{next-extent}.
|
|
|
302
|
|
|
303 @defun next-extent extent
|
|
|
304 Given an extent @var{extent}, this function returns the next extent in
|
|
|
305 the buffer or string's display order. If @var{extent} is a buffer or
|
|
|
306 string, this returns the first extent in the buffer or string.
|
|
|
307 @end defun
|
|
|
308
|
|
|
309 @defun previous-extent extent
|
|
|
310 Given an extent @var{extent}, this function returns the previous extent
|
|
|
311 in the buffer or string's display order. If @var{extent} is a buffer or
|
|
|
312 string, this returns the last extent in the buffer or string.
|
|
|
313 @end defun
|
|
|
314
|
|
|
315 @node Mapping Over Extents
|
|
|
316 @section Mapping Over Extents
|
|
|
317 @cindex extents, mapping
|
|
|
318
|
|
|
319 The most basic and general function for mapping over extents is called
|
|
|
320 @code{map-extents}. You should read through the definition of this
|
|
|
321 function to familiarize yourself with the concepts and optional
|
|
|
322 arguments involved. However, in practice you may find it more
|
|
|
323 convenient to use the function @code{mapcar-extents} or to create a loop
|
|
|
324 using the @code{before} argument to @code{extent-at} (@pxref{Finding
|
|
|
325 Extents}).
|
|
|
326
|
|
|
327 @defun map-extents function &optional object from to maparg flags property value
|
|
|
328 This function maps @var{function} over the extents which overlap a
|
|
|
329 region in @var{object}. @var{object} is normally a buffer or string but
|
|
|
330 could be an extent (see below). The region is normally bounded by
|
|
|
331 [@var{from}, @var{to}) (i.e. the beginning of the region is closed and
|
|
|
332 the end of the region is open), but this can be changed with the
|
|
|
333 @var{flags} argument (see below for a complete discussion).
|
|
|
334
|
|
|
335 @var{function} is called with the arguments (extent, @var{maparg}).
|
|
|
336 The arguments @var{object}, @var{from}, @var{to}, @var{maparg}, and
|
|
|
337 @var{flags} are all optional and default to the current buffer, the
|
|
444
|
338 beginning of @var{object}, the end of @var{object}, @code{nil}, and
|
|
|
339 @code{nil}, respectively. @code{map-extents} returns the first
|
|
428
|
340 non-@code{nil} result produced by @var{function}, and no more calls to
|
|
|
341 @var{function} are made after it returns non-@code{nil}.
|
|
|
342
|
|
|
343 If @var{object} is an extent, @var{from} and @var{to} default to the
|
|
|
344 extent's endpoints, and the mapping omits that extent and its
|
|
|
345 predecessors. This feature supports restarting a loop based on
|
|
|
346 @code{map-extents}. Note: @var{object} must be attached to a buffer or
|
|
|
347 string, and the mapping is done over that buffer or string.
|
|
|
348
|
|
|
349 An extent overlaps the region if there is any point in the extent that
|
|
|
350 is also in the region. (For the purpose of overlap, zero-length extents
|
|
|
351 and regions are treated as closed on both ends regardless of their
|
|
|
352 endpoints' specified open/closedness.) Note that the endpoints of an
|
|
|
353 extent or region are considered to be in that extent or region if and
|
|
|
354 only if the corresponding end is closed. For example, the extent [5,7]
|
|
|
355 overlaps the region [2,5] because 5 is in both the extent and the
|
|
|
356 region. However, (5,7] does not overlap [2,5] because 5 is not in the
|
|
|
357 extent, and neither [5,7] nor (5,7] overlaps the region [2,5) because 5
|
|
|
358 is not in the region.
|
|
|
359
|
|
|
360 The optional @var{flags} can be a symbol or a list of one or more
|
|
|
361 symbols, modifying the behavior of @code{map-extents}. Allowed symbols
|
|
|
362 are:
|
|
|
363
|
|
|
364 @table @code
|
|
|
365 @item end-closed
|
|
|
366 The region's end is closed.
|
|
|
367
|
|
|
368 @item start-open
|
|
|
369 The region's start is open.
|
|
|
370
|
|
|
371 @item all-extents-closed
|
|
|
372 Treat all extents as closed on both ends for the purpose of determining
|
|
|
373 whether they overlap the region, irrespective of their actual open- or
|
|
|
374 closedness.
|
|
|
375 @item all-extents-open
|
|
|
376 Treat all extents as open on both ends.
|
|
|
377 @item all-extents-closed-open
|
|
|
378 Treat all extents as start-closed, end-open.
|
|
|
379 @item all-extents-open-closed
|
|
|
380 Treat all extents as start-open, end-closed.
|
|
|
381
|
|
|
382 @item start-in-region
|
|
|
383 In addition to the above conditions for extent overlap, the extent's
|
|
|
384 start position must lie within the specified region. Note that, for
|
|
|
385 this condition, open start positions are treated as if 0.5 was added to
|
|
|
386 the endpoint's value, and open end positions are treated as if 0.5 was
|
|
|
387 subtracted from the endpoint's value.
|
|
|
388 @item end-in-region
|
|
|
389 The extent's end position must lie within the region.
|
|
|
390 @item start-and-end-in-region
|
|
|
391 Both the extent's start and end positions must lie within the region.
|
|
|
392 @item start-or-end-in-region
|
|
|
393 Either the extent's start or end position must lie within the region.
|
|
|
394
|
|
|
395 @item negate-in-region
|
|
|
396 The condition specified by a @code{*-in-region} flag must @emph{not}
|
|
|
397 hold for the extent to be considered.
|
|
|
398 @end table
|
|
|
399
|
|
|
400 At most one of @code{all-extents-closed}, @code{all-extents-open},
|
|
|
401 @code{all-extents-closed-open}, and @code{all-extents-open-closed} may
|
|
|
402 be specified.
|
|
|
403
|
|
|
404 At most one of @code{start-in-region}, @code{end-in-region},
|
|
|
405 @code{start-and-end-in-region}, and @code{start-or-end-in-region} may be
|
|
|
406 specified.
|
|
|
407
|
|
|
408 If optional arg @var{property} is non-@code{nil}, only extents with
|
|
|
409 that property set on them will be visited. If optional arg @var{value}
|
|
|
410 is non-@code{nil}, only extents whose value for that property is
|
|
|
411 @code{eq} to @var{value} will be visited.
|
|
|
412 @end defun
|
|
|
413
|
|
|
414 If you want to map over extents and accumulate a list of results,
|
|
|
415 the following function may be more convenient than @code{map-extents}.
|
|
|
416
|
|
|
417 @defun mapcar-extents function &optional predicate buffer-or-string from to flags property value
|
|
|
418 This function applies @var{function} to all extents which overlap a
|
|
|
419 region in @var{buffer-or-string}. The region is delimited by
|
|
|
420 @var{from} and @var{to}. @var{function} is called with one argument,
|
|
|
421 the extent. A list of the values returned by @var{function} is
|
|
|
422 returned. An optional @var{predicate} may be used to further limit the
|
|
|
423 extents over which @var{function} is mapped. The optional arguments
|
|
|
424 @var{flags}, @var{property}, and @var{value} may also be used to control
|
|
|
425 the extents passed to @var{predicate} or @var{function}, and have the
|
|
|
426 same meaning as in @code{map-extents}.
|
|
|
427 @end defun
|
|
|
428
|
|
|
429 @defun map-extent-children function &optional object from to maparg flags property value
|
|
|
430 This function is similar to @code{map-extents}, but differs in that:
|
|
|
431
|
|
|
432 @itemize @bullet
|
|
|
433 @item
|
|
|
434 It only visits extents which start in the given region.
|
|
|
435 @item
|
|
|
436 After visiting an extent @var{e}, it skips all other extents which start
|
|
|
437 inside @var{e} but end before @var{e}'s end.
|
|
|
438 @end itemize
|
|
|
439
|
|
|
440 Thus, this function may be used to walk a tree of extents in a buffer:
|
|
|
441 @example
|
|
|
442 (defun walk-extents (buffer &optional ignore)
|
|
|
443 (map-extent-children 'walk-extents buffer))
|
|
|
444 @end example
|
|
|
445 @end defun
|
|
|
446
|
|
|
447 @defun extent-in-region-p extent &optional from to flags
|
|
444
|
448 This function returns @code{t} if @code{map-extents} would visit
|
|
428
|
449 @var{extent} if called with the given arguments.
|
|
|
450 @end defun
|
|
|
451
|
|
|
452 @node Extent Properties
|
|
|
453 @section Properties of Extents
|
|
|
454 @cindex extent property
|
|
|
455 @cindex property of an extent
|
|
|
456
|
|
|
457 Each extent has a property list associating property names with
|
|
|
458 values. Some property names have predefined meanings, and can usually
|
|
|
459 only assume particular values. Assigning other values to such a
|
|
|
460 property either cause the value to be converted into a legal value
|
|
|
461 (e.g., assigning anything but @code{nil} to a Boolean property will
|
|
|
462 cause the value of @code{t} to be assigned to the property) or will
|
|
|
463 cause an error. Property names without predefined meanings can be
|
|
|
464 assigned any value. An undefined property is equivalent to a property
|
|
|
465 with a value of @code{nil}, or with a particular default value in the
|
|
|
466 case of properties with predefined meanings. Note that, when an extent
|
|
|
467 is created, the @code{end-open} and @code{detachable} properties are set
|
|
|
468 on it.
|
|
|
469
|
|
|
470 If an extent has a parent, all of its properties actually derive
|
|
|
471 from that parent (or from the root ancestor if the parent in turn
|
|
|
472 has a parent), and setting a property of the extent actually sets
|
|
|
473 that property on the parent. @xref{Extent Parents}.
|
|
|
474
|
|
444
|
475 @defun extent-property extent property &optional default
|
|
|
476 This function returns @var{extent}'s value for @var{property}, or
|
|
|
477 @var{default} if no such property exists.
|
|
428
|
478 @end defun
|
|
|
479
|
|
|
480 @defun extent-properties extent
|
|
|
481 This function returns a list of all of @var{extent}'s properties that do
|
|
|
482 not have the value of @code{nil} (or the default value, for properties
|
|
|
483 with predefined meanings).
|
|
|
484 @end defun
|
|
|
485
|
|
|
486 @defun set-extent-property extent property value
|
|
|
487 This function sets @var{property} to @var{value} in @var{extent}. (If
|
|
|
488 @var{property} has a predefined meaning, only certain values are
|
|
|
489 allowed, and some values may be converted to others before being
|
|
|
490 stored.)
|
|
|
491 @end defun
|
|
|
492
|
|
|
493 @defun set-extent-properties extent plist
|
|
|
494 Change some properties of @var{extent}. @var{plist} is a property
|
|
|
495 list. This is useful to change many extent properties at once.
|
|
|
496 @end defun
|
|
|
497
|
|
|
498 The following table lists the properties with predefined meanings, along
|
|
|
499 with their allowable values.
|
|
|
500
|
|
|
501 @table @code
|
|
|
502 @item detached
|
|
|
503 (Boolean) Whether the extent is detached. Setting this is the same
|
|
|
504 as calling @code{detach-extent}. @xref{Detached Extents}.
|
|
|
505
|
|
|
506 @item destroyed
|
|
|
507 (Boolean) Whether the extent has been deleted. Setting this is the same
|
|
|
508 as calling @code{delete-extent}.
|
|
|
509
|
|
|
510 @item priority
|
|
|
511 (integer) The extent's redisplay priority. Defaults to 0. @xref{Intro
|
|
|
512 to Extents, priority}. This property can also be set with
|
|
|
513 @code{set-extent-priority} and accessed with @code{extent-priority}.
|
|
|
514
|
|
|
515 @item start-open
|
|
|
516 (Boolean) Whether the start position of the extent is open, meaning that
|
|
|
517 characters inserted at that position go outside of the extent.
|
|
|
518 @xref{Extent Endpoints}.
|
|
|
519
|
|
|
520 @item start-closed
|
|
|
521 (Boolean) Same as @code{start-open} but with the opposite sense. Setting
|
|
|
522 this property clears @code{start-open} and vice-versa.
|
|
|
523
|
|
|
524 @item end-open
|
|
|
525 (Boolean) Whether the end position of the extent is open, meaning that
|
|
|
526 characters inserted at that position go outside of the extent. This is
|
|
|
527 @code{t} by default.
|
|
|
528 @xref{Extent Endpoints}.
|
|
|
529
|
|
|
530 @item end-closed
|
|
|
531 (Boolean) Same as @code{end-open} but with the opposite sense. Setting
|
|
|
532 this property clears @code{end-open} and vice-versa.
|
|
|
533
|
|
|
534 @item read-only
|
|
|
535 (Boolean) Whether text within this extent will be unmodifiable.
|
|
|
536
|
|
|
537 @item face
|
|
|
538 (face, face name, list of faces or face names, or @code{nil}) The face
|
|
|
539 in which to display the extent's text. This property can also be set
|
|
|
540 with @code{set-extent-face} and accessed with @code{extent-face}.
|
|
|
541 Note that if a list of faces is specified, the faces are merged together,
|
|
|
542 with faces earlier in the list having priority over faces later in the
|
|
|
543 list.
|
|
|
544
|
|
|
545 @item mouse-face
|
|
|
546 (face, face name, list of faces or face names, or @code{nil}) The face
|
|
|
547 used to display the extent when the mouse moves over it. This property
|
|
|
548 can also be set with @code{set-extent-mouse-face} and accessed with
|
|
|
549 @code{extent-mouse-face}. Note that if a list of faces is specified,
|
|
|
550 the faces are merged together, with faces earlier in the list having
|
|
|
551 priority over faces later in the list. @xref{Extents and Events}.
|
|
|
552
|
|
|
553 @item pointer
|
|
|
554 (pointer glyph) The glyph used as the pointer when the mouse moves over
|
|
|
555 the extent. This takes precedence over the @code{text-pointer-glyph}
|
|
|
556 and @code{nontext-pointer-glyph} variables. If for any reason this
|
|
|
557 glyph is an invalid pointer, the standard glyphs will be used as
|
|
|
558 fallbacks. @xref{Mouse Pointer}.
|
|
|
559
|
|
|
560 @item detachable
|
|
|
561 (Boolean) Whether this extent becomes detached when all of the text it
|
|
|
562 covers is deleted. This is @code{t} by default. @xref{Detached
|
|
|
563 Extents}.
|
|
|
564
|
|
|
565 @item duplicable
|
|
|
566 (Boolean) Whether this extent should be copied into strings, so that
|
|
|
567 kill, yank, and undo commands will restore or copy it. @xref{Duplicable
|
|
|
568 Extents}.
|
|
|
569
|
|
|
570 @item unique
|
|
|
571 (Boolean) Meaningful only in conjunction with @code{duplicable}.
|
|
|
572 When this is set, there may be only one instance of
|
|
|
573 this extent attached at a time. @xref{Duplicable Extents}.
|
|
|
574
|
|
|
575 @item invisible
|
|
|
576 (Boolean) If @code{t}, text under this extent will not be displayed --
|
|
|
577 it will look as if the text is not there at all.
|
|
|
578
|
|
|
579 @item keymap
|
|
|
580 (keymap or @code{nil}) This keymap is consulted for mouse clicks on this
|
|
|
581 extent or keypresses made while @code{point} is within the extent.
|
|
|
582 @xref{Extents and Events}.
|
|
|
583
|
|
|
584 @item copy-function
|
|
|
585 This is a hook that is run when a duplicable extent is about to be
|
|
|
586 copied from a buffer to a string (or the kill ring). @xref{Duplicable
|
|
|
587 Extents}.
|
|
|
588
|
|
|
589 @item paste-function
|
|
|
590 This is a hook that is run when a duplicable extent is about to be
|
|
|
591 copied from a string (or the kill ring) into a buffer. @xref{Duplicable
|
|
|
592 Extents}.
|
|
|
593
|
|
|
594 @item begin-glyph
|
|
|
595 (glyph or @code{nil}) This extent's begin glyph.
|
|
|
596 @xref{Annotations}.
|
|
|
597
|
|
|
598 @item end-glyph
|
|
|
599 (glyph or @code{nil}) This extent's end glyph.
|
|
|
600 @xref{Annotations}.
|
|
|
601
|
|
|
602 @item begin-glyph-layout
|
|
|
603 (@code{text}, @code{whitespace}, @code{inside-margin}, or
|
|
|
604 @code{outside-margin}) The layout policy for this extent's begin glyph.
|
|
|
605 Defaults to @code{text}. @xref{Annotations}.
|
|
|
606
|
|
|
607 @item end-glyph-layout
|
|
|
608 (@code{text}, @code{whitespace}, @code{inside-margin}, or
|
|
|
609 @code{outside-margin}) The layout policy for this extent's end glyph.
|
|
|
610 Defaults to @code{text}. @xref{Annotations}.
|
|
|
611
|
|
|
612 @item initial-redisplay-function
|
|
|
613 (any funcallable object) The function to be called the first time (a
|
|
|
614 part of) the extent is redisplayed. It will be called with the extent
|
|
|
615 as its argument.
|
|
|
616
|
|
|
617 This is used by @code{lazy-shot} to implement lazy font-locking. The
|
|
|
618 functionality is still experimental, and may change without further
|
|
|
619 notice.
|
|
|
620 @end table
|
|
|
621
|
|
|
622 The following convenience functions are provided for accessing
|
|
|
623 particular properties of an extent.
|
|
|
624
|
|
|
625 @defun extent-face extent
|
|
|
626 This function returns the @code{face} property of @var{extent}. This
|
|
|
627 might also return a list of face names. Do not modify this list
|
|
|
628 directly! Instead, use @code{set-extent-face}.
|
|
|
629
|
|
|
630 Note that you can use @code{eq} to compare lists of faces as returned
|
|
|
631 by @code{extent-face}. In other words, if you set the face of two
|
|
|
632 different extents to two lists that are @code{equal} but not @code{eq},
|
|
|
633 then the return value of @code{extent-face} on the two extents will
|
|
|
634 return the identical list.
|
|
|
635 @end defun
|
|
|
636
|
|
|
637 @defun extent-mouse-face extent
|
|
|
638 This function returns the @code{mouse-face} property of @var{extent}.
|
|
|
639 This might also return a list of face names. Do not modify this list
|
|
|
640 directly! Instead, use @code{set-extent-mouse-face}.
|
|
|
641
|
|
|
642 Note that you can use @code{eq} to compare lists of faces as returned
|
|
|
643 by @code{extent-mouse-face}, just like for @code{extent-face}.
|
|
|
644 @end defun
|
|
|
645
|
|
|
646 @defun extent-priority extent
|
|
|
647 This function returns the @code{priority} property of @var{extent}.
|
|
|
648 @end defun
|
|
|
649
|
|
|
650 @defun extent-keymap extent
|
|
|
651 This function returns the @code{keymap} property of @var{extent}.
|
|
|
652 @end defun
|
|
|
653
|
|
|
654 @defun extent-begin-glyph-layout extent
|
|
|
655 This function returns the @code{begin-glyph-layout} property of
|
|
|
656 @var{extent}, i.e. the layout policy associated with the @var{extent}'s
|
|
|
657 begin glyph.
|
|
|
658 @end defun
|
|
|
659
|
|
|
660 @defun extent-end-glyph-layout extent
|
|
|
661 This function returns the @code{end-glyph-layout} property of
|
|
|
662 @var{extent}, i.e. the layout policy associated with the @var{extent}'s
|
|
|
663 end glyph.
|
|
|
664 @end defun
|
|
|
665
|
|
|
666 @defun extent-begin-glyph extent
|
|
|
667 This function returns the @code{begin-glyph} property of @var{extent},
|
|
|
668 i.e. the glyph object displayed at the beginning of @var{extent}. If
|
|
|
669 there is none, @code{nil} is returned.
|
|
|
670 @end defun
|
|
|
671
|
|
|
672 @defun extent-end-glyph extent
|
|
|
673 This function returns the @code{end-glyph} property of @var{extent},
|
|
|
674 i.e. the glyph object displayed at the end of @var{extent}. If
|
|
|
675 there is none, @code{nil} is returned.
|
|
|
676 @end defun
|
|
|
677
|
|
|
678 The following convenience functions are provided for setting particular
|
|
|
679 properties of an extent.
|
|
|
680
|
|
444
|
681 @defun set-extent-priority extent priority
|
|
428
|
682 This function sets the @code{priority} property of @var{extent} to
|
|
444
|
683 @var{priority}.
|
|
428
|
684 @end defun
|
|
|
685
|
|
|
686 @defun set-extent-face extent face
|
|
|
687 This function sets the @code{face} property of @var{extent} to
|
|
|
688 @var{face}.
|
|
|
689 @end defun
|
|
|
690
|
|
|
691 @defun set-extent-mouse-face extent face
|
|
|
692 This function sets the @code{mouse-face} property of @var{extent} to
|
|
|
693 @var{face}.
|
|
|
694 @end defun
|
|
|
695
|
|
|
696 @defun set-extent-keymap extent keymap
|
|
|
697 This function sets the @code{keymap} property of @var{extent} to
|
|
|
698 @var{keymap}. @var{keymap} must be either a keymap object, or
|
|
|
699 @code{nil}.
|
|
|
700 @end defun
|
|
|
701
|
|
|
702 @defun set-extent-begin-glyph-layout extent layout
|
|
|
703 This function sets the @code{begin-glyph-layout} property of
|
|
|
704 @var{extent} to @var{layout}.
|
|
|
705 @end defun
|
|
|
706
|
|
|
707 @defun set-extent-end-glyph-layout extent layout
|
|
|
708 This function sets the @code{end-glyph-layout} property of
|
|
|
709 @var{extent} to @var{layout}.
|
|
|
710 @end defun
|
|
|
711
|
|
|
712 @defun set-extent-begin-glyph extent begin-glyph &optional layout
|
|
|
713 This function sets the @code{begin-glyph} and @code{glyph-layout}
|
|
|
714 properties of @var{extent} to @var{begin-glyph} and @var{layout},
|
|
|
715 respectively. (@var{layout} defaults to @code{text} if not specified.)
|
|
|
716 @end defun
|
|
|
717
|
|
|
718 @defun set-extent-end-glyph extent end-glyph &optional layout
|
|
|
719 This function sets the @code{end-glyph} and @code{glyph-layout}
|
|
|
720 properties of @var{extent} to @var{end-glyph} and @var{layout},
|
|
|
721 respectively. (@var{layout} defaults to @code{text} if not specified.)
|
|
|
722 @end defun
|
|
|
723
|
|
|
724 @defun set-extent-initial-redisplay-function extent function
|
|
444
|
725 This function sets the @code{initial-redisplay-function} property of the
|
|
428
|
726 extent to @var{function}.
|
|
|
727 @end defun
|
|
|
728
|
|
|
729 @node Detached Extents
|
|
|
730 @section Detached Extents
|
|
|
731 @cindex detached extent
|
|
|
732
|
|
|
733 A detached extent is an extent that is not attached to a buffer or
|
|
|
734 string but can be re-inserted. Detached extents have a start position
|
|
|
735 and end position of @code{nil}. Extents can be explicitly detached
|
|
|
736 using @code{detach-extent}. An extent is also detached when all of its
|
|
|
737 characters are all killed by a deletion, if its @code{detachable}
|
|
|
738 property is set; if this property is not set, the extent becomes a
|
|
|
739 zero-length extent. (Zero-length extents with the @code{detachable}
|
|
|
740 property set behave specially. @xref{Extent Endpoints, zero-length
|
|
|
741 extents}.)
|
|
|
742
|
|
|
743 @defun detach-extent extent
|
|
|
744 This function detaches @var{extent} from its buffer or string. If
|
|
|
745 @var{extent} has the @code{duplicable} property, its detachment is
|
|
|
746 tracked by the undo mechanism. @xref{Duplicable Extents}.
|
|
|
747 @end defun
|
|
|
748
|
|
|
749 @defun extent-detached-p extent
|
|
|
750 This function returns @code{nil} if @var{extent} is detached, and
|
|
|
751 @code{t} otherwise.
|
|
|
752 @end defun
|
|
|
753
|
|
|
754 @defun copy-extent extent &optional object
|
|
|
755 This function makes a copy of @var{extent}. It is initially detached.
|
|
|
756 Optional argument @var{object} defaults to @var{extent}'s object
|
|
|
757 (normally a buffer or string, but could be @code{nil}).
|
|
|
758 @end defun
|
|
|
759
|
|
|
760 @defun insert-extent extent &optional start end no-hooks object
|
|
|
761 This function inserts @var{extent} from @var{start} to @var{end} in
|
|
|
762 @var{object} (a buffer or string). If @var{extent} is detached from a
|
|
|
763 different buffer or string, or in most cases when @var{extent} is
|
|
|
764 already attached, the extent will first be copied as if with
|
|
|
765 @code{copy-extent}. This function operates the same as if @code{insert}
|
|
|
766 were called on a string whose extent data calls for @var{extent} to be
|
|
|
767 inserted, except that if @var{no-hooks} is non-@code{nil},
|
|
|
768 @var{extent}'s @code{paste-function} will not be invoked.
|
|
|
769 @xref{Duplicable Extents}.
|
|
|
770 @end defun
|
|
|
771
|
|
|
772 @node Extent Parents
|
|
|
773 @section Extent Parents
|
|
|
774 @cindex extent parent
|
|
|
775 @cindex extent children
|
|
|
776 @cindex parent, of extent
|
|
|
777 @cindex children, of extent
|
|
|
778
|
|
|
779 An extent can have a parent extent set for it. If this is the case,
|
|
|
780 the extent derives all its properties from that extent and has no
|
|
|
781 properties of its own. The only ``properties'' that the extent keeps
|
|
|
782 are the buffer or string it refers to and the start and end points.
|
|
|
783 (More correctly, the extent's own properties are shadowed. If you
|
|
|
784 later change the extent to have no parent, its own properties will
|
|
|
785 become visible again.)
|
|
|
786
|
|
|
787 It is possible for an extent's parent to itself have a parent,
|
|
|
788 and so on. Through this, a whole tree of extents can be created,
|
|
|
789 all deriving their properties from one root extent. Note, however,
|
|
440
|
790 that you cannot create an inheritance loop---this is explicitly
|
|
428
|
791 disallowed.
|
|
|
792
|
|
|
793 Parent extents are used to implement the extents over the modeline.
|
|
|
794
|
|
|
795 @defun set-extent-parent extent parent
|
|
|
796 This function sets the parent of @var{extent} to @var{parent}.
|
|
|
797 If @var{parent} is @code{nil}, the extent is set to have no parent.
|
|
|
798 @end defun
|
|
|
799
|
|
|
800 @defun extent-parent extent
|
|
|
801 This function return the parents (if any) of @var{extent}, or
|
|
|
802 @code{nil}.
|
|
|
803 @end defun
|
|
|
804
|
|
|
805 @defun extent-children extent
|
|
|
806 This function returns a list of the children (if any) of @var{extent}.
|
|
|
807 The children of an extent are all those extents whose parent is that
|
|
|
808 extent. This function does not recursively trace children of children.
|
|
|
809 @end defun
|
|
|
810
|
|
|
811 @defun extent-descendants extent
|
|
|
812 This function returns a list of all descendants of @var{extent},
|
|
|
813 including @var{extent}. This recursively applies @code{extent-children}
|
|
|
814 to any children of @var{extent}, until no more children can be found.
|
|
|
815 @end defun
|
|
|
816
|
|
|
817 @node Duplicable Extents
|
|
|
818 @section Duplicable Extents
|
|
|
819 @cindex duplicable extent
|
|
|
820 @cindex unique extents
|
|
|
821 @cindex extent replica
|
|
|
822 @cindex extent, duplicable
|
|
|
823 @cindex extent, unique
|
|
|
824
|
|
|
825 If an extent has the @code{duplicable} property, it will be copied into
|
|
|
826 strings, so that kill, yank, and undo commands will restore or copy it.
|
|
|
827
|
|
|
828 Specifically:
|
|
|
829
|
|
|
830 @itemize @bullet
|
|
|
831 @item
|
|
|
832 When a string is created using @code{buffer-substring} or
|
|
|
833 @code{buffer-string}, any duplicable extents in the region corresponding
|
|
|
834 to the string will be copied into the string (@pxref{Buffer
|
|
456
|
835 Contents}). When the string is inserted into a buffer using
|
|
428
|
836 @code{insert}, @code{insert-before-markers}, @code{insert-buffer} or
|
|
|
837 @code{insert-buffer-substring}, the extents in the string will be copied
|
|
|
838 back into the buffer (@pxref{Insertion}). The extents in a string can,
|
|
|
839 of course, be retrieved explicitly using the standard extent primitives
|
|
|
840 over the string.
|
|
|
841
|
|
|
842 @item
|
|
|
843 Similarly, when text is copied or cut into the kill ring, any duplicable
|
|
|
844 extents will be remembered and reinserted later when the text is pasted
|
|
|
845 back into a buffer.
|
|
|
846
|
|
|
847 @item
|
|
|
848 When @code{concat} is called on strings, the extents in the strings are
|
|
|
849 copied into the resulting string.
|
|
|
850
|
|
|
851 @item
|
|
|
852 When @code{substring} is called on a string, the relevant extents
|
|
|
853 are copied into the resulting string.
|
|
|
854
|
|
|
855 @item
|
|
|
856 When a duplicable extent is detached by @code{detach-extent} or string
|
|
|
857 deletion, or inserted by @code{insert-extent} or string insertion, the
|
|
|
858 action is recorded by the undo mechanism so that it can be undone later.
|
|
|
859 Note that if an extent gets detached and then a later undo causes the
|
|
|
860 extent to get reinserted, the new extent will not be `eq' to the original
|
|
|
861 extent.
|
|
|
862
|
|
|
863 @item
|
|
|
864 Extent motion, face changes, and attachment via @code{make-extent} are
|
|
|
865 not recorded by the undo mechanism. This means that extent changes
|
|
|
866 which are to be undo-able must be performed by character editing, or by
|
|
|
867 insertion and detachment of duplicable extents.
|
|
|
868
|
|
|
869 @item
|
|
|
870 A duplicable extent's @code{copy-function} property, if non-@code{nil},
|
|
|
871 should be a function, and will be run when a duplicable extent is about
|
|
|
872 to be copied from a buffer to a string (or the kill ring). It is called
|
|
|
873 with three arguments: the extent and the buffer positions within it
|
|
|
874 which are being copied. If this function returns @code{nil}, then the
|
|
|
875 extent will not be copied; otherwise it will.
|
|
|
876
|
|
|
877 @item
|
|
|
878 A duplicable extent's @code{paste-function} property, if non-@code{nil},
|
|
|
879 should be a function, and will be run when a duplicable extent is about
|
|
|
880 to be copied from a string (or the kill ring) into a buffer. It is
|
|
|
881 called with three arguments: the original extent and the buffer
|
|
|
882 positions which the copied extent will occupy. (This hook is run after
|
|
|
883 the corresponding text has already been inserted into the buffer.) Note
|
|
|
884 that the extent argument may be detached when this function is run. If
|
|
|
885 this function returns @code{nil}, no extent will be inserted.
|
|
|
886 Otherwise, there will be an extent covering the range in question.
|
|
|
887
|
|
|
888 Note: if the extent to be copied is already attached to the buffer and
|
|
|
889 overlaps the new range, the extent will simply be extended and the
|
|
|
890 @code{paste-function} will not be called.
|
|
|
891 @end itemize
|
|
|
892
|
|
|
893 @node Extents and Events
|
|
|
894 @section Interaction of Extents with Keyboard and Mouse Events
|
|
|
895
|
|
|
896 If an extent has the @code{mouse-face} property set, it will be
|
|
|
897 highlighted when the mouse passes over it. Highlighting is accomplished
|
|
|
898 by merging the extent's face with the face or faces specified by the
|
|
|
899 @code{mouse-face} property. The effect is as if a pseudo-extent with
|
|
|
900 the @code{mouse-face} face were inserted after the extent in the display
|
|
|
901 order (@pxref{Extent Endpoints}, display order).
|
|
|
902
|
|
|
903 @defvar mouse-highlight-priority
|
|
|
904 This variable holds the priority to use when merging in the highlighting
|
|
|
905 pseudo-extent. The default is 1000. This is purposely set very high
|
|
|
906 so that the highlighting pseudo-extent shows up even if there are other
|
|
|
907 extents with various priorities at the same location.
|
|
|
908 @end defvar
|
|
|
909
|
|
|
910 You can also explicitly cause an extent to be highlighted. Only one
|
|
|
911 extent at a time can be highlighted in this fashion, and any other
|
|
|
912 highlighted extent will be de-highlighted.
|
|
|
913
|
|
|
914 @defun highlight-extent extent &optional highlight-p
|
|
|
915 This function highlights (if @var{highlight-p} is non-@code{nil}) or
|
|
|
916 de-highlights (if @var{highlight-p} is @code{nil}) @var{extent}, if
|
|
|
917 @var{extent} has the @code{mouse-face} property. (Nothing happens if
|
|
|
918 @var{extent} does not have the @code{mouse-face} property.)
|
|
|
919 @end defun
|
|
|
920
|
|
|
921 @defun force-highlight-extent extent &optional highlight-p
|
|
|
922 This function is similar to @code{highlight-extent} but highlights
|
|
|
923 or de-highlights the extent regardless of whether it has the
|
|
|
924 @code{mouse-face} property.
|
|
|
925 @end defun
|
|
|
926
|
|
|
927 If an extent has a @code{keymap} property, this keymap will be
|
|
|
928 consulted for mouse clicks on the extent and keypresses made while
|
|
|
929 @code{point} is within the extent. The behavior of mouse clicks and
|
|
|
930 keystrokes not defined in the keymap is as normal for the buffer.
|
|
|
931
|
|
|
932 @node Atomic Extents
|
|
|
933 @section Atomic Extents
|
|
|
934 @cindex atomic extent
|
|
|
935
|
|
|
936 If the Lisp file @file{atomic-extents} is loaded, then the atomic
|
|
|
937 extent facility is available. An @dfn{atomic extent} is an extent for
|
|
|
938 which @code{point} cannot be positioned anywhere within it. This
|
|
|
939 ensures that when selecting text, either all or none of the extent is
|
|
|
940 selected.
|
|
|
941
|
|
|
942 To make an extent atomic, set its @code{atomic} property.
|
