Selection Extended

Represents a selection in the TextEditor.

Event Subscription

This section only has Extended methods.

Extended Methods

::onDidChangeRange(callback)

Calls your callback when the selection was moved.

Argument Description

callback

Function

event

Object

oldBufferRange

Range

oldScreenRange

Range

newBufferRange

Range

newScreenRange

Range

selection

Selection that triggered the event

Return values

Returns a Disposable on which .dispose() can be called to unsubscribe.

::onDidDestroy(callback)

Calls your callback when the selection was destroyed

Argument Description

callback

Function

Return values

Returns a Disposable on which .dispose() can be called to unsubscribe.

Managing the selection range

::getScreenRange()

Return values

Returns the screen Range for the selection.

::setScreenRange(screenRange, options)

Modifies the screen range for the selection.

Argument Description

screenRange

The new Range to use.

options

optional

Object options matching those found in ::setBufferRange.

::getBufferRange()

Return values

Returns the buffer Range for the selection.

::setBufferRange(bufferRange, options)

Modifies the buffer Range for the selection.

Argument Description

bufferRange

The new Range to select.

options

optional

Object with the keys:

reversed

Boolean indicating whether to set the selection in a reversed orientation.

preserveFolds

if true, the fold settings are preserved after the selection moves.

autoscroll

Boolean indicating whether to autoscroll to the new range. Defaults to true if this is the most recently added selection, false otherwise.

::getBufferRowRange()

Return values

Returns the starting and ending buffer rows the selection is highlighting.

Returns an Array of two Numbers: the starting row, and the ending row.

Info about the selection

::isEmpty()

Determines if the selection contains anything.

::isReversed()

Determines if the ending position of a marker is greater than the starting position.

This can happen when, for example, you highlight text “up” in a TextBuffer.

::isSingleScreenLine()

Return values

Returns whether the selection is a single line or not.

::getText()

Return values

Returns the text in the selection.

::intersectsBufferRange(bufferRange)

Identifies if a selection intersects with a given buffer range.

Argument Description

bufferRange

A Range to check against.

Return values

Returns a Boolean

::intersectsWith(otherSelection)

Identifies if a selection intersects with another selection.

Argument Description

otherSelection

A Selection to check against.

Return values

Returns a Boolean

Modifying the selected range

::clear(options)

Clears the selection, moving the marker to the head.

Argument Description

options

optional

Object with the following keys:

autoscroll

Boolean indicating whether to autoscroll to the new range. Defaults to true if this is the most recently added selection, false otherwise.

::selectToScreenPosition(position)

Selects the text from the current cursor position to a given screen position.

Argument Description

position

An instance of Point, with a given row and column.

::selectToBufferPosition(position)

Selects the text from the current cursor position to a given buffer position.

Argument Description

position

An instance of Point, with a given row and column.

::selectRight(columnCount)

Selects the text one position right of the cursor.

Argument Description

columnCount

optional

Number number of columns to select (default: 1)

::selectLeft(columnCount)

Selects the text one position left of the cursor.

Argument Description

columnCount

optional

Number number of columns to select (default: 1)

::selectUp(rowCount)

Selects all the text one position above the cursor.

Argument Description

rowCount

optional

Number number of rows to select (default: 1)

::selectDown(rowCount)

Selects all the text one position below the cursor.

Argument Description

rowCount

optional

Number number of rows to select (default: 1)

::selectToTop()

Selects all the text from the current cursor position to the top of the buffer.

::selectToBottom()

Selects all the text from the current cursor position to the bottom of the buffer.

::selectAll()

Selects all the text in the buffer.

::selectToBeginningOfLine()

Selects all the text from the current cursor position to the beginning of the line.

::selectToFirstCharacterOfLine()

Selects all the text from the current cursor position to the first character of the line.

::selectToEndOfLine()

Selects all the text from the current cursor position to the end of the screen line.

::selectToEndOfBufferLine()

Selects all the text from the current cursor position to the end of the buffer line.

::selectToBeginningOfWord()

Selects all the text from the current cursor position to the beginning of the word.

::selectToEndOfWord()

