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
activeTextEditor
The TextEditor instance that is currently focused in the workspace. This may be null if no text editor is focused.
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.
debugSessions
An array of DebugSession objects which are running for the workspace.
This property is readonly.
Added in Nova 9.
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.
previewRootPath
The root path of the workspace’s preview. This path represents the directory being served at the root of previews. This property will return null or undefined in cases where previewing is not available for the workspace.
This property is readonly.
Added in Nova 9.
previewURL
The computed URL for the workspace’s preview as a String. If the workspace is using Nova’s built-in web server this property will represent that server’s root. If the workspace has a custom preview URL set by the user this property will represent that URL. This method will return null or undefined in cases where previewing is not available for the workspace.
This property is readonly.
Added in Nova 9.
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.
Methods
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.
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.
onDidEndDebugSession(callback, [thisValue])
Adds an event listener that invokes the provided callback when the workspace ends a debug session. The callback will receive as an argument the DebugSession object.
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.
Added in Nova 9.
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.
onDidStartDebugSession(callback, [thisValue])
Adds an event listener that invokes the provided callback when the workspace starts a debug session. The callback will receive as an argument the DebugSession object.
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.
Added in Nova 9.
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, [options])
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.
The optional options parameter may be an object with the following possible properties:
| Value | Description |
|---|---|
| line | Line number to jump to after opening |
| column | Column number to jump to after opening (requires line) |
openNewTextDocument([options])
Requests the workspace open a new, untitled document tab.
The optional options parameter may be an object with the following possible properties:
| Value | Description |
|---|---|
| content | The content of the new document, if any |
| line | Line number to jump to after opening |
| column | Column number to jump to after opening (requires line) |
| syntax | The identifier for a syntax to set for the document. If not specified, the user’s default syntax will be used. |
previewURLForPath(path)
Returns a String representing the URL for previewing the file at the specified path. This method will return null or undefined in cases where previewing is not available for the workspace or if the specified file is not within the directory tree being served by the workspace’s preview.
Added in Nova 9.
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 then relative prefix components (../) will be applied as necessary to create a relative path. If the workspace is not bound to a folder this method returns the path unchanged.
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.
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).
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.
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.
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.
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.
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) |
| value | Text with which to pre-fill the palette (Added in Nova 6.) |
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.
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.
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.