Workspace

A Workspace contains properties and methods related to an open workspace window. Extensions are loaded on a per-workspace basis, so there is generally only one workspace object available from the perspective of executing extension code.

An instance representing the current workspace is always available via the workspace property of the global nova Environment object.

Properties

path

Returns the workspace’s path on disk, as a String. If the workspace is not bound to a folder this may be null or undefined.

This property is readonly.

config

The Configuration object for the workspace, written into the workspace’s internal metadata folder.

Extensions may store values in this configuration that should be written into a per-workspace storage, and potentially stored in source control by the user.

This property is readonly.

textDocuments

An array of TextDocument objects representing each document open in the workspace. Text Documents are not necessarily one-to-one with the textEditors properties, as multiple editors can be opened for a single text document.

This property is readonly.

textEditors

An array of TextEditor objects representing each text editor open in the workspace. Text Editors are not necessarily one-to-one with the documents properties, as multiple editors can be opened for a single document.

This property is readonly.

activeTextEditor

The TextEditor instance that is currently focused in the workspace.

This property is readonly.

Methods

onDidAddTextEditor(callback, [thisValue])

Adds an event listener that invokes the provided callback when the workspace opens a text editor. The callback will receive as an argument the TextEditor object.

As a convenience, when this method is invoked the callback will also immediately be called with all open text editors.

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.

This method returns a Disposable that can be used to unregister the listener.

onDidChangePath(callback, [thisValue])

Adds an event listener that invokes the provided callback when the workspace’s path changes. The callback will receive as an argument the new path as a string.

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.

This method returns a Disposable that can be used to unregister the listener.

onDidOpenTextDocument(callback, [thisValue])

Adds an event listener that invokes the provided callback when the workspace opens a text document. The callback will receive as an argument the TextDocument object.

As a convenience, when this method is invoked the callback will also immediately be called with all open text documents.

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.

This method returns a Disposable that can be used to unregister the listener.

contains(path)

Returns true if the workspace contains the file at a specified path. If the workspace is not bound to a folder, this method always returns false.

relativizePath(path)

Converts an absolute path into a path relative to the workspace root. If the provided path is not a descendant of the workspace root, or if the workspace is not bound to a folder, this method returns the path unchanged.

openConfig([identifier])

Requests the workspace open the project settings view for a specified extension, by identifier. If no identifier is specified, the current extension’s project settings will be opened.

openFile(uri)

Requests the workspace open a file by URI. For local files, this can be either a file:// URI or a path on disk. Returns a Promise object that, on success, resolves to the new editor’s object (usually a TextEditor object), or null if the editor does not expose extension API.

showInformativeMessage(message)

Displays an informative message to the user as an alert. The alert will be titled with the calling extension’s name, and the provided message will be displayed as the alert body.

showWarningMessage(message)

Displays a warning message to the user as an alert. The alert will be titled with the calling extension’s name, and the provided message will be displayed as the alert body. This method is similar to showInformativeMessage except it includes additional UI indications that the message indicates a warning, and may bring the workspace’s window to the foreground.

showErrorMessage(message)

Displays an error message to the user as an alert. The alert will be titled with the calling extension’s name, and the provided message will be displayed as the alert body. This method is similar to showInformativeMessage except it includes additional UI indications that the message indicates an error, and may bring the workspace’s window to the foreground.

showActionPanel(message, [options], [callback])

Displays an action panel to the user. The panel will be titled with the calling extension’s name, and the provided message will be displayed as the panel body.

The optional options argument may contain the following values:

Option Description Note
buttons An array of strings, used as button names in the alert If not specified, a single “OK” button will be included.

The optional callback argument should be a callable, which will be invoked when the user chooses a button in the alert. The callback will be passed the button index chosen (as a Number), or null if the alert was dismissed by other means (such as the application cancelling the alert without user intervention).

showInputPanel(message, [options], [callback])

Displays an input panel to the user (in the style of a modal sheet). The panel will be titled with the calling extension’s name, and the provided message will be displayed as the panel body.

Input panels include a single text field to ask user for a value, as well as two buttons (“Cancel” and “OK”).

The optional options argument may contain the following values:

Value Description
label Label to display before the input field (string)
placeholder Text to display if no value is present (string)
value Default value to display (string)
prompt Text to display instead for the “OK” button (string)
secure Whether the field should be “secure” (display its value using dots) (boolean)

The optional callback argument should be a callable, which will be invoked when the user chooses a button in the alert. The callback will be passed the value provided by the user (as a String), or null if the alert was cancelled.

showInputPalette(message, [options], [callback])

Displays an input palette to the user (in the style of the command palette). The provided message will be displayed as the palette’s descriptive text.

Input palettes include a single text field to ask user for a value.

The optional options argument may contain the following values:

Value Description
placeholder Text to display if no value is present (string)

The optional callback argument should be a callable, which will be invoked when the user confirms with the Return key. The callback will be passed the value provided by the user (as a String), or null if the palette was cancelled.

showChoicePalette(choices, [options], [callback])

Displays a choice palette to the user (in the style of the command palette). The provided array of strings, choices, will be displayed as the initial results of the palette, and can be filtered by the user by typing.

The optional options argument may contain the following values:

Value Description
placeholder Text to display if no value is present (string)

The optional callback argument should be a callable, which will be invoked when the user confirms with the Return key. The callback will be passed the choice (from the choices array) selected by the user or null if the palette was cancelled, as well as optionally the index of the choice within the provided array as the second argument.

showFileChooser(message, [options], [callback])

Displays a file chooser panel to the user. The panel will be titled with the calling extension’s name, and the provided message will be displayed as the panel body.

File chooser panels show a standard macOS open panel to request file(s) and folder(s) be selected by the user.

The optional options argument may contain the following values:

Value Description
prompt Text to display instead for the “OK” button
allowFiles Whether the user may choose files
allowFolders Whether the user may choose folders
allowMultiple Whether the user may choose multiple files (boolean)
filetype The file types allowed, as an array of strings. Types may be file extensions or uniform type identifiers.
relative Whether to return paths to the caller which are relative to the workspace (boolean)

The optional callback argument should be a callable, which will be invoked when the user dismisses the panel. The callback will be passed an array of paths chosen, or null if the alert was cancelled.

reloadTasks(identifier)

Requests that the IDE reload tasks from the task assistant with the provided identifier. This will cause the IDE to invoke the provideTasks() method on the assistant asynchronously.

If an assistant with the provided identifier is not registered this method has no effect.