Commit | Line | Data |
---|---|---|
b8d4c8d0 GM |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Emacs Lisp Reference Manual. | |
2ad80941 | 3 | @c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc. |
b8d4c8d0 | 4 | @c See the file elisp.texi for copying conditions. |
ecc6530d | 5 | @node Markers |
b8d4c8d0 GM |
6 | @chapter Markers |
7 | @cindex markers | |
8 | ||
9 | A @dfn{marker} is a Lisp object used to specify a position in a buffer | |
10 | relative to the surrounding text. A marker changes its offset from the | |
11 | beginning of the buffer automatically whenever text is inserted or | |
12 | deleted, so that it stays with the two characters on either side of it. | |
13 | ||
14 | @menu | |
15 | * Overview of Markers:: The components of a marker, and how it relocates. | |
16 | * Predicates on Markers:: Testing whether an object is a marker. | |
17 | * Creating Markers:: Making empty markers or markers at certain places. | |
18 | * Information from Markers:: Finding the marker's buffer or character position. | |
19 | * Marker Insertion Types:: Two ways a marker can relocate when you | |
20 | insert where it points. | |
21 | * Moving Markers:: Moving the marker to a new buffer or position. | |
22 | * The Mark:: How "the mark" is implemented with a marker. | |
23 | * The Region:: How to access "the region". | |
24 | @end menu | |
25 | ||
26 | @node Overview of Markers | |
27 | @section Overview of Markers | |
28 | ||
2ad80941 GM |
29 | A marker specifies a buffer and a position in that buffer. A |
30 | marker can be used to represent a position in functions that | |
b8d4c8d0 GM |
31 | require one, just as an integer could be used. In that case, the |
32 | marker's buffer is normally ignored. Of course, a marker used in this | |
33 | way usually points to a position in the buffer that the function | |
34 | operates on, but that is entirely the programmer's responsibility. | |
35 | @xref{Positions}, for a complete description of positions. | |
36 | ||
37 | A marker has three attributes: the marker position, the marker | |
38 | buffer, and the insertion type. The marker position is an integer | |
39 | that is equivalent (at a given time) to the marker as a position in | |
2ad80941 GM |
40 | that buffer. But the marker's position value can change during |
41 | the life of the marker, and often does. Insertion and deletion of | |
42 | text in the buffer relocate the marker. The idea is that a marker | |
43 | positioned between two characters remains between those two characters | |
44 | despite insertion and deletion elsewhere in the buffer. Relocation | |
45 | changes the integer equivalent of the marker. | |
b8d4c8d0 GM |
46 | |
47 | @cindex marker relocation | |
48 | Deleting text around a marker's position leaves the marker between the | |
49 | characters immediately before and after the deleted text. Inserting | |
50 | text at the position of a marker normally leaves the marker either in | |
51 | front of or after the new text, depending on the marker's @dfn{insertion | |
52 | type} (@pxref{Marker Insertion Types})---unless the insertion is done | |
53 | with @code{insert-before-markers} (@pxref{Insertion}). | |
54 | ||
55 | @cindex marker garbage collection | |
56 | Insertion and deletion in a buffer must check all the markers and | |
57 | relocate them if necessary. This slows processing in a buffer with a | |
58 | large number of markers. For this reason, it is a good idea to make a | |
59 | marker point nowhere if you are sure you don't need it any more. | |
a9685db7 GM |
60 | Markers that can no longer be accessed are eventually removed |
61 | (@pxref{Garbage Collection}). | |
b8d4c8d0 GM |
62 | |
63 | @cindex markers as numbers | |
64 | Because it is common to perform arithmetic operations on a marker | |
2ad80941 | 65 | position, most of these operations (including @code{+} and |
b8d4c8d0 GM |
66 | @code{-}) accept markers as arguments. In such cases, the marker |
67 | stands for its current position. | |
68 | ||
69 | Here are examples of creating markers, setting markers, and moving point | |
70 | to markers: | |
71 | ||
72 | @example | |
73 | @group | |
74 | ;; @r{Make a new marker that initially does not point anywhere:} | |
75 | (setq m1 (make-marker)) | |
76 | @result{} #<marker in no buffer> | |
77 | @end group | |
78 | ||
79 | @group | |
80 | ;; @r{Set @code{m1} to point between the 99th and 100th characters} | |
81 | ;; @r{in the current buffer:} | |
82 | (set-marker m1 100) | |
83 | @result{} #<marker at 100 in markers.texi> | |
84 | @end group | |
85 | ||
86 | @group | |
87 | ;; @r{Now insert one character at the beginning of the buffer:} | |
88 | (goto-char (point-min)) | |
89 | @result{} 1 | |
90 | (insert "Q") | |
91 | @result{} nil | |
92 | @end group | |
93 | ||
94 | @group | |
95 | ;; @r{@code{m1} is updated appropriately.} | |
96 | m1 | |
97 | @result{} #<marker at 101 in markers.texi> | |
98 | @end group | |
99 | ||
100 | @group | |
101 | ;; @r{Two markers that point to the same position} | |
102 | ;; @r{are not @code{eq}, but they are @code{equal}.} | |
103 | (setq m2 (copy-marker m1)) | |
104 | @result{} #<marker at 101 in markers.texi> | |
105 | (eq m1 m2) | |
106 | @result{} nil | |
107 | (equal m1 m2) | |
108 | @result{} t | |
109 | @end group | |
110 | ||
111 | @group | |
112 | ;; @r{When you are finished using a marker, make it point nowhere.} | |
113 | (set-marker m1 nil) | |
114 | @result{} #<marker in no buffer> | |
115 | @end group | |
116 | @end example | |
117 | ||
118 | @node Predicates on Markers | |
119 | @section Predicates on Markers | |
120 | ||
121 | You can test an object to see whether it is a marker, or whether it is | |
122 | either an integer or a marker. The latter test is useful in connection | |
123 | with the arithmetic functions that work with both markers and integers. | |
124 | ||
125 | @defun markerp object | |
126 | This function returns @code{t} if @var{object} is a marker, @code{nil} | |
127 | otherwise. Note that integers are not markers, even though many | |
128 | functions will accept either a marker or an integer. | |
129 | @end defun | |
130 | ||
131 | @defun integer-or-marker-p object | |
132 | This function returns @code{t} if @var{object} is an integer or a marker, | |
133 | @code{nil} otherwise. | |
134 | @end defun | |
135 | ||
136 | @defun number-or-marker-p object | |
137 | This function returns @code{t} if @var{object} is a number (either | |
138 | integer or floating point) or a marker, @code{nil} otherwise. | |
139 | @end defun | |
140 | ||
141 | @node Creating Markers | |
142 | @section Functions that Create Markers | |
143 | ||
144 | When you create a new marker, you can make it point nowhere, or point | |
145 | to the present position of point, or to the beginning or end of the | |
146 | accessible portion of the buffer, or to the same place as another given | |
147 | marker. | |
148 | ||
149 | The next four functions all return markers with insertion type | |
150 | @code{nil}. @xref{Marker Insertion Types}. | |
151 | ||
152 | @defun make-marker | |
153 | This function returns a newly created marker that does not point | |
154 | anywhere. | |
155 | ||
156 | @example | |
157 | @group | |
158 | (make-marker) | |
159 | @result{} #<marker in no buffer> | |
160 | @end group | |
161 | @end example | |
162 | @end defun | |
163 | ||
164 | @defun point-marker | |
165 | This function returns a new marker that points to the present position | |
166 | of point in the current buffer. @xref{Point}. For an example, see | |
167 | @code{copy-marker}, below. | |
168 | @end defun | |
169 | ||
170 | @defun point-min-marker | |
171 | This function returns a new marker that points to the beginning of the | |
172 | accessible portion of the buffer. This will be the beginning of the | |
173 | buffer unless narrowing is in effect. @xref{Narrowing}. | |
174 | @end defun | |
175 | ||
176 | @defun point-max-marker | |
177 | This function returns a new marker that points to the end of the | |
178 | accessible portion of the buffer. This will be the end of the buffer | |
179 | unless narrowing is in effect. @xref{Narrowing}. | |
180 | ||
181 | Here are examples of this function and @code{point-min-marker}, shown in | |
182 | a buffer containing a version of the source file for the text of this | |
183 | chapter. | |
184 | ||
185 | @example | |
186 | @group | |
187 | (point-min-marker) | |
188 | @result{} #<marker at 1 in markers.texi> | |
189 | (point-max-marker) | |
2ad80941 | 190 | @result{} #<marker at 24080 in markers.texi> |
b8d4c8d0 GM |
191 | @end group |
192 | ||
193 | @group | |
194 | (narrow-to-region 100 200) | |
195 | @result{} nil | |
196 | @end group | |
197 | @group | |
198 | (point-min-marker) | |
199 | @result{} #<marker at 100 in markers.texi> | |
200 | @end group | |
201 | @group | |
202 | (point-max-marker) | |
203 | @result{} #<marker at 200 in markers.texi> | |
204 | @end group | |
205 | @end example | |
206 | @end defun | |
207 | ||
0b128ac4 | 208 | @defun copy-marker &optional marker-or-integer insertion-type |
b8d4c8d0 GM |
209 | If passed a marker as its argument, @code{copy-marker} returns a |
210 | new marker that points to the same place and the same buffer as does | |
211 | @var{marker-or-integer}. If passed an integer as its argument, | |
212 | @code{copy-marker} returns a new marker that points to position | |
213 | @var{marker-or-integer} in the current buffer. | |
214 | ||
215 | The new marker's insertion type is specified by the argument | |
216 | @var{insertion-type}. @xref{Marker Insertion Types}. | |
217 | ||
218 | If passed an integer argument less than 1, @code{copy-marker} returns a | |
219 | new marker that points to the beginning of the current buffer. If | |
220 | passed an integer argument greater than the length of the buffer, | |
221 | @code{copy-marker} returns a new marker that points to the end of the | |
222 | buffer. | |
223 | ||
224 | @example | |
225 | @group | |
226 | (copy-marker 0) | |
227 | @result{} #<marker at 1 in markers.texi> | |
228 | @end group | |
229 | ||
230 | @group | |
2ad80941 GM |
231 | (copy-marker 90000) |
232 | @result{} #<marker at 24080 in markers.texi> | |
b8d4c8d0 GM |
233 | @end group |
234 | @end example | |
235 | ||
236 | An error is signaled if @var{marker} is neither a marker nor an | |
237 | integer. | |
238 | @end defun | |
239 | ||
240 | Two distinct markers are considered @code{equal} (even though not | |
241 | @code{eq}) to each other if they have the same position and buffer, or | |
242 | if they both point nowhere. | |
243 | ||
244 | @example | |
245 | @group | |
246 | (setq p (point-marker)) | |
247 | @result{} #<marker at 2139 in markers.texi> | |
248 | @end group | |
249 | ||
250 | @group | |
251 | (setq q (copy-marker p)) | |
252 | @result{} #<marker at 2139 in markers.texi> | |
253 | @end group | |
254 | ||
255 | @group | |
256 | (eq p q) | |
257 | @result{} nil | |
258 | @end group | |
259 | ||
260 | @group | |
261 | (equal p q) | |
262 | @result{} t | |
263 | @end group | |
264 | @end example | |
265 | ||
266 | @node Information from Markers | |
267 | @section Information from Markers | |
268 | ||
269 | This section describes the functions for accessing the components of a | |
270 | marker object. | |
271 | ||
272 | @defun marker-position marker | |
273 | This function returns the position that @var{marker} points to, or | |
274 | @code{nil} if it points nowhere. | |
275 | @end defun | |
276 | ||
277 | @defun marker-buffer marker | |
278 | This function returns the buffer that @var{marker} points into, or | |
279 | @code{nil} if it points nowhere. | |
280 | ||
281 | @example | |
282 | @group | |
283 | (setq m (make-marker)) | |
284 | @result{} #<marker in no buffer> | |
285 | @end group | |
286 | @group | |
287 | (marker-position m) | |
288 | @result{} nil | |
289 | @end group | |
290 | @group | |
291 | (marker-buffer m) | |
292 | @result{} nil | |
293 | @end group | |
294 | ||
295 | @group | |
296 | (set-marker m 3770 (current-buffer)) | |
297 | @result{} #<marker at 3770 in markers.texi> | |
298 | @end group | |
299 | @group | |
300 | (marker-buffer m) | |
301 | @result{} #<buffer markers.texi> | |
302 | @end group | |
303 | @group | |
304 | (marker-position m) | |
305 | @result{} 3770 | |
306 | @end group | |
307 | @end example | |
308 | @end defun | |
309 | ||
310 | @defun buffer-has-markers-at position | |
311 | This function returns @code{t} if one or more markers | |
312 | point at position @var{position} in the current buffer. | |
313 | @end defun | |
314 | ||
315 | @node Marker Insertion Types | |
316 | @section Marker Insertion Types | |
317 | ||
318 | @cindex insertion type of a marker | |
319 | When you insert text directly at the place where a marker points, | |
320 | there are two possible ways to relocate that marker: it can point before | |
321 | the inserted text, or point after it. You can specify which one a given | |
322 | marker should do by setting its @dfn{insertion type}. Note that use of | |
323 | @code{insert-before-markers} ignores markers' insertion types, always | |
324 | relocating a marker to point after the inserted text. | |
325 | ||
326 | @defun set-marker-insertion-type marker type | |
327 | This function sets the insertion type of marker @var{marker} to | |
328 | @var{type}. If @var{type} is @code{t}, @var{marker} will advance when | |
329 | text is inserted at its position. If @var{type} is @code{nil}, | |
330 | @var{marker} does not advance when text is inserted there. | |
331 | @end defun | |
332 | ||
333 | @defun marker-insertion-type marker | |
334 | This function reports the current insertion type of @var{marker}. | |
335 | @end defun | |
336 | ||
337 | Most functions that create markers, without an argument allowing to | |
338 | specify the insertion type, create them with insertion type | |
339 | @code{nil}. Also, the mark has, by default, insertion type | |
340 | @code{nil}. | |
341 | ||
342 | @node Moving Markers | |
343 | @section Moving Marker Positions | |
344 | ||
345 | This section describes how to change the position of an existing | |
346 | marker. When you do this, be sure you know whether the marker is used | |
347 | outside of your program, and, if so, what effects will result from | |
348 | moving it---otherwise, confusing things may happen in other parts of | |
349 | Emacs. | |
350 | ||
351 | @defun set-marker marker position &optional buffer | |
352 | This function moves @var{marker} to @var{position} | |
353 | in @var{buffer}. If @var{buffer} is not provided, it defaults to | |
354 | the current buffer. | |
355 | ||
356 | If @var{position} is less than 1, @code{set-marker} moves @var{marker} | |
357 | to the beginning of the buffer. If @var{position} is greater than the | |
52404181 CY |
358 | size of the buffer (@pxref{Point}), @code{set-marker} moves marker to |
359 | the end of the buffer. If @var{position} is @code{nil} or a marker | |
360 | that points nowhere, then @var{marker} is set to point nowhere. | |
b8d4c8d0 GM |
361 | |
362 | The value returned is @var{marker}. | |
363 | ||
364 | @example | |
365 | @group | |
366 | (setq m (point-marker)) | |
367 | @result{} #<marker at 4714 in markers.texi> | |
368 | @end group | |
369 | @group | |
370 | (set-marker m 55) | |
371 | @result{} #<marker at 55 in markers.texi> | |
372 | @end group | |
373 | @group | |
374 | (setq b (get-buffer "foo")) | |
375 | @result{} #<buffer foo> | |
376 | @end group | |
377 | @group | |
378 | (set-marker m 0 b) | |
379 | @result{} #<marker at 1 in foo> | |
380 | @end group | |
381 | @end example | |
382 | @end defun | |
383 | ||
384 | @defun move-marker marker position &optional buffer | |
385 | This is another name for @code{set-marker}. | |
386 | @end defun | |
387 | ||
388 | @node The Mark | |
389 | @section The Mark | |
390 | @cindex mark, the | |
391 | @cindex mark ring | |
392 | ||
47af2f4b CY |
393 | Each buffer has a special marker, which is designated @dfn{the |
394 | mark}. When a buffer is newly created, this marker exists but does | |
395 | not point anywhere; this means that the mark ``doesn't exist'' in that | |
396 | buffer yet. Subsequent commands can set the mark. | |
397 | ||
398 | The mark specifies a position to bound a range of text for many | |
399 | commands, such as @code{kill-region} and @code{indent-rigidly}. These | |
400 | commands typically act on the text between point and the mark, which | |
401 | is called the @dfn{region}. If you are writing a command that | |
402 | operates on the region, don't examine the mark directly; instead, use | |
b8d4c8d0 GM |
403 | @code{interactive} with the @samp{r} specification. This provides the |
404 | values of point and the mark as arguments to the command in an | |
405 | interactive call, but permits other Lisp programs to specify arguments | |
406 | explicitly. @xref{Interactive Codes}. | |
407 | ||
47af2f4b CY |
408 | Some commands set the mark as a side-effect. Commands should do |
409 | this only if it has a potential use to the user, and never for their | |
410 | own internal purposes. For example, the @code{replace-regexp} command | |
411 | sets the mark to the value of point before doing any replacements, | |
412 | because this enables the user to move back there conveniently after | |
413 | the replace is finished. | |
b8d4c8d0 GM |
414 | |
415 | Once the mark ``exists'' in a buffer, it normally never ceases to | |
47af2f4b CY |
416 | exist. However, it may become @dfn{inactive}, if Transient Mark mode |
417 | is enabled. The buffer-local variable @code{mark-active}, if | |
418 | non-@code{nil}, means that the mark is active. A command can call the | |
419 | function @code{deactivate-mark} to deactivate the mark directly, or it | |
420 | can request deactivation of the mark upon return to the editor command | |
421 | loop by setting the variable @code{deactivate-mark} to a | |
422 | non-@code{nil} value. | |
423 | ||
67cd45a2 CY |
424 | If Transient Mark mode is enabled, certain editing commands that |
425 | normally apply to text near point, apply instead to the region when | |
426 | the mark is active. This is the main motivation for using Transient | |
427 | Mark mode. (Another is that this enables highlighting of the region | |
428 | when the mark is active. @xref{Display}.) | |
b8d4c8d0 GM |
429 | |
430 | In addition to the mark, each buffer has a @dfn{mark ring} which is a | |
431 | list of markers containing previous values of the mark. When editing | |
432 | commands change the mark, they should normally save the old value of the | |
433 | mark on the mark ring. The variable @code{mark-ring-max} specifies the | |
434 | maximum number of entries in the mark ring; once the list becomes this | |
435 | long, adding a new element deletes the last element. | |
436 | ||
437 | There is also a separate global mark ring, but that is used only in a | |
438 | few particular user-level commands, and is not relevant to Lisp | |
439 | programming. So we do not describe it here. | |
440 | ||
441 | @defun mark &optional force | |
442 | @cindex current buffer mark | |
443 | This function returns the current buffer's mark position as an integer, | |
444 | or @code{nil} if no mark has ever been set in this buffer. | |
445 | ||
446 | If Transient Mark mode is enabled, and @code{mark-even-if-inactive} is | |
447 | @code{nil}, @code{mark} signals an error if the mark is inactive. | |
448 | However, if @var{force} is non-@code{nil}, then @code{mark} disregards | |
47af2f4b CY |
449 | inactivity of the mark, and returns the mark position (or @code{nil}) |
450 | anyway. | |
b8d4c8d0 GM |
451 | @end defun |
452 | ||
453 | @defun mark-marker | |
454 | This function returns the marker that represents the current buffer's | |
455 | mark. It is not a copy, it is the marker used internally. Therefore, | |
456 | changing this marker's position will directly affect the buffer's | |
457 | mark. Don't do that unless that is the effect you want. | |
458 | ||
459 | @example | |
460 | @group | |
461 | (setq m (mark-marker)) | |
462 | @result{} #<marker at 3420 in markers.texi> | |
463 | @end group | |
464 | @group | |
465 | (set-marker m 100) | |
466 | @result{} #<marker at 100 in markers.texi> | |
467 | @end group | |
468 | @group | |
469 | (mark-marker) | |
470 | @result{} #<marker at 100 in markers.texi> | |
471 | @end group | |
472 | @end example | |
473 | ||
474 | Like any marker, this marker can be set to point at any buffer you | |
475 | like. If you make it point at any buffer other than the one of which | |
476 | it is the mark, it will yield perfectly consistent, but rather odd, | |
477 | results. We recommend that you not do it! | |
478 | @end defun | |
479 | ||
b8d4c8d0 GM |
480 | @defun set-mark position |
481 | This function sets the mark to @var{position}, and activates the mark. | |
482 | The old value of the mark is @emph{not} pushed onto the mark ring. | |
483 | ||
484 | @strong{Please note:} Use this function only if you want the user to | |
485 | see that the mark has moved, and you want the previous mark position to | |
486 | be lost. Normally, when a new mark is set, the old one should go on the | |
487 | @code{mark-ring}. For this reason, most applications should use | |
488 | @code{push-mark} and @code{pop-mark}, not @code{set-mark}. | |
489 | ||
490 | Novice Emacs Lisp programmers often try to use the mark for the wrong | |
491 | purposes. The mark saves a location for the user's convenience. An | |
492 | editing command should not alter the mark unless altering the mark is | |
493 | part of the user-level functionality of the command. (And, in that | |
494 | case, this effect should be documented.) To remember a location for | |
495 | internal use in the Lisp program, store it in a Lisp variable. For | |
496 | example: | |
497 | ||
498 | @example | |
499 | @group | |
500 | (let ((beg (point))) | |
501 | (forward-line 1) | |
502 | (delete-region beg (point))). | |
503 | @end group | |
504 | @end example | |
505 | @end defun | |
506 | ||
b8d4c8d0 GM |
507 | @defun push-mark &optional position nomsg activate |
508 | This function sets the current buffer's mark to @var{position}, and | |
509 | pushes a copy of the previous mark onto @code{mark-ring}. If | |
510 | @var{position} is @code{nil}, then the value of point is used. | |
2ad80941 GM |
511 | @c Doesn't seem relevant. |
512 | @c @code{push-mark} returns @code{nil}. | |
b8d4c8d0 GM |
513 | |
514 | The function @code{push-mark} normally @emph{does not} activate the | |
515 | mark. To do that, specify @code{t} for the argument @var{activate}. | |
516 | ||
517 | A @samp{Mark set} message is displayed unless @var{nomsg} is | |
518 | non-@code{nil}. | |
519 | @end defun | |
520 | ||
521 | @defun pop-mark | |
522 | This function pops off the top element of @code{mark-ring} and makes | |
523 | that mark become the buffer's actual mark. This does not move point in | |
524 | the buffer, and it does nothing if @code{mark-ring} is empty. It | |
525 | deactivates the mark. | |
2ad80941 GM |
526 | @c |
527 | @c Seems even less relevant. | |
528 | @c The return value is not meaningful. | |
b8d4c8d0 GM |
529 | @end defun |
530 | ||
531 | @defopt transient-mark-mode | |
47af2f4b CY |
532 | This variable, if non-@code{nil}, enables Transient Mark mode. In |
533 | Transient Mark mode, every buffer-modifying primitive sets | |
534 | @code{deactivate-mark}. As a consequence, most commands that modify | |
535 | the buffer also deactivate the mark. | |
b8d4c8d0 | 536 | |
47af2f4b CY |
537 | When Transient Mark mode is enabled and the mark is active, many |
538 | commands that normally apply to the text near point instead apply to | |
539 | the region. Such commands should use the function @code{use-region-p} | |
540 | to test whether they should operate on the region. @xref{The Region}. | |
2de17c73 | 541 | |
16624be8 EZ |
542 | Lisp programs can set @code{transient-mark-mode} to non-@code{nil}, |
543 | non-@code{t} values to enable Transient Mark mode temporarily. If the | |
66e3cca6 | 544 | value is @code{lambda}, Transient Mark mode is automatically turned |
16624be8 EZ |
545 | off after any action, such as buffer modification, that would normally |
546 | deactivate the mark. If the value is @w{@code{(only . @var{oldval})}}, | |
547 | then @code{transient-mark-mode} is set to the value @var{oldval} after | |
548 | any subsequent command that moves point and is not shift-translated | |
549 | (@pxref{Key Sequence Input, shift-translation}), or after any other | |
550 | action that would normally deactivate the mark. | |
b8d4c8d0 GM |
551 | @end defopt |
552 | ||
553 | @defopt mark-even-if-inactive | |
554 | If this is non-@code{nil}, Lisp programs and the Emacs user can use the | |
555 | mark even when it is inactive. This option affects the behavior of | |
556 | Transient Mark mode. When the option is non-@code{nil}, deactivation of | |
557 | the mark turns off region highlighting, but commands that use the mark | |
558 | behave as if the mark were still active. | |
559 | @end defopt | |
560 | ||
561 | @defvar deactivate-mark | |
562 | If an editor command sets this variable non-@code{nil}, then the editor | |
563 | command loop deactivates the mark after the command returns (if | |
564 | Transient Mark mode is enabled). All the primitives that change the | |
565 | buffer set @code{deactivate-mark}, to deactivate the mark when the | |
566 | command is finished. | |
567 | ||
568 | To write Lisp code that modifies the buffer without causing | |
569 | deactivation of the mark at the end of the command, bind | |
570 | @code{deactivate-mark} to @code{nil} around the code that does the | |
571 | modification. For example: | |
572 | ||
573 | @example | |
574 | (let (deactivate-mark) | |
575 | (insert " ")) | |
576 | @end example | |
577 | @end defvar | |
578 | ||
6bbd4600 | 579 | @defun deactivate-mark &optional force |
b40c84b0 CY |
580 | If Transient Mark mode is enabled or @var{force} is non-@code{nil}, |
581 | this function deactivates the mark and runs the normal hook | |
582 | @code{deactivate-mark-hook}. Otherwise, it does nothing. | |
b8d4c8d0 GM |
583 | @end defun |
584 | ||
585 | @defvar mark-active | |
2de17c73 EZ |
586 | The mark is active when this variable is non-@code{nil}. This |
587 | variable is always buffer-local in each buffer. Do @emph{not} use the | |
588 | value of this variable to decide whether a command that normally | |
589 | operates on text near point should operate on the region instead. Use | |
47af2f4b | 590 | the function @code{use-region-p} for that (@pxref{The Region}). |
b8d4c8d0 GM |
591 | @end defvar |
592 | ||
593 | @defvar activate-mark-hook | |
594 | @defvarx deactivate-mark-hook | |
595 | These normal hooks are run, respectively, when the mark becomes active | |
596 | and when it becomes inactive. The hook @code{activate-mark-hook} is | |
eaa6bc3c GM |
597 | also run at the end of the command loop if the mark is active and it |
598 | is possible that the region may have changed. | |
599 | @ignore | |
600 | This piece of command_loop_1, run unless deactivating the mark: | |
601 | if (current_buffer != prev_buffer || MODIFF != prev_modiff) | |
602 | { | |
603 | Lisp_Object hook = intern ("activate-mark-hook"); | |
604 | Frun_hooks (1, &hook); | |
605 | } | |
606 | @end ignore | |
b8d4c8d0 GM |
607 | @end defvar |
608 | ||
47af2f4b CY |
609 | @defun handle-shift-selection |
610 | This function implements the ``shift-selection'' behavior of | |
611 | point-motion commands. @xref{Shift Selection,,, emacs, The GNU Emacs | |
612 | Manual}. It is called automatically by the Emacs command loop | |
613 | whenever a command with a @samp{^} character in its @code{interactive} | |
614 | spec is invoked, before the command itself is executed | |
615 | (@pxref{Interactive Codes, ^}). | |
616 | ||
617 | If @code{shift-select-mode} is non-@code{nil} and the current command | |
618 | was invoked via shift translation (@pxref{Key Sequence Input, | |
619 | shift-translation}), this function sets the mark and temporarily | |
620 | activates the region, unless the region was already temporarily | |
621 | activated in this way. Otherwise, if the region has been activated | |
622 | temporarily, it deactivates the mark and restores the variable | |
623 | @code{transient-mark-mode} to its earlier value. | |
624 | @end defun | |
625 | ||
b8d4c8d0 GM |
626 | @defvar mark-ring |
627 | The value of this buffer-local variable is the list of saved former | |
628 | marks of the current buffer, most recent first. | |
629 | ||
630 | @example | |
631 | @group | |
632 | mark-ring | |
633 | @result{} (#<marker at 11050 in markers.texi> | |
634 | #<marker at 10832 in markers.texi> | |
635 | @dots{}) | |
636 | @end group | |
637 | @end example | |
638 | @end defvar | |
639 | ||
640 | @defopt mark-ring-max | |
641 | The value of this variable is the maximum size of @code{mark-ring}. If | |
642 | more marks than this are pushed onto the @code{mark-ring}, | |
643 | @code{push-mark} discards an old mark when it adds a new one. | |
644 | @end defopt | |
645 | ||
00e84de0 GM |
646 | @c There is also global-mark-ring-max, but this chapter explicitly |
647 | @c does not talk about the global mark. | |
648 | ||
b8d4c8d0 GM |
649 | @node The Region |
650 | @section The Region | |
651 | @cindex region (between point and mark) | |
652 | ||
653 | The text between point and the mark is known as @dfn{the region}. | |
654 | Various functions operate on text delimited by point and the mark, but | |
655 | only those functions specifically related to the region itself are | |
656 | described here. | |
657 | ||
658 | The next two functions signal an error if the mark does not point | |
659 | anywhere. If Transient Mark mode is enabled and | |
660 | @code{mark-even-if-inactive} is @code{nil}, they also signal an error | |
661 | if the mark is inactive. | |
662 | ||
663 | @defun region-beginning | |
664 | This function returns the position of the beginning of the region (as | |
665 | an integer). This is the position of either point or the mark, | |
666 | whichever is smaller. | |
667 | @end defun | |
668 | ||
669 | @defun region-end | |
670 | This function returns the position of the end of the region (as an | |
671 | integer). This is the position of either point or the mark, whichever is | |
672 | larger. | |
673 | @end defun | |
674 | ||
67cd45a2 CY |
675 | Instead of using @code{region-beginning} and @code{region-end}, a |
676 | command designed to operate on a region should normally use | |
677 | @code{interactive} with the @samp{r} specification to find the | |
678 | beginning and end of the region. This lets other Lisp programs | |
679 | specify the bounds explicitly as arguments. @xref{Interactive Codes}. | |
b8d4c8d0 | 680 | |
47af2f4b CY |
681 | @defun use-region-p |
682 | This function returns @code{t} if Transient Mark mode is enabled, the | |
67cd45a2 CY |
683 | mark is active, and there is a valid region in the buffer. This |
684 | function is intended to be used by commands that operate on the | |
685 | region, instead of on text near point, when the mark is active. | |
00e84de0 GM |
686 | |
687 | A region is valid if it has a non-zero size, or if the user option | |
688 | @code{use-empty-active-region} is non-@code{nil} (by default, it is | |
689 | @code{nil}). The function @code{region-active-p} is similar to | |
690 | @code{use-region-p}, but considers all regions as valid. In most | |
691 | cases, you should not use @code{region-active-p}, since if the region | |
692 | is empty it is often more appropriate to operate on point. | |
47af2f4b | 693 | @end defun |
00e84de0 | 694 |