Selects all the text from the current cursor position to the end of the word.

::selectToBeginningOfNextWord()

Selects all the text from the current cursor position to the beginning of the next word.

::selectToPreviousWordBoundary()

Selects text to the previous word boundary.

::selectToNextWordBoundary()

Selects text to the next word boundary.

::selectToPreviousSubwordBoundary()

Selects text to the previous subword boundary.

::selectToNextSubwordBoundary()

Selects text to the next subword boundary.

::selectToBeginningOfNextParagraph()

Selects all the text from the current cursor position to the beginning of the next paragraph.

::selectToBeginningOfPreviousParagraph()

Selects all the text from the current cursor position to the beginning of the previous paragraph.

::selectWord()

Modifies the selection to encompass the current word.

Return values

Returns a Range.

::expandOverWord()

Expands the newest selection to include the entire word on which the cursors rests.

::selectLine(row)

Selects an entire line in the buffer.

Argument Description

row

The line Number to select (default: the row of the cursor).

::expandOverLine()

Expands the newest selection to include the entire line on which the cursor currently rests.

It also includes the newline character.

Modifying the selected text

::insertText(text, options)

Replaces text at the current selection.

Argument Description

text

A String representing the text to add

options

optional

Object with keys:

select

If true, selects the newly added text.

autoIndent

If true, indents all inserted text appropriately.

autoIndentNewline

If true, indent newline appropriately.

autoDecreaseIndent

If true, decreases indent level appropriately (for example, when a closing bracket is inserted).

preserveTrailingLineIndentation

By default, when pasting multiple lines, Atom attempts to preserve the relative indent level between the first line and trailing lines, even if the indent level of the first line has changed from the copied text. If this option is true, this behavior is suppressed. level between the first lines and the trailing lines.

normalizeLineEndings

optional

Boolean (default: true)

undo

Deprecated If skip, skips the undo stack for this operation. This property is deprecated. Call groupLastChanges() on the TextBuffer afterward instead.

bypassReadOnly

optional

Boolean Must be true to modify a read-only editor. (default: false)

::backspace(options)

Removes the first character before the selection if the selection is empty otherwise it deletes the selection.

Argument Description

options

optional

Object

bypassReadOnly

optional

Boolean Must be true to modify text within a read-only editor. (default: false)

::deleteToPreviousWordBoundary(options)

Removes the selection or, if nothing is selected, then all characters from the start of the selection back to the previous word boundary.

Argument Description

options

optional

Object

bypassReadOnly

optional

Boolean Must be true to modify text within a read-only editor. (default: false)

::deleteToNextWordBoundary(options)

Removes the selection or, if nothing is selected, then all characters from the start of the selection up to the next word boundary.

Argument Description

options

optional

Object

bypassReadOnly

optional

Boolean Must be true to modify text within a read-only editor. (default: false)

::deleteToBeginningOfWord(options)

Removes from the start of the selection to the beginning of the current word if the selection is empty otherwise it deletes the selection.

Argument Description

options

optional

Object

bypassReadOnly

optional

Boolean Must be true to modify text within a read-only editor. (default: false)

::deleteToBeginningOfLine(options)

Removes from the beginning of the line which the selection begins on all the way through to the end of the selection.

Argument Description

options

optional

Object

bypassReadOnly

optional

Boolean Must be true to modify text within a read-only editor. (default: false)

::delete(options)

Removes the selection or the next character after the start of the selection if the selection is empty.

Argument Description

options

optional

Object

bypassReadOnly

optional

Boolean Must be true to modify text within a read-only editor. (default: false)

::deleteToEndOfLine(options)

If the selection is empty, removes all text from the cursor to the end of the line. If the cursor is already at the end of the line, it removes the following newline. If the selection isn’t empty, only deletes the contents of the selection.

Argument Description

options

optional

Object

bypassReadOnly

optional

Boolean Must be true to modify text within a read-only editor. (default: false)

::deleteToEndOfWord(options)

Removes the selection or all characters from the start of the selection to the end of the current word if nothing is selected.

Argument Description

options

optional

Object

bypassReadOnly

optional

