|
0
|
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.
|
