Previous: , Up: Markers   [Contents][Index]


42.7 The Region

The text between point and the mark is known as the region. Various functions operate on text delimited by point and the mark, but only those functions specifically related to the region itself are described here.

When zmacs-regions is non-nil (this is the default), the concept of an active region exists. The region is active when the corresponding mark is active. Note that only one active region at a time can exist—i.e. only one buffer’s region is active at a time. See The Mark, for more information about active regions.

User Option: zmacs-regions

If non-nil (the default), active regions are used. See The Mark, for a detailed explanation of what this means.

A number of functions are provided for explicitly determining the bounds of the region and whether it is active. Few programs need to use these functions, however. A command designed to operate on a region should normally use interactive with the ‘r’ specification to find the beginning and end of the region. This lets other Lisp programs specify the bounds explicitly as arguments and automatically respects the user’s setting for zmacs-regions. (See Interactive Codes.)

Function: region-beginning &optional buffer

This function returns the position of the beginning of buffer’s region (as an integer). This is the position of either point or the mark, whichever is smaller. buffer defaults to the current buffer if omitted.

If the mark does not point anywhere, an error is signaled. Note that this function ignores whether the region is active.

Function: region-end &optional buffer

This function returns the position of the end of buffer’s region (as an integer). This is the position of either point or the mark, whichever is larger. buffer defaults to the current buffer if omitted.

If the mark does not point anywhere, an error is signaled. Note that this function ignores whether the region is active.

Function: region-exists-p

This function is non-nil if the region exists. If active regions are in use (i.e. zmacs-regions is true), this means that the region is active. Otherwise, this means that the user has pushed a mark in this buffer at some point in the past. If this function returns nil, a function that uses the ‘r’ interactive specification will cause an error when called interactively.

Function: region-active-p

If zmacs-regions is true, this is equivalent to region-exists-p. Otherwise, this function always returns false. This function is used by commands such as fill-paragraph-or-region and capitalize-region-or-word, which operate either on the active region or on something else (e.g. the word or paragraph at point).

Variable: zmacs-region-stays

If a command sets this variable to true, the currently active region will remain activated when the command finishes. (Normally the region is deactivated when each command terminates.) If zmacs-regions is false, however, this has no effect. Under normal circumstances, you do not need to set this; use the interactive specification ‘_’ instead, if you want the region to remain active.

Function: zmacs-activate-region

This function activates the region in the current buffer (this is equivalent to activating the current buffer’s mark). This will normally also highlight the text in the active region and set zmacs-region-stays to t. (If zmacs-regions is false, however, this function has no effect.)

Function: zmacs-deactivate-region

This function deactivates the region in the current buffer (this is equivalent to deactivating the current buffer’s mark). This will normally also unhighlight the text in the active region and set zmacs-region-stays to nil. (If zmacs-regions is false, however, this function has no effect.)

Function: zmacs-update-region

This function updates the active region, if it’s currently active. (If there is no active region, this function does nothing.) This has the effect of updating the highlighting on the text in the region; but you should never need to call this except under rather strange circumstances. The command loop automatically calls it when appropriate. Calling this function will call the hook zmacs-update-region-hook, if the region is active.

Variable: zmacs-activate-region-hook

This normal hook is called when a region becomes active. (Usually this happens as a result of a command that activates the region, such as set-mark-command, activate-region, or exchange-point-and-mark.) Note that calling zmacs-activate-region will call this hook, even if the region is already active. If zmacs-regions is false, however, this hook will never get called under any circumstances.

Variable: zmacs-deactivate-region-hook

This normal hook is called when an active region becomes inactive. (Calling zmacs-deactivate-region when the region is inactive will not cause this hook to be called.) If zmacs-regions is false, this hook will never get called.

Variable: zmacs-update-region-hook

This normal hook is called when an active region is "updated" by zmacs-update-region. This normally gets called at the end of each command that sets zmacs-region-stays to t, indicating that the region should remain activated. The motion commands do this.


Previous: , Up: Markers   [Contents][Index]