Mercurial > emacs
comparison doc/lispref/markers.texi @ 98784:ae2c057fb447
(The Mark): Document use-region-p.
author | Eli Zaretskii <eliz@gnu.org> |
---|---|
date | Thu, 16 Oct 2008 20:05:32 +0000 |
parents | ef39b163f82b |
children | b5ddab370f08 |
comparison
equal
deleted
inserted
replaced
98783:9ae4dbce33ae | 98784:ae2c057fb447 |
---|---|
421 means yes. A command can request deactivation of the mark upon return | 421 means yes. A command can request deactivation of the mark upon return |
422 to the editor command loop by setting @code{deactivate-mark} to a | 422 to the editor command loop by setting @code{deactivate-mark} to a |
423 non-@code{nil} value (but this causes deactivation only if Transient | 423 non-@code{nil} value (but this causes deactivation only if Transient |
424 Mark mode is enabled). | 424 Mark mode is enabled). |
425 | 425 |
426 The main motivation for using Transient Mark mode is that this mode | 426 Certain editing commands that normally apply to text near point, |
427 work on the region when Transient Mode is enabled and the mark is | |
428 active. This is the main motivation for using Transient Mark mode. | |
429 | |
430 Another motivation for using Transient Mark mode is that this mode | |
427 also enables highlighting of the region when the mark is active. | 431 also enables highlighting of the region when the mark is active. |
428 @xref{Display}. | 432 @xref{Display}. |
429 | 433 |
430 In addition to the mark, each buffer has a @dfn{mark ring} which is a | 434 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 | 435 list of markers containing previous values of the mark. When editing |
552 @c @cindex Transient Mark mode Redundant | 556 @c @cindex Transient Mark mode Redundant |
553 This variable if non-@code{nil} enables Transient Mark mode, in which | 557 This variable if non-@code{nil} enables Transient Mark mode, in which |
554 every buffer-modifying primitive sets @code{deactivate-mark}. The | 558 every buffer-modifying primitive sets @code{deactivate-mark}. The |
555 consequence of this is that commands that modify the buffer normally | 559 consequence of this is that commands that modify the buffer normally |
556 make the mark inactive. | 560 make the mark inactive. |
561 | |
562 Certain commands normally apply to text near point, but in Transient | |
563 Mark mode when the mark is active, they apply to the region instead. | |
564 These commands should call @code{use-region-p} to test whether they | |
565 should operate on the region. | |
557 | 566 |
558 Lisp programs can set @code{transient-mark-mode} to non-@code{nil}, | 567 Lisp programs can set @code{transient-mark-mode} to non-@code{nil}, |
559 non-@code{t} values to enable Transient Mark mode temporarily. If the | 568 non-@code{t} values to enable Transient Mark mode temporarily. If the |
560 value is @code{lambda}, Transient Mark mode is automatically turned | 569 value is @code{lambda}, Transient Mark mode is automatically turned |
561 off after any action, such as buffer modification, that would normally | 570 off after any action, such as buffer modification, that would normally |
564 any subsequent command that moves point and is not shift-translated | 573 any subsequent command that moves point and is not shift-translated |
565 (@pxref{Key Sequence Input, shift-translation}), or after any other | 574 (@pxref{Key Sequence Input, shift-translation}), or after any other |
566 action that would normally deactivate the mark. | 575 action that would normally deactivate the mark. |
567 @end defopt | 576 @end defopt |
568 | 577 |
578 @deffn Subroutine 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 deffn | |
585 | |
569 @defopt mark-even-if-inactive | 586 @defopt mark-even-if-inactive |
570 If this is non-@code{nil}, Lisp programs and the Emacs user can use the | 587 If this is non-@code{nil}, Lisp programs and the Emacs user can use the |
571 mark even when it is inactive. This option affects the behavior of | 588 mark even when it is inactive. This option affects the behavior of |
572 Transient Mark mode. When the option is non-@code{nil}, deactivation of | 589 Transient Mark mode. When the option is non-@code{nil}, deactivation of |
573 the mark turns off region highlighting, but commands that use the mark | 590 the mark turns off region highlighting, but commands that use the mark |
596 This function deactivates the mark, if Transient Mark mode is enabled. | 613 This function deactivates the mark, if Transient Mark mode is enabled. |
597 Otherwise it does nothing. | 614 Otherwise it does nothing. |
598 @end defun | 615 @end defun |
599 | 616 |
600 @defvar mark-active | 617 @defvar mark-active |
601 The mark is active when this variable is non-@code{nil}. This variable | 618 The mark is active when this variable is non-@code{nil}. This |
602 is always buffer-local in each buffer. | 619 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 | |
621 operates on text near point should operate on the region instead. Use | |
622 the @code{use-region-p} subroutine (see above) for that. | |
603 @end defvar | 623 @end defvar |
604 | 624 |
605 @defvar activate-mark-hook | 625 @defvar activate-mark-hook |
606 @defvarx deactivate-mark-hook | 626 @defvarx deactivate-mark-hook |
607 These normal hooks are run, respectively, when the mark becomes active | 627 These normal hooks are run, respectively, when the mark becomes active |