Boolean Must be true to modify text within a read-only editor. (default: false)

::deleteToBeginningOfSubword(options)

Removes the selection or all characters from the start of the selection to the end of the current word if nothing is selected.

Argument Description

options

optional

Object

bypassReadOnly

optional

Boolean Must be true to modify text within a read-only editor. (default: false)

::deleteToEndOfSubword(options)

Removes the selection or all characters from the start of the selection to the end of the current word if nothing is selected.

Argument Description

options

optional

Object

bypassReadOnly

optional

Boolean Must be true to modify text within a read-only editor. (default: false)

::deleteSelectedText(options)

Removes only the selected text.

Argument Description

options

optional

Object

bypassReadOnly

optional

Boolean Must be true to modify text within a read-only editor. (default: false)

::deleteLine(options)

Removes the line at the beginning of the selection if the selection is empty unless the selection spans multiple lines in which case all lines are removed.

Argument Description

options

optional

Object

bypassReadOnly

optional

Boolean Must be true to modify text within a read-only editor. (default: false)

::joinLines(options)

Joins the current line with the one below it. Lines will be separated by a single space.

If there selection spans more than one line, all the lines are joined together.

Argument Description

options

optional

Object

bypassReadOnly

optional

Boolean Must be true to modify text within a read-only editor. (default: false)

::outdentSelectedRows(options)

Removes one level of indent from the currently selected rows.

Argument Description

options

optional

Object

bypassReadOnly

optional

Boolean Must be true to modify text within a read-only editor. (default: false)

::autoIndentSelectedRows(options)

Sets the indentation level of all selected rows to values suggested by the relevant grammars.

Argument Description

options

optional

Object

bypassReadOnly

optional

Boolean Must be true to modify text within a read-only editor. (default: false)

::toggleLineComments(options)

Wraps the selected lines in comments if they aren’t currently part of a comment.

Removes the comment if they are currently wrapped in a comment.

Argument Description

options

optional

Object

bypassReadOnly

optional

Boolean Must be true to modify text within a read-only editor. (default: false)

::cutToEndOfLine(maintainClipboard, options)

Cuts the selection until the end of the screen line.

Argument Description

maintainClipboard

Boolean

options

optional

Object

bypassReadOnly

optional

Boolean Must be true to modify text within a read-only editor. (default: false)

::cutToEndOfBufferLine(maintainClipboard, options)

Cuts the selection until the end of the buffer line.

Argument Description

maintainClipboard

Boolean

options

optional

Object

bypassReadOnly

optional

Boolean Must be true to modify text within a read-only editor. (default: false)

::cut(maintainClipboard, fullLine, bypassReadOnly)

Copies the selection to the clipboard and then deletes it.

Argument Description

maintainClipboard

Boolean (default: false) See ::copy

fullLine

Boolean (default: false) See ::copy

bypassReadOnly

Boolean (default: false) Must be true to modify text within a read-only editor.

::copy(maintainClipboard, fullLine)

Copies the current selection to the clipboard.

Argument Description

maintainClipboard

Boolean if true, a specific metadata property is created to store each content copied to the clipboard. The clipboard text still contains the concatenation of the clipboard with the current selection. (default: false)

fullLine

Boolean if true, the copied text will always be pasted at the beginning of the line containing the cursor, regardless of the cursor’s horizontal position. (default: false)

::fold()

Creates a fold containing the current selection.

::indentSelectedRows(options)

If the selection spans multiple rows, indent all of them.

Argument Description

options

optional

Object with the keys:

bypassReadOnly

optional

Boolean Must be true to modify text within a read-only editor. (default: false)

Managing multiple selections

::addSelectionBelow()

Moves the selection down one row.

::addSelectionAbove()

Moves the selection up one row.

::merge(otherSelection, options)

Combines the given selection into this selection and then destroys the given selection.

Argument Description

otherSelection

A Selection to merge with.

options

optional

Object options matching those found in ::setBufferRange.

Comparing to other selections

::compare(otherSelection)

Compare this selection’s buffer range to another selection’s buffer range.

See Range::compare for more details.

Argument Description

otherSelection

A Selection to compare against