Mercurial > hg > xemacs-beta

comparison man/lispref/extents.texi @ 444:576fb035e263 r21-2-37

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r21-2-37
author cvs
date Mon, 13 Aug 2007 11:36:19 +0200
parents abe6d1db359e
children e7ef97881643
comparison
equal deleted inserted replaced
443:a8296e22da4e 444:576fb035e263
1 @c -*-texinfo-*- 1 @c -*-texinfo-*-
2 @c This is part of the XEmacs Lisp Reference Manual. 2 @c This is part of the XEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. 3 @c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
4 @c Copyright (C) 1996 Ben Wing. 4 @c Copyright (C) 1996 Ben Wing.
5 @c See the file lispref.texi for copying conditions. 5 @c See the file lispref.texi for copying conditions.
6 @setfilename ../../info/extents.info 6 @setfilename ../../info/extents.info
7 @node Extents, Specifiers, Abbrevs, top 7 @node Extents, Specifiers, Abbrevs, top
8 @chapter Extents 8 @chapter Extents
106 commands. @xref{Duplicable Extents}. 106 commands. @xref{Duplicable Extents}.
107 107
108 @node Creating and Modifying Extents 108 @node Creating and Modifying Extents
109 @section Creating and Modifying Extents 109 @section Creating and Modifying Extents
110 110
111 @defun make-extent from to &optional object 111 @defun make-extent from to &optional buffer-or-string
112 This function makes an extent for the range [@var{from}, @var{to}) in 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 113 @var{buffer-or-string} (a buffer or string). @var{buffer-or-string}
114 buffer. Insertions at point @var{to} will be outside of the extent; 114 defaults to the current buffer. Insertions at point @var{to} will be
115 insertions at @var{from} will be inside the extent, causing the extent 115 outside of the extent; insertions at @var{from} will be inside the
116 to grow (@pxref{Extent Endpoints}). This is the same way that markers 116 extent, causing the extent to grow (@pxref{Extent Endpoints}). This is
117 behave. The extent is initially detached if both @var{from} and 117 the same way that markers behave. The extent is initially detached if
118 @var{to} are @code{nil}, and in this case @var{object} defaults to 118 both @var{from} and @var{to} are @code{nil}, and in this case
119 @code{nil}, meaning the extent is in no buffer or string 119 @var{buffer-or-string} defaults to @code{nil}, meaning the extent is in
120 (@pxref{Detached Extents}). 120 no buffer or string (@pxref{Detached Extents}).
121 @end defun 121 @end defun
122 122
123 @defun delete-extent extent 123 @defun delete-extent extent
124 This function removes @var{extent} from its buffer and destroys it. 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. 125 This does not modify the buffer's text, only its display properties.
133 the return value is @code{nil}, this means that the extent is detached; 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 134 however, a detached extent will not necessarily return a value of
135 @code{nil}. 135 @code{nil}.
136 @end defun 136 @end defun
137 137
138 @defun extent-live-p extent 138 @defun extent-live-p object
139 This function returns @code{nil} if @var{extent} is deleted, and 139 This function returns @code{t} if @var{object} is an extent that has not
140 @code{t} otherwise. 140 been deleted, and @code{nil} otherwise.
141 @end defun 141 @end defun
142 142
143 @node Extent Endpoints 143 @node Extent Endpoints
144 @section Extent Endpoints 144 @section Extent Endpoints
145 @cindex extent endpoint 145 @cindex extent endpoint
229 primitives for mapping over the extents in a range of a buffer or string 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 230 are also provided (@pxref{Mapping Over Extents}). When reading through
231 this section, keep in mind the way that extents are ordered 231 this section, keep in mind the way that extents are ordered
232 (@pxref{Extent Endpoints}). 232 (@pxref{Extent Endpoints}).
233 233
234 @defun extent-list &optional buffer-or-string from to flags 234 @defun extent-list &optional buffer-or-string from to flags property value
235 This function returns a list of the extents in @var{buffer-or-string}. 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. 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 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 238 extents are returned; if omitted, all extents in the buffer or string
239 are returned. 239 are returned.
243 of the range) are included in the list. @var{from} and @var{to} default 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. 244 to the beginning and end of @var{buffer-or-string}, respectively.
245 245
246 @var{flags} controls how end cases are treated. For a discussion of 246 @var{flags} controls how end cases are treated. For a discussion of
247 this, and exactly what ``overlap'' means, see @code{map-extents}. 247 this, and exactly what ``overlap'' means, see @code{map-extents}.
248
249 The optional arguments @var{property} and @var{value} can be used to
250 further restrict which extents are returned. They have the same meaning
251 as for @code{map-extents}.
252
253 If you want to map a function over the extents in a buffer or string,
254 consider using @code{map-extents} or @code{mapcar-extents} instead.
255
256 See also the function @code{extents-at}.
248 @end defun 257 @end defun
249 258
250 Functions that create extents must be prepared for the possibility 259 Functions that create extents must be prepared for the possibility
251 that there are other extents in the same area, created by other 260 that there are other extents in the same area, created by other
252 functions. To deal with this, functions typically mark their own 261 functions. To deal with this, functions typically mark their own
253 extents by setting a particular property on them. The following 262 extents by setting a particular property on them. The following
254 function makes it easier to locate those extents. 263 function makes it easier to locate those extents.
255 264
256 @defun extent-at pos &optional object property before at-flag 265 @defun extent-at pos &optional object property before at-flag
324 @var{flags} argument (see below for a complete discussion). 333 @var{flags} argument (see below for a complete discussion).
325 334
326 @var{function} is called with the arguments (extent, @var{maparg}). 335 @var{function} is called with the arguments (extent, @var{maparg}).
327 The arguments @var{object}, @var{from}, @var{to}, @var{maparg}, and 336 The arguments @var{object}, @var{from}, @var{to}, @var{maparg}, and
328 @var{flags} are all optional and default to the current buffer, the 337 @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 338 beginning of @var{object}, the end of @var{object}, @code{nil}, and
330 @var{nil}, respectively. @code{map-extents} returns the first 339 @code{nil}, respectively. @code{map-extents} returns the first
331 non-@code{nil} result produced by @var{function}, and no more calls to 340 non-@code{nil} result produced by @var{function}, and no more calls to
332 @var{function} are made after it returns non-@code{nil}. 341 @var{function} are made after it returns non-@code{nil}.
333 342
334 If @var{object} is an extent, @var{from} and @var{to} default to the 343 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 344 extent's endpoints, and the mapping omits that extent and its
434 (map-extent-children 'walk-extents buffer)) 443 (map-extent-children 'walk-extents buffer))
435 @end example 444 @end example
436 @end defun 445 @end defun
437 446
438 @defun extent-in-region-p extent &optional from to flags 447 @defun extent-in-region-p extent &optional from to flags
439 This function returns @var{t} if @code{map-extents} would visit 448 This function returns @code{t} if @code{map-extents} would visit
440 @var{extent} if called with the given arguments. 449 @var{extent} if called with the given arguments.
441 @end defun 450 @end defun
442 451
443 @node Extent Properties 452 @node Extent Properties
444 @section Properties of Extents 453 @section Properties of Extents
461 If an extent has a parent, all of its properties actually derive 470 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 471 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 472 has a parent), and setting a property of the extent actually sets
464 that property on the parent. @xref{Extent Parents}. 473 that property on the parent. @xref{Extent Parents}.
465 474
466 @defun extent-property extent property 475 @defun extent-property extent property &optional default
467 This function returns the value of @var{property} in @var{extent}. If 476 This function returns @var{extent}'s value for @var{property}, or
468 @var{property} is undefined, @code{nil} is returned. 477 @var{default} if no such property exists.
469 @end defun 478 @end defun
470 479
471 @defun extent-properties extent 480 @defun extent-properties extent
472 This function returns a list of all of @var{extent}'s properties that do 481 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 482 not have the value of @code{nil} (or the default value, for properties
667 @end defun 676 @end defun
668 677
669 The following convenience functions are provided for setting particular 678 The following convenience functions are provided for setting particular
670 properties of an extent. 679 properties of an extent.
671 680
672 @defun set-extent-priority extent pri 681 @defun set-extent-priority extent priority
673 This function sets the @code{priority} property of @var{extent} to 682 This function sets the @code{priority} property of @var{extent} to
674 @var{pri}. 683 @var{priority}.
675 @end defun 684 @end defun
676 685
677 @defun set-extent-face extent face 686 @defun set-extent-face extent face
678 This function sets the @code{face} property of @var{extent} to 687 This function sets the @code{face} property of @var{extent} to
679 @var{face}. 688 @var{face}.
711 properties of @var{extent} to @var{end-glyph} and @var{layout}, 720 properties of @var{extent} to @var{end-glyph} and @var{layout},
712 respectively. (@var{layout} defaults to @code{text} if not specified.) 721 respectively. (@var{layout} defaults to @code{text} if not specified.)
713 @end defun 722 @end defun
714 723
715 @defun set-extent-initial-redisplay-function extent function 724 @defun set-extent-initial-redisplay-function extent function
716 This function sets the @code{initial-redisplay-function} property of the 725 This function sets the @code{initial-redisplay-function} property of the
717 extent to @var{function}. 726 extent to @var{function}.
718 @end defun 727 @end defun
719 728
720 @node Detached Extents 729 @node Detached Extents
721 @section Detached Extents 730 @section Detached Extents