Cursor

Description

The Cursor class represents the little blinking line identifying where text can be inserted.

Cursors belong to TextEditors and have some metadata attached in the form of a Marker.

API documentation

Event Subscription

::onDidChangePosition(callback)

Calls your callback when the cursor has been moved.

Argument Description
callback

Function
event

Object
oldBufferPosition

Point
oldScreenPosition

Point
newBufferPosition

Point
newScreenPosition

Point
textChanged

Boolean
Cursor

Cursor that triggered the event
Return values

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

::onDidDestroy(callback)

Calls your callback when the cursor is destroyed

Argument Description
callback

Function
Return values

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

::onDidChangeVisibility(callback)

Calls your callback when the cursor's visibility has changed

Argument Description
callback

Function
visibility

Boolean
Return values

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

Managing Cursor Position

::setScreenPosition(screenPosition, options)

Moves a cursor to a given screen position.

Argument Description
screenPosition

Array of two numbers: the screen row, and the screen column.
options optional

Object with the following keys:
autoscroll

A Boolean which, if true, scrolls the TextEditor to wherever the cursor moves to.

::getScreenPosition()

Return values

  • Returns the screen position of the cursor as an Array.

::setBufferPosition(bufferPosition, options)

Moves a cursor to a given buffer position.

Argument Description
bufferPosition

Array of two numbers: the buffer row, and the buffer column.
options optional

Object with the following keys:
autoscroll

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

::getBufferPosition()

Return values

  • Returns the current buffer position as an Array.

::getScreenRow()

Return values

  • Returns the cursor's current screen row.

::getScreenColumn()

Return values

  • Returns the cursor's current screen column.

::getBufferRow()

Retrieves the cursor's current buffer row.

::getBufferColumn()

Return values

  • Returns the cursor's current buffer column.

::getCurrentBufferLine()

Return values

  • Returns the cursor's current buffer row of text excluding its line ending.

::isAtBeginningOfLine()

Return values

  • Returns whether the cursor is at the start of a line.

::isAtEndOfLine()

Return values

  • Returns whether the cursor is on the line return character.

Cursor Position Details

::getMarker()

Return values

  • Returns the underlying Marker for the cursor. Useful with overlay Decorations.

::isSurroundedByWhitespace()

Identifies if the cursor is surrounded by whitespace.

"Surrounded" here means that the character directly before and after the cursor are both whitespace.

Return values

::isBetweenWordAndNonWord()

This method returns false if the character before or after the cursor is whitespace.

Return values

  • Returns whether the cursor is currently between a word and non-word character. The non-word characters are defined by the editor.nonWordCharacters config value.

  • Returns a Boolean.

::isInsideWord(options)

Argument Description
options optional

Object
wordRegex

A RegExp indicating what constitutes a "word" (default: Cursor::wordRegExp).
Return values

  • Returns whether this cursor is between a word's start and end.

  • Returns a Boolean

::getIndentLevel()

Return values

  • Returns the indentation level of the current line.

::getScopeDescriptor()

Retrieves the scope descriptor for the cursor's current position.

Return values

::hasPrecedingCharactersOnLine()

Return values

  • Returns true if this cursor has no non-whitespace characters before its current position.

::isLastCursor()

Identifies if this cursor is the last in the TextEditor.

"Last" is defined as the most recently added cursor.

Return values

Moving the Cursor

::moveUp(rowCount, options)

Moves the cursor up one screen row.

Argument Description
rowCount optional

Number number of rows to move (default: 1)
options optional

Object with the following keys:
moveToEndOfSelection

if true, move to the left of the selection if a selection exists.

::moveDown(rowCount, options)

Moves the cursor down one screen row.

Argument Description
rowCount optional

Number number of rows to move (default: 1)
options optional

Object with the following keys:
moveToEndOfSelection

if true, move to the left of the selection if a selection exists.

::moveLeft(columnCount, options)

Moves the cursor left one screen column.

Argument Description
columnCount optional

Number number of columns to move (default: 1)
options optional

Object with the following keys:
moveToEndOfSelection

if true, move to the left of the selection if a selection exists.

::moveRight(columnCount, options)

Moves the cursor right one screen column.

Argument Description
columnCount optional

Number number of columns to move (default: 1)
options optional

Object with the following keys:
moveToEndOfSelection

if true, move to the right of the selection if a selection exists.

