Link Search Menu Expand Document

=== workspace

workspace

properties

fs

A file system instance that allows to interact with local and remote files, e.g. vscode.workspace.fs.readDirectory(someUri) allows to retrieve all entries of a directory or vscode.workspace.fs.stat(anotherUri) returns the meta data for a file.

name

The name of the workspace. undefined when no folder has been opened.

rootPath, deprecated

textDocuments: ReadonlyArray

workspaceFile: Uri | undefined

  • The location of the workspace file, for example:

  • eg:
    • file:///Users/name/Development/myProject.code-workspace
  • eg:note saved

    • untitled:1555503116870
  • The location can e.g. be used with the vscode.openFolder command to open the workspace again after it has been closed
vscode.commands.executeCommand("vscode.openFolder", uriOfWorkspace);
  • Note: it is not advised to use workspace.workspaceFile to write configuration data into the file. You can use workspace.getConfiguration().update() for that purpose which will work both when a single folder is opened as well as an untitled or saved workspace.

workspaceFolders: ReadonlyArray | undefined

  • List of workspace folders or undefined when no folder is open. Note that the first entry corresponds to the value of rootPath.
{"ctx":"activate","wsFolders":[
    {"uri":{"$mid":1,"fsPath":"/Users/kevinlin/Documents/Dendron","external":"file:///Users/kevinlin/Documents/Dendron","path":"/Users/kevinlin/Documents/Dendron","scheme":"file"},"name":"Dendron","index":0}
]}

events

onDidCreateFiles: Event

Note: This event is triggered by user gestures, like creating a file from the explorer, or from the workspace.applyEdit-api, but this event is not fired when files change on disk, e.g triggered by another application, or when using the workspace.fs-api.

onDidChangeTextDocument: Event

  • TextDocumentChangeEvent: Uri

onDidOpenTextDocument

  • Event<TextDocument>

An event that is emitted when a text document is opened or when the language id of a text document has been changed.

To add an event listener when a visible text document is opened, use the TextEditor events in the window namespace. Note that:

The event is emitted before the document is updated in the active text editor
When a text document is already open (e.g.: open in another visible text editor) this event is not emitted

onDidRenameFile

  • Event

  • this event is not fired when files change on disk, e.g triggered by another application, or when using the workspace.fs-api.

  • FileRenameEvent:

    • files: ReadonlyArray<{newUri: Uri, oldUri: Uri}>

onWillCreateFiles: Event

  • Note 1: This event is triggered by user gestures, like creating a file from the explorer, or from the workspace.applyEdit-api. This event is not fired when files change on disk, e.g triggered by another application, or when using the workspace.fs-api.
  • Note 2: When this event is fired, edits to files that are are being created cannot be applied.

onWillSaveTextDocument: Event

An event that is emitted when a text document will be saved to disk.

Note 1: Subscribers can delay saving by registering asynchronous work. For the sake of data integrity the editor might save without firing this event. For instance when shutting down with dirty files.

Note 2: Subscribers are called sequentially and they can delay saving by registering asynchronous work. Protection against misbehaving listeners is implemented as such:

there is an overall time budget that all listeners share and if that is exhausted no further listener is called
listeners that take a long time or produce errors frequently will not be called anymore

The current thresholds are 1.5 seconds as overall time budget and a listener can misbehave 3 times before being ignored.

methods

createFileSystemWatcher

  • sig: (globPattern: GlobPattern, ignoreCreateEvents?: boolean, ignoreChangeEvents?: boolean, ignoreDeleteEvents?: boolean): FileSystemWatcher

  • params
    • globPattern: A glob pattern that is applied to the absolute paths of created, changed, and deleted files. Use a relative pattern to limit events to a certain workspace folder.
  • note
    • only files within the current workspace folders can be watched #star
    • does not respect files.exclude setting, need to add watcher.exclude

findFiles

  • signature
(
  include: GlobPattern, 
  exclude?: GlobPattern | null, 
  maxResults?: number, 
  token?: CancellationToken
): Thenable<Uri[]>
  • Find files across all workspace folders in the workspace.

  • eg:

findFiles("**/*.js", "**/node_modules/**", 10);

getWorkspaceFolder

  • sig
