Skip to content

Multiple Selection and Virtual Space

Note

This page is adapted from the upstream Scintilla 5.6.3 documentation (ScintillaDoc.html), converted to Markdown for this site. It documents the underlying ScintillaEditBase.send/sends message API -- see the API reference for the Python bindings themselves.

There may be multiple selections active at one time. More selections are made by holding down the Ctrl key while dragging with the mouse. The most recent selection is the main selection and determines which part of the document is shown automatically. Any selection apart from the main selection is called an additional selection. The calls in the previous section operate on the main selection. There is always at least one selection. The selection can be simplified down to just the main selection by SCI_CANCEL which is normally mapped to the Esc key.

Rectangular selections are handled as multiple selections although the original rectangular range is remembered so that subsequent operations may be handled differently for rectangular selections. For example, pasting a rectangular selection places each piece in a vertical column.

Virtual space is space beyond the end of each line. The caret may be moved into virtual space but no real space will be added to the document until there is some text typed or some other text insertion command is used.

When discontiguous selections are copied to the clipboard, each selection is added to the clipboard text in order with no delimiting characters. For rectangular selections the document's line end is added after each line's text. Rectangular selections are always copied from top line to bottom, not in the in order of selection. Virtual space is not copied.

SCI_SETMULTIPLESELECTION(bool multipleSelection)

SCI_GETMULTIPLESELECTION → bool

Enable or disable multiple selection. When multiple selection is disabled, it is not possible to select multiple ranges by holding down the Ctrl key while dragging with the mouse.

SCI_SETADDITIONALSELECTIONTYPING(bool additionalSelectionTyping)

SCI_GETADDITIONALSELECTIONTYPING → bool

Whether typing, new line, cursor left/right/up/down, backspace, delete, home, and end work with multiple selections simultaneously. Also allows selection and word and line deletion commands.

SCI_SETMULTIPASTE(int multiPaste)

SCI_GETMULTIPASTE → int

When pasting into multiple selections, the pasted text can go into just the main selection with SC_MULTIPASTE_ONCE=0 or into each selection with SC_MULTIPASTE_EACH=1. SC_MULTIPASTE_ONCE is the default.

SCI_SETVIRTUALSPACEOPTIONS(int virtualSpaceOptions)

SCI_GETVIRTUALSPACEOPTIONS → int

Virtual space can be enabled or disabled for rectangular selections or in other circumstances or in both. There are three bit flags SCVS_RECTANGULARSELECTION=1, SCVS_USERACCESSIBLE=2, and SCVS_NOWRAPLINESTART=4 which can be set independently. SCVS_NONE=0, the default, disables all use of virtual space.

SCVS_NOWRAPLINESTART prevents left arrow movement and selection from wrapping to the previous line. This is most commonly desired in conjunction with virtual space but is an independent setting so works without virtual space.
SCVS_NONE 0 The default: no virtual space.
SCVS_RECTANGULARSELECTION 1 Virtual space is enabled for rectangular selections.
SCVS_USERACCESSIBLE 2 Virtual space is enabled for user actions such as right arrow key or clicking beyond line end.
SCVS_NOWRAPLINESTART 4 Left arrow does not wrap to the previous line.

SCI_SETRECTANGULARSELECTIONMODIFIER(int modifier)

SCI_GETRECTANGULARSELECTIONMODIFIER → int

On GTK and Qt, the key used to indicate that a rectangular selection should be created when combined with a mouse drag can be set. The three possible values are SCMOD_CTRL=2, SCMOD_ALT=4 (default) or SCMOD_SUPER=8. Since SCMOD_ALT may already be used by a window manager, the window manager may need configuring to allow this choice. SCMOD_SUPER is often a system dependent modifier key such as the Left Windows key on a Windows keyboard or the Command key on a Mac.

SCI_GETSELECTIONS → int

Return the number of selections currently active. There is always at least one selection.

SCI_GETSELECTIONEMPTY → bool

Return 1 if every selected range is empty else 0.

SCI_CLEARSELECTIONS

Set a single empty selection at 0 as the only selection.

SCI_SETSELECTION(position caret, position anchor)

Set a single selection from anchor to caret as the only selection.

SCI_ADDSELECTION(position caret, position anchor)

Add a new selection from anchor to caret as the main selection retaining all other selections as additional selections. Since there is always at least one selection, to set a list of selections, the first selection should be added with SCI_SETSELECTION and later selections added with SCI_ADDSELECTION

SCI_SELECTIONFROMPOINT(int x, int y) → int

Return the index of the selection at the point. If there is no selection at the point, return -1. This can be used to drop a selection or make it the main selection.

SCI_DROPSELECTIONN(int selection)

If there are multiple selections, remove the indicated selection. If this was the main selection then make the previous selection the main and if it was the first then the last selection becomes main. If there is only one selection, or there is no selection selection, then there is no effect.

SCI_SETMAINSELECTION(int selection)

SCI_GETMAINSELECTION → int

One of the selections is the main selection which is used to determine what range of text is automatically visible. The main selection may be displayed in different colours or with a differently styled caret. Only an already existing selection can be made main.

SCI_SETSELECTIONNCARET(int selection, position caret)

