The [selection] command.

Introduction

The selection command lets you manipulate selections in a text document.
Alpha supports multiple selections. Each range is specified by a two-elements Tcl list containing the start and the end positions.
Note that, in case the window has been split into several subpanes, the command always applies to the currently selected pane. Each pane may have its own set of selected ranges.

Synopsis

The formal syntax of the [selection] command is:

selection subcommand ?options?

The possible subcommands are described below. Depending on the subcommand, some additional options may be specified.
All the subcommands of the [selection] command support the -w option in order to specify the window it applies to. If this option is not specified, the frontmost document window is used. If the document window is split in different subpanes, the [selection] command applies to the current pane.

The [clear] subcommand

This subcommand removes a (possibly multiple) selection. The syntax is:

    selection clear ?-w win?

The command applies to all the currently selected ranges: it unselects everything in the current pane.

The [count] subcommand

This subcommand returns the number of currently selected ranges. The complete syntax is:

    selection count ?-w win?

The [delete] subcommand

This subcommand deletes the currently selected text. The syntax is:

    selection delete ?-w win?

The command applies to all the currently selected ranges.

The [empty] subcommand

This subcommand tells if there is a selection. The syntax is:

    selection empty ?-w win?

The command returns a boolean (1 or 0) telling whether the selection is empty or not.

The [extend] subcommand

This subcommand extends the selection to a new position. The syntax is:

    selection extend ?-w win? pos

If the position specified by the pos argument is inside the selected range, nothing happens. If it is less than the selection's start, the selection is extended to the left. If it is greater than the selection's end, the selection is extended to the right.
This command makes sense only for single selections: in the case of an existing multiple selection, the command operates on the first selected range and deselects the others. The command returns the new selected range.

The [find] subcommand

This subcommand finds if a given position or range is inside the current (possibly multiple) selection. The syntax is:

   selection find ?-w win? ?-indices? range

The range argument can be either a single position or a list of two positions corrresponding to an interval. By default, the command returns the index of the selected range (in a multiple selection) containing the given range, or -1 if the given position or range is not included in the selection. In particular, in case of success, the returned index would be 0 if there is a single selection. If the -indices option is specified, the command returns the containing range itself, or an empty string if there is no such range.

The [get] subcommand

This subcommand returns the current (possibly multiple) selection. The syntax is:

   selection get ?-w win? ?-all? ?-indices?

The options have the following meaning:

-all: If the option -all is not specified, the command returns the data corresponding to the first selected range if it exists, or an empty string otherwise. If the option -all is specified, the command returns a list of all the selected chunks (or all the selected ranges if the -indices option is specified).
-indices: If the option -indices is not specified, the command returns the selected text. Otherwise, it returns the corresponding range, i-e a two elements list containing the start and end positions of the selected text.

Note that if both the options -all and -indices are on, the result is a list of pairs, even if there is only one selected region. For instance, if the region between positions 120 and 135 were selected, the return value would be {120 135} with the option -all and 120 135 without it. In order to detect if there is a multiple selection, one can also use the [selection count] command.

The [set] subcommand

This subcommand installs a (possibly multiple) selection. The syntax is:

    selection set ?-w win? ?{start end}...?
    selection set ?-w win? start end

The command clears the current selection before installing the new one. In the first form, the arguments are two-element lists containing the start and end position of each range. The second syntax installs a single selection and is supported for compatibility reasons.

Last updated 2019-10-17 13:29:35