Cursor Extended

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 DisplayMarker.

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.

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 a Point.

::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 DisplayMarker 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
Returns a Boolean.

::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: ::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
Returns a ScopeDescriptor

::getSyntaxTreeScopeDescriptor()

Retrieves the syntax tree scope descriptor for the cursor’s current position.

Return values
Returns a ScopeDescriptor

::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
Returns a Boolean.

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.

::moveToPreviousSubwordBoundary()

Moves the cursor to the previous subword boundary.

::moveToNextSubwordBoundary()

Moves the cursor to the next subword 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: ::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: ::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: ::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
Returns a Range.

::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: ::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
Returns a Range.

::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: ::wordRegExp).

Return values
Returns a Range

::getCurrentWordBufferRange(options)

Argument	Description
`options`	optional Object
`wordRegex`	A RegExp indicating what constitutes a “word” (default: ::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 or comments.

Return values
Returns a Range.

::getCurrentWordPrefix()

Return values
Returns the characters preceding the cursor in the current word.

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

::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
Returns a RegExp.

::subwordRegExp(options)

Get the RegExp used by the cursor to determine what a “subword” is.

Argument	Description
`options`	optional Object with the following keys:
`backwards`	A Boolean indicating whether to look forwards or backwards for the next subword. (default: false)

Return values
Returns a RegExp.