show-region(2)

NAME

show-region - Show the current copy region

SYNOPSIS

n show-region

DESCRIPTION

show-region manipulates the currently defined region, it can be used to inquire the state of the current region, if any. It can also be used to define a region, enable and disable the region hilighting, as well as move the cursor to the start or end of the region.

Region hilighting occurs between the mark (see set-mark(2)) and point (current cursor) positions within the current buffer. A region is defined when text is copied to the kill buffer, by using any of the kill commands such as kill-region(2), or copy-region(2). However, the kill region is only visible after a copy-region(2) or a yank(2) operation. A hilight region is also created on a successful search using commands like search-forward(2), the region encloses the search matching string. Spell(2) also creates a hilight region around the current spell word. The user can also define their own region using the numeric argument to show-region.

The argument n supplied to the command indicates the require functionality and can take the following values:-

-3 - Set the start position of the region.
-2 - Move the cursor the  Mark position.
-1 - Disable the hilighting of the current region.
 0 - Return the current status of the region in
$result(5).
 1 - Enable the hilighting of the current region.
 2 - Move the cursor the  Dot position.
 3 - Set the end position of the region.

Where an argument of 0 is used to return the current state the value of $result is a bit based flag where:-

0x01


Indicates a region is currently active (visible).

0x02


Indicates a region has been fixed (may not visible).

0x04


Indicates the region is in the current buffer.

0x08


Indicates the cursor is in the current region.

The color of the selection hilight is defined by add-color-scheme(2) and is determined by $buffer-scheme(5), $global-scheme(5) or $buffer-hilight(5).

DIAGNOSTICS

The following errors can be generated, in each case the command returns a FALSE status:

[No current region]


There is no current defined region on which to operate.

[Current region not in this buffer]


An argument of 2 or -2 was used and the defined region isn't in the current window so the cursor can not be moved to it.

NOTES

If no argument is given to the command it hilights the current region, similar to an argument of 1. But the properties of the hilight, namely how long it will be hilighted for, are inherited from the setting of $show-region(5), whereas if an argument of 1 is passed in then the hilighting is set to be kept until the region becomes invalid (i.e. as if $show-region(5) is set to 3).

SEE ALSO

$show-region(5), $buffer-hilight(5), $buffer-scheme(5), $global-scheme(5), add-color-scheme(2), copy-region(2), yank(2), search-forward(2), spell(2), set-mark(2).

(c) Copyright JASSPA 1999
Last Modified: 1998/06/16
Generated On: 1999/12/01