SCI_GETSELECTIONNCARET(int selection) → position

SCI_SETSELECTIONNCARETVIRTUALSPACE(int selection, position space)

SCI_GETSELECTIONNCARETVIRTUALSPACE(int selection) → position

SCI_SETSELECTIONNANCHOR(int selection, position anchor)

SCI_GETSELECTIONNANCHOR(int selection) → position

SCI_SETSELECTIONNANCHORVIRTUALSPACE(int selection, position space)

SCI_GETSELECTIONNANCHORVIRTUALSPACE(int selection) → position

Set or query the position and amount of virtual space for the caret and anchor of each already existing selection.

SCI_SETSELECTIONNSTART(int selection, position anchor)

SCI_GETSELECTIONNSTART(int selection) → position

SCI_GETSELECTIONNSTARTVIRTUALSPACE(int selection) → position

SCI_SETSELECTIONNEND(int selection, position caret)

SCI_GETSELECTIONNEND(int selection) → position

SCI_GETSELECTIONNENDVIRTUALSPACE(int selection) → position

Set or query the start and end position of each already existing selection. Query the virtual space at start and end of each selection. Mostly of use to query each range for its text. The selection parameter is zero-based.

SCI_SETRECTANGULARSELECTIONCARET(position caret)

SCI_GETRECTANGULARSELECTIONCARET → position

SCI_SETRECTANGULARSELECTIONCARETVIRTUALSPACE(position space)

SCI_GETRECTANGULARSELECTIONCARETVIRTUALSPACE → position

SCI_SETRECTANGULARSELECTIONANCHOR(position anchor)

SCI_GETRECTANGULARSELECTIONANCHOR → position

SCI_SETRECTANGULARSELECTIONANCHORVIRTUALSPACE(position space)

SCI_GETRECTANGULARSELECTIONANCHORVIRTUALSPACE → position

Set or query the position and amount of virtual space for the caret and anchor of the rectangular selection. After setting the rectangular selection, this is broken down into multiple selections, one for each line.

SCI_SETSELECTIONSERIALIZED(<unused>, const char *selectionString)

SCI_GETSELECTIONSERIALIZED(<unused>, char *selectionString) → position

Set or query the selection type and positions as a serialized string. The format of this string may change in future versions so should not be persisted beyond the current session.

The format is currently [selType:R|L|T] [# mainRange ,] [anchor [v virtualSpace] [- caret [v virtualSpace]]] [, ...] Example of a multiple selection with virtual space: #1,5v3-2,1

SC_ELEMENT_SELECTION_ADDITIONAL_TEXT : colouralpha

SC_ELEMENT_SELECTION_ADDITIONAL_BACK : colouralpha

SCI_SETADDITIONALSELALPHA(alpha alpha)

SCI_GETADDITIONALSELALPHA → int

SCI_SETADDITIONALSELFORE(colour fore)

SCI_SETADDITIONALSELBACK(colour back)

Modify the appearance of additional selections so that they can be differentiated from the main selection which has its appearance set with SC_ELEMENT_SELECTION_TEXT, SC_ELEMENT_SELECTION_BACK, SCI_SETSELALPHA, SCI_GETSELALPHA, SCI_SETSELFORE, and SCI_SETSELBACK. The element APIs are preferred and the following messages discouraged. The additional selection background is drawn on the layer defined for all selection backgrounds by SCI_SETSELECTIONLAYER. SCI_SETADDITIONALSELFORE and SCI_SETADDITIONALSELBACK calls have no effect until SCI_SETSELFORE and SCI_SETSELBACK are called with useSetting value set to true. Subsequent calls to SCI_SETSELFORE, and SCI_SETSELBACK will overwrite the values set by SCI_SETADDITIONALSEL* functions.

SC_ELEMENT_CARET_ADDITIONAL : colouralpha

SCI_SETADDITIONALCARETFORE(colour fore)

SCI_GETADDITIONALCARETFORE → colour

Modify the appearance of additional carets so that they can be differentiated from the main caret which has its appearance set with SC_ELEMENT_CARET, SCI_SETCARETFORE, SCI_GETCARETFORE, SCI_SETCARETPERIOD, and SCI_GETCARETPERIOD.

SCI_SETADDITIONALCARETSVISIBLE(bool additionalCaretsVisible)

SCI_GETADDITIONALCARETSVISIBLE → bool

Determine whether to show additional carets (defaults to true).

SCI_SWAPMAINANCHORCARET

SCI_ROTATESELECTION

SCI_MULTIPLESELECTADDNEXT

SCI_MULTIPLESELECTADDEACH

These commands may be assigned to keys to make it possible to manipulate multiple selections. SCI_SWAPMAINANCHORCARET moves the caret to the opposite end of the main selection. SCI_ROTATESELECTION makes the next selection be the main selection. SCI_MULTIPLESELECTADDNEXT adds the next occurrence of the main selection within the target to the set of selections as main. If the current selection is empty then select word around caret. The current searchFlags are used so the application may choose case sensitivity and word search options. SCI_MULTIPLESELECTADDEACH is similar to SCI_MULTIPLESELECTADDNEXT but adds multiple occurrences instead of just one.