Mercurial > emacs
comparison doc/lispref/markers.texi @ 102855:17ba809d0f96
* markers.texi (The Mark): Copyedits. Improve description of
handle-shift-selection.
(The Region): Move use-region-p here from The Mark.
author | Chong Yidong <cyd@stupidchicken.com> |
---|---|
date | Mon, 06 Apr 2009 01:20:55 +0000 |
parents | b713c93aa5ba |
children | 60606ee8aee7 |
comparison
equal
deleted
inserted
replaced
102854:326cfd14d174 | 102855:17ba809d0f96 |
---|---|
390 @node The Mark | 390 @node The Mark |
391 @section The Mark | 391 @section The Mark |
392 @cindex mark, the | 392 @cindex mark, the |
393 @cindex mark ring | 393 @cindex mark ring |
394 | 394 |
395 One special marker in each buffer is designated @dfn{the mark}. It | 395 Each buffer has a special marker, which is designated @dfn{the |
396 specifies a position to bound a range of text for commands such as | 396 mark}. When a buffer is newly created, this marker exists but does |
397 @code{kill-region} and @code{indent-rigidly}. Lisp programs should | 397 not point anywhere; this means that the mark ``doesn't exist'' in that |
398 set the mark only to values that have a potential use to the user, and | 398 buffer yet. Subsequent commands can set the mark. |
399 never for their own internal purposes. For example, the | 399 |
400 @code{replace-regexp} command sets the mark to the value of point | 400 The mark specifies a position to bound a range of text for many |
401 before doing any replacements, because this enables the user to move | 401 commands, such as @code{kill-region} and @code{indent-rigidly}. These |
402 back there conveniently after the replace is finished. | 402 commands typically act on the text between point and the mark, which |
403 | 403 is called the @dfn{region}. If you are writing a command that |
404 Many commands are designed to operate on the text between point and | 404 operates on the region, don't examine the mark directly; instead, use |
405 the mark when called interactively. If you are writing such a | |
406 command, don't examine the mark directly; instead, use | |
407 @code{interactive} with the @samp{r} specification. This provides the | 405 @code{interactive} with the @samp{r} specification. This provides the |
408 values of point and the mark as arguments to the command in an | 406 values of point and the mark as arguments to the command in an |
409 interactive call, but permits other Lisp programs to specify arguments | 407 interactive call, but permits other Lisp programs to specify arguments |
410 explicitly. @xref{Interactive Codes}. | 408 explicitly. @xref{Interactive Codes}. |
411 | 409 |
412 Each buffer has a marker which represents the value of the mark in | 410 Some commands set the mark as a side-effect. Commands should do |
413 that buffer, independent of any other buffer. When a buffer is newly | 411 this only if it has a potential use to the user, and never for their |
414 created, this marker exists but does not point anywhere. That means | 412 own internal purposes. For example, the @code{replace-regexp} command |
415 the mark ``doesn't exist'' in that buffer as yet. | 413 sets the mark to the value of point before doing any replacements, |
414 because this enables the user to move back there conveniently after | |
415 the replace is finished. | |
416 | 416 |
417 Once the mark ``exists'' in a buffer, it normally never ceases to | 417 Once the mark ``exists'' in a buffer, it normally never ceases to |
418 exist. However, it may become @dfn{inactive}, if Transient Mark mode is | 418 exist. However, it may become @dfn{inactive}, if Transient Mark mode |
419 enabled. The variable @code{mark-active}, which is always buffer-local | 419 is enabled. The buffer-local variable @code{mark-active}, if |
420 in all buffers, indicates whether the mark is active: non-@code{nil} | 420 non-@code{nil}, means that the mark is active. A command can call the |
421 means yes. A command can request deactivation of the mark upon return | 421 function @code{deactivate-mark} to deactivate the mark directly, or it |
422 to the editor command loop by setting @code{deactivate-mark} to a | 422 can request deactivation of the mark upon return to the editor command |
423 non-@code{nil} value (but this causes deactivation only if Transient | 423 loop by setting the variable @code{deactivate-mark} to a |
424 Mark mode is enabled). | 424 non-@code{nil} value. |
425 | 425 |
426 Certain editing commands that normally apply to text near point, | 426 If Transient Mode is enabled, certain editing commands that normally |
427 work on the region when Transient Mode is enabled and the mark is | 427 apply to text near point, apply instead to the region when the mark is |
428 active. This is the main motivation for using Transient Mark mode. | 428 active. This is the main motivation for using Transient Mark mode. |
429 | 429 (Another is that this enables highlighting of the region when the mark |
430 Another motivation for using Transient Mark mode is that this mode | 430 is active. @xref{Display}.) |
431 also enables highlighting of the region when the mark is active. | |
432 @xref{Display}. | |
433 | 431 |
434 In addition to the mark, each buffer has a @dfn{mark ring} which is a | 432 In addition to the mark, each buffer has a @dfn{mark ring} which is a |
435 list of markers containing previous values of the mark. When editing | 433 list of markers containing previous values of the mark. When editing |
436 commands change the mark, they should normally save the old value of the | 434 commands change the mark, they should normally save the old value of the |
437 mark on the mark ring. The variable @code{mark-ring-max} specifies the | 435 mark on the mark ring. The variable @code{mark-ring-max} specifies the |
448 or @code{nil} if no mark has ever been set in this buffer. | 446 or @code{nil} if no mark has ever been set in this buffer. |
449 | 447 |
450 If Transient Mark mode is enabled, and @code{mark-even-if-inactive} is | 448 If Transient Mark mode is enabled, and @code{mark-even-if-inactive} is |
451 @code{nil}, @code{mark} signals an error if the mark is inactive. | 449 @code{nil}, @code{mark} signals an error if the mark is inactive. |
452 However, if @var{force} is non-@code{nil}, then @code{mark} disregards | 450 However, if @var{force} is non-@code{nil}, then @code{mark} disregards |
453 inactivity of the mark, and returns the mark position anyway (or | 451 inactivity of the mark, and returns the mark position (or @code{nil}) |
454 @code{nil}). | 452 anyway. |
455 @end defun | 453 @end defun |
456 | 454 |
457 @defun mark-marker | 455 @defun mark-marker |
458 This function returns the marker that represents the current buffer's | 456 This function returns the marker that represents the current buffer's |
459 mark. It is not a copy, it is the marker used internally. Therefore, | 457 mark. It is not a copy, it is the marker used internally. Therefore, |
478 Like any marker, this marker can be set to point at any buffer you | 476 Like any marker, this marker can be set to point at any buffer you |
479 like. If you make it point at any buffer other than the one of which | 477 like. If you make it point at any buffer other than the one of which |
480 it is the mark, it will yield perfectly consistent, but rather odd, | 478 it is the mark, it will yield perfectly consistent, but rather odd, |
481 results. We recommend that you not do it! | 479 results. We recommend that you not do it! |
482 @end defun | 480 @end defun |
483 | |
484 @ignore | |
485 @deffn Command set-mark-command jump | |
486 If @var{jump} is @code{nil}, this command sets the mark to the value | |
487 of point and pushes the previous value of the mark on the mark ring. The | |
488 message @samp{Mark set} is also displayed in the echo area. | |
489 | |
490 If @var{jump} is not @code{nil}, this command sets point to the value | |
491 of the mark, and sets the mark to the previous saved mark value, which | |
492 is popped off the mark ring. | |
493 | |
494 This function is @emph{only} intended for interactive use. | |
495 @end deffn | |
496 @end ignore | |
497 | 481 |
498 @defun set-mark position | 482 @defun set-mark position |
499 This function sets the mark to @var{position}, and activates the mark. | 483 This function sets the mark to @var{position}, and activates the mark. |
500 The old value of the mark is @emph{not} pushed onto the mark ring. | 484 The old value of the mark is @emph{not} pushed onto the mark ring. |
501 | 485 |
520 (delete-region beg (point))). | 504 (delete-region beg (point))). |
521 @end group | 505 @end group |
522 @end example | 506 @end example |
523 @end defun | 507 @end defun |
524 | 508 |
525 @c for interactive use only | |
526 @ignore | |
527 @deffn Command exchange-point-and-mark | |
528 This function exchanges the positions of point and the mark. | |
529 It is intended for interactive use. | |
530 @end deffn | |
531 @end ignore | |
532 | |
533 @defun push-mark &optional position nomsg activate | 509 @defun push-mark &optional position nomsg activate |
534 This function sets the current buffer's mark to @var{position}, and | 510 This function sets the current buffer's mark to @var{position}, and |
535 pushes a copy of the previous mark onto @code{mark-ring}. If | 511 pushes a copy of the previous mark onto @code{mark-ring}. If |
536 @var{position} is @code{nil}, then the value of point is used. | 512 @var{position} is @code{nil}, then the value of point is used. |
537 @code{push-mark} returns @code{nil}. | 513 @code{push-mark} returns @code{nil}. |
551 | 527 |
552 The return value is not meaningful. | 528 The return value is not meaningful. |
553 @end defun | 529 @end defun |
554 | 530 |
555 @defopt transient-mark-mode | 531 @defopt transient-mark-mode |
556 @c @cindex Transient Mark mode Redundant | 532 This variable, if non-@code{nil}, enables Transient Mark mode. In |
557 This variable if non-@code{nil} enables Transient Mark mode, in which | 533 Transient Mark mode, every buffer-modifying primitive sets |
558 every buffer-modifying primitive sets @code{deactivate-mark}. The | 534 @code{deactivate-mark}. As a consequence, most commands that modify |
559 consequence of this is that commands that modify the buffer normally | 535 the buffer also deactivate the mark. |
560 make the mark inactive. | 536 |
561 | 537 When Transient Mark mode is enabled and the mark is active, many |
562 Certain commands normally apply to text near point, but in Transient | 538 commands that normally apply to the text near point instead apply to |
563 Mark mode when the mark is active, they apply to the region instead. | 539 the region. Such commands should use the function @code{use-region-p} |
564 These commands should call @code{use-region-p} to test whether they | 540 to test whether they should operate on the region. @xref{The Region}. |
565 should operate on the region. | |
566 | 541 |
567 Lisp programs can set @code{transient-mark-mode} to non-@code{nil}, | 542 Lisp programs can set @code{transient-mark-mode} to non-@code{nil}, |
568 non-@code{t} values to enable Transient Mark mode temporarily. If the | 543 non-@code{t} values to enable Transient Mark mode temporarily. If the |
569 value is @code{lambda}, Transient Mark mode is automatically turned | 544 value is @code{lambda}, Transient Mark mode is automatically turned |
570 off after any action, such as buffer modification, that would normally | 545 off after any action, such as buffer modification, that would normally |
573 any subsequent command that moves point and is not shift-translated | 548 any subsequent command that moves point and is not shift-translated |
574 (@pxref{Key Sequence Input, shift-translation}), or after any other | 549 (@pxref{Key Sequence Input, shift-translation}), or after any other |
575 action that would normally deactivate the mark. | 550 action that would normally deactivate the mark. |
576 @end defopt | 551 @end defopt |
577 | 552 |
578 @defun use-region-p | |
579 This function returns @code{t} if Transient Mark mode is enabled, the | |
580 mark is active, and there's a valid region in the buffer. Commands | |
581 that operate on the region (instead of on text near point) when | |
582 there's an active mark should use this subroutine to test whether to | |
583 do that. | |
584 @end defun | |
585 | |
586 @defopt mark-even-if-inactive | 553 @defopt mark-even-if-inactive |
587 If this is non-@code{nil}, Lisp programs and the Emacs user can use the | 554 If this is non-@code{nil}, Lisp programs and the Emacs user can use the |
588 mark even when it is inactive. This option affects the behavior of | 555 mark even when it is inactive. This option affects the behavior of |
589 Transient Mark mode. When the option is non-@code{nil}, deactivation of | 556 Transient Mark mode. When the option is non-@code{nil}, deactivation of |
590 the mark turns off region highlighting, but commands that use the mark | 557 the mark turns off region highlighting, but commands that use the mark |
617 @defvar mark-active | 584 @defvar mark-active |
618 The mark is active when this variable is non-@code{nil}. This | 585 The mark is active when this variable is non-@code{nil}. This |
619 variable is always buffer-local in each buffer. Do @emph{not} use the | 586 variable is always buffer-local in each buffer. Do @emph{not} use the |
620 value of this variable to decide whether a command that normally | 587 value of this variable to decide whether a command that normally |
621 operates on text near point should operate on the region instead. Use | 588 operates on text near point should operate on the region instead. Use |
622 the @code{use-region-p} subroutine (see above) for that. | 589 the function @code{use-region-p} for that (@pxref{The Region}). |
623 @end defvar | 590 @end defvar |
624 | 591 |
625 @defvar activate-mark-hook | 592 @defvar activate-mark-hook |
626 @defvarx deactivate-mark-hook | 593 @defvarx deactivate-mark-hook |
627 These normal hooks are run, respectively, when the mark becomes active | 594 These normal hooks are run, respectively, when the mark becomes active |
628 and when it becomes inactive. The hook @code{activate-mark-hook} is | 595 and when it becomes inactive. The hook @code{activate-mark-hook} is |
629 also run at the end of a command if the mark is active and it is | 596 also run at the end of a command if the mark is active and it is |
630 possible that the region may have changed. | 597 possible that the region may have changed. |
631 @end defvar | 598 @end defvar |
632 | 599 |
600 @defun handle-shift-selection | |
601 This function implements the ``shift-selection'' behavior of | |
602 point-motion commands. @xref{Shift Selection,,, emacs, The GNU Emacs | |
603 Manual}. It is called automatically by the Emacs command loop | |
604 whenever a command with a @samp{^} character in its @code{interactive} | |
605 spec is invoked, before the command itself is executed | |
606 (@pxref{Interactive Codes, ^}). | |
607 | |
608 If @code{shift-select-mode} is non-@code{nil} and the current command | |
609 was invoked via shift translation (@pxref{Key Sequence Input, | |
610 shift-translation}), this function sets the mark and temporarily | |
611 activates the region, unless the region was already temporarily | |
612 activated in this way. Otherwise, if the region has been activated | |
613 temporarily, it deactivates the mark and restores the variable | |
614 @code{transient-mark-mode} to its earlier value. | |
615 @end defun | |
616 | |
633 @defvar mark-ring | 617 @defvar mark-ring |
634 The value of this buffer-local variable is the list of saved former | 618 The value of this buffer-local variable is the list of saved former |
635 marks of the current buffer, most recent first. | 619 marks of the current buffer, most recent first. |
636 | 620 |
637 @example | 621 @example |
647 @defopt mark-ring-max | 631 @defopt mark-ring-max |
648 The value of this variable is the maximum size of @code{mark-ring}. If | 632 The value of this variable is the maximum size of @code{mark-ring}. If |
649 more marks than this are pushed onto the @code{mark-ring}, | 633 more marks than this are pushed onto the @code{mark-ring}, |
650 @code{push-mark} discards an old mark when it adds a new one. | 634 @code{push-mark} discards an old mark when it adds a new one. |
651 @end defopt | 635 @end defopt |
652 | |
653 @defun handle-shift-selection | |
654 This function checks whether the current command was invoked via shift | |
655 translation (@pxref{Key Sequence Input, shift-translation}), and if | |
656 so, sets the mark and temporarily activates the region, unless the | |
657 region is already temporarily activated in this way. If the command | |
658 was invoked without shift translation and the region is temporarily | |
659 active, or if the region was activated by the mouse, the function | |
660 deactivates the mark. | |
661 | |
662 This function is called whenever a command with a @samp{^} character | |
663 in its @code{interactive} spec (@pxref{Interactive Codes, ^}) is | |
664 invoked while @code{shift-select-mode} (@pxref{Shift Selection,,, | |
665 emacs, The GNU Emacs Manual}) is non-@code{nil}. | |
666 @end defun | |
667 | 636 |
668 @node The Region | 637 @node The Region |
669 @section The Region | 638 @section The Region |
670 @cindex region (between point and mark) | 639 @cindex region (between point and mark) |
671 | 640 |
696 should normally use @code{interactive} with the @samp{r} specification | 665 should normally use @code{interactive} with the @samp{r} specification |
697 to find the beginning and end of the region. This lets other Lisp | 666 to find the beginning and end of the region. This lets other Lisp |
698 programs specify the bounds explicitly as arguments. (@xref{Interactive | 667 programs specify the bounds explicitly as arguments. (@xref{Interactive |
699 Codes}.) | 668 Codes}.) |
700 | 669 |
670 @defun use-region-p | |
671 This function returns @code{t} if Transient Mark mode is enabled, the | |
672 mark is active, and there's a valid region in the buffer. Commands | |
673 that operate on the region (instead of on text near point) when | |
674 there's an active mark should use this to test whether to do that. | |
675 @end defun | |
676 | |
701 @ignore | 677 @ignore |
702 arch-tag: b1ba2e7a-a0f3-4c5e-875c-7d8e22d73299 | 678 arch-tag: b1ba2e7a-a0f3-4c5e-875c-7d8e22d73299 |
703 @end ignore | 679 @end ignore |