::moveToTop()

Moves the cursor to the top of the buffer.

::moveToBottom()

Moves the cursor to the bottom of the buffer.

::moveToBeginningOfScreenLine()

Moves the cursor to the beginning of the line.

::moveToBeginningOfLine()

Moves the cursor to the beginning of the buffer line.

::moveToFirstCharacterOfLine()

Moves the cursor to the beginning of the first character in the line.

::moveToEndOfScreenLine()

Moves the cursor to the end of the line.

::moveToEndOfLine()

Moves the cursor to the end of the buffer line.

::moveToBeginningOfWord()

Moves the cursor to the beginning of the word.

::moveToEndOfWord()

Moves the cursor to the end of the word.

::moveToBeginningOfNextWord()

Moves the cursor to the beginning of the next word.

::moveToPreviousWordBoundary()

Moves the cursor to the previous word boundary.

::moveToNextWordBoundary()

Moves the cursor to the next word boundary.

::skipLeadingWhitespace()

Moves the cursor to the beginning of the buffer line, skipping all whitespace.

::moveToBeginningOfNextParagraph()

Moves the cursor to the beginning of the next paragraph

::moveToBeginningOfPreviousParagraph()

Moves the cursor to the beginning of the previous paragraph

Local Positions and Ranges

::getPreviousWordBoundaryBufferPosition(options)

Argument Description
options optional

Object with the following keys:
wordRegex

A RegExp indicating what constitutes a "word" (default: Cursor::wordRegExp)
Return values

  • Returns buffer position of previous word boundary. It might be on the current word, or the previous word.

::getNextWordBoundaryBufferPosition(options)

Argument Description
options optional

Object with the following keys:
wordRegex

A RegExp indicating what constitutes a "word" (default: Cursor::wordRegExp)
Return values

  • Returns buffer position of the next word boundary. It might be on the current word, or the previous word.

::getBeginningOfCurrentWordBufferPosition(options)

Retrieves the buffer position of where the current word starts.

Argument Description
options optional

An Object with the following keys:
wordRegex

A RegExp indicating what constitutes a "word" (default: Cursor::wordRegExp).
includeNonWordCharacters

A Boolean indicating whether to include non-word characters in the default word regex. Has no effect if wordRegex is set.
allowPrevious

A Boolean indicating whether the beginning of the previous word can be returned.
Return values

::getEndOfCurrentWordBufferPosition(options)

Retrieves the buffer position of where the current word ends.

Argument Description
options optional

Object with the following keys:
wordRegex

A RegExp indicating what constitutes a "word" (default: Cursor::wordRegExp)
includeNonWordCharacters

A Boolean indicating whether to include non-word characters in the default word regex. Has no effect if wordRegex is set.
Return values

::getBeginningOfNextWordBufferPosition(options)

Retrieves the buffer position of where the next word starts.

Argument Description
options optional

Object
wordRegex

A RegExp indicating what constitutes a "word" (default: Cursor::wordRegExp).
Return values

::getCurrentWordBufferRange(options)

Argument Description
options optional

Object
wordRegex

A RegExp indicating what constitutes a "word" (default: Cursor::wordRegExp).
Return values

  • Returns the buffer Range occupied by the word located under the cursor.

::getCurrentLineBufferRange(options)

Argument Description
options optional

Object
includeNewline

A Boolean which controls whether the Range should include the newline.
Return values

  • Returns the buffer Range for the current line.

::getCurrentParagraphBufferRange()

Retrieves the range for the current paragraph.

A paragraph is defined as a block of text surrounded by empty lines.

Return values

::getCurrentWordPrefix()

Return values

  • Returns the characters preceding the cursor in the current word.

Visibility

::setVisible()

Sets whether the cursor is visible.

::isVisible()

Return values

  • Returns the visibility of the cursor.

Comparing to another cursor

::compare(otherCursor)

Compare this cursor's buffer position to another cursor's buffer position.

See Point::compare for more details.

Argument Description
otherCursor

Cursor to compare against

Utilities

::clearAutoscroll()

Prevents this cursor from causing scrolling.

::clearSelection()

Deselects the current selection.

::wordRegExp(options)

Get the RegExp used by the cursor to determine what a "word" is.

Argument Description
options optional

Object with the following keys:
includeNonWordCharacters

A Boolean indicating whether to include non-word characters in the regex. (default: true)
Return values