Selection

Overview

The Selection component handles the text selection and notify other components of the status. It also provides the way to set a new selection or modify the existing one.

Properties

`lines`

get

Returns the latest Lines instance. This is an alias of Code#Lines.

`i18n`

get

Returns the i18n collection. This is an alias of this.options.i18n.

`STATES`

readonly STATES

The collection of selection states.

State	Description
`IDLE`	The editor is not active.
`COLLAPSED`	The selection is collapsed.
`START`	The selection will change soon. The native selection has not been updated at this timing.
`CHANGED`	The selection has just changed after the `START` or `EXTEND` state. The native selection has been updated.
`UPDATE`	The selection has been manually updated via `update()`.
`SELECTING`	An user starts selecting texts.
`EXTEND`	The existing selection will be extended soon.
`END`	An user finishes selection. The native selection has not been updated at this timing (in Gecko).
`SELECTED`	The selection which is not collapsed has been settled.
`SELECTED_ALL`	All contents has been selected.
`CLICKED_RIGHT`	The selection is right-clicked.

`state`

readonly state: State

The State instance that manages the selection states.

`anchor`

readonly anchor: Position

The position where the selection starts.

`focus`

readonly focus: Position

The position where the selection ends.

Methods

`set()`

set( anchor: Position, focus?: Position ): void

Sets a new selection.

Params

`anchor`	An anchor position.
`focus`	Optional. A focus position. If omitted, the selection will be collapsed to the anchor.

`get()`

get( normalize: boolean ): Range

Returns positions of the current selection. If the normalize is true, the start will be always preceding position.

Params

`normalize`	Optional. Whether to normalize the position or not.

Return

An object literal with anchor and focus positions.

`update()`

update( anchor: Position, focus?: Position, silently?: boolean ): void

Updates the custom selection range without using the native selection.

Params

`anchor`	An anchor position.
`focus`	Optional. A focus position.
`silently`	Optional. Whether to change the state or not.

`selectLine()`

selectLine( row: number, refresh: boolean, backwards?: boolean ): void

Selects the current or specified line.

Params

`row`	Optional. A row index where to select.
`refresh`	Optional. Determines whether to refresh the current selection or not.
`backwards`	Optional. Determines whether to select a line backwards or not.

`reselect()`

reselect(): void

Selects again the current selection.

`selectAll()`

selectAll(): void

Selects the whole code.

`hold()`

hold(): void

Holds the current state so that it won't change.

`release()`

release(): void

Disables to hold the state so that it will change.

`toString()`

toString(): string

Converts the selection to a string. This returns an empty string when the selection is collapsed.

Return

A string representing the current selection.

`getRect()`

getRect( focus: boolean ): DOMRect

Returns the DOMRect object of the native selection boundary. Note that the boundary node is usually a Text node, but sometimes the line or the editable element.

Params

`focus`	Determines whether to get the DOMRect of the focus or anchor node.

Return

A DOMRect object if available, or otherwise null.

`getLocation()`

getLocation(): string

Returns the current location as a string formatted by the i18n definition, such as 'Line: %s, Column: %s'.

Return

A string that describes the current location.

`is()`

is( states: number[] ): boolean

Checks if the selection state is one of the provided states or not. This is just an alias of the state.is() method.

// Checks if the state is COLLAPSED or not:
Selection.is( Selection.STATES.COLLAPSED );

// Checks if the state is START, EXTEND or not:
Selection.is( Selection.STATES.START, Selection.STATES.EXTEND );
TypeScript

// Checks if the state is COLLAPSED or not:
Selection.is( Selection.STATES.COLLAPSED );


// Checks if the state is START, EXTEND or not:
Selection.is( Selection.STATES.START, Selection.STATES.EXTEND );

Params

`states`	A state or states to check.

Return

true if the current state is one of the provided states, or otherwise false.

`collapse()`

collapse( toFocus?: boolean ): void

Collapses the selection to the anchor or focus position.

Params

`toFocus`	Optional. Collapses the selection to the focus position.

`isBackward()`

isBackward(): boolean

Checks is the selection is backward or not.

Return

true if the selection is backward, or otherwise false.

`isCollapsed()`

isCollapsed(): boolean

Checks if the selection is collapsed or not.

Return

true if the selection is collapsed, or otherwise false.

`isMultiline()`

isMultiline(): boolean

Checks if more than one line is selected or not.

Return

true if more than one line is selected or otherwise false.

`isInside()`

isInside( clientX: number, clientY: number ): boolean

Checks if the provided client position is inside the current selection or not.

Params

`clientX`	The X position that is relative to the client.
`clientY`	The Y position that is relative to the client.

Return

true if the position is inside the selection, or otherwise false.