(uri: Uri): WorkspaceFolder | undefined
  • return
    • Returns the workspace folder that contains a given uri.
      • returns undefined when the given uri doesn’t match any workspace folder
      • returns the input when the given uri is a workspace folder itself

openTextDocument

  • sig:
openTextDocument(uri: Uri): Thenable<TextDocument>
  • sig3
    • opens untitled document
openTextDocument(options?: {content: string, language: string}): Thenable<TextDocument>

Opens a document. Will return early if this document is already open. Otherwise the document is loaded and the didOpen-event fires.

The document is denoted by an uri. Depending on the scheme the following rules apply:

  • file-scheme: Open a file on disk, will be rejected if the file does not exist or cannot be loaded.
  • untitled-scheme: A new file that should be saved on disk, e.g. untitled:c:\frodo\new.js. The language will be derived from the file name.
  • For all other schemes contributed text document content providers and file system providers are consulted.

Note that the lifecycle of the returned document is owned by the editor and not by the extension. That means an onDidClose-event can occur at any time after opening it.

registerFileSystemProvider(scheme: string, provider: FileSystemProvider, options?: {isCaseSensitive: boolean, isReadonly: boolean}): Disposable

  • Register a filesystem provider for a given scheme, e.g. ftp.
  • There can only be one provider per scheme and an error is being thrown when a scheme has been claimed by another provider or when it is reserved.

setDecorations

(decorationType: TextEditorDecorationType, rangesOrOptions: Range[] | DecorationOptions[]): void

updateWorkspaceFolders

  • signature
(start: number, deleteCount: number | undefined | null, ...workspaceFoldersToAdd: {name: string, uri: Uri}[]): boolean
  • params
    • start: the zero-based location in the list of currently opened workspace folders from which to start deleting workspace folders.
    • deleteCount: the optional number of workspace folders to remove.
    • workspaceFoldersToAdd: the optional variable set of workspace folders to add in place of the deleted ones. Each workspace is identified with a mandatory URI and an optional name.
  • return: boolean

    • true if the operation was successfully started and false otherwise if arguments were used that would result in invalid workspace folder state (e.g. 2 folders with the same URI).
  • eg: remove 1st ws folder
workspace.updateWorkspaceFolders(0, 1);
  • eg: replace existing ws folder
workspace.updateWorkspaceFolders(0, 1, { uri: ...});

  • note
    • It is valid to remove an existing workspace folder and add it again with a different name to rename that folder.
    • it is not valid to call updateWorkspaceFolders() multiple times without waiting for the onDidChangeWorkspaceFolders() to fire.

Clipboard

link: https://code.visualstudio.com/api/references/vscode-api#Clipboard

  • The clipboard provides read and write access to the system’s clipboard.

CodeAction

  • A code action represents a change that can be performed in code, e.g. to fix a problem or to refactor code.

CodeLensProvider

  • A code lens provider adds commands to source text. The commands will be shown as dedicated horizontal lines in between the source text.

Command

  • Represents a reference to a command. Provides a title which will be used to represent a command in the UI and, optionally, an array of arguments which will be passed to the command handler function when invoked.

Comment

A comment is displayed within the editor or the Comments Panel, depending on how it is provided.

CompletionItem

range

Completions that are triggered at the end of a word usually replace that word. However when completions are triggered inside words, it’s not clear if the word-end should be replaced or not. Depending on the preference of the extension author, users get the one behavior or the other. That’s not ideal and now there is an API to express the insert and replace ranges for a completion item.

For that, we have added a new OR-type to CompletionItem#range:

export class CompletionItem {
  range?: Range | { inserting: Range; replacing: Range };

  //...
}
  1. If the range is undefined, then VS Code uses the current word range for replacing and the same range cropped at the cursor position for inserting.
  2. If the range is a simple vscode.Range, then VS Code knows there is only one location for inserting or replacing.
  3. If the range is an object with inserting and replacing ranges, VS Code will use them directly.

This information is used in combination with editor.suggest.insertMode setting that allows users to define their preference. We ask extension authors to please adopt this API quickly because we have plans to make insert and replace behavior more visible in the next release.

CompletionItemProvider

resolveCompletionItem?(item: T, token: CancellationToken): ProviderResult;

