001: @c This is part of the Emacs manual.
002: @c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2018 Free Software
003: @c Foundation, Inc.
004: @c See file emacs.texi for copying conditions.
005: @node Mark
006: @chapter The Mark and the Region
007: @cindex mark
008: @cindex setting a mark
009: @cindex region
010: 
011:   Many Emacs commands operate on an arbitrary contiguous part of the
012: current buffer.  To specify the text for such a command to operate on,
013: you set @dfn{the mark} at one end of it, and move point to the other
014: end.  The text between point and the mark is called @dfn{the region}.
015: The region always extends between point and the mark, no matter which
016: one comes earlier in the text; each time you move point, the region
017: changes.
018: 
019: @cindex active region
020: @cindex activating the mark
021:   Setting the mark at a position in the text also @dfn{activates} it.
022: When the mark is active, we say also that the region is active; Emacs
023: indicates its extent by highlighting the text within it, using the
024: @code{region} face (@pxref{Face Customization}).
025: 
026: @cindex deactivating the mark
027:   After certain non-motion commands, including any command that
028: changes the text in the buffer, Emacs automatically @dfn{deactivates}
029: the mark; this turns off the highlighting.  You can also explicitly
030: deactivate the mark at any time, by typing @kbd{C-g}
031: (@pxref{Quitting}).
032: 
033:   The above default behavior is known as Transient Mark mode.
034: Disabling Transient Mark mode switches Emacs to an alternative
035: behavior, in which the region is usually not highlighted.
036: @xref{Disabled Transient Mark}.
037: 
038: @vindex highlight-nonselected-windows
039:   Setting the mark in one buffer has no effect on the marks in other
040: buffers.  When you return to a buffer with an active mark, the mark is
041: at the same place as before.  When multiple windows show the same
042: buffer, they can have different values of point, and thus different
043: regions, but they all share one common mark position.  @xref{Windows}.
044: Ordinarily, only the selected window highlights its region; however,
045: if the variable @code{highlight-nonselected-windows} is
046: non-@code{nil}, each window highlights its own region.
047: 
048:   There is another kind of region: the rectangular region.
049: @xref{Rectangles}.
050: 
051: @menu
052: * Setting Mark::            Commands to set the mark.
053: * Marking Objects::         Commands to put region around textual units.
054: * Using Region::            Summary of ways to operate on contents of the region.
055: * Mark Ring::               Previous mark positions saved so you can go back there.
056: * Global Mark Ring::        Previous mark positions in various buffers.
057: * Shift Selection::         Using shifted cursor motion keys.
058: * Disabled Transient Mark:: Leaving regions unhighlighted by default.
059: @end menu
060: 
061: @node Setting Mark
062: @section Setting the Mark
063: 
064:   Here are some commands for setting the mark:
065: 
066: @table @kbd
067: @item C-@key{SPC}
068: Set the mark at point, and activate it (@code{set-mark-command}).
069: @item C-@@
070: The same.
071: @item C-x C-x
072: Set the mark at point, and activate it; then move point where the mark
073: used to be (@code{exchange-point-and-mark}).
074: @item Drag-mouse-1
075: Set point and the mark around the text you drag across.
076: @item mouse-3
077: Set the mark at point, then move point to where you click
078: (@code{mouse-save-then-kill}).
079: @item @samp{Shifted cursor motion keys}
080: Set the mark at point if the mark is inactive, then move point.
081: @xref{Shift Selection}.
082: @end table
083: 
084: @kindex C-SPC
085: @kindex C-@@
086: @findex set-mark-command
087:   The most common way to set the mark is with @kbd{C-@key{SPC}}
088: (@code{set-mark-command})@footnote{There is no @kbd{C-@key{SPC}}
089: character in @acronym{ASCII}; usually, typing @kbd{C-@key{SPC}} on a
090: text terminal gives the character @kbd{C-@@}.  This key is also bound
091: to @code{set-mark-command}, so unless you are unlucky enough to have
092: a text terminal that behaves differently, you might as well think of
093: @kbd{C-@@} as @kbd{C-@key{SPC}}.}.  This sets the mark where point is,
094: and activates it.  You can then move point away, leaving the mark
095: behind.
096: 
097:   For example, suppose you wish to convert part of the buffer to upper
098: case.  To accomplish this, go to one end of the desired text, type
099: @kbd{C-@key{SPC}}, and move point until the desired portion of text is
100: highlighted.  Now type @kbd{C-x C-u} (@code{upcase-region}).  This
101: converts the text in the region to upper case, and then deactivates
102: the mark.
103: 
104:   Whenever the mark is active, you can deactivate it by typing
105: @kbd{C-g} (@pxref{Quitting}).  Most commands that operate on the
106: region also automatically deactivate the mark, like @kbd{C-x C-u} in
107: the above example.
108: 
109:   Instead of setting the mark in order to operate on a region, you can
110: also use it to remember a position in the buffer (by typing
111: @kbd{C-@key{SPC} C-@key{SPC}}), and later jump back there (by typing
112: @kbd{C-u C-@key{SPC}}).  @xref{Mark Ring}, for details.
113: 
114: @kindex C-x C-x
115: @findex exchange-point-and-mark
116:   The command @kbd{C-x C-x} (@code{exchange-point-and-mark}) exchanges
117: the positions of point and the mark.  @kbd{C-x C-x} is useful when you
118: are satisfied with the position of point but want to move the other
119: end of the region (where the mark is).  Using @kbd{C-x C-x} a second
120: time, if necessary, puts the mark at the new position with point back
121: at its original position.  Normally, if the mark is inactive, this
122: command first reactivates the mark wherever it was last set, to ensure
123: that the region is left highlighted.  However, if you call it with a
124: prefix argument, it leaves the mark inactive and the region
125: unhighlighted; you can use this to jump to the mark in a manner
126: similar to @kbd{C-u C-@key{SPC}}.
127: 
128:   You can also set the mark with the mouse.  If you press the left
129: mouse button (@kbd{down-mouse-1}) and drag the mouse across a range of
130: text, this sets the mark where you first pressed the mouse button and
131: puts point where you release it.  Alternatively, clicking the right
132: mouse button (@kbd{mouse-3}) sets the mark at point and then moves
133: point to where you clicked.  @xref{Mouse Commands}, for a more
134: detailed description of these mouse commands.
135: 
136:   Finally, you can set the mark by holding down the shift key while
137: typing certain cursor motion commands (such as @kbd{S-@key{RIGHT}},
138: @kbd{S-C-f}, @kbd{S-C-n}, etc.).  This is called @dfn{shift-selection}.
139: It sets the mark at point before moving point, but only if there is no
140: active mark set via a previous shift-selection or mouse commands.  The
141: mark set by mouse commands and by shift-selection behaves slightly
142: differently from the usual mark: any subsequent unshifted cursor motion
143: command deactivates it automatically.  For details, see @ref{Shift
144: Selection}.
145: 
146:   Many commands that insert text, such as @kbd{C-y} (@code{yank}), set
147: the mark at the other end of the inserted text, without activating it.
148: This lets you easily return to that position (@pxref{Mark Ring}).  You
149: can tell that a command does this when it shows @samp{Mark set} in the
150: echo area.
151: 
152: @cindex primary selection, when active region changes
153:   Under X, every time the active region changes, Emacs saves the text
154: in the region to the @dfn{primary selection}.  This lets you insert
155: that text into other X applications with @kbd{mouse-2} clicks.
156: @xref{Primary Selection}.
157: 
158: @node Marking Objects
159: @section Commands to Mark Textual Objects
160: 
161: @cindex marking sections of text
162:   Here are commands for placing point and the mark around a textual
163: object such as a word, list, paragraph or page:
164: 
165: @table @kbd
166: @item M-@@
167: Set mark at the end of the next word (@code{mark-word}).  This does not
168: move point.
169: @item C-M-@@
170: Set mark after end of following balanced expression
171: (@code{mark-sexp}).  This does not move point.
172: @item M-h
173: Move point to the beginning of the current paragraph, and set mark at
174: the end (@code{mark-paragraph}).
175: @item C-M-h
176: Move point to the beginning of the current defun, and set mark at the
177: end (@code{mark-defun}).
178: @item C-x C-p
179: Move point to the beginning of the current page, and set mark at the
180: end (@code{mark-page}).
181: @item C-x h
182: Move point to the beginning of the buffer, and set mark at the end
183: (@code{mark-whole-buffer}).
184: @end table
185: 
186: @kindex M-@@
187: @findex mark-word
188:   @kbd{M-@@} (@code{mark-word}) sets the mark at the end of the next
189: word (@pxref{Words}, for information about words).  Repeated
190: invocations of this command extend the region by advancing the mark
191: one word at a time.  As an exception, if the mark is active and
192: located before point, @kbd{M-@@} moves the mark backwards from its
193: current position one word at a time.
194: 
195:   This command also accepts a numeric argument @var{n}, which tells it
196: to advance the mark by @var{n} words.  A negative argument moves the
197: mark back by @var{n} words.
198: 
199: @kindex C-M-@@
200: @findex mark-sexp
201:   Similarly, @kbd{C-M-@@} (@code{mark-sexp}) puts the mark at the end
202: of the next balanced expression (@pxref{Expressions}).  Repeated
203: invocations extend the region to subsequent expressions, while
204: positive or negative numeric arguments move the mark forward or
205: backward by the specified number of expressions.
206: 
207:    The other commands in the above list set both point and mark, so as
208: to delimit an object in the buffer.  @kbd{M-h} (@code{mark-paragraph})
209: marks paragraphs (@pxref{Paragraphs}), @kbd{C-M-h} (@code{mark-defun})
210: marks top-level definitions (@pxref{Moving by Defuns}), and @kbd{C-x
211: C-p} (@code{mark-page}) marks pages (@pxref{Pages}).  Repeated
212: invocations again play the same role, extending the region to
213: consecutive objects; similarly, numeric arguments specify how many
214: objects to move the mark by.
215: 
216: @kindex C-x h
217: @findex mark-whole-buffer
218: @cindex select all
219:   @kbd{C-x h} (@code{mark-whole-buffer}) sets up the entire buffer as
220: the region, by putting point at the beginning and the mark at the end.
221: 
222: @node Using Region
223: @section Operating on the Region
224: 
225: @cindex operations on a marked region
226:   Once you have a region, here are some of the ways you can operate on
227: it:
228: 
229: @itemize @bullet
230: @item
231: Kill it with @kbd{C-w} (@pxref{Killing}).
232: @item
233: Copy it to the kill ring with @kbd{M-w} (@pxref{Yanking}).
234: @item
235: Convert case with @kbd{C-x C-l} or @kbd{C-x C-u} (@pxref{Case}).
236: @item
237: Undo changes within it using @kbd{C-u C-/} (@pxref{Undo}).
238: @item
239: Replace text within it using @kbd{M-%} (@pxref{Query Replace}).
240: @item
241: Indent it with @kbd{C-x @key{TAB}} or @kbd{C-M-\} (@pxref{Indentation}).
242: @item
243: Fill it as text with @kbd{M-x fill-region} (@pxref{Filling}).
244: @item
245: Check the spelling of words within it with @kbd{M-$} (@pxref{Spelling}).
246: @item
247: Evaluate it as Lisp code with @kbd{M-x eval-region} (@pxref{Lisp Eval}).
248: @item
249: Save it in a register with @kbd{C-x r s} (@pxref{Registers}).
250: @item
251: Save it in a buffer or a file (@pxref{Accumulating Text}).
252: @end itemize
253: 
254:   Some commands have a default behavior when the mark is inactive, but
255: operate on the region if the mark is active.  For example, @kbd{M-$}
256: (@code{ispell-word}) normally checks the spelling of the word at
257: point, but it checks the text in the region if the mark is active
258: (@pxref{Spelling}).  Normally, such commands use their default
259: behavior if the region is empty (i.e., if mark and point are at the
260: same position).  If you want them to operate on the empty region,
261: change the variable @code{use-empty-active-region} to @code{t}.
262: 
263: @vindex delete-active-region
264:   As described in @ref{Erasing}, the @key{DEL}
265: (@code{backward-delete-char}) and @key{Delete}
266: (@code{delete-forward-char}) commands also act this way.  If the mark
267: is active, they delete the text in the region.  (As an exception, if
268: you supply a numeric argument @var{n}, where @var{n} is not one, these
269: commands delete @var{n} characters regardless of whether the mark is
270: active).  If you change the variable @code{delete-active-region} to
271: @code{nil}, then these commands don't act differently when the mark is
272: active.  If you change the value to @code{kill}, these commands
273: @dfn{kill} the region instead of deleting it (@pxref{Killing}).
274: 
275: @vindex mark-even-if-inactive
276:   Other commands always operate on the region, and have no default
277: behavior.  Such commands usually have the word @code{region} in their
278: names, like @kbd{C-w} (@code{kill-region}) and @kbd{C-x C-u}
279: (@code{upcase-region}).  If the mark is inactive, they operate on the
280: @dfn{inactive region}---that is, on the text between point and the
281: position at which the mark was last set (@pxref{Mark Ring}).  To
282: disable this behavior, change the variable
283: @code{mark-even-if-inactive} to @code{nil}.  Then these commands will
284: instead signal an error if the mark is inactive.
285: 
286: @cindex Delete Selection mode
287: @cindex mode, Delete Selection
288: @findex delete-selection-mode
289:   By default, text insertion occurs normally even if the mark is
290: active---for example, typing @kbd{a} inserts the character @samp{a},
291: then deactivates the mark.  Delete Selection mode, a minor mode,
292: modifies this behavior: if you enable that mode, then inserting text
293: while the mark is active causes the text in the region to be deleted
294: first.  To toggle Delete Selection mode on or off, type @kbd{M-x
295: delete-selection-mode}.
296: 
297: @node Mark Ring
298: @section The Mark Ring
299: 
300: @cindex mark ring
301:   Each buffer remembers previous locations of the mark, in the
302: @dfn{mark ring}.  Commands that set the mark also push the old mark
303: onto this ring.  One of the uses of the mark ring is to remember spots
304: that you may want to go back to.
305: 
306: @table @kbd
307: @item C-@key{SPC} C-@key{SPC}
308: Set the mark, pushing it onto the mark ring, without activating it.
309: @item C-u C-@key{SPC}
310: Move point to where the mark was, and restore the mark from the ring
311: of former marks.
312: @end table
313: 
314: @kindex C-SPC C-SPC
315:   The command @kbd{C-@key{SPC} C-@key{SPC}} is handy when you want to
316: use the mark to remember a position to which you may wish to return.
317: It pushes the current point onto the mark ring, without activating the
318: mark (which would cause Emacs to highlight the region).  This is
319: actually two consecutive invocations of @kbd{C-@key{SPC}}
320: (@code{set-mark-command}); the first @kbd{C-@key{SPC}} sets the mark,
321: and the second @kbd{C-@key{SPC}} deactivates it.  (When Transient Mark
322: mode is off, @kbd{C-@key{SPC} C-@key{SPC}} instead activates Transient
323: Mark mode temporarily; @pxref{Disabled Transient Mark}.)
324: 
325: @kindex C-u C-SPC
326:   To return to a marked position, use @code{set-mark-command} with a
327: prefix argument: @kbd{C-u C-@key{SPC}}.  This moves point to where the
328: mark was, and deactivates the mark if it was active.  Each subsequent
329: @kbd{C-u C-@key{SPC}} jumps to a prior position stored in the mark
330: ring.  The positions you move through in this way are not lost; they
331: go to the end of the ring.
332: 
333: @vindex set-mark-command-repeat-pop
334:   If you set @code{set-mark-command-repeat-pop} to non-@code{nil},
335: then immediately after you type @kbd{C-u C-@key{SPC}}, you can type
336: @kbd{C-@key{SPC}} instead of @kbd{C-u C-@key{SPC}} to cycle through
337: the mark ring.  By default, @code{set-mark-command-repeat-pop} is
338: @code{nil}.
339: 
340:   Each buffer has its own mark ring.  All editing commands use the
341: current buffer's mark ring.  In particular, @kbd{C-u C-@key{SPC}}
342: always stays in the same buffer.
343: 
344: @vindex mark-ring-max
345:   The variable @code{mark-ring-max} specifies the maximum number of
346: entries to keep in the mark ring.  This defaults to 16 entries.  If
347: that many entries exist and another one is pushed, the earliest one in
348: the list is discarded.  Repeating @kbd{C-u C-@key{SPC}} cycles through
349: the positions currently in the ring.
350: 
351:   If you want to move back to the same place over and over, the mark
352: ring may not be convenient enough.  If so, you can record the position
353: in a register for later retrieval (@pxref{Position Registers,, Saving
354: Positions in Registers}).
355: 
356: @node Global Mark Ring
357: @section The Global Mark Ring
358: @cindex global mark ring
359: 
360: @vindex global-mark-ring-max
361:   In addition to the ordinary mark ring that belongs to each buffer,
362: Emacs has a single @dfn{global mark ring}.  Each time you set a mark,
363: this is recorded in the global mark ring in addition to the current
364: buffer's own mark ring, if you have switched buffers since the
365: previous mark setting.  Hence, the global mark ring records a sequence
366: of buffers that you have been in, and, for each buffer, a place where
367: you set the mark.  The length of the global mark ring is controlled by
368: @code{global-mark-ring-max}, and is 16 by default.
369: 
370: @kindex C-x C-SPC
371: @findex pop-global-mark
372:   The command @kbd{C-x C-@key{SPC}} (@code{pop-global-mark}) jumps to
373: the buffer and position of the latest entry in the global ring.  It also
374: rotates the ring, so that successive uses of @kbd{C-x C-@key{SPC}} take
375: you to earlier buffers and mark positions.
376: 
377: @node Shift Selection
378: @section Shift Selection
379: @cindex shift-selection
380: 
381:   If you hold down the shift key while typing a cursor motion command,
382: this sets the mark before moving point, so that the region extends
383: from the original position of point to its new position.  This feature
384: is referred to as @dfn{shift-selection}.  It is similar to the way
385: text is selected in other editors.
386: 
387:   The mark set via shift-selection behaves a little differently from
388: what we have described above.  Firstly, in addition to the usual ways
389: of deactivating the mark (such as changing the buffer text or typing
390: @kbd{C-g}), the mark is deactivated by any @emph{unshifted} cursor
391: motion command.  Secondly, any subsequent @emph{shifted} cursor motion
392: command avoids setting the mark anew.  Therefore, a series of shifted
393: cursor motion commands will continuously adjust the region.
394: 
395:   Shift-selection only works if the shifted cursor motion key is not
396: already bound to a separate command (@pxref{Customization}).  For
397: example, if you bind @kbd{S-C-f} to another command, typing
398: @kbd{S-C-f} runs that command instead of performing a shift-selected
399: version of @kbd{C-f} (@code{forward-char}).
400: 
401:   A mark set via mouse commands behaves the same as a mark set via
402: shift-selection (@pxref{Setting Mark}).  For example, if you specify a
403: region by dragging the mouse, you can continue to extend the region
404: using shifted cursor motion commands.  In either case, any unshifted
405: cursor motion command deactivates the mark.
406: 
407:   To turn off shift-selection, set @code{shift-select-mode} to
408: @code{nil}.  Doing so does not disable setting the mark via mouse
409: commands.
410: 
411: @node Disabled Transient Mark
412: @section Disabling Transient Mark Mode
413: @cindex mode, Transient Mark
414: @cindex Transient Mark mode
415: @cindex highlighting region
416: @cindex region highlighting
417: @cindex Zmacs mode
418: @findex transient-mark-mode
419: 
420:   The default behavior of the mark and region, in which setting the
421: mark activates it and highlights the region, is called Transient Mark
422: mode.  This is a minor mode that is enabled by default.  It can be
423: toggled with @kbd{M-x transient-mark-mode}, or with the @samp{Active
424: Region Highlighting} menu item in the @samp{Options} menu.  Turning it
425: off switches Emacs to an alternative mode of operation:
426: 
427: @itemize @bullet
428: @item
429: Setting the mark, with commands like @kbd{C-@key{SPC}} or @kbd{C-x
430: C-x}, does not highlight the region.  Therefore, you can't tell by
431: looking where the mark is located; you have to remember.
432: 
433: The usual solution to this problem is to set the mark and then use it
434: soon, before you forget where it is.  You can also check where the
435: mark is by using @kbd{C-x C-x}, which exchanges the positions of the
436: point and the mark (@pxref{Setting Mark}).
437: 
438: @item
439: Some commands, which ordinarily act on the region when the mark is
440: active, no longer do so.  For example, normally @kbd{M-%}
441: (@code{query-replace}) performs replacements within the region, if the
442: mark is active.  When Transient Mark mode is off, it always operates
443: from point to the end of the buffer.  Commands that act this way are
444: identified in their own documentation.
445: @end itemize
446: 
447: @cindex enabling Transient Mark mode temporarily
448:   While Transient Mark mode is off, you can activate it temporarily
449: using @kbd{C-@key{SPC} C-@key{SPC}} or @kbd{C-u C-x C-x}.
450: 
451: @table @kbd
452: @item C-@key{SPC} C-@key{SPC}
453: @kindex C-SPC C-SPC@r{, enabling Transient Mark mode temporarily}
454: Set the mark at point (like plain @kbd{C-@key{SPC}}) and enable
455: Transient Mark mode just once, until the mark is deactivated.  (This
456: is not really a separate command; you are using the @kbd{C-@key{SPC}}
457: command twice.)
458: 
459: @item C-u C-x C-x
460: @kindex C-u C-x C-x
461: Exchange point and mark, activate the mark and enable Transient Mark
462: mode temporarily, until the mark is next deactivated.  (This is the
463: @kbd{C-x C-x} command, @code{exchange-point-and-mark}, with a prefix
464: argument.)
465: @end table
466: 
467:   These commands set or activate the mark, and enable Transient Mark
468: mode only until the mark is deactivated.  One reason you may want to
469: use them is that some commands operate on the entire buffer instead of
470: the region when Transient Mark mode is off.  Enabling Transient Mark
471: mode momentarily gives you a way to use these commands on the region.
472: 
473:   When you specify a region with the mouse (@pxref{Setting Mark}), or
474: with shift-selection (@pxref{Shift Selection}), this likewise
475: activates Transient Mark mode temporarily and highlights the region.
476: