GNU Info
(elisp)The Mark
The Mark ======== One special marker in each buffer is designated "the mark". It records a position for the user for the sake of commands such as `kill-region' and `indent-rigidly'. Lisp programs should set the mark only to values that have a potential use to the user, and never for their own internal purposes. For example, the `replace-regexp' command sets the mark to the value of point before doing any replacements, because this enables the user to move back there conveniently after the replace is finished. Many commands are designed so that when called interactively they operate on the text between point and the mark. If you are writing such a command, don't examine the mark directly; instead, use `interactive' with the `r' specification. This provides the values of point and the mark as arguments to the command in an interactive call, but permits other Lisp programs to specify arguments explicitly. Note: Interactive Codes. Each buffer has its own value of the mark that is independent of the value of the mark in other buffers. When a buffer is created, the mark exists but does not point anywhere. We consider this state as "the absence of a mark in that buffer." Once the mark "exists" in a buffer, it normally never ceases to exist. However, it may become "inactive", if Transient Mark mode is enabled. The variable `mark-active', which is always buffer-local in all buffers, indicates whether the mark is active: non-`nil' means yes. A command can request deactivation of the mark upon return to the editor command loop by setting `deactivate-mark' to a non-`nil' value (but this causes deactivation only if Transient Mark mode is enabled). The main motivation for using Transient Mark mode is that this mode also enables highlighting of the region when the mark is active. Note: Display. In addition to the mark, each buffer has a "mark ring" which is a list of markers containing previous values of the mark. When editing commands change the mark, they should normally save the old value of the mark on the mark ring. The variable `mark-ring-max' specifies the maximum number of entries in the mark ring; once the list becomes this long, adding a new element deletes the last element. There is also a separate global mark ring, but that is used only in a few particular user-level commands, and is not relevant to Lisp programming. So we do not describe it here. - Function: mark &optional force This function returns the current buffer's mark position as an integer. If the mark is inactive, `mark' normally signals an error. However, if FORCE is non-`nil', then `mark' returns the mark position anyway--or `nil', if the mark is not yet set for this buffer. - Function: mark-marker This function returns the current buffer's mark. This is the very marker that records the mark location inside Emacs, not a copy. Therefore, changing this marker's position will directly affect the position of the mark. Don't do it unless that is the effect you want. (setq m (mark-marker)) => #<marker at 3420 in markers.texi> (set-marker m 100) => #<marker at 100 in markers.texi> (mark-marker) => #<marker at 100 in markers.texi> Like any marker, this marker can be set to point at any buffer you like. We don't recommend that you make it point at any buffer other than the one of which it is the mark. If you do, it will yield perfectly consistent, but rather odd, results. - Function: set-mark position This function sets the mark to POSITION, and activates the mark. The old value of the mark is _not_ pushed onto the mark ring. *Please note:* Use this function only if you want the user to see that the mark has moved, and you want the previous mark position to be lost. Normally, when a new mark is set, the old one should go on the `mark-ring'. For this reason, most applications should use `push-mark' and `pop-mark', not `set-mark'. Novice Emacs Lisp programmers often try to use the mark for the wrong purposes. The mark saves a location for the user's convenience. An editing command should not alter the mark unless altering the mark is part of the user-level functionality of the command. (And, in that case, this effect should be documented.) To remember a location for internal use in the Lisp program, store it in a Lisp variable. For example: (let ((beg (point))) (forward-line 1) (delete-region beg (point))). - Function: push-mark &optional position nomsg activate This function sets the current buffer's mark to POSITION, and pushes a copy of the previous mark onto `mark-ring'. If POSITION is `nil', then the value of point is used. `push-mark' returns `nil'. The function `push-mark' normally _does not_ activate the mark. To do that, specify `t' for the argument ACTIVATE. A `Mark set' message is displayed unless NOMSG is non-`nil'. - Function: pop-mark This function pops off the top element of `mark-ring' and makes that mark become the buffer's actual mark. This does not move point in the buffer, and it does nothing if `mark-ring' is empty. It deactivates the mark. The return value is not meaningful. - User Option: transient-mark-mode This variable if non-`nil' enables Transient Mark mode, in which every buffer-modifying primitive sets `deactivate-mark'. The consequence of this is that commands that modify the buffer normally make the mark inactive. - User Option: mark-even-if-inactive If this is non-`nil', Lisp programs and the Emacs user can use the mark even when it is inactive. This option affects the behavior of Transient Mark mode. When the option is non-`nil', deactivation of the mark turns off region highlighting, but commands that use the mark behave as if the mark were still active. - Variable: deactivate-mark If an editor command sets this variable non-`nil', then the editor command loop deactivates the mark after the command returns (if Transient Mark mode is enabled). All the primitives that change the buffer set `deactivate-mark', to deactivate the mark when the command is finished. - Function: deactivate-mark This function deactivates the mark, if Transient Mark mode is enabled. Otherwise it does nothing. - Variable: mark-active The mark is active when this variable is non-`nil'. This variable is always buffer-local in each buffer. - Variable: activate-mark-hook - Variable: deactivate-mark-hook These normal hooks are run, respectively, when the mark becomes active and when it becomes inactive. The hook `activate-mark-hook' is also run at the end of a command if the mark is active and it is possible that the region may have changed. - Variable: mark-ring The value of this buffer-local variable is the list of saved former marks of the current buffer, most recent first. mark-ring => (#<marker at 11050 in markers.texi> #<marker at 10832 in markers.texi> ...) - User Option: mark-ring-max The value of this variable is the maximum size of `mark-ring'. If more marks than this are pushed onto the `mark-ring', `push-mark' discards an old mark when it adds a new one.
automatically generated by info2www version 1.2.2.9