link: https://github.com/microsoft/vscode/blob/11fda69d237b9aa006eb53da724fa509afe92e0a/src/vs/vscode.d.ts#L3966

  • Providers can delay the computation of
  • properties that are needed for the initial sorting and filtering, like sortText, filterText, insertText, and range, must not be changed during resolve.

  • Providers are asked for completions either explicitly by a user gesture or -depending on the configuration-implicitly when typing words or trigger characters.

  • release notes

    The CompletionItemProvider#resolveCompletionItem function allows providers to lazily enrich completions with more data. This “lazy” data must be optional and must not change the insert behavior of completions. Extensions can still fill in additionalTextEdits and if additional edits arrive after a completion has been inserted, the editor will still attempt to apply them. Note that this only applies to additional edits, not to the main edit (insertText) which must not change once provided.

CustomTextEditorProvider

link: https://code.visualstudio.com/api/references/vscode-api#CustomTextEditorProvider

Text based custom editors use a TextDocument as their data model. This considerably simplifies implementing a custom editor as it allows VS Code to handle many common operations such as undo and backup. The provider is responsible for synchronizing text changes between the webview and the TextDocument.

Disposable

  • Represents a type which can release resources, such as event listening or a timer

constructor

new(callOnDispose: Function)

DocumentFilter

  • denotes a document by different properties like the language, the scheme of its resource, or a glob-pattern that is applied to the path.
  • eg: A language filter that applies to typescript files on disk: { language: ‘typescript’, scheme: ‘file’ }
  • eg2: A language filter that applies to all package.json paths: { language: ‘json’, scheme: ‘untitled’, pattern: ‘**/package.json’ }

DocumentHighlight

  • range inside a text document which deserves special attention. Usually a document highlight is visualized by changing the background color of its range.

DocumentLink

  • range in a text document that links to an internal or external resource, like another text document or a web site.

EndOfLine

  • Represents an end of line character sequence in a document.

EnterAction

Describes what to do when pressing Enter.

Event

  • Represents a typed event

  • eg: A function that represents an event to which you subscribe by calling it with a listener function as argument.

item.onDidChange(function (event) {
  console.log("Event happened: " + event);
});

EnvironmentVariableCollection

These collections are extension and workspace-specific and VS Code handles how conflicts between multiple extensions are dealt with. They are persisted across window reloads such that terminals created immediately after the window is loaded do not block on the extension host launching but instead use the last known version. These persisted collections are removed by disposing of the collection or when the extension is uninstalled.

When collections change, an indicator will appear on the terminal. Whether this indicator shows for any active change or just for “stale” terminals is defined by the terminal.integrated.environmentChangesIndicator setting. This API is now also used by the built-in Git extension to let VS Code be an authentication provider.

const collection = context.environmentVariableCollection;
const separator = process.platform === "win32" ? ";" : ":";
collection.prepend("PATH", `/foo${separator}`);
collection.replace("JAVA_HOME", "/bar");

ExtensionContext

tags:

  • #extensions

  • collection of utilities private to an extension.

  • prod

