TextEditor

A TextEditor represents an open text editor in the application. An editor has a reference to its backing TextDocument object. Text editors are not one-to-one to text documents, since multiple editors may be open for a single document.

Notes About Text Editing:

Text operations enqueued from extensions are performed on a secondary thread. As such, there is the possibility that the contents of the editor’s document may change in between calls to methods on a TextEditor object. To ensure consistency when performing multiple edito operations in quick succession, be sure to only make multiple changes to a document within a call to the edit() method. Otherwise, use methods such as insert() to make singular edits atomically.

Class Methods

isTextEditor(object)

Returns true if the object provided is a TextEditor instance, otherwise returning false. This can be most useful for a Commands handler function, which can receive either a Workspace or TextEditor instance as its first argument.

Properties

document

The TextDocument object backing the editor.

selectedRange

The currently selected range, as a Range. If the receiver has multiple selected ranges, this will return the primary range (generally the first range).

This property is settable.

selectedRanges

An array of all currently selected ranges, as Range objects. The ranges are guaranteed to be in ascending order, and have no intersections.

This property is settable.

selectedText

The currently selected text, as a String. If the receiver has multiple selected ranges, this will return the text for the primary range (as returned by selectedRange).

This property is readonly.

softTabs

Whether the editor is set to use soft tabs (spaces). (Boolean)

This property is settable.

tabLength

The number of spaces used as a single tab length. (Number)

This property is settable.

tabText

A String representation of a single tab in the editor’s preferred indentation style and tab width.

This property is readonly.

Methods

edit(callback, [options])

Begins an atomic edit session for the editor.

The first argument must be a callable that will be invoked immediately to collect changes. The caller is responsible for doing all work in the callback it intends to represent a “single” operation on the undo stack.

The callback will receive as an argument a TextEditorEdit object that can be used to queue changes for the edit operation.

This method returns a Promise object that resolves when the edit operation is either accepted or rejected by the editor. The editor may reject an edit operation if, for example, the extension has taken too long to queue changes such that editor responsiveness may be impacted.

It is a programming error to invoke this method from within a text change callback (such as one registered using onDidChange()). Attempting to do so will throw an Error.

insert(string, [format])

Shorthand for inserting text quickly at the editor’s current insertion point(s). If there is any selection, it will be replaced by the provided text. Multiple calls to insert() within the same function will not be coalesced into one undo operation. To coalesce changes into a single undo operation, use the edit() API.

The second argument provided, format, is an InsertTextFormat enumeration value defining in what format the text provided should be parsed. Supported values are:

This method returns a Promise object that resolves when the insert operation is either accepted or rejected by the editor. The editor may reject an insert operation if, for example, the extension has taken too long to queue changes such that editor responsiveness may be impacted.

It is a programming error to invoke this method from within a text change callback (such as one registered using onDidChange()). Attempting to do so will throw an Error.

The format argument was added in Nova 1.2.

save()

Requests that the editor be saved. For unsaved documents, this will present a modal save panel to the user requesting that a path be chosen.

This method returns a Promise object that resolves when the save operation is finished, or rejects if the save operation failed.

getTextInRange(range)

Returns a section of the document’s text indicated by a provided Range as a String. If the range exceeds the receiver’s bounds, an Error will be thrown.

This is a convenience method that is effectively the same as invoking getTextInRange(range) on the editor’s document.

getLineRangeForRange(range)

Given a Range, this method will return the range of all lines encompassing that range. If the range exceeds the receiver’s bounds, an Error will be thrown.

This is a convenience method that is effectively the same as invoking getLineRangeForRange(range) on the editor’s document.

onDidChange(callback)

Adds an event listener that invokes the provided callback when the editor’s text changes. The callback will receive as an argument the TextEditor object.

Note: This callback is potentially invoked very often as text changes. If you would like to perform actions in response to a user pausing after typing, consider the .onDidStopChanging() event handler instead.

onDidStopChanging(callback)

Adds an event listener that invokes the provided callback a short time after the editor stops changing. Multiple changes to text in a short time will be coalesced into one event that can be acted upon performantly. The callback will receive as an argument the TextEditor object.

onWillSave(callback)

Adds an event listener that invokes the provided callback just before the editor is saved. The callback will receive as an argument the TextEditor object. If the callback performs modifications to the editor within the callback (such as with edit()), they will be applied in such a way as to include them in the pending save operation.

If a callback registered using this method takes too long to perform operations, any edits enqueued may be deferred until after the save operation, or discarded entirely. In the case they are discarded, an error will be reported from the Promise object returned from edit().

onDidSave(callback)

Adds an event listener that invokes the provided callback when the editor is saved. The callback will receive as an argument the TextEditor object.

onDidChangeSelection(callback)

Adds an event listener that invokes the provided callback when the editor’s selected ranges change. The callback will receive as an argument the TextEditor object.

onDidDestroy(callback)

Adds an event listener that invokes the provided callback when the editor is being closed. The callback will receive as an argument the TextEditor object.

addSelectionForRange(range)

Adds the provided Range to the editor’s selected ranges, automatically coalescing any overlapping ranges. If the provided range is zero-length, the range will be added as a cursor.

selectToPosition(position)

Extends the editor’s primary selected range to the provided character position.

selectUp(rowCount)

Extends the editor’s primary selected range upward a specific number of lines.

selectDown(rowCount)

Extends the editor’s primary selected range downward a specific number of lines.

selectLeft(columnCount)

Extends the editor’s primary selected range leftward a specific number of characters.

selectRight(columnCount)

Extends the editor’s primary selected range rightward a specific number of characters.

selectToTop()

Extends the editor’s primary selected range to the beginning of the text.

selectToBottom()

Extends the editor’s primary selected range to the end of the text.

selectAll()

Selects all text in the editor.

selectLinesContainingCursors()

Extends all selected ranges and cursors to encompass all lines in which they intersect.

selectToBeginningOfLine()

Extends all selected ranges and cursors backward to the beginning of their first (or only) line.

selectToEndOfLine()

Extends all selected ranges and cursors forward to the end of their last (or only) line.

selectWordsContainingCursors()

Extends all selected ranges and cursors to encompass all words in which they intersect.

selectToBeginningOfWord()

Extends all selected ranges and cursors backward to the beginning of their first (or only) word.

selectToEndOfWord()

Extends all selected ranges and cursors forward to the end of their last (or only) word.

scrollToCursorPosition()

Scrolls the editor to ensure that the primary selected range is visible.

scrollToPosition(position)

Scrolls the editor to ensure that the provided character position is visible.

startShadowTyping(ranges, [charset])

Begins a shadow typing session for the editor with a set of ranges. The ranges provided will be added as selected text ranges (or cursors, if zero-length) in the editor in a similar way to adding them to the selectedRanges property. However, the ranges will only remain valid while typing text in the current undo coalescing state. If the selection or undo state changes by any other means (such as by moving the cursors manually or saving the document), the ranges will be removed and the shadow typing session will end.

The optional charset argument may be provided with a Charset object. As the user types, the characters will be compared with this character set. If a character does not match, the shadow typing session will end automatically.

endShadowTyping()

Explicitly ends the current shadow typing session, if any. It’s generally not required to invoke this manually except in very specific circumstances that the shadow typing session’s attribute (such as its charset) cannot handle.

symbolAtPosition(position)

Gets the deepest displayable symbol containing the provided text position, as a Symbol object. If no symbol could be found, this method returns null.

symbolsForSelectedRanges()

Gets the deepest displayable symbol for the start position of each of the selected ranges of the editor, as an array of Symbol objects. If no symbol could be found at a specific position, the array will contain a null entry for that range.