|
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
|
|
298
|
48 @emph{Please note:} An alternative way to add properties to a buffer or
|
|
0
|
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
|
|
98
|
87 An extent can optionally have a @dfn{begin-glyph} or @dfn{end-glyph}
|
|
211
|
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}.
|
|
0
|
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
|
|
2
|
410 region in @var{buffer-or-string}. The region is delimited by
|
|
0
|
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
|
|
207
|
484 @defun set-extent-properties extent plist
|
|
|
485 Change some properties of @var{extent}. @var{plist} is a property
|
|
|
486 list. This is useful to change many extent properties at once.
|
|
|
487 @end defun
|
|
|
488
|
|
0
|
489 The following table lists the properties with predefined meanings, along
|
|
|
490 with their allowable values.
|
|
|
491
|
|
|
492 @table @code
|
|
|
493 @item detached
|
|
|
494 (Boolean) Whether the extent is detached. Setting this is the same
|
|
|
495 as calling @code{detach-extent}. @xref{Detached Extents}.
|
|
|
496
|
|
|
497 @item destroyed
|
|
|
498 (Boolean) Whether the extent has been deleted. Setting this is the same
|
|
|
499 as calling @code{delete-extent}.
|
|
|
500
|
|
|
501 @item priority
|
|
|
502 (integer) The extent's redisplay priority. Defaults to 0. @xref{Intro
|
|
|
503 to Extents, priority}. This property can also be set with
|
|
|
504 @code{set-extent-priority} and accessed with @code{extent-priority}.
|
|
|
505
|
|
|
506 @item start-open
|
|
|
507 (Boolean) Whether the start position of the extent is open, meaning that
|
|
|
508 characters inserted at that position go outside of the extent.
|
|
|
509 @xref{Extent Endpoints}.
|
|
|
510
|
|
|
511 @item start-closed
|
|
|
512 (Boolean) Same as @code{start-open} but with the opposite sense. Setting
|
|
|
513 this property clears @code{start-open} and vice-versa.
|
|
|
514
|
|
|
515 @item end-open
|
|
|
516 (Boolean) Whether the end position of the extent is open, meaning that
|
|
|
517 characters inserted at that position go outside of the extent. This is
|
|
|
518 @code{t} by default.
|
|
|
519 @xref{Extent Endpoints}.
|
|
|
520
|
|
|
521 @item end-closed
|
|
|
522 (Boolean) Same as @code{end-open} but with the opposite sense. Setting
|
|
|
523 this property clears @code{end-open} and vice-versa.
|
|
|
524
|
|
|
525 @item read-only
|
|
|
526 (Boolean) Whether text within this extent will be unmodifiable.
|
|
|
527
|
|
|
528 @item face
|
|
|
529 (face, face name, list of faces or face names, or @code{nil}) The face
|
|
|
530 in which to display the extent's text. This property can also be set
|
|
|
531 with @code{set-extent-face} and accessed with @code{extent-face}.
|
|
|
532 Note that if a list of faces is specified, the faces are merged together,
|
|
|
533 with faces earlier in the list having priority over faces later in the
|
|
|
534 list.
|
|
|
535
|
|
|
536 @item mouse-face
|
|
|
537 (face, face name, list of faces or face names, or @code{nil}) The face
|
|
|
538 used to display the extent when the mouse moves over it. This property
|
|
|
539 can also be set with @code{set-extent-mouse-face} and accessed with
|
|
|
540 @code{extent-mouse-face}. Note that if a list of faces is specified,
|
|
|
541 the faces are merged together, with faces earlier in the list having
|
|
|
542 priority over faces later in the list. @xref{Extents and Events}.
|
|
|
543
|
|
|
544 @item pointer
|
|
|
545 (pointer glyph) The glyph used as the pointer when the mouse moves over
|
|
|
546 the extent. This takes precedence over the @code{text-pointer-glyph}
|
|
|
547 and @code{nontext-pointer-glyph} variables. If for any reason this
|
|
|
548 glyph is an invalid pointer, the standard glyphs will be used as
|
|
335
|
549 fallbacks. @xref{Mouse Pointer}.
|
|
0
|
550
|
|
|
551 @item detachable
|
|
|
552 (Boolean) Whether this extent becomes detached when all of the text it
|
|
|
553 covers is deleted. This is @code{t} by default. @xref{Detached
|
|
|
554 Extents}.
|
|
|
555
|
|
|
556 @item duplicable
|
|
|
557 (Boolean) Whether this extent should be copied into strings, so that
|
|
|
558 kill, yank, and undo commands will restore or copy it. @xref{Duplicable
|
|
|
559 Extents}.
|
|
|
560
|
|
|
561 @item unique
|
|
96
|
562 (Boolean) Meaningful only in conjunction with @code{duplicable}.
|
|
|
563 When this is set, there may be only one instance of
|
|
0
|
564 this extent attached at a time. @xref{Duplicable Extents}.
|
|
|
565
|
|
|
566 @item invisible
|
|
|
567 (Boolean) If @code{t}, text under this extent will not be displayed --
|
|
|
568 it will look as if the text is not there at all.
|
|
|
569
|
|
|
570 @item keymap
|
|
|
571 (keymap or @code{nil}) This keymap is consulted for mouse clicks on this
|
|
|
572 extent or keypresses made while @code{point} is within the extent.
|
|
|
573 @xref{Extents and Events}.
|
|
|
574
|
|
|
575 @item copy-function
|
|
|
576 This is a hook that is run when a duplicable extent is about to be
|
|
|
577 copied from a buffer to a string (or the kill ring). @xref{Duplicable
|
|
|
578 Extents}.
|
|
|
579
|
|
|
580 @item paste-function
|
|
|
581 This is a hook that is run when a duplicable extent is about to be
|
|
|
582 copied from a string (or the kill ring) into a buffer. @xref{Duplicable
|
|
|
583 Extents}.
|
|
|
584
|
|
|
585 @item begin-glyph
|
|
|
586 (glyph or @code{nil}) This extent's begin glyph.
|
|
|
587 @xref{Annotations}.
|
|
|
588
|
|
|
589 @item end-glyph
|
|
|
590 (glyph or @code{nil}) This extent's end glyph.
|
|
|
591 @xref{Annotations}.
|
|
|
592
|
|
|
593 @item begin-glyph-layout
|
|
|
594 (@code{text}, @code{whitespace}, @code{inside-margin}, or
|
|
|
595 @code{outside-margin}) The layout policy for this extent's begin glyph.
|
|
|
596 Defaults to @code{text}. @xref{Annotations}.
|
|
|
597
|
|
|
598 @item end-glyph-layout
|
|
|
599 (@code{text}, @code{whitespace}, @code{inside-margin}, or
|
|
|
600 @code{outside-margin}) The layout policy for this extent's end glyph.
|
|
|
601 Defaults to @code{text}. @xref{Annotations}.
|
|
207
|
602
|
|
|
603 @item initial-redisplay-function
|
|
|
604 (any funcallable object) The function to be called the first time (a
|
|
|
605 part of) the extent is redisplayed. It will be called with the extent
|
|
|
606 as its argument.
|
|
|
607
|
|
|
608 This is used by @code{lazy-shot} to implement lazy font-locking. The
|
|
|
609 functionality is still experimental, and may change without further
|
|
|
610 notice.
|
|
0
|
611 @end table
|
|
|
612
|
|
|
613 The following convenience functions are provided for accessing
|
|
|
614 particular properties of an extent.
|
|
|
615
|
|
|
616 @defun extent-face extent
|
|
|
617 This function returns the @code{face} property of @var{extent}. This
|
|
|
618 might also return a list of face names. Do not modify this list
|
|
|
619 directly! Instead, use @code{set-extent-face}.
|
|
|
620
|
|
|
621 Note that you can use @code{eq} to compare lists of faces as returned
|
|
|
622 by @code{extent-face}. In other words, if you set the face of two
|
|
|
623 different extents to two lists that are @code{equal} but not @code{eq},
|
|
|
624 then the return value of @code{extent-face} on the two extents will
|
|
|
625 return the identical list.
|
|
|
626 @end defun
|
|
|
627
|
|
|
628 @defun extent-mouse-face extent
|
|
|
629 This function returns the @code{mouse-face} property of @var{extent}.
|
|
|
630 This might also return a list of face names. Do not modify this list
|
|
|
631 directly! Instead, use @code{set-extent-mouse-face}.
|
|
|
632
|
|
|
633 Note that you can use @code{eq} to compare lists of faces as returned
|
|
|
634 by @code{extent-mouse-face}, just like for @code{extent-face}.
|
|
|
635 @end defun
|
|
|
636
|
|
|
637 @defun extent-priority extent
|
|
|
638 This function returns the @code{priority} property of @var{extent}.
|
|
|
639 @end defun
|
|
|
640
|
|
211
|
641 @defun extent-keymap extent
|
|
|
642 This function returns the @code{keymap} property of @var{extent}.
|
|
|
643 @end defun
|
|
|
644
|
|
0
|
645 @defun extent-begin-glyph-layout extent
|
|
|
646 This function returns the @code{begin-glyph-layout} property of
|
|
|
647 @var{extent}, i.e. the layout policy associated with the @var{extent}'s
|
|
|
648 begin glyph.
|
|
|
649 @end defun
|
|
|
650
|
|
|
651 @defun extent-end-glyph-layout extent
|
|
|
652 This function returns the @code{end-glyph-layout} property of
|
|
|
653 @var{extent}, i.e. the layout policy associated with the @var{extent}'s
|
|
|
654 end glyph.
|
|
|
655 @end defun
|
|
|
656
|
|
|
657 @defun extent-begin-glyph extent
|
|
|
658 This function returns the @code{begin-glyph} property of @var{extent},
|
|
|
659 i.e. the glyph object displayed at the beginning of @var{extent}. If
|
|
|
660 there is none, @code{nil} is returned.
|
|
|
661 @end defun
|
|
|
662
|
|
|
663 @defun extent-end-glyph extent
|
|
|
664 This function returns the @code{end-glyph} property of @var{extent},
|
|
|
665 i.e. the glyph object displayed at the end of @var{extent}. If
|
|
|
666 there is none, @code{nil} is returned.
|
|
|
667 @end defun
|
|
|
668
|
|
|
669 The following convenience functions are provided for setting particular
|
|
|
670 properties of an extent.
|
|
|
671
|
|
|
672 @defun set-extent-priority extent pri
|
|
|
673 This function sets the @code{priority} property of @var{extent} to
|
|
|
674 @var{pri}.
|
|
|
675 @end defun
|
|
|
676
|
|
|
677 @defun set-extent-face extent face
|
|
|
678 This function sets the @code{face} property of @var{extent} to
|
|
|
679 @var{face}.
|
|
|
680 @end defun
|
|
|
681
|
|
|
682 @defun set-extent-mouse-face extent face
|
|
|
683 This function sets the @code{mouse-face} property of @var{extent} to
|
|
|
684 @var{face}.
|
|
|
685 @end defun
|
|
|
686
|
|
|
687 @defun set-extent-keymap extent keymap
|
|
|
688 This function sets the @code{keymap} property of @var{extent} to
|
|
207
|
689 @var{keymap}. @var{keymap} must be either a keymap object, or
|
|
|
690 @code{nil}.
|
|
0
|
691 @end defun
|
|
|
692
|
|
|
693 @defun set-extent-begin-glyph-layout extent layout
|
|
|
694 This function sets the @code{begin-glyph-layout} property of
|
|
|
695 @var{extent} to @var{layout}.
|
|
|
696 @end defun
|
|
|
697
|
|
|
698 @defun set-extent-end-glyph-layout extent layout
|
|
|
699 This function sets the @code{end-glyph-layout} property of
|
|
|
700 @var{extent} to @var{layout}.
|
|
|
701 @end defun
|
|
|
702
|
|
|
703 @defun set-extent-begin-glyph extent begin-glyph &optional layout
|
|
|
704 This function sets the @code{begin-glyph} and @code{glyph-layout}
|
|
|
705 properties of @var{extent} to @var{begin-glyph} and @var{layout},
|
|
|
706 respectively. (@var{layout} defaults to @code{text} if not specified.)
|
|
|
707 @end defun
|
|
|
708
|
|
|
709 @defun set-extent-end-glyph extent end-glyph &optional layout
|
|
|
710 This function sets the @code{end-glyph} and @code{glyph-layout}
|
|
|
711 properties of @var{extent} to @var{end-glyph} and @var{layout},
|
|
|
712 respectively. (@var{layout} defaults to @code{text} if not specified.)
|
|
|
713 @end defun
|
|
|
714
|
|
207
|
715 @defun set-extent-initial-redisplay-function extent function
|
|
|
716 This function sets the @code{initial-redisplay-function} property of the
|
|
|
717 extent to @var{function}.
|
|
|
718 @end defun
|
|
|
719
|
|
0
|
720 @node Detached Extents
|
|
|
721 @section Detached Extents
|
|
|
722 @cindex detached extent
|
|
|
723
|
|
|
724 A detached extent is an extent that is not attached to a buffer or
|
|
|
725 string but can be re-inserted. Detached extents have a start position
|
|
|
726 and end position of @code{nil}. Extents can be explicitly detached
|
|
|
727 using @code{detach-extent}. An extent is also detached when all of its
|
|
|
728 characters are all killed by a deletion, if its @code{detachable}
|
|
|
729 property is set; if this property is not set, the extent becomes a
|
|
|
730 zero-length extent. (Zero-length extents with the @code{detachable}
|
|
|
731 property set behave specially. @xref{Extent Endpoints, zero-length
|
|
|
732 extents}.)
|
|
|
733
|
|
|
734 @defun detach-extent extent
|
|
|
735 This function detaches @var{extent} from its buffer or string. If
|
|
|
736 @var{extent} has the @code{duplicable} property, its detachment is
|
|
|
737 tracked by the undo mechanism. @xref{Duplicable Extents}.
|
|
|
738 @end defun
|
|
|
739
|
|
|
740 @defun extent-detached-p extent
|
|
|
741 This function returns @code{nil} if @var{extent} is detached, and
|
|
|
742 @code{t} otherwise.
|
|
|
743 @end defun
|
|
|
744
|
|
|
745 @defun copy-extent extent &optional object
|
|
|
746 This function makes a copy of @var{extent}. It is initially detached.
|
|
|
747 Optional argument @var{object} defaults to @var{extent}'s object
|
|
|
748 (normally a buffer or string, but could be @code{nil}).
|
|
|
749 @end defun
|
|
|
750
|
|
|
751 @defun insert-extent extent &optional start end no-hooks object
|
|
|
752 This function inserts @var{extent} from @var{start} to @var{end} in
|
|
|
753 @var{object} (a buffer or string). If @var{extent} is detached from a
|
|
|
754 different buffer or string, or in most cases when @var{extent} is
|
|
|
755 already attached, the extent will first be copied as if with
|
|
|
756 @code{copy-extent}. This function operates the same as if @code{insert}
|
|
|
757 were called on a string whose extent data calls for @var{extent} to be
|
|
|
758 inserted, except that if @var{no-hooks} is non-@code{nil},
|
|
|
759 @var{extent}'s @code{paste-function} will not be invoked.
|
|
|
760 @xref{Duplicable Extents}.
|
|
|
761 @end defun
|
|
|
762
|
|
|
763 @node Extent Parents
|
|
|
764 @section Extent Parents
|
|
|
765 @cindex extent parent
|
|
|
766 @cindex extent children
|
|
|
767 @cindex parent, of extent
|
|
|
768 @cindex children, of extent
|
|
|
769
|
|
|
770 An extent can have a parent extent set for it. If this is the case,
|
|
|
771 the extent derives all its properties from that extent and has no
|
|
|
772 properties of its own. The only ``properties'' that the extent keeps
|
|
|
773 are the buffer or string it refers to and the start and end points.
|
|
|
774 (More correctly, the extent's own properties are shadowed. If you
|
|
|
775 later change the extent to have no parent, its own properties will
|
|
|
776 become visible again.)
|
|
|
777
|
|
|
778 It is possible for an extent's parent to itself have a parent,
|
|
|
779 and so on. Through this, a whole tree of extents can be created,
|
|
|
780 all deriving their properties from one root extent. Note, however,
|
|
|
781 that you cannot create an inheritance loop -- this is explicitly
|
|
|
782 disallowed.
|
|
|
783
|
|
96
|
784 Parent extents are used to implement the extents over the modeline.
|
|
0
|
785
|
|
|
786 @defun set-extent-parent extent parent
|
|
|
787 This function sets the parent of @var{extent} to @var{parent}.
|
|
|
788 If @var{parent} is @code{nil}, the extent is set to have no parent.
|
|
|
789 @end defun
|
|
|
790
|
|
|
791 @defun extent-parent extent
|
|
|
792 This function return the parents (if any) of @var{extent}, or
|
|
|
793 @code{nil}.
|
|
|
794 @end defun
|
|
|
795
|
|
|
796 @defun extent-children extent
|
|
|
797 This function returns a list of the children (if any) of @var{extent}.
|
|
|
798 The children of an extent are all those extents whose parent is that
|
|
|
799 extent. This function does not recursively trace children of children.
|
|
|
800 @end defun
|
|
|
801
|
|
|
802 @defun extent-descendants extent
|
|
|
803 This function returns a list of all descendants of @var{extent},
|
|
|
804 including @var{extent}. This recursively applies @code{extent-children}
|
|
|
805 to any children of @var{extent}, until no more children can be found.
|
|
|
806 @end defun
|
|
|
807
|
|
|
808 @node Duplicable Extents
|
|
|
809 @section Duplicable Extents
|
|
|
810 @cindex duplicable extent
|
|
|
811 @cindex unique extents
|
|
|
812 @cindex extent replica
|
|
|
813 @cindex extent, duplicable
|
|
|
814 @cindex extent, unique
|
|
|
815
|
|
|
816 If an extent has the @code{duplicable} property, it will be copied into
|
|
|
817 strings, so that kill, yank, and undo commands will restore or copy it.
|
|
|
818
|
|
|
819 Specifically:
|
|
|
820
|
|
|
821 @itemize @bullet
|
|
|
822 @item
|
|
|
823 When a string is created using @code{buffer-substring} or
|
|
|
824 @code{buffer-string}, any duplicable extents in the region corresponding
|
|
|
825 to the string will be copied into the string (@pxref{Buffer
|
|
|
826 Contents}). When the string in inserted into a buffer using
|
|
|
827 @code{insert}, @code{insert-before-markers}, @code{insert-buffer} or
|
|
|
828 @code{insert-buffer-substring}, the extents in the string will be copied
|
|
|
829 back into the buffer (@pxref{Insertion}). The extents in a string can,
|
|
|
830 of course, be retrieved explicitly using the standard extent primitives
|
|
|
831 over the string.
|
|
|
832
|
|
|
833 @item
|
|
|
834 Similarly, when text is copied or cut into the kill ring, any duplicable
|
|
|
835 extents will be remembered and reinserted later when the text is pasted
|
|
|
836 back into a buffer.
|
|
|
837
|
|
|
838 @item
|
|
|
839 When @code{concat} is called on strings, the extents in the strings are
|
|
96
|
840 copied into the resulting string.
|
|
0
|
841
|
|
|
842 @item
|
|
|
843 When @code{substring} is called on a string, the relevant extents
|
|
|
844 are copied into the resulting string.
|
|
|
845
|
|
|
846 @item
|
|
|
847 When a duplicable extent is detached by @code{detach-extent} or string
|
|
|
848 deletion, or inserted by @code{insert-extent} or string insertion, the
|
|
|
849 action is recorded by the undo mechanism so that it can be undone later.
|
|
|
850 Note that if an extent gets detached and then a later undo causes the
|
|
96
|
851 extent to get reinserted, the new extent will not be `eq' to the original
|
|
|
852 extent.
|
|
0
|
853
|
|
|
854 @item
|
|
|
855 Extent motion, face changes, and attachment via @code{make-extent} are
|
|
|
856 not recorded by the undo mechanism. This means that extent changes
|
|
|
857 which are to be undo-able must be performed by character editing, or by
|
|
|
858 insertion and detachment of duplicable extents.
|
|
|
859
|
|
|
860 @item
|
|
|
861 A duplicable extent's @code{copy-function} property, if non-@code{nil},
|
|
|
862 should be a function, and will be run when a duplicable extent is about
|
|
|
863 to be copied from a buffer to a string (or the kill ring). It is called
|
|
|
864 with three arguments: the extent and the buffer positions within it
|
|
|
865 which are being copied. If this function returns @code{nil}, then the
|
|
|
866 extent will not be copied; otherwise it will.
|
|
|
867
|
|
|
868 @item
|
|
|
869 A duplicable extent's @code{paste-function} property, if non-@code{nil},
|
|
|
870 should be a function, and will be run when a duplicable extent is about
|
|
|
871 to be copied from a string (or the kill ring) into a buffer. It is
|
|
|
872 called with three arguments: the original extent and the buffer
|
|
|
873 positions which the copied extent will occupy. (This hook is run after
|
|
|
874 the corresponding text has already been inserted into the buffer.) Note
|
|
|
875 that the extent argument may be detached when this function is run. If
|
|
|
876 this function returns @code{nil}, no extent will be inserted.
|
|
|
877 Otherwise, there will be an extent covering the range in question.
|
|
|
878
|
|
|
879 Note: if the extent to be copied is already attached to the buffer and
|
|
|
880 overlaps the new range, the extent will simply be extended and the
|
|
|
881 @code{paste-function} will not be called.
|
|
|
882 @end itemize
|
|
|
883
|
|
|
884 @node Extents and Events
|
|
|
885 @section Interaction of Extents with Keyboard and Mouse Events
|
|
|
886
|
|
|
887 If an extent has the @code{mouse-face} property set, it will be
|
|
|
888 highlighted when the mouse passes over it. Highlighting is accomplished
|
|
|
889 by merging the extent's face with the face or faces specified by the
|
|
|
890 @code{mouse-face} property. The effect is as if a pseudo-extent with
|
|
|
891 the @code{mouse-face} face were inserted after the extent in the display
|
|
|
892 order (@pxref{Extent Endpoints}, display order).
|
|
|
893
|
|
|
894 @defvar mouse-highlight-priority
|
|
|
895 This variable holds the priority to use when merging in the highlighting
|
|
|
896 pseudo-extent. The default is 1000. This is purposely set very high
|
|
|
897 so that the highlighting pseudo-extent shows up even if there are other
|
|
|
898 extents with various priorities at the same location.
|
|
|
899 @end defvar
|
|
|
900
|
|
|
901 You can also explicitly cause an extent to be highlighted. Only one
|
|
|
902 extent at a time can be highlighted in this fashion, and any other
|
|
|
903 highlighted extent will be de-highlighted.
|
|
|
904
|
|
|
905 @defun highlight-extent extent &optional highlight-p
|
|
|
906 This function highlights (if @var{highlight-p} is non-@code{nil}) or
|
|
|
907 de-highlights (if @var{highlight-p} is @code{nil}) @var{extent}, if
|
|
|
908 @var{extent} has the @code{mouse-face} property. (Nothing happens if
|
|
|
909 @var{extent} does not have the @code{mouse-face} property.)
|
|
|
910 @end defun
|
|
|
911
|
|
|
912 @defun force-highlight-extent extent &optional highlight-p
|
|
|
913 This function is similar to @code{highlight-extent} but highlights
|
|
|
914 or de-highlights the extent regardless of whether it has the
|
|
|
915 @code{mouse-face} property.
|
|
|
916 @end defun
|
|
|
917
|
|
|
918 If an extent has a @code{keymap} property, this keymap will be
|
|
|
919 consulted for mouse clicks on the extent and keypresses made while
|
|
|
920 @code{point} is within the extent. The behavior of mouse clicks and
|
|
|
921 keystrokes not defined in the keymap is as normal for the buffer.
|
|
|
922
|
|
|
923 @node Atomic Extents
|
|
|
924 @section Atomic Extents
|
|
|
925 @cindex atomic extent
|
|
|
926
|
|
|
927 If the Lisp file @file{atomic-extents} is loaded, then the atomic
|
|
|
928 extent facility is available. An @dfn{atomic extent} is an extent for
|
|
|
929 which @code{point} cannot be positioned anywhere within it. This
|
|
|
930 ensures that when selecting text, either all or none of the extent is
|
|
|
931 selected.
|
|
|
932
|
|
|
933 To make an extent atomic, set its @code{atomic} property.
|