{
  "level": 30,
  "time": 1593449542864,
  "pid": 75542,
  "hostname": "Kevins-MacBook-Pro.local",
  "name": "dendron",
  "ctx": "activate",
  "logPath": "/Users/kevinlin/Library/Application Support/Code - Insiders/logs/20200628T153037/exthost10/dendron.dendron-plugin-core",
  "extensionPath": "/Users/kevinlin/.vscode-insiders/extensions/dendron.dendron-plugin-core-0.2.4",
  "extensionUri": {
    "$mid": 1,
    "fsPath": "/Users/kevinlin/.vscode-insiders/extensions/dendron.dendron-plugin-core-0.2.4",
    "path": "/Users/kevinlin/.vscode-insiders/extensions/dendron.dendron-plugin-core-0.2.4",
    "scheme": "file"
  },
  "storagePath": "/Users/kevinlin/Library/Application Support/Code - Insiders/User/workspaceStorage/8404fce9717101a619601cf71dca457f/dendron.dendron-plugin-core",
  "globalStoragePath": "/Users/kevinlin/Library/Application Support/Code - Insiders/User/globalStorage/dendron.dendron-plugin-core"
}
  • 1st run
{
  "logPath": "/Users/kevinlin/Library/Application Support/Code/logs/20200624T200601/exthost137/dendron.@dendronhq/plugin-core",
  "extensionPath": "/Users/kevinlin/projects/dendronv2/dendron/packages/plugin-core",
  "extensionUri": {
    "$mid": 1,
    "fsPath": "/Users/kevinlin/projects/dendronv2/dendron/packages/plugin-core",
    "path": "/Users/kevinlin/projects/dendronv2/dendron/packages/plugin-core",
    "scheme": "file"
  },
  "storagePath": "/Users/kevinlin/Library/Application Support/Code/User/workspaceStorage/60a7b37c990c01aec0c916623495a0b7/dendron.@dendronhq/plugin-core",
  "globalStoragePath": "/Users/kevinlin/Library/Application Support/Code/User/globalStorage/dendron.@dendronhq/plugin-core"
}
  • 2nd run
{
  "logPath": "/Users/kevinlin/Library/Application Support/Code/logs/20200624T200601/exthost137/dendron.@dendronhq/plugin-core",
  "extensionPath": "/Users/kevinlin/projects/dendronv2/dendron/packages/plugin-core",
  "extensionUri": {
    "$mid": 1,
    "fsPath": "/Users/kevinlin/projects/dendronv2/dendron/packages/plugin-core",
    "path": "/Users/kevinlin/projects/dendronv2/dendron/packages/plugin-core",
    "scheme": "file"
  },
  "storagePath": "/Users/kevinlin/Library/Application Support/Code/User/workspaceStorage/60a7b37c990c01aec0c916623495a0b7/dendron.@dendronhq/plugin-core",
  "globalStoragePath": "/Users/kevinlin/Library/Application Support/Code/User/globalStorage/dendron.@dendronhq/plugin-core"
}

props

globalState

  • use:
    • to delete key, set value to undefined

globalStoragePath

  • good option if you need to store large files that are accessible from all workspaces.
  • VS Code takes care of cleaning up this path when the extension is removed.
/**
 * An absolute file path in which the extension can store global state.
 * The directory might not exist on disk and creation is
 * up to the extension. However, the parent directory is guaranteed to be existent.
 *
 * Use [`globalState`](#ExtensionContext.globalState) to store key value data.
 */
globalStoragePath: string;

logPath: string

An absolute file path of a directory in which the extension can create log files. The directory might not exist on disk and creation is up to the extension. However, the parent directory is guaranteed to be existent.

methods

asAbsolutePath

asAbsolutePath(relativePath: string): string`
  • eg: “/Users/kevinlin/projects/vscode-extension/dendron/foo.exists”

EventEmitter

  • can be used to create and manage an event for others to subscribe to. One emitter always owns one event
  • Use this class if you want to provide event from within your extension, for instance inside a TextDocumentContentProvider or when providing API to other extensions

Extension

id: a6fc2f9c-259f-4dc5-8b3c-124eff389441

Represents an extension.

props

exports: T

  • public API of extension
  • NOTE: extension must be activated before accessing thisf field

isActive: bool

packageJSON

  • parsed contents of package

methods

activate: Promise

  • activate extension and return public API

FileSystem

link: https://code.visualstudio.com/api/references/vscode-api#FileSystem

The file system interface exposes the editor’s built-in and contributed file system providers. It allows extensions to work with files from the local disk as well as files from remote places, like the remote extension host or ftp-servers.

Note that an instance of this interface is available as workspace.fs

FileSystemProvider

  • defines what the editor needs to read, write, discover, and to manage files and folders
  • allows extensions to serve files from remote places, like ftp-servers, and to seamlessly integrate those into the editor
  • notes:
    • works with uris and assumes hierarchical paths, e.g. foo:/my/path is a child of foo:/my/ and a parent of foo:/my/path/deeper.
    • activation event onFileSystem: that fires when a file or folder is being accessed.
    • ‘file’ is often used to denote all kinds of files, e.g. folders, symbolic links, and regular files.

Events

onDidChangeFile

  • event to signal that a resource has been created, changed, or deleted

methods

copy(source: Uri, destination: Uri, options: {overwrite: boolean}): void Thenable
createDirectory(uri: Uri): void Thenable
delete(uri: Uri, options: {recursive: boolean}): void Thenable
readDirectory(uri: Uri): [string, FileType][] Thenable<[string, FileType][]>
readFile(uri: Uri): Uint8Array Thenable
rename(oldUri: Uri, newUri: Uri, options: {overwrite: boolean}): void Thenable
stat(uri: Uri): FileStat Thenable

watch(uri: Uri, options: {excludes: string[], recursive: boolean}): Disposable

writeFile(uri: Uri, content: Uint8Array, options: {create: boolean, overwrite: boolean}): void Thenable

FileType

  • Enumeration of file types. The types File and Directory can also be a symbolic links, in that case use FileType.File FileType.SymbolicLink and FileType.Directory FileType.SymbolicLink.

FoldingRange

FoldingRangeKind

FoldingRangeProvider

FormattingOptions

GlobPattern

  • either be a glob pattern string (like */.{ts,js} or *.{ts,js}) or a relative pattern

A file glob pattern to match file paths against. This can either be a glob pattern string (like */.{ts,js} or *.{ts,js}) or a relative pattern.

Glob patterns can have the following syntax:

* to match one or more characters in a path segment
? to match on one character in a path segment
** to match any number of path segments, including none
{} to group conditions (e.g. **/*.{ts,js} matches all TypeScript and JavaScript files)
[] to declare a range of characters to match in a path segment (e.g., example.[0-9] to match on example.0, example.1, …)
[!...] to negate a range of characters to match in a path segment (e.g., example.[!0-9] to match on example.a, example.b, but not example.0)

Note: a backslash () is not valid within a glob pattern. If you have an existing file path to match against, consider to use the relative pattern support that takes care of converting any backslash into slash. Otherwise, make sure to convert any backslash to slash when creating the glob pattern.

Hover

  • additional information for a symbol or word. Hovers are rendered in a tooltip-like widget

HoverProvider

ImplementationProvider

  • contract between extensions and the go to implementation feature.

InputBox

  • concrete QuickInput to let the user input a text value.
  • many cases the more convenient window.showInputBox is easier to use. window.createInputBox should be used when window.showInputBox does not offer the required flexibility

OutputChannel

link: https://code.visualstudio.com/api/references/vscode-api#OutputChannel

  • An output channel is a container for readonly textual information.

Position

  • Represents a line and character position, such as the position of the cursor.

  • Position objects are immutable. Use the with or translate methods to derive new positions from an existing position.

Progress

ProgressOptions

  • #window

udpates

We’ve added a new option to the ProgressOptions.location of the window.withProgress API to allow progress to be shown on a specific view. To use, set ProgressOptions.location = { viewId: <view-id> }; where <view-id> specifies the ID of the view you’d like to show progress for. There is short video of this in action in the view progress section above.

ProviderResult

  • A provider result represents the values a provider, like the HoverProvider, may return
  • this is the actual result type T, like Hover, or a thenable that resolves to that type T. In addition, null and undefined can be returned - either directly or from a thenable

QuickDiffProvider

QuickInput

  • user input UI that is initially not visible

  • After configuring it through its properties the extension can make it visible by calling QuickInput.show

  • A user pressing Enter or some other gesture implying acceptance of the current state does not automatically hide this UI componen

  • When the extension no longer needs this input UI, it should QuickInput.dispose

  • consider using window.showInputBox

QuickPick

events

onDidAccept: Event onDidChangeActive: Event<T\[]> onDidChangeSelection: Event<T\[]> onDidChangeValue: Event onDidHide: Event onDidTriggerButton: Event

props

activeItems: ReadonlyArray

busy: boolean

buttons: ReadonlyArray

canSelectMany: boolean

enabled: boolean

ignoreFocusOut: boolean

items: ReadonlyArray

matchOnDescription: boolean

matchOnDetail: boolean

placeholder: string undefined

selectedItems: ReadonlyArray

step: number undefined
title: string undefined
totalSteps: number undefined

value: string

methods

dispose(): void

hide(): void

show(): void

QuickPickItem

  • Represents an item that can be selected from a list of items.

prop

alwaysShow?

busy

  • type: boolean

If the UI should show a progress indicator. Defaults to false. Change this to true, e.g., while loading more data or validating user input.

label: string

description?: string

A human-readable string which is rendered less prominent in the same line. Supports rendering of theme icons via the \$()-syntax.

detail?: string

A human-readable string which is rendered less prominent in a separate line. Supports rendering of theme icons via the \$()-syntax.

picked?: boolean

Optional flag indicating if this item is picked initially. (Only honored when the picker allows multiple selections.)

QuickPickOptions

events

onDidSelectItem

onDidAccept

ShellExecution

SnippetString

  • template which allows to insert text and to control the editor cursor when insertion happens.

SourceControl

TextDocument

Represents a text document, such as a source file. Text documents have lines and knowledge about an underlying resource like a file.

TextDocumentContentChangeEvent

export interface TextDocumentContentChangeEvent {
    /**
     * The range that got replaced.
     */
    readonly range: Range;
    /**
     * The offset of the range that got replaced.
     */
    readonly rangeOffset: number;
    /**
     * The length of the range that got replaced.
     */
    readonly rangeLength: number;
    /**
     * The new text for the range.
     */
    readonly text: string;
}


TextDocumentWillSaveEvent#

An event that is fired when a document will be saved.

To make modifications to the document before it is being saved, call the waitUntil-function with a thenable that resolves to an array of text edits.

properties

document: TextDocument reason: TextDocumentSaveReason

methods

waitUntil

  • sig: (thenable: Thenable<TextEdit[]>): void
workspace.onWillSaveTextDocument(event => {
    // async, will *throw* an error
    setTimeout(() => event.waitUntil(promise));

    // sync, OK
    event.waitUntil(promise);
})

TextEdit

A text edit represents edits that should be applied to a document.

TextEditor

edit

Perform an edit on the document associated with this text editor.

The given callback-function is invoked with an edit-builder which must be used to make edits. Note that the edit-builder is only valid while the callback executes.

  • sig
(callback: (editBuilder: TextEditorEdit) => void, options?: {undoStopAfter: boolean, undoStopBefore: boolean}): Thenable<boolean>

TextEditorEdit

A complex edit that will be applied in one transaction on a TextEditor. This holds a description of the edits and if the edits are valid (i.e. no overlapping regions, document was not changed in the meantime, etc.) they can be applied on a document associated with a text editor.

ThemeIcon

related:

  • codicons: https://microsoft.github.io/vscode-codicons/dist/codicon.html

  • A reference to a named icon

  • Currently, File, Folder, and codicons are supported

  • Using a theme icon is preferred over a custom icon as it gives theme authors the possibility to change the icons.

  • Note that theme icons can also be rendered inside labels and descriptions

  • Places that support theme icons spell this out and they use the $()-syntax, for instance quickPick.label = "Hello World $(globe)".

WebviewOptions

localResourceRoots?: ReadonlyArray

Root paths from which the webview can load local (filesystem) resources using uris from asWebviewUri

Default to the root folders of the current workspace plus the extension’s install directory.

Pass in an empty array to disallow access to any local resources.

WebviewPanelSerializer

Restore webview panels that have been persisted when vscode shuts down.

There are two types of webview persistence:

Persistence within a session.
Persistence across sessions (across restarts of VS Code).

A WebviewPanelSerializer is only required for the second case: persisting a webview across sessions.

WorkspaceConfiguration

  • merge of
    • Default Settings
    • Global (User) Settings
    • Workspace settings
    • Workspace Folder settings - From one of the Workspace Folders under which requested resource belongs to.
    • Language settings - Settings defined under requested language.

methods

update

  • sig: update(section: string, value: any, configurationTarget?: ConfigurationTarget | boolean, overrideInLanguage?: boolean): Thenable<void>
  • Note: To remove a configuration value use undefined, like so: config.update(‘somekey’, undefined)
  • params:
  • throws - error while updating configuration which is not registered. window configuration to workspace folder configuration to workspace or workspace folder when no workspace is opened. configuration to workspace folder when there is no workspace folder settings. configuration to workspace folder when WorkspaceConfiguration is not scoped to a resource.

WorkspaceEdit

replace

  • sig
replace(uri: Uri, range: Range, newText: string, metadata?: WorkspaceEditEntryMetadata): void

Related


Table of contents


Copyright © 2020 Thence LLC