Mercurial > emacs
annotate lispref/markers.texi @ 25177:0ac130f2181a
(outline-previous-heading): New function.
(outline-up-heading-all): Use outline-previous-heading.
(outline-next-heading): Delete definition inserted yesterday.
author | Richard M. Stallman <rms@gnu.org> |
---|---|
date | Thu, 05 Aug 1999 14:50:30 +0000 |
parents | 40089afa2b1d |
children | 467b88fab665 |
rev | line source |
---|---|
6444 | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc. |
6444 | 4 @c See the file elisp.texi for copying conditions. |
5 @setfilename ../info/markers | |
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. | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
20 * Marker Insertion Types:: Two ways a marker can relocate when you |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
21 insert where it points. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
22 * Moving Markers:: Moving the marker to a new buffer or position. |
6444 | 23 * The Mark:: How ``the mark'' is implemented with a marker. |
24 * The Region:: How to access ``the region''. | |
25 @end menu | |
26 | |
27 @node Overview of Markers | |
28 @section Overview of Markers | |
29 | |
30 A marker specifies a buffer and a position in that buffer. The marker | |
31 can be used to represent a position in the functions that require one, | |
32 just as an integer could be used. @xref{Positions}, for a complete | |
33 description of positions. | |
34 | |
35 A marker has two attributes: the marker position, and the marker | |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6444
diff
changeset
|
36 buffer. The marker position is an integer that is equivalent (at a |
6444 | 37 given time) to the marker as a position in that buffer. But the |
38 marker's position value can change often during the life of the marker. | |
39 Insertion and deletion of text in the buffer relocate the marker. The | |
40 idea is that a marker positioned between two characters remains between | |
41 those two characters despite insertion and deletion elsewhere in the | |
42 buffer. Relocation changes the integer equivalent of the marker. | |
43 | |
44 @cindex marker relocation | |
45 Deleting text around a marker's position leaves the marker between the | |
46 characters immediately before and after the deleted text. Inserting | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
47 text at the position of a marker normally leaves the marker either in |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
48 front of or after the new text, depending on the marker's @dfn{insertion |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
49 type} (@pxref{Marker Insertion Types})---unless the insertion is done |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
50 with @code{insert-before-markers} (@pxref{Insertion}). |
6444 | 51 |
52 @cindex marker garbage collection | |
53 Insertion and deletion in a buffer must check all the markers and | |
54 relocate them if necessary. This slows processing in a buffer with a | |
55 large number of markers. For this reason, it is a good idea to make a | |
56 marker point nowhere if you are sure you don't need it any more. | |
57 Unreferenced markers are garbage collected eventually, but until then | |
58 will continue to use time if they do point somewhere. | |
59 | |
60 @cindex markers as numbers | |
61 Because it is common to perform arithmetic operations on a marker | |
62 position, most of the arithmetic operations (including @code{+} and | |
63 @code{-}) accept markers as arguments. In such cases, the marker | |
64 stands for its current position. | |
65 | |
66 Here are examples of creating markers, setting markers, and moving point | |
67 to markers: | |
68 | |
69 @example | |
70 @group | |
71 ;; @r{Make a new marker that initially does not point anywhere:} | |
72 (setq m1 (make-marker)) | |
73 @result{} #<marker in no buffer> | |
74 @end group | |
75 | |
76 @group | |
77 ;; @r{Set @code{m1} to point between the 99th and 100th characters} | |
78 ;; @r{in the current buffer:} | |
79 (set-marker m1 100) | |
80 @result{} #<marker at 100 in markers.texi> | |
81 @end group | |
82 | |
83 @group | |
84 ;; @r{Now insert one character at the beginning of the buffer:} | |
85 (goto-char (point-min)) | |
86 @result{} 1 | |
87 (insert "Q") | |
88 @result{} nil | |
89 @end group | |
90 | |
91 @group | |
92 ;; @r{@code{m1} is updated appropriately.} | |
93 m1 | |
94 @result{} #<marker at 101 in markers.texi> | |
95 @end group | |
96 | |
97 @group | |
98 ;; @r{Two markers that point to the same position} | |
99 ;; @r{are not @code{eq}, but they are @code{equal}.} | |
100 (setq m2 (copy-marker m1)) | |
101 @result{} #<marker at 101 in markers.texi> | |
102 (eq m1 m2) | |
103 @result{} nil | |
104 (equal m1 m2) | |
105 @result{} t | |
106 @end group | |
107 | |
108 @group | |
109 ;; @r{When you are finished using a marker, make it point nowhere.} | |
110 (set-marker m1 nil) | |
111 @result{} #<marker in no buffer> | |
112 @end group | |
113 @end example | |
114 | |
115 @node Predicates on Markers | |
116 @section Predicates on Markers | |
117 | |
118 You can test an object to see whether it is a marker, or whether it is | |
119 either an integer or a marker. The latter test is useful in connection | |
120 with the arithmetic functions that work with both markers and integers. | |
121 | |
122 @defun markerp object | |
123 This function returns @code{t} if @var{object} is a marker, @code{nil} | |
124 otherwise. Note that integers are not markers, even though many | |
125 functions will accept either a marker or an integer. | |
126 @end defun | |
127 | |
128 @defun integer-or-marker-p object | |
129 This function returns @code{t} if @var{object} is an integer or a marker, | |
130 @code{nil} otherwise. | |
131 @end defun | |
132 | |
133 @defun number-or-marker-p object | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
134 This function returns @code{t} if @var{object} is a number (either |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
135 integer or floating point) or a marker, @code{nil} otherwise. |
6444 | 136 @end defun |
137 | |
138 @node Creating Markers | |
139 @section Functions That Create Markers | |
140 | |
141 When you create a new marker, you can make it point nowhere, or point | |
142 to the present position of point, or to the beginning or end of the | |
143 accessible portion of the buffer, or to the same place as another given | |
144 marker. | |
145 | |
146 @defun make-marker | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
147 This function returns a newly created marker that does not point |
6444 | 148 anywhere. |
149 | |
150 @example | |
151 @group | |
152 (make-marker) | |
153 @result{} #<marker in no buffer> | |
154 @end group | |
155 @end example | |
156 @end defun | |
157 | |
158 @defun point-marker | |
159 This function returns a new marker that points to the present position | |
160 of point in the current buffer. @xref{Point}. For an example, see | |
161 @code{copy-marker}, below. | |
162 @end defun | |
163 | |
164 @defun point-min-marker | |
165 This function returns a new marker that points to the beginning of the | |
166 accessible portion of the buffer. This will be the beginning of the | |
167 buffer unless narrowing is in effect. @xref{Narrowing}. | |
168 @end defun | |
169 | |
170 @defun point-max-marker | |
171 @cindex end of buffer marker | |
172 This function returns a new marker that points to the end of the | |
173 accessible portion of the buffer. This will be the end of the buffer | |
174 unless narrowing is in effect. @xref{Narrowing}. | |
175 | |
176 Here are examples of this function and @code{point-min-marker}, shown in | |
177 a buffer containing a version of the source file for the text of this | |
178 chapter. | |
179 | |
180 @example | |
181 @group | |
182 (point-min-marker) | |
183 @result{} #<marker at 1 in markers.texi> | |
184 (point-max-marker) | |
185 @result{} #<marker at 15573 in markers.texi> | |
186 @end group | |
187 | |
188 @group | |
189 (narrow-to-region 100 200) | |
190 @result{} nil | |
191 @end group | |
192 @group | |
193 (point-min-marker) | |
194 @result{} #<marker at 100 in markers.texi> | |
195 @end group | |
196 @group | |
197 (point-max-marker) | |
198 @result{} #<marker at 200 in markers.texi> | |
199 @end group | |
200 @end example | |
201 @end defun | |
202 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
203 @defun copy-marker marker-or-integer insertion-type |
6444 | 204 If passed a marker as its argument, @code{copy-marker} returns a |
205 new marker that points to the same place and the same buffer as does | |
206 @var{marker-or-integer}. If passed an integer as its argument, | |
207 @code{copy-marker} returns a new marker that points to position | |
208 @var{marker-or-integer} in the current buffer. | |
209 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
210 The new marker's insertion type is specified by the argument |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
211 @var{insertion-type}. @xref{Marker Insertion Types}. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
212 |
6444 | 213 If passed an integer argument less than 1, @code{copy-marker} returns a |
214 new marker that points to the beginning of the current buffer. If | |
215 passed an integer argument greater than the length of the buffer, | |
216 @code{copy-marker} returns a new marker that points to the end of the | |
217 buffer. | |
218 | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
219 @example |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
220 @group |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
221 (copy-marker 0) |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
222 @result{} #<marker at 1 in markers.texi> |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
223 @end group |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
224 |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
225 @group |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
226 (copy-marker 20000) |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
227 @result{} #<marker at 7572 in markers.texi> |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
228 @end group |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
229 @end example |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
230 |
6444 | 231 An error is signaled if @var{marker} is neither a marker nor an |
232 integer. | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
233 @end defun |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
234 |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
235 Two distinct markers are considered @code{equal} (even though not |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
236 @code{eq}) to each other if they have the same position and buffer, or |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
237 if they both point nowhere. |
6444 | 238 |
239 @example | |
240 @group | |
241 (setq p (point-marker)) | |
242 @result{} #<marker at 2139 in markers.texi> | |
243 @end group | |
244 | |
245 @group | |
246 (setq q (copy-marker p)) | |
247 @result{} #<marker at 2139 in markers.texi> | |
248 @end group | |
249 | |
250 @group | |
251 (eq p q) | |
252 @result{} nil | |
253 @end group | |
254 | |
255 @group | |
256 (equal p q) | |
257 @result{} t | |
258 @end group | |
259 @end example | |
260 | |
261 @node Information from Markers | |
262 @section Information from Markers | |
263 | |
264 This section describes the functions for accessing the components of a | |
265 marker object. | |
266 | |
267 @defun marker-position marker | |
268 This function returns the position that @var{marker} points to, or | |
269 @code{nil} if it points nowhere. | |
270 @end defun | |
271 | |
272 @defun marker-buffer marker | |
273 This function returns the buffer that @var{marker} points into, or | |
274 @code{nil} if it points nowhere. | |
275 | |
276 @example | |
277 @group | |
278 (setq m (make-marker)) | |
279 @result{} #<marker in no buffer> | |
280 @end group | |
281 @group | |
282 (marker-position m) | |
283 @result{} nil | |
284 @end group | |
285 @group | |
286 (marker-buffer m) | |
287 @result{} nil | |
288 @end group | |
289 | |
290 @group | |
291 (set-marker m 3770 (current-buffer)) | |
292 @result{} #<marker at 3770 in markers.texi> | |
293 @end group | |
294 @group | |
295 (marker-buffer m) | |
296 @result{} #<buffer markers.texi> | |
297 @end group | |
298 @group | |
299 (marker-position m) | |
300 @result{} 3770 | |
301 @end group | |
302 @end example | |
303 @end defun | |
304 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
305 @node Marker Insertion Types |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
306 @section Marker Insertion Types |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
307 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
308 @cindex insertion type of a marker |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
309 When you insert text directly at the place where a marker points, |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
310 there are two possible ways to relocate that marker: it can point before |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
311 the inserted text, or point after it. You can specify which one a given |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
312 marker should do by setting its @dfn{insertion type}. Note that use of |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
313 @code{insert-before-markers} ignores markers' insertion types, always |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
314 relocating a marker to point after the inserted text. |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
315 |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
316 @defun set-marker-insertion-type marker type |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
317 @tindex set-marker-insertion-type |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
318 This function sets the insertion type of marker @var{marker} to |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
319 @var{type}. If @var{type} is @code{t}, @var{marker} will advance when |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
320 text is inserted at its position. If @var{type} is @code{nil}, |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
321 @var{marker} does not advance when text is inserted there. |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
322 @end defun |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
323 |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
324 @defun marker-insertion-type marker |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
325 @tindex marker-insertion-type |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
326 This function reports the current insertion type of @var{marker}. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
327 @end defun |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
328 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
329 @node Moving Markers |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
330 @section Moving Marker Positions |
6444 | 331 |
332 This section describes how to change the position of an existing | |
333 marker. When you do this, be sure you know whether the marker is used | |
334 outside of your program, and, if so, what effects will result from | |
335 moving it---otherwise, confusing things may happen in other parts of | |
336 Emacs. | |
337 | |
338 @defun set-marker marker position &optional buffer | |
339 This function moves @var{marker} to @var{position} | |
340 in @var{buffer}. If @var{buffer} is not provided, it defaults to | |
341 the current buffer. | |
342 | |
343 If @var{position} is less than 1, @code{set-marker} moves @var{marker} | |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6444
diff
changeset
|
344 to the beginning of the buffer. If @var{position} is greater than the |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6444
diff
changeset
|
345 size of the buffer, @code{set-marker} moves marker to the end of the |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6444
diff
changeset
|
346 buffer. If @var{position} is @code{nil} or a marker that points |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6444
diff
changeset
|
347 nowhere, then @var{marker} is set to point nowhere. |
6444 | 348 |
349 The value returned is @var{marker}. | |
350 | |
351 @example | |
352 @group | |
353 (setq m (point-marker)) | |
354 @result{} #<marker at 4714 in markers.texi> | |
355 @end group | |
356 @group | |
357 (set-marker m 55) | |
358 @result{} #<marker at 55 in markers.texi> | |
359 @end group | |
360 @group | |
361 (setq b (get-buffer "foo")) | |
362 @result{} #<buffer foo> | |
363 @end group | |
364 @group | |
365 (set-marker m 0 b) | |
366 @result{} #<marker at 1 in foo> | |
367 @end group | |
368 @end example | |
369 @end defun | |
370 | |
371 @defun move-marker marker position &optional buffer | |
372 This is another name for @code{set-marker}. | |
373 @end defun | |
374 | |
375 @node The Mark | |
376 @section The Mark | |
377 @cindex mark, the | |
378 @cindex mark ring | |
379 | |
380 One special marker in each buffer is designated @dfn{the mark}. It | |
381 records a position for the user for the sake of commands such as | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
382 @code{kill-region} and @code{indent-rigidly}. Lisp programs should set |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
383 the mark only to values that have a potential use to the user, and never |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
384 for their own internal purposes. For example, the @code{replace-regexp} |
6444 | 385 command sets the mark to the value of point before doing any |
386 replacements, because this enables the user to move back there | |
387 conveniently after the replace is finished. | |
388 | |
389 Many commands are designed so that when called interactively they | |
390 operate on the text between point and the mark. If you are writing such | |
391 a command, don't examine the mark directly; instead, use | |
392 @code{interactive} with the @samp{r} specification. This provides the | |
393 values of point and the mark as arguments to the command in an | |
394 interactive call, but permits other Lisp programs to specify arguments | |
395 explicitly. @xref{Interactive Codes}. | |
396 | |
397 Each buffer has its own value of the mark that is independent of the | |
398 value of the mark in other buffers. When a buffer is created, the mark | |
399 exists but does not point anywhere. We consider this state as ``the | |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6444
diff
changeset
|
400 absence of a mark in that buffer.'' |
6444 | 401 |
402 Once the mark ``exists'' in a buffer, it normally never ceases to | |
403 exist. However, it may become @dfn{inactive}, if Transient Mark mode is | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
404 enabled. The variable @code{mark-active}, which is always buffer-local |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
405 in all buffers, indicates whether the mark is active: non-@code{nil} |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
406 means yes. A command can request deactivation of the mark upon return |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
407 to the editor command loop by setting @code{deactivate-mark} to a |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
408 non-@code{nil} value (but this causes deactivation only if Transient |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
409 Mark mode is enabled). |
6444 | 410 |
411 The main motivation for using Transient Mark mode is that this mode | |
412 also enables highlighting of the region when the mark is active. | |
413 @xref{Display}. | |
414 | |
415 In addition to the mark, each buffer has a @dfn{mark ring} which is a | |
416 list of markers containing previous values of the mark. When editing | |
417 commands change the mark, they should normally save the old value of the | |
418 mark on the mark ring. The variable @code{mark-ring-max} specifies the | |
419 maximum number of entries in the mark ring; once the list becomes this | |
420 long, adding a new element deletes the last element. | |
421 | |
422 @defun mark &optional force | |
423 @cindex current buffer mark | |
424 This function returns the current buffer's mark position as an integer. | |
425 | |
426 If the mark is inactive, @code{mark} normally signals an error. | |
427 However, if @var{force} is non-@code{nil}, then @code{mark} returns the | |
428 mark position anyway---or @code{nil}, if the mark is not yet set for | |
429 this buffer. | |
430 @end defun | |
431 | |
432 @defun mark-marker | |
433 This function returns the current buffer's mark. This is the very marker | |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6444
diff
changeset
|
434 that records the mark location inside Emacs, not a copy. Therefore, |
6444 | 435 changing this marker's position will directly affect the position of the mark. |
436 Don't do it unless that is the effect you want. | |
437 | |
438 @example | |
439 @group | |
440 (setq m (mark-marker)) | |
441 @result{} #<marker at 3420 in markers.texi> | |
442 @end group | |
443 @group | |
444 (set-marker m 100) | |
445 @result{} #<marker at 100 in markers.texi> | |
446 @end group | |
447 @group | |
448 (mark-marker) | |
449 @result{} #<marker at 100 in markers.texi> | |
450 @end group | |
451 @end example | |
452 | |
453 Like any marker, this marker can be set to point at any buffer you like. | |
454 We don't recommend that you make it point at any buffer other than the | |
455 one of which it is the mark. If you do, it will yield perfectly | |
456 consistent, but rather odd, results. | |
457 @end defun | |
458 | |
459 @ignore | |
460 @deffn Command set-mark-command jump | |
461 If @var{jump} is @code{nil}, this command sets the mark to the value | |
462 of point and pushes the previous value of the mark on the mark ring. The | |
463 message @samp{Mark set} is also displayed in the echo area. | |
464 | |
465 If @var{jump} is not @code{nil}, this command sets point to the value | |
466 of the mark, and sets the mark to the previous saved mark value, which | |
467 is popped off the mark ring. | |
468 | |
469 This function is @emph{only} intended for interactive use. | |
470 @end deffn | |
471 @end ignore | |
472 | |
473 @defun set-mark position | |
474 This function sets the mark to @var{position}, and activates the mark. | |
475 The old value of the mark is @emph{not} pushed onto the mark ring. | |
476 | |
7734 | 477 @strong{Please note:} Use this function only if you want the user to |
6444 | 478 see that the mark has moved, and you want the previous mark position to |
479 be lost. Normally, when a new mark is set, the old one should go on the | |
480 @code{mark-ring}. For this reason, most applications should use | |
481 @code{push-mark} and @code{pop-mark}, not @code{set-mark}. | |
482 | |
483 Novice Emacs Lisp programmers often try to use the mark for the wrong | |
484 purposes. The mark saves a location for the user's convenience. An | |
485 editing command should not alter the mark unless altering the mark is | |
486 part of the user-level functionality of the command. (And, in that | |
487 case, this effect should be documented.) To remember a location for | |
488 internal use in the Lisp program, store it in a Lisp variable. For | |
489 example: | |
490 | |
491 @example | |
492 @group | |
493 (let ((beg (point))) | |
494 (forward-line 1) | |
495 (delete-region beg (point))). | |
496 @end group | |
497 @end example | |
498 @end defun | |
499 | |
500 @c for interactive use only | |
501 @ignore | |
502 @deffn Command exchange-point-and-mark | |
503 This function exchanges the positions of point and the mark. | |
504 It is intended for interactive use. | |
505 @end deffn | |
506 @end ignore | |
507 | |
508 @defun push-mark &optional position nomsg activate | |
509 This function sets the current buffer's mark to @var{position}, and | |
510 pushes a copy of the previous mark onto @code{mark-ring}. If | |
511 @var{position} is @code{nil}, then the value of point is used. | |
512 @code{push-mark} returns @code{nil}. | |
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. | |
526 | |
527 The return value is not meaningful. | |
528 @end defun | |
529 | |
530 @defopt transient-mark-mode | |
531 @cindex Transient Mark mode | |
12098 | 532 This variable if non-@code{nil} enables Transient Mark mode, in which |
533 every buffer-modifying primitive sets @code{deactivate-mark}. The | |
534 consequence of this is that commands that modify the buffer normally | |
535 make the mark inactive. | |
6444 | 536 @end defopt |
537 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
538 @defopt mark-even-if-inactive |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
539 If this is non-@code{nil}, Lisp programs and the Emacs user can use the |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
540 mark even when it is inactive. This option affects the behavior of |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
541 Transient Mark mode. When the option is non-@code{nil}, deactivation of |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
542 the mark turns off region highlighting, but commands that use the mark |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
543 behave as if the mark were still active. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
544 @end defopt |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
545 |
6444 | 546 @defvar deactivate-mark |
547 If an editor command sets this variable non-@code{nil}, then the editor | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
548 command loop deactivates the mark after the command returns (if |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
549 Transient Mark mode is enabled). All the primitives that change the |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
550 buffer set @code{deactivate-mark}, to deactivate the mark when the |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
551 command is finished. |
6444 | 552 @end defvar |
553 | |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6444
diff
changeset
|
554 @defun deactivate-mark |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
555 This function deactivates the mark, if Transient Mark mode is enabled. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
556 Otherwise it does nothing. |
7729
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6444
diff
changeset
|
557 @end defun |
a1c07008521d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6444
diff
changeset
|
558 |
6444 | 559 @defvar mark-active |
560 The mark is active when this variable is non-@code{nil}. This variable | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
561 is always buffer-local in each buffer. |
6444 | 562 @end defvar |
563 | |
564 @defvar activate-mark-hook | |
565 @defvarx deactivate-mark-hook | |
566 These normal hooks are run, respectively, when the mark becomes active | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
567 and when it becomes inactive. The hook @code{activate-mark-hook} is |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
568 also run at the end of a command if the mark is active and it is |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12098
diff
changeset
|
569 possible that the region may have changed. |
6444 | 570 @end defvar |
571 | |
572 @defvar mark-ring | |
573 The value of this buffer-local variable is the list of saved former | |
574 marks of the current buffer, most recent first. | |
575 | |
576 @example | |
577 @group | |
578 mark-ring | |
579 @result{} (#<marker at 11050 in markers.texi> | |
580 #<marker at 10832 in markers.texi> | |
581 @dots{}) | |
582 @end group | |
583 @end example | |
584 @end defvar | |
585 | |
586 @defopt mark-ring-max | |
587 The value of this variable is the maximum size of @code{mark-ring}. If | |
588 more marks than this are pushed onto the @code{mark-ring}, | |
589 @code{push-mark} discards an old mark when it adds a new one. | |
590 @end defopt | |
591 | |
592 @node The Region | |
593 @section The Region | |
594 @cindex region, the | |
595 | |
596 The text between point and the mark is known as @dfn{the region}. | |
597 Various functions operate on text delimited by point and the mark, but | |
598 only those functions specifically related to the region itself are | |
599 described here. | |
600 | |
601 @defun region-beginning | |
602 This function returns the position of the beginning of the region (as | |
603 an integer). This is the position of either point or the mark, | |
604 whichever is smaller. | |
605 | |
606 If the mark does not point anywhere, an error is signaled. | |
607 @end defun | |
608 | |
609 @defun region-end | |
610 This function returns the position of the end of the region (as an | |
611 integer). This is the position of either point or the mark, whichever is | |
612 larger. | |
613 | |
614 If the mark does not point anywhere, an error is signaled. | |
615 @end defun | |
616 | |
617 Few programs need to use the @code{region-beginning} and | |
618 @code{region-end} functions. A command designed to operate on a region | |
619 should normally use @code{interactive} with the @samp{r} specification | |
620 to find the beginning and end of the region. This lets other Lisp | |
621 programs specify the bounds explicitly as arguments. (@xref{Interactive | |
622 Codes}.) |