Mercurial > hg > xemacs-beta
annotate man/lispref/markers.texi @ 5940:c608d4b0b75e cygwin64 tip
rescue lost branch from 64bit.backup
| author | Henry Thompson <ht@markup.co.uk> |
|---|---|
| date | Thu, 16 Dec 2021 18:48:58 +0000 |
| parents | 9fae6227ede5 |
| children |
| rev | line source |
|---|---|
| 428 | 1 @c -*-texinfo-*- |
| 2 @c This is part of the XEmacs Lisp Reference Manual. | |
| 444 | 3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. |
| 428 | 4 @c See the file lispref.texi for copying conditions. |
| 5 @setfilename ../../info/markers.info | |
| 6 @node Markers, Text, Positions, Top | |
| 7 @chapter Markers | |
| 8 @cindex markers | |
| 9 | |
| 10 A @dfn{marker} is a Lisp object used to specify a position in a buffer | |
| 11 relative to the surrounding text. A marker changes its offset from the | |
| 12 beginning of the buffer automatically whenever text is inserted or | |
| 13 deleted, so that it stays with the two characters on either side of it. | |
| 14 | |
| 15 @menu | |
| 16 * Overview of Markers:: The components of a marker, and how it relocates. | |
| 17 * Predicates on Markers:: Testing whether an object is a marker. | |
| 18 * Creating Markers:: Making empty markers or markers at certain places. | |
| 19 * Information from Markers:: Finding the marker's buffer or character position. | |
| 20 * Changing Markers:: Moving the marker to a new buffer or position. | |
| 21 * The Mark:: How ``the mark'' is implemented with a marker. | |
| 22 * The Region:: How to access ``the region''. | |
| 23 @end menu | |
| 24 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
1738
diff
changeset
|
25 @node Overview of Markers, Predicates on Markers, Markers, Markers |
| 428 | 26 @section Overview of Markers |
| 27 | |
| 28 A marker specifies a buffer and a position in that buffer. The marker | |
| 29 can be used to represent a position in the functions that require one, | |
| 30 just as an integer could be used. @xref{Positions}, for a complete | |
| 31 description of positions. | |
| 32 | |
| 33 A marker has two attributes: the marker position, and the marker | |
| 34 buffer. The marker position is an integer that is equivalent (at a | |
| 35 given time) to the marker as a position in that buffer. But the | |
| 36 marker's position value can change often during the life of the marker. | |
| 37 Insertion and deletion of text in the buffer relocate the marker. The | |
| 38 idea is that a marker positioned between two characters remains between | |
| 39 those two characters despite insertion and deletion elsewhere in the | |
| 40 buffer. Relocation changes the integer equivalent of the marker. | |
| 41 | |
| 42 @cindex marker relocation | |
| 43 Deleting text around a marker's position leaves the marker between the | |
| 44 characters immediately before and after the deleted text. Inserting | |
| 45 text at the position of a marker normally leaves the marker in front of | |
| 46 the new text---unless it is inserted with @code{insert-before-markers} | |
| 47 (@pxref{Insertion}). | |
| 48 | |
| 49 @cindex marker garbage collection | |
| 50 Insertion and deletion in a buffer must check all the markers and | |
| 51 relocate them if necessary. This slows processing in a buffer with a | |
| 52 large number of markers. For this reason, it is a good idea to make a | |
| 53 marker point nowhere if you are sure you don't need it any more. | |
| 54 Unreferenced markers are garbage collected eventually, but until then | |
| 55 will continue to use time if they do point somewhere. | |
| 56 | |
| 57 @cindex markers as numbers | |
| 58 Because it is common to perform arithmetic operations on a marker | |
| 59 position, most of the arithmetic operations (including @code{+} and | |
| 60 @code{-}) accept markers as arguments. In such cases, the marker | |
| 61 stands for its current position. | |
| 62 | |
| 63 @cindex markers vs. extents | |
| 64 Note that you can use extents to achieve the same functionality, and | |
| 65 more, as markers. (Markers were defined before extents, which is why | |
| 66 they both continue to exist.) A zero-length extent with the | |
| 67 @code{detachable} property removed is almost identical to a marker. | |
| 68 (@xref{Extent Endpoints}, for more information on zero-length extents.) | |
| 69 | |
| 70 In particular: | |
| 71 | |
| 72 @itemize @bullet | |
| 73 @item | |
| 74 In order to get marker-like behavior in a zero-length extent, the | |
| 75 @code{detachable} property must be removed (otherwise, the extent | |
| 76 will disappear when text near it is deleted) and exactly one | |
| 77 endpoint must be closed (if both endpoints are closed, the extent | |
| 78 will expand to contain text inserted where it is located). | |
| 79 @item | |
| 80 If a zero-length extent has the @code{end-open} property but not | |
| 81 the @code{start-open} property (this is the default), text inserted | |
| 82 at the extent's location causes the extent to move forward, just | |
| 83 like a marker. | |
| 84 @item | |
| 85 If a zero-length extent has the @code{start-open} property but not | |
| 86 the @code{end-open} property, text inserted at the extent's location | |
| 87 causes the extent to remain before the text, like what happens to | |
| 88 markers when @code{insert-before-markers} is used. | |
| 89 @item | |
| 90 Markers end up after or before inserted text depending on whether | |
| 91 @code{insert} or @code{insert-before-markers} was called. These | |
| 92 functions do not affect zero-length extents differently; instead, | |
| 93 the presence or absence of the @code{start-open} and @code{end-open} | |
| 94 extent properties determines this, as just described. | |
| 95 @item | |
| 96 Markers are automatically removed from a buffer when they are no | |
| 97 longer in use. Extents remain around until explicitly removed | |
| 98 from a buffer. | |
| 99 @item | |
| 100 Many functions are provided for listing the extents in a buffer or | |
| 101 in a region of a buffer. No such functions exist for markers. | |
| 102 @end itemize | |
| 103 | |
| 104 Here are examples of creating markers, setting markers, and moving point | |
| 105 to markers: | |
| 106 | |
| 107 @example | |
| 108 @group | |
| 109 ;; @r{Make a new marker that initially does not point anywhere:} | |
| 110 (setq m1 (make-marker)) | |
| 111 @result{} #<marker in no buffer> | |
| 112 @end group | |
| 113 | |
| 114 @group | |
| 115 ;; @r{Set @code{m1} to point between the 99th and 100th characters} | |
| 116 ;; @r{in the current buffer:} | |
| 117 (set-marker m1 100) | |
| 118 @result{} #<marker at 100 in markers.texi> | |
| 119 @end group | |
| 120 | |
| 121 @group | |
| 122 ;; @r{Now insert one character at the beginning of the buffer:} | |
| 123 (goto-char (point-min)) | |
| 124 @result{} 1 | |
| 125 (insert "Q") | |
| 126 @result{} nil | |
| 127 @end group | |
| 128 | |
| 129 @group | |
| 130 ;; @r{@code{m1} is updated appropriately.} | |
| 131 m1 | |
| 132 @result{} #<marker at 101 in markers.texi> | |
| 133 @end group | |
| 134 | |
| 135 @group | |
| 136 ;; @r{Two markers that point to the same position} | |
| 137 ;; @r{are not @code{eq}, but they are @code{equal}.} | |
| 138 (setq m2 (copy-marker m1)) | |
| 139 @result{} #<marker at 101 in markers.texi> | |
| 140 (eq m1 m2) | |
| 141 @result{} nil | |
| 142 (equal m1 m2) | |
| 143 @result{} t | |
| 144 @end group | |
| 145 | |
| 146 @group | |
| 147 ;; @r{When you are finished using a marker, make it point nowhere.} | |
| 148 (set-marker m1 nil) | |
| 149 @result{} #<marker in no buffer> | |
| 150 @end group | |
| 151 @end example | |
| 152 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
1738
diff
changeset
|
153 @node Predicates on Markers, Creating Markers, Overview of Markers, Markers |
| 428 | 154 @section Predicates on Markers |
| 155 | |
| 156 You can test an object to see whether it is a marker, or whether it is | |
| 157 either an integer or a marker or either an integer, a character, or a | |
| 158 marker. The latter tests are useful in connection with the arithmetic | |
| 159 functions that work with any of markers, integers, or characters. | |
| 160 | |
| 161 @defun markerp object | |
| 162 This function returns @code{t} if @var{object} is a marker, @code{nil} | |
| 163 otherwise. Note that integers are not markers, even though many | |
| 164 functions will accept either a marker or an integer. | |
| 165 @end defun | |
| 166 | |
| 167 @defun integer-or-marker-p object | |
| 168 This function returns @code{t} if @var{object} is an integer or a marker, | |
| 169 @code{nil} otherwise. | |
| 170 @end defun | |
| 171 | |
| 172 @defun integer-char-or-marker-p object | |
| 173 This function returns @code{t} if @var{object} is an integer, a | |
| 174 character, or a marker, @code{nil} otherwise. | |
| 175 @end defun | |
| 176 | |
| 177 @defun number-or-marker-p object | |
| 178 This function returns @code{t} if @var{object} is a number (either kind) | |
| 179 or a marker, @code{nil} otherwise. | |
| 180 @end defun | |
| 181 | |
| 182 @defun number-char-or-marker-p object | |
| 183 This function returns @code{t} if @var{object} is a number (either | |
| 184 kind), a character, or a marker, @code{nil} otherwise. | |
| 185 @end defun | |
| 186 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
1738
diff
changeset
|
187 @node Creating Markers, Information from Markers, Predicates on Markers, Markers |
| 428 | 188 @section Functions That Create Markers |
| 189 | |
| 190 When you create a new marker, you can make it point nowhere, or point | |
| 191 to the present position of point, or to the beginning or end of the | |
| 192 accessible portion of the buffer, or to the same place as another given | |
| 193 marker. | |
| 194 | |
| 195 @defun make-marker | |
| 196 This functions returns a newly created marker that does not point | |
| 197 anywhere. | |
| 198 | |
| 199 @example | |
| 200 @group | |
| 201 (make-marker) | |
| 202 @result{} #<marker in no buffer> | |
| 203 @end group | |
| 204 @end example | |
| 205 @end defun | |
| 206 | |
| 207 @defun point-marker &optional dont-copy-p buffer | |
| 208 This function returns a marker that points to the present position of | |
| 209 point in @var{buffer}, which defaults to the current buffer. | |
| 210 @xref{Point}. For an example, see @code{copy-marker}, below. | |
| 211 | |
| 212 Internally, a marker corresponding to point is always maintained. | |
| 213 Normally the marker returned by @code{point-marker} is a copy; you | |
| 214 may modify it with reckless abandon. However, if optional argument | |
| 215 @var{dont-copy-p} is non-@code{nil}, then the real point-marker is | |
| 216 returned; modifying the position of this marker will move point. | |
| 217 It is illegal to change the buffer of it, or make it point nowhere. | |
| 218 @end defun | |
| 219 | |
| 220 @defun point-min-marker &optional buffer | |
| 221 This function returns a new marker that points to the beginning of the | |
| 222 accessible portion of @var{buffer}, which defaults to the current | |
| 223 buffer. This will be the beginning of the buffer unless narrowing is in | |
| 224 effect. @xref{Narrowing}. | |
| 225 @end defun | |
| 226 | |
| 227 @defun point-max-marker &optional buffer | |
| 228 @cindex end of buffer marker | |
| 229 This function returns a new marker that points to the end of the | |
| 230 accessible portion of @var{buffer}, which defaults to the current | |
| 231 buffer. This will be the end of the buffer unless narrowing is in | |
| 232 effect. @xref{Narrowing}. | |
| 233 | |
| 234 Here are examples of this function and @code{point-min-marker}, shown in | |
| 235 a buffer containing a version of the source file for the text of this | |
| 236 chapter. | |
| 237 | |
| 238 @example | |
| 239 @group | |
| 240 (point-min-marker) | |
| 241 @result{} #<marker at 1 in markers.texi> | |
| 242 (point-max-marker) | |
| 243 @result{} #<marker at 15573 in markers.texi> | |
| 244 @end group | |
| 245 | |
| 246 @group | |
| 247 (narrow-to-region 100 200) | |
| 248 @result{} nil | |
| 249 @end group | |
| 250 @group | |
| 251 (point-min-marker) | |
| 252 @result{} #<marker at 100 in markers.texi> | |
| 253 @end group | |
| 254 @group | |
| 255 (point-max-marker) | |
| 256 @result{} #<marker at 200 in markers.texi> | |
| 257 @end group | |
| 258 @end example | |
| 259 @end defun | |
| 260 | |
| 444 | 261 @defun copy-marker marker-or-integer &optional marker-type |
| 428 | 262 If passed a marker as its argument, @code{copy-marker} returns a |
| 263 new marker that points to the same place and the same buffer as does | |
| 264 @var{marker-or-integer}. If passed an integer as its argument, | |
| 265 @code{copy-marker} returns a new marker that points to position | |
| 266 @var{marker-or-integer} in the current buffer. | |
| 267 | |
| 268 If passed an integer argument less than 1, @code{copy-marker} returns a | |
| 269 new marker that points to the beginning of the current buffer. If | |
| 270 passed an integer argument greater than the length of the buffer, | |
| 271 @code{copy-marker} returns a new marker that points to the end of the | |
| 272 buffer. | |
| 273 | |
| 444 | 274 An error is signaled if @var{marker-or-integer} is neither a marker nor |
| 275 an integer. | |
| 276 | |
| 277 Optional second argument @var{marker-type} specifies the insertion type | |
| 278 of the new marker; see @code{marker-insertion-type}. | |
| 428 | 279 |
| 280 @example | |
| 281 @group | |
| 282 (setq p (point-marker)) | |
| 283 @result{} #<marker at 2139 in markers.texi> | |
| 284 @end group | |
| 285 | |
| 286 @group | |
| 287 (setq q (copy-marker p)) | |
| 288 @result{} #<marker at 2139 in markers.texi> | |
| 289 @end group | |
| 290 | |
| 291 @group | |
| 292 (eq p q) | |
| 293 @result{} nil | |
| 294 @end group | |
| 295 | |
| 296 @group | |
| 297 (equal p q) | |
| 298 @result{} t | |
| 299 @end group | |
| 300 | |
| 301 @group | |
| 302 (point) | |
| 303 @result{} 2139 | |
| 304 @end group | |
| 305 | |
| 306 @group | |
| 307 (set-marker p 3000) | |
| 308 @result{} #<marker at 3000 in markers.texi> | |
| 309 @end group | |
| 310 | |
| 311 @group | |
| 312 (point) | |
| 313 @result{} 2139 | |
| 314 @end group | |
| 315 | |
| 316 @group | |
| 317 (setq p (point-marker t)) | |
| 318 @result{} #<marker at 2139 in markers.texi> | |
| 319 @end group | |
| 320 | |
| 321 @group | |
| 322 (set-marker p 3000) | |
| 323 @result{} #<marker at 3000 in markers.texi> | |
| 324 @end group | |
| 325 | |
| 326 @group | |
| 327 (point) | |
| 328 @result{} 3000 | |
| 329 @end group | |
| 330 | |
| 331 @group | |
| 332 (copy-marker 0) | |
| 333 @result{} #<marker at 1 in markers.texi> | |
| 334 @end group | |
| 335 | |
| 336 @group | |
| 337 (copy-marker 20000) | |
| 338 @result{} #<marker at 7572 in markers.texi> | |
| 339 @end group | |
| 340 @end example | |
| 341 @end defun | |
| 342 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
1738
diff
changeset
|
343 @node Information from Markers, Changing Markers, Creating Markers, Markers |
| 428 | 344 @section Information from Markers |
| 345 | |
| 346 This section describes the functions for accessing the components of a | |
| 347 marker object. | |
| 348 | |
| 349 @defun marker-position marker | |
| 350 This function returns the position that @var{marker} points to, or | |
| 351 @code{nil} if it points nowhere. | |
| 352 @end defun | |
| 353 | |
| 354 @defun marker-buffer marker | |
| 355 This function returns the buffer that @var{marker} points into, or | |
| 356 @code{nil} if it points nowhere. | |
| 357 | |
| 358 @example | |
| 359 @group | |
| 360 (setq m (make-marker)) | |
| 361 @result{} #<marker in no buffer> | |
| 362 @end group | |
| 363 @group | |
| 364 (marker-position m) | |
| 365 @result{} nil | |
| 366 @end group | |
| 367 @group | |
| 368 (marker-buffer m) | |
| 369 @result{} nil | |
| 370 @end group | |
| 371 | |
| 372 @group | |
| 373 (set-marker m 3770 (current-buffer)) | |
| 374 @result{} #<marker at 3770 in markers.texi> | |
| 375 @end group | |
| 376 @group | |
| 377 (marker-buffer m) | |
| 378 @result{} #<buffer markers.texi> | |
| 379 @end group | |
| 380 @group | |
| 381 (marker-position m) | |
| 382 @result{} 3770 | |
| 383 @end group | |
| 384 @end example | |
| 385 @end defun | |
| 386 | |
| 387 Two distinct markers are considered @code{equal} (even though not | |
| 388 @code{eq}) to each other if they have the same position and buffer, or | |
| 389 if they both point nowhere. | |
| 390 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
1738
diff
changeset
|
391 @node Changing Markers, The Mark, Information from Markers, Markers |
| 428 | 392 @section Changing Marker Positions |
| 393 | |
| 394 This section describes how to change the position of an existing | |
| 395 marker. When you do this, be sure you know whether the marker is used | |
| 396 outside of your program, and, if so, what effects will result from | |
| 397 moving it---otherwise, confusing things may happen in other parts of | |
| 398 Emacs. | |
| 399 | |
| 400 @defun set-marker marker position &optional buffer | |
| 401 This function moves @var{marker} to @var{position} | |
| 402 in @var{buffer}. If @var{buffer} is not provided, it defaults to | |
| 403 the current buffer. | |
| 404 | |
| 444 | 405 @var{position} can be a marker, an integer or @code{nil}. If |
| 406 @var{position} is an integer, @code{set-marker} moves @var{marker} to | |
| 407 point before the @var{position}th character in @var{buffer}. If | |
| 408 @var{position} is @code{nil}, @var{marker} is made to point nowhere. | |
| 409 Then it no longer slows down editing in any buffer. If @var{position} | |
| 410 is less than 1, @var{marker} is moved to the beginning of @var{buffer}. | |
| 411 If @var{position} is greater than the size of @var{buffer}, @var{marker} | |
| 412 is moved to the end of @var{buffer}. | |
| 428 | 413 |
| 414 The value returned is @var{marker}. | |
| 415 | |
| 416 @example | |
| 417 @group | |
| 418 (setq m (point-marker)) | |
| 419 @result{} #<marker at 4714 in markers.texi> | |
| 420 @end group | |
| 421 @group | |
| 422 (set-marker m 55) | |
| 423 @result{} #<marker at 55 in markers.texi> | |
| 424 @end group | |
| 425 @group | |
| 426 (setq b (get-buffer "foo")) | |
| 427 @result{} #<buffer foo> | |
| 428 @end group | |
| 429 @group | |
| 430 (set-marker m 0 b) | |
| 431 @result{} #<marker at 1 in foo> | |
| 432 @end group | |
| 433 @end example | |
| 434 @end defun | |
| 435 | |
| 436 @defun move-marker marker position &optional buffer | |
| 437 This is another name for @code{set-marker}. | |
| 438 @end defun | |
| 439 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
1738
diff
changeset
|
440 @node The Mark, The Region, Changing Markers, Markers |
| 428 | 441 @section The Mark |
| 442 @cindex mark, the | |
| 443 @cindex mark ring | |
| 444 @cindex global mark ring | |
| 445 | |
| 446 One special marker in each buffer is designated @dfn{the mark}. It | |
| 447 records a position for the user for the sake of commands such as | |
| 448 @kbd{C-w} and @kbd{C-x @key{TAB}}. Lisp programs should set the mark | |
| 449 only to values that have a potential use to the user, and never for | |
| 450 their own internal purposes. For example, the @code{replace-regexp} | |
| 451 command sets the mark to the value of point before doing any | |
| 452 replacements, because this enables the user to move back there | |
| 453 conveniently after the replace is finished. | |
| 454 | |
| 455 Once the mark ``exists'' in a buffer, it normally never ceases to | |
| 456 exist. However, it may become @dfn{inactive}, and usually does so | |
| 457 after each command (other than simple motion commands and some | |
| 458 commands that explicitly activate the mark). When the mark is active, | |
| 459 the region between point and the mark is called the @dfn{active region} | |
| 460 and is highlighted specially. | |
| 461 | |
| 462 Many commands are designed so that when called interactively they | |
| 463 operate on the text between point and the mark. Such commands work | |
| 464 only when an active region exists, i.e. when the mark is active. | |
| 465 (The reason for this is to prevent you from accidentally deleting | |
| 466 or changing large chunks of your text.) If you are writing such | |
| 467 a command, don't examine the mark directly; instead, use | |
| 468 @code{interactive} with the @samp{r} specification. This provides the | |
| 469 values of point and the mark as arguments to the command in an | |
| 470 interactive call, but permits other Lisp programs to specify arguments | |
| 471 explicitly, and automatically signals an error if the command is called | |
| 472 interactively when no active region exists. @xref{Interactive Codes}. | |
| 473 | |
| 474 Each buffer has its own value of the mark that is independent of the | |
| 475 value of the mark in other buffers. (When a buffer is created, the mark | |
| 476 exists but does not point anywhere. We consider this state as ``the | |
| 477 absence of a mark in that buffer.'') However, only one active region can | |
| 478 exist at a time. Activating the mark in one buffer automatically | |
| 479 deactivates an active mark in any other buffer. Note that the user can | |
| 480 explicitly activate a mark at any time by using the command | |
| 481 @code{activate-region} (normally bound to @kbd{M-C-z}) or by using the | |
| 482 command @code{exchange-point-and-mark} (normally bound to @kbd{C-x C-x}), | |
| 483 which has the side effect of activating the mark. | |
| 484 | |
| 485 Some people do not like active regions, so they disable this behavior | |
| 486 by setting the variable @code{zmacs-regions} to @code{nil}. This makes | |
| 487 the mark always active (except when a buffer is just created and the | |
| 488 mark points nowhere), and turns off the highlighting of the region | |
| 489 between point and the mark. Commands that explicitly retrieve the value | |
| 490 of the mark should make sure that they behave correctly and consistently | |
| 491 irrespective of the setting of @code{zmacs-regions}; some primitives are | |
| 492 provided to ensure this behavior. | |
| 493 | |
| 494 In addition to the mark, each buffer has a @dfn{mark ring} which is a | |
| 495 list of markers containing previous values of the mark. When editing | |
| 496 commands change the mark, they should normally save the old value of the | |
| 497 mark on the mark ring. The variable @code{mark-ring-max} specifies the | |
| 498 maximum number of entries in the mark ring; once the list becomes this | |
| 499 long, adding a new element deletes the last element. | |
| 500 | |
| 501 @defun mark &optional force buffer | |
| 502 @cindex current buffer mark | |
| 503 This function returns @var{buffer}'s mark position as an integer. | |
| 504 @var{buffer} defaults to the current buffer if omitted. | |
| 505 | |
| 506 If the mark is inactive, @code{mark} normally returns @code{nil}. | |
| 507 However, if @var{force} is non-@code{nil}, then @code{mark} returns the | |
| 508 mark position anyway---or @code{nil}, if the mark is not yet set for | |
| 509 the buffer. | |
| 510 | |
| 1738 | 511 (Remember that if @code{zmacs-regions} is @code{nil}, the mark is |
| 428 | 512 always active as long as it exists, and the @var{force} argument |
| 513 will have no effect.) | |
| 514 | |
| 515 If you are using this in an editing command, you are most likely making | |
| 516 a mistake; see the documentation of @code{set-mark} below. | |
| 517 @end defun | |
| 518 | |
| 444 | 519 @defun mark-marker &optional force buffer |
| 428 | 520 This function returns @var{buffer}'s mark. @var{buffer} defaults to the |
| 521 current buffer if omitted. This is the very marker that records the | |
| 522 mark location inside XEmacs, not a copy. Therefore, changing this | |
| 523 marker's position will directly affect the position of the mark. Don't | |
| 524 do it unless that is the effect you want. | |
| 525 | |
| 526 If the mark is inactive, @code{mark-marker} normally returns @code{nil}. | |
| 527 However, if @var{force} is non-@code{nil}, then @code{mark-marker} | |
| 528 returns the mark anyway. | |
| 529 @example | |
| 530 @group | |
| 531 (setq m (mark-marker)) | |
| 532 @result{} #<marker at 3420 in markers.texi> | |
| 533 @end group | |
| 534 @group | |
| 535 (set-marker m 100) | |
| 536 @result{} #<marker at 100 in markers.texi> | |
| 537 @end group | |
| 538 @group | |
| 539 (mark-marker) | |
| 540 @result{} #<marker at 100 in markers.texi> | |
| 541 @end group | |
| 542 @end example | |
| 543 | |
| 544 Like any marker, this marker can be set to point at any buffer you like. | |
| 545 We don't recommend that you make it point at any buffer other than the | |
| 546 one of which it is the mark. If you do, it will yield perfectly | |
| 547 consistent, but rather odd, results. | |
| 548 @end defun | |
| 549 | |
| 550 @ignore | |
| 551 @deffn Command set-mark-command jump | |
| 552 If @var{jump} is @code{nil}, this command sets the mark to the value | |
| 553 of point and pushes the previous value of the mark on the mark ring. The | |
| 554 message @samp{Mark set} is also displayed in the echo area. | |
| 555 | |
| 556 If @var{jump} is not @code{nil}, this command sets point to the value | |
| 557 of the mark, and sets the mark to the previous saved mark value, which | |
| 558 is popped off the mark ring. | |
| 559 | |
| 560 This function is @emph{only} intended for interactive use. | |
| 561 @end deffn | |
| 562 @end ignore | |
| 563 | |
| 564 @defun set-mark position &optional buffer | |
| 565 This function sets @code{buffer}'s mark to @var{position}, and activates | |
| 566 the mark. @var{buffer} defaults to the current buffer if omitted. The | |
| 567 old value of the mark is @emph{not} pushed onto the mark ring. | |
| 568 | |
| 569 @strong{Please note:} Use this function only if you want the user to | |
| 570 see that the mark has moved, and you want the previous mark position to | |
| 571 be lost. Normally, when a new mark is set, the old one should go on the | |
| 572 @code{mark-ring}. For this reason, most applications should use | |
| 573 @code{push-mark} and @code{pop-mark}, not @code{set-mark}. | |
| 574 | |
| 575 Novice XEmacs Lisp programmers often try to use the mark for the wrong | |
| 576 purposes. The mark saves a location for the user's convenience. An | |
| 577 editing command should not alter the mark unless altering the mark is | |
| 578 part of the user-level functionality of the command. (And, in that | |
| 579 case, this effect should be documented.) To remember a location for | |
| 580 internal use in the Lisp program, store it in a Lisp variable. For | |
| 581 example: | |
| 582 | |
| 583 @example | |
| 584 @group | |
| 444 | 585 (let ((start (point))) |
| 428 | 586 (forward-line 1) |
| 444 | 587 (delete-region start (point))). |
| 428 | 588 @end group |
| 589 @end example | |
| 590 @end defun | |
| 591 | |
| 592 @deffn Command exchange-point-and-mark &optional dont-activate-region | |
| 593 This function exchanges the positions of point and the mark. | |
| 594 It is intended for interactive use. The mark is also activated | |
| 595 unless @var{dont-activate-region} is non-@code{nil}. | |
| 596 @end deffn | |
| 597 | |
| 598 @defun push-mark &optional position nomsg activate buffer | |
| 599 This function sets @var{buffer}'s mark to @var{position}, and pushes a | |
| 600 copy of the previous mark onto @code{mark-ring}. @var{buffer} defaults | |
| 601 to the current buffer if omitted. If @var{position} is @code{nil}, then | |
| 602 the value of point is used. @code{push-mark} returns @code{nil}. | |
| 603 | |
| 604 If the last global mark pushed was not in @var{buffer}, also push | |
| 605 @var{position} on the global mark ring (see below). | |
| 606 | |
| 607 The function @code{push-mark} normally @emph{does not} activate the | |
| 608 mark. To do that, specify @code{t} for the argument @var{activate}. | |
| 609 | |
| 610 A @samp{Mark set} message is displayed unless @var{nomsg} is | |
| 611 non-@code{nil}. | |
| 612 @end defun | |
| 613 | |
| 614 @defun pop-mark | |
| 615 This function pops off the top element of @code{mark-ring} and makes | |
| 616 that mark become the buffer's actual mark. This does not move point in | |
| 617 the buffer, and it does nothing if @code{mark-ring} is empty. It | |
| 618 deactivates the mark. | |
| 619 | |
| 620 The return value is not meaningful. | |
| 621 @end defun | |
| 622 | |
| 623 @defvar mark-ring | |
| 624 The value of this buffer-local variable is the list of saved former | |
| 625 marks of the current buffer, most recent first. | |
| 626 | |
| 627 @example | |
| 628 @group | |
| 629 mark-ring | |
| 444 | 630 @result{} (#<marker at 11050 in markers.texi> |
| 428 | 631 #<marker at 10832 in markers.texi> |
| 632 @dots{}) | |
| 633 @end group | |
| 634 @end example | |
| 635 @end defvar | |
| 636 | |
| 637 @defopt mark-ring-max | |
| 638 The value of this variable is the maximum size of @code{mark-ring}. If | |
| 639 more marks than this are pushed onto the @code{mark-ring}, | |
| 640 @code{push-mark} discards an old mark when it adds a new one. | |
| 641 @end defopt | |
| 642 | |
| 643 In additional to a per-buffer mark ring, there is a @dfn{global mark | |
| 644 ring}. Marks are pushed onto the global mark ring the first time you | |
| 645 set a mark after switching buffers. | |
| 646 | |
| 647 @defvar global-mark-ring | |
| 648 The value of this variable is the list of saved former global marks, | |
| 649 most recent first. | |
| 650 @end defvar | |
| 651 | |
| 652 @defopt mark-ring-max | |
| 653 The value of this variable is the maximum size of | |
| 654 @code{global-mark-ring}. If more marks than this are pushed onto the | |
| 655 @code{global-mark-ring}, @code{push-mark} discards an old mark when it | |
| 656 adds a new one. | |
| 657 @end defopt | |
| 658 | |
| 659 @deffn Command pop-global-mark | |
| 660 This function pops a mark off the global mark ring and jumps to that | |
| 661 location. | |
| 662 @end deffn | |
| 663 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
1738
diff
changeset
|
664 @node The Region, , The Mark, Markers |
| 428 | 665 @section The Region |
| 666 @cindex region, the | |
| 667 | |
| 668 The text between point and the mark is known as @dfn{the region}. | |
| 669 Various functions operate on text delimited by point and the mark, but | |
| 670 only those functions specifically related to the region itself are | |
| 671 described here. | |
| 672 | |
| 673 When @code{zmacs-regions} is non-@code{nil} (this is the default), the | |
| 674 concept of an @dfn{active region} exists. The region is active when the | |
| 675 corresponding mark is active. Note that only one active region at a | |
| 440 | 676 time can exist---i.e. only one buffer's region is active at a time. |
| 428 | 677 @xref{The Mark}, for more information about active regions. |
| 678 | |
| 679 @defopt zmacs-regions | |
| 680 If non-@code{nil} (the default), active regions are used. @xref{The Mark}, | |
| 681 for a detailed explanation of what this means. | |
| 682 @end defopt | |
| 683 | |
| 684 A number of functions are provided for explicitly determining the | |
| 685 bounds of the region and whether it is active. Few programs need to use | |
| 686 these functions, however. A command designed to operate on a region | |
| 687 should normally use @code{interactive} with the @samp{r} specification | |
| 688 to find the beginning and end of the region. This lets other Lisp | |
| 689 programs specify the bounds explicitly as arguments and automatically | |
| 1738 | 690 respects the user's setting for @code{zmacs-regions}. |
| 691 (@xref{Interactive Codes}.) | |
| 428 | 692 |
| 693 @defun region-beginning &optional buffer | |
| 694 This function returns the position of the beginning of @var{buffer}'s | |
| 695 region (as an integer). This is the position of either point or the | |
| 696 mark, whichever is smaller. @var{buffer} defaults to the current buffer | |
| 697 if omitted. | |
| 698 | |
| 699 If the mark does not point anywhere, an error is signaled. Note that | |
| 700 this function ignores whether the region is active. | |
| 701 @end defun | |
| 702 | |
| 703 @defun region-end &optional buffer | |
| 704 This function returns the position of the end of @var{buffer}'s region | |
| 705 (as an integer). This is the position of either point or the mark, | |
| 706 whichever is larger. @var{buffer} defaults to the current buffer if | |
| 707 omitted. | |
| 708 | |
| 709 If the mark does not point anywhere, an error is signaled. Note that | |
| 710 this function ignores whether the region is active. | |
| 711 @end defun | |
| 712 | |
| 713 @defun region-exists-p | |
| 714 This function is non-@code{nil} if the region exists. If active regions | |
| 715 are in use (i.e. @code{zmacs-regions} is true), this means that the | |
| 716 region is active. Otherwise, this means that the user has pushed a mark | |
| 717 in this buffer at some point in the past. If this function returns @code{nil}, | |
| 718 a function that uses the @samp{r} interactive specification will cause | |
| 719 an error when called interactively. | |
| 720 @end defun | |
| 721 | |
| 722 @defun region-active-p | |
| 723 If @code{zmacs-regions} is true, this is equivalent to | |
| 724 @code{region-exists-p}. Otherwise, this function always returns false. | |
| 725 This function is used by commands such as @code{fill-paragraph-or-region} | |
| 726 and @code{capitalize-region-or-word}, which operate either on the active | |
| 727 region or on something else (e.g. the word or paragraph at point). | |
| 728 @end defun | |
| 729 | |
| 730 @defvar zmacs-region-stays | |
| 731 If a command sets this variable to true, the currently active region | |
| 732 will remain activated when the command finishes. (Normally the region is | |
| 1738 | 733 deactivated when each command terminates.) If @code{zmacs-regions} is |
| 428 | 734 false, however, this has no effect. Under normal circumstances, you do |
| 735 not need to set this; use the interactive specification @samp{_} | |
| 736 instead, if you want the region to remain active. | |
| 737 @end defvar | |
| 738 | |
| 739 @defun zmacs-activate-region | |
| 740 This function activates the region in the current buffer (this is | |
| 741 equivalent to activating the current buffer's mark). This will normally | |
| 742 also highlight the text in the active region and set | |
| 1738 | 743 @code{zmacs-region-stays} to @code{t}. (If @code{zmacs-regions} is |
| 744 false, however, this function has no effect.) | |
| 428 | 745 @end defun |
| 746 | |
| 747 @defun zmacs-deactivate-region | |
| 748 This function deactivates the region in the current buffer (this is | |
| 749 equivalent to deactivating the current buffer's mark). This will | |
| 750 normally also unhighlight the text in the active region and set | |
| 1738 | 751 @code{zmacs-region-stays} to @code{nil}. (If @code{zmacs-regions} is |
| 428 | 752 false, however, this function has no effect.) |
| 753 @end defun | |
| 754 | |
| 755 @defun zmacs-update-region | |
| 756 This function updates the active region, if it's currently active. (If | |
| 757 there is no active region, this function does nothing.) This has the | |
| 758 effect of updating the highlighting on the text in the region; but you | |
| 759 should never need to call this except under rather strange | |
| 760 circumstances. The command loop automatically calls it when | |
| 761 appropriate. Calling this function will call the hook | |
| 762 @code{zmacs-update-region-hook}, if the region is active. | |
| 763 @end defun | |
| 764 | |
| 765 @defvar zmacs-activate-region-hook | |
| 766 This normal hook is called when a region becomes active. (Usually this | |
| 767 happens as a result of a command that activates the region, such as | |
| 768 @code{set-mark-command}, @code{activate-region}, or | |
| 769 @code{exchange-point-and-mark}.) Note that calling | |
| 770 @file{zmacs-activate-region} will call this hook, even if the region is | |
| 1738 | 771 already active. If @code{zmacs-regions} is false, however, this hook |
| 428 | 772 will never get called under any circumstances. |
| 773 @end defvar | |
| 774 | |
| 775 @defvar zmacs-deactivate-region-hook | |
| 776 This normal hook is called when an active region becomes inactive. | |
| 777 (Calling @file{zmacs-deactivate-region} when the region is inactive will | |
| 1738 | 778 @emph{not} cause this hook to be called.) If @code{zmacs-regions} is |
| 428 | 779 false, this hook will never get called. |
| 780 @end defvar | |
| 781 | |
| 782 @defvar zmacs-update-region-hook | |
| 783 This normal hook is called when an active region is "updated" by | |
| 784 @code{zmacs-update-region}. This normally gets called at the end | |
| 1738 | 785 of each command that sets @code{zmacs-region-stays} to @code{t}, |
| 428 | 786 indicating that the region should remain activated. The motion |
| 787 commands do this. | |
| 788 @end defvar | |
| 789 | |
| 790 |