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.

This property is readonly.

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:

InsertTextFormat.PlainText: The text is plain text and will not be modified (the default value).
InsertTextFormat.Snippet: The text uses the Snippets format and will be parsed for editor placeholders.

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, [thisValue])

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.

The optional thisValue argument may be used to set what this is bound to when the callable is invoked. If omitted, this will be undefined.