From 833b0549e34a29ffe9f674259e2f98a207b59304 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Moreno?= Date: Fri, 7 Nov 2025 13:48:24 +0100 Subject: [PATCH] remove vscode-api.md from source, it gets generated by vscode-website --- api/references/.gitignore | 1 + api/references/vscode-api.md | 21446 --------------------------------- 2 files changed, 1 insertion(+), 21446 deletions(-) create mode 100644 api/references/.gitignore delete mode 100644 api/references/vscode-api.md diff --git a/api/references/.gitignore b/api/references/.gitignore new file mode 100644 index 0000000000..2a3e3ee064 --- /dev/null +++ b/api/references/.gitignore @@ -0,0 +1 @@ +vscode-api.md \ No newline at end of file diff --git a/api/references/vscode-api.md b/api/references/vscode-api.md deleted file mode 100644 index 216da6d46c..0000000000 --- a/api/references/vscode-api.md +++ /dev/null @@ -1,21446 +0,0 @@ ---- -# DO NOT TOUCH — Managed by doc writer -ContentId: 8CEBCDF8-4F0A-4C81-A904-3DEA43480EA6 -DateApproved: 10/09/2025 - -VSCodeCommitHash: 96d03d1ecc393a047d549dc8bd13c74dc174f20a -VSCodeVersion: 1.51.0 - -# Summarize the whole topic in less than 300 characters for SEO purpose -MetaDescription: Visual Studio Code extensions (plug-in) API Reference. ---- - -# VS Code API - -**VS Code API** is a set of JavaScript APIs that you can invoke in your Visual Studio Code extension. This page lists all VS Code APIs available to extension authors. - -## API namespaces and classes - -This listing is compiled from the [`vscode.d.ts`](https://github.com/microsoft/vscode/blob/main/src/vs/vscode.d.ts) file from the VS Code repository. - -## authentication - - - -

Namespace for authentication.

-
- -#### Events - - - -onDidChangeSessions: Event<AuthenticationSessionsChangeEvent> -
-

An event which fires when the authentication sessions of an authentication provider have -been added, removed, or changed.

-
-
- -#### Functions - - - -getSession(providerId: string, scopes: string[], options: AuthenticationGetSessionOptions & {createIfNone: true}): Thenable<AuthenticationSession> -
-

Get an authentication session matching the desired scopes. Rejects if a provider with providerId is not -registered, or if the user does not consent to sharing authentication information with -the extension. If there are multiple sessions with the same scopes, the user will be shown a -quickpick to select which account they would like to use.

-

Currently, there are only two authentication providers that are contributed from built in extensions -to VS Code that implement GitHub and Microsoft authentication: their providerId's are 'github' and 'microsoft'.

-
-
- - - - - - - -
ParameterDescription
providerId: string

The id of the provider to use

-
scopes: string[]

A list of scopes representing the permissions requested. These are dependent on the authentication provider

-
options: AuthenticationGetSessionOptions & {createIfNone: true}

The getSessionOptions to use

-
ReturnsDescription
Thenable<AuthenticationSession>

A thenable that resolves to an authentication session

-
-
-
- - - -getSession(providerId: string, scopes: string[], options?: AuthenticationGetSessionOptions): Thenable<AuthenticationSession | undefined> -
-

Get an authentication session matching the desired scopes. Rejects if a provider with providerId is not -registered, or if the user does not consent to sharing authentication information with -the extension. If there are multiple sessions with the same scopes, the user will be shown a -quickpick to select which account they would like to use.

-

Currently, there are only two authentication providers that are contributed from built in extensions -to VS Code that implement GitHub and Microsoft authentication: their providerId's are 'github' and 'microsoft'.

-
-
- - - - - - - -
ParameterDescription
providerId: string

The id of the provider to use

-
scopes: string[]

A list of scopes representing the permissions requested. These are dependent on the authentication provider

-
options?: AuthenticationGetSessionOptions

The getSessionOptions to use

-
ReturnsDescription
Thenable<AuthenticationSession | undefined>

A thenable that resolves to an authentication session if available, or undefined if there are no sessions

-
-
-
- -## commands - - - -

Namespace for dealing with commands. In short, a command is a function with a -unique identifier. The function is sometimes also called command handler.

-

Commands can be added to the editor using the registerCommand -and registerTextEditorCommand functions. Commands -can be executed manually or from a UI gesture. Those are:

- -

Commands from other extensions and from the editor itself are accessible to an extension. However, -when invoking an editor command not all argument types are supported.

-

This is a sample that registers a command handler and adds an entry for that command to the palette. First -register a command handler with the identifier extension.sayHello.

- -
commands.registerCommand('extension.sayHello', () => {
-    window.showInformationMessage('Hello World!');
-});
-
-

Second, bind the command identifier to a title under which it will show in the palette (package.json).

- -
{
-    "contributes": {
-        "commands": [{
-            "command": "extension.sayHello",
-            "title": "Hello World"
-        }]
-    }
-}
-
-
- -#### Functions - - - -executeCommand<T>(command: string, ...rest: any[]): Thenable<T | undefined> -
-

Executes the command denoted by the given command identifier.

-
    -
  • Note 1: When executing an editor command not all types are allowed to -be passed as arguments. Allowed are the primitive types string, boolean, -number, undefined, and null, as well as Position, Range, Uri and Location.
    • -
  • Note 2: There are no restrictions when executing commands that have been contributed -by extensions.
    • -
-
-
- - - - - - -
ParameterDescription
command: string

Identifier of the command to execute.

-
...rest: any[]

Parameters passed to the command function.

-
ReturnsDescription
Thenable<T | undefined>

A thenable that resolves to the returned value of the given command. undefined when -the command handler function doesn't return anything.

-
-
-
- - - -getCommands(filterInternal?: boolean): Thenable<string[]> -
-

Retrieve the list of all available commands. Commands starting with an underscore are -treated as internal commands.

-
-
- - - - - -
ParameterDescription
filterInternal?: boolean

Set true to not see internal commands (starting with an underscore)

-
ReturnsDescription
Thenable<string[]>

Thenable that resolves to a list of command ids.

-
-
-
- - - -registerCommand(command: string, callback: (args: any[]) => any, thisArg?: any): Disposable -
-

Registers a command that can be invoked via a keyboard shortcut, -a menu item, an action, or directly.

-

Registering a command with an existing command identifier twice -will cause an error.

-
-
- - - - - - - -
ParameterDescription
command: string

A unique identifier for the command.

-
callback: (args: any[]) => any

A command handler function.

-
thisArg?: any

The this context used when invoking the handler function.

-
ReturnsDescription
Disposable

Disposable which unregisters this command on disposal.

-
-
-
- - - -registerTextEditorCommand(command: string, callback: (textEditor: TextEditor, edit: TextEditorEdit, args: any[]) => void, thisArg?: any): Disposable -
-

Registers a text editor command that can be invoked via a keyboard shortcut, -a menu item, an action, or directly.

-

Text editor commands are different from ordinary commands as -they only execute when there is an active editor when the command is called. Also, the -command handler of an editor command has access to the active editor and to an -edit-builder. Note that the edit-builder is only valid while the -callback executes.

-
-
- - - - - - - -
ParameterDescription
command: string

A unique identifier for the command.

-
callback: (textEditor: TextEditor, edit: TextEditorEdit, args: any[]) => void

A command handler function with access to an editor and an edit.

-
thisArg?: any

The this context used when invoking the handler function.

-
ReturnsDescription
Disposable

Disposable which unregisters this command on disposal.

-
-
-
- -## comments - - - -
- -#### Functions - - - -createCommentController(id: string, label: string): CommentController -
-

Creates a new comment controller instance.

-
-
- - - - - - -
ParameterDescription
id: string

An id for the comment controller.

-
label: string

A human-readable string for the comment controller.

-
ReturnsDescription
CommentController

An instance of comment controller.

-
-
-
- -## debug - - - -

Namespace for debug functionality.

-
- -#### Variables - - - -activeDebugConsole: DebugConsole -
-

The currently active debug console. -If no debug session is active, output sent to the debug console is not shown.

-
-
- - - -activeDebugSession: DebugSession | undefined -
-

The currently active debug session or undefined. The active debug session is the one -represented by the debug action floating window or the one currently shown in the dropdown menu of the debug action floating window. -If no debug session is active, the value is undefined.

-
-
- - - -breakpoints: Breakpoint[] -
-

List of breakpoints.

-
-
- -#### Events - - - -onDidChangeActiveDebugSession: Event<DebugSession | undefined> -
-

An event which fires when the active debug session -has changed. Note that the event also fires when the active debug session changes -to undefined.

-
-
- - - -onDidChangeBreakpoints: Event<BreakpointsChangeEvent> -
-

An event that is emitted when the set of breakpoints is added, removed, or changed.

-
-
- - - -onDidReceiveDebugSessionCustomEvent: Event<DebugSessionCustomEvent> -
-

An event which fires when a custom DAP event is received from the debug session.

-
-
- - - -onDidStartDebugSession: Event<DebugSession> -
-

An event which fires when a new debug session has been started.

-
-
- - - -onDidTerminateDebugSession: Event<DebugSession> -
-

An event which fires when a debug session has terminated.

-
-
- -#### Functions - - - -addBreakpoints(breakpoints: Breakpoint[]): void -
-

Add breakpoints.

-
-
- - - - - -
ParameterDescription
breakpoints: Breakpoint[]

The breakpoints to add.

-
ReturnsDescription
void
-
-
- - - -asDebugSourceUri(source: DebugProtocolSource, session?: DebugSession): Uri -
-

Converts a "Source" descriptor object received via the Debug Adapter Protocol into a Uri that can be used to load its contents. -If the source descriptor is based on a path, a file Uri is returned. -If the source descriptor uses a reference number, a specific debug Uri (scheme 'debug') is constructed that requires a corresponding VS Code ContentProvider and a running debug session

-

If the "Source" descriptor has insufficient information for creating the Uri, an error is thrown.

-
-
- - - - - - -
ParameterDescription
source: DebugProtocolSource

An object conforming to the Source type defined in the Debug Adapter Protocol.

-
session?: DebugSession

An optional debug session that will be used when the source descriptor uses a reference number to load the contents from an active debug session.

-
ReturnsDescription
Uri

A uri that can be used to load the contents of the source.

-
-
-
- - - -registerDebugAdapterDescriptorFactory(debugType: string, factory: DebugAdapterDescriptorFactory): Disposable -
-

Register a debug adapter descriptor factory for a specific debug type. -An extension is only allowed to register a DebugAdapterDescriptorFactory for the debug type(s) defined by the extension. Otherwise an error is thrown. -Registering more than one DebugAdapterDescriptorFactory for a debug type results in an error.

-
-
- - - - - - -
ParameterDescription
debugType: string

The debug type for which the factory is registered.

-
factory: DebugAdapterDescriptorFactory

The debug adapter descriptor factory to register.

-
ReturnsDescription
Disposable

A disposable that unregisters this factory when being disposed.

-
-
-
- - - -registerDebugAdapterTrackerFactory(debugType: string, factory: DebugAdapterTrackerFactory): Disposable -
-

Register a debug adapter tracker factory for the given debug type.

-
-
- - - - - - -
ParameterDescription
debugType: string

The debug type for which the factory is registered or '*' for matching all debug types.

-
factory: DebugAdapterTrackerFactory

The debug adapter tracker factory to register.

-
ReturnsDescription
Disposable

A disposable that unregisters this factory when being disposed.

-
-
-
- - - -registerDebugConfigurationProvider(debugType: string, provider: DebugConfigurationProvider, triggerKind?: DebugConfigurationProviderTriggerKind): Disposable -
-

Register a debug configuration provider for a specific debug type. -The optional triggerKind can be used to specify when the provideDebugConfigurations method of the provider is triggered. -Currently two trigger kinds are possible: with the value Initial (or if no trigger kind argument is given) the provideDebugConfigurations method is used to provide the initial debug configurations to be copied into a newly created launch.json. -With the trigger kind Dynamic the provideDebugConfigurations method is used to dynamically determine debug configurations to be presented to the user (in addition to the static configurations from the launch.json). -Please note that the triggerKind argument only applies to the provideDebugConfigurations method: so the resolveDebugConfiguration methods are not affected at all. -Registering a single provider with resolve methods for different trigger kinds, results in the same resolve methods called multiple times. -More than one provider can be registered for the same type.

-
-
- - - - - - - -
ParameterDescription
debugType: string
provider: DebugConfigurationProvider

The debug configuration provider to register.

-
triggerKind?: DebugConfigurationProviderTriggerKind

The trigger for which the 'provideDebugConfiguration' method of the provider is registered. If triggerKind is missing, the value DebugConfigurationProviderTriggerKind.Initial is assumed.

-
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

-
-
-
- - - -removeBreakpoints(breakpoints: Breakpoint[]): void -
-

Remove breakpoints.

-
-
- - - - - -
ParameterDescription
breakpoints: Breakpoint[]

The breakpoints to remove.

-
ReturnsDescription
void
-
-
- - - -startDebugging(folder: WorkspaceFolder | undefined, nameOrConfiguration: string | DebugConfiguration, parentSessionOrOptions?: DebugSession | DebugSessionOptions): Thenable<boolean> -
-

Start debugging by using either a named launch or named compound configuration, -or by directly passing a DebugConfiguration. -The named configurations are looked up in '.vscode/launch.json' found in the given folder. -Before debugging starts, all unsaved files are saved and the launch configurations are brought up-to-date. -Folder specific variables used in the configuration (e.g. '${workspaceFolder}') are resolved against the given folder.

-
-
- - - - - - - -
ParameterDescription
folder: WorkspaceFolder | undefined

The workspace folder for looking up named configurations and resolving variables or undefined for a non-folder setup.

-
nameOrConfiguration: string | DebugConfiguration

Either the name of a debug or compound configuration or a DebugConfiguration object.

-
parentSessionOrOptions?: DebugSession | DebugSessionOptions

Debug session options. When passed a parent debug session, assumes options with just this parent session.

-
ReturnsDescription
Thenable<boolean>

A thenable that resolves when debugging could be successfully started.

-
-
-
- - - -stopDebugging(session?: DebugSession): Thenable<void> -
-

Stop the given debug session or stop all debug sessions if session is omitted.

-
-
- - - - - -
ParameterDescription
session?: DebugSession

The debug session to stop; if omitted all sessions are stopped.

-
ReturnsDescription
Thenable<void>
-
-
- -## env - - - -

Namespace describing the environment the editor runs in.

-
- -#### Variables - - - -appName: string -
-

The application name of the editor, like 'VS Code'.

-
-
- - - -appRoot: string -
-

The application root folder from which the editor is running.

-

Note that the value is the empty string when running in an -environment that has no representation of an application root folder.

-
-
- - - -clipboard: Clipboard -
-

The system clipboard.

-
-
- - - -language: string -
-

Represents the preferred user-language, like de-CH, fr, or en-US.

-
-
- - - -machineId: string -
-

A unique identifier for the computer.

-
-
- - - -remoteName: string | undefined -
-

The name of a remote. Defined by extensions, popular samples are wsl for the Windows -Subsystem for Linux or ssh-remote for remotes using a secure shell.

-

Note that the value is undefined when there is no remote extension host but that the -value is defined in all extension hosts (local and remote) in case a remote extension host -exists. Use Extension#extensionKind to know if -a specific extension runs remote or not.

-
-
- - - -sessionId: string -
-

A unique identifier for the current session. -Changes each time the editor is started.

-
-
- - - -shell: string -
-

The detected default shell for the extension host, this is overridden by the -terminal.integrated.shell setting for the extension host's platform. Note that in -environments that do not support a shell the value is the empty string.

-
-
- - - -uiKind: UIKind -
-

The UI kind property indicates from which UI extensions -are accessed from. For example, extensions could be accessed -from a desktop application or a web browser.

-
-
- - - -uriScheme: string -
-

The custom uri scheme the editor registers to in the operating system.

-
-
- -#### Functions - - - -asExternalUri(target: Uri): Thenable<Uri> -
-

Resolves a uri to form that is accessible externally. Currently only supports https:, http: and -vscode.env.uriScheme uris.

-

http: or https: scheme

-

Resolves an external uri, such as a http: or https: link, from where the extension is running to a -uri to the same resource on the client machine.

-

This is a no-op if the extension is running on the client machine.

-

If the extension is running remotely, this function automatically establishes a port forwarding tunnel -from the local machine to target on the remote and returns a local uri to the tunnel. The lifetime of -the port forwarding tunnel is managed by VS Code and the tunnel can be closed by the user.

-

Note that uris passed through openExternal are automatically resolved and you should not call asExternalUri on them.

-

vscode.env.uriScheme

-

Creates a uri that - if opened in a browser (e.g. via openExternal) - will result in a registered UriHandler -to trigger.

-

Extensions should not make any assumptions about the resulting uri and should not alter it in anyway. -Rather, extensions can e.g. use this uri in an authentication flow, by adding the uri as callback query -argument to the server to authenticate to.

-

Note that if the server decides to add additional query parameters to the uri (e.g. a token or secret), it -will appear in the uri that is passed to the UriHandler.

-

Example of an authentication flow:

- -
vscode.window.registerUriHandler({
-  handleUri(uri: vscode.Uri): vscode.ProviderResult<void> {
-    if (uri.path === '/did-authenticate') {
-      console.log(uri.toString());
-    }
-  }
-});
-
-const callableUri = await vscode.env.asExternalUri(vscode.Uri.parse(`${vscode.env.uriScheme}://my.extension/did-authenticate`));
-await vscode.env.openExternal(callableUri);
-
-

Note that extensions should not cache the result of asExternalUri as the resolved uri may become invalid due to -a system or user action — for example, in remote cases, a user may close a port forwarding tunnel that was opened by -asExternalUri.

-
-
- - - - - -
ParameterDescription
target: Uri
ReturnsDescription
Thenable<Uri>

A uri that can be used on the client machine.

-
-
-
- - - -openExternal(target: Uri): Thenable<boolean> -
-

Opens a link externally using the default application. Depending on the -used scheme this can be:

-
    -
  • a browser (http:, https:)
    • -
  • a mail client (mailto:)
    • -
  • VSCode itself (vscode: from vscode.env.uriScheme)
    • -
-

Note that showTextDocument is the right -way to open a text document inside the editor, not this function.

-
-
- - - - - -
ParameterDescription
target: Uri

The uri that should be opened.

-
ReturnsDescription
Thenable<boolean>

A promise indicating if open was successful.

-
-
-
- -## extensions - - - -

Namespace for dealing with installed extensions. Extensions are represented -by an extension-interface which enables reflection on them.

-

Extension writers can provide APIs to other extensions by returning their API public -surface from the activate-call.

- -
export function activate(context: vscode.ExtensionContext) {
-    let api = {
-        sum(a, b) {
-            return a + b;
-        },
-        mul(a, b) {
-            return a * b;
-        }
-    };
-    // 'export' public api-surface
-    return api;
-}
-
-

When depending on the API of another extension add an extensionDependencies-entry -to package.json, and use the getExtension-function -and the exports-property, like below:

- -
let mathExt = extensions.getExtension('genius.math');
-let importedApi = mathExt.exports;
-
-console.log(importedApi.mul(42, 1));
-
-
- -#### Variables - - - -all: ReadonlyArray<Extension<any>> -
-

All extensions currently known to the system.

-
-
- -#### Events - - - -onDidChange: Event<void> -
-

An event which fires when extensions.all changes. This can happen when extensions are -installed, uninstalled, enabled or disabled.

-
-
- -#### Functions - - - -getExtension(extensionId: string): Extension<any> | undefined -
-

Get an extension by its full identifier in the form of: publisher.name.

-
-
- - - - - -
ParameterDescription
extensionId: string

An extension identifier.

-
ReturnsDescription
Extension<any> | undefined

An extension or undefined.

-
-
-
- - - -getExtension<T>(extensionId: string): Extension<T> | undefined -
-

Get an extension by its full identifier in the form of: publisher.name.

-
-
- - - - - -
ParameterDescription
extensionId: string

An extension identifier.

-
ReturnsDescription
Extension<T> | undefined

An extension or undefined.

-
-
-
- -## languages - - - -

Namespace for participating in language-specific editor features, -like IntelliSense, code actions, diagnostics etc.

-

Many programming languages exist and there is huge variety in syntaxes, semantics, and paradigms. Despite that, features -like automatic word-completion, code navigation, or code checking have become popular across different tools for different -programming languages.

-

The editor provides an API that makes it simple to provide such common features by having all UI and actions already in place and -by allowing you to participate by providing data only. For instance, to contribute a hover all you have to do is provide a function -that can be called with a TextDocument and a Position returning hover info. The rest, like tracking the -mouse, positioning the hover, keeping the hover stable etc. is taken care of by the editor.

- -
languages.registerHoverProvider('javascript', {
-    provideHover(document, position, token) {
-        return new Hover('I am a hover!');
-    }
-});
-
-

Registration is done using a document selector which is either a language ID, like javascript or -a more complex filter like { language: 'typescript', scheme: 'file' }. Matching a document against such -a selector will result in a score that is used to determine if and how a provider shall be used. When -scores are equal the provider that came last wins. For features that allow full arity, like hover, -the score is only checked to be >0, for other features, like IntelliSense the -score is used for determining the order in which providers are asked to participate.

-
- -#### Events - - - -onDidChangeDiagnostics: Event<DiagnosticChangeEvent> -
-

An event which fires when the global set of diagnostics changes. This is -newly added and removed diagnostics.

-
-
- -#### Functions - - - -createDiagnosticCollection(name?: string): DiagnosticCollection -
-

Create a diagnostics collection.

-
-
- - - - - -
ParameterDescription
name?: string

The name of the collection.

-
ReturnsDescription
DiagnosticCollection

A new diagnostic collection.

-
-
-
- - - -getDiagnostics(resource: Uri): Diagnostic[] -
-

Get all diagnostics for a given resource.

-
-
- - - - - -
ParameterDescription
resource: Uri

A resource

-
ReturnsDescription
Diagnostic[]

An array of diagnostics objects or an empty array.

-
-
-
- - - -getDiagnostics(): [Uri, Diagnostic[]][] -
-

Get all diagnostics.

-
-
- - - -
ReturnsDescription
[Uri, Diagnostic[]][]

An array of uri-diagnostics tuples or an empty array.

-
-
-
- - - -getLanguages(): Thenable<string[]> -
-

Return the identifiers of all known languages.

-
-
- - - -
ReturnsDescription
Thenable<string[]>

Promise resolving to an array of identifier strings.

-
-
-
- - - -match(selector: DocumentSelector, document: TextDocument): number -
-

Compute the match between a document selector and a document. Values -greater than zero mean the selector matches the document.

-

A match is computed according to these rules:

-
    -
  1. When DocumentSelector is an array, compute the match for each contained DocumentFilter or language identifier and take the maximum value.
    2. -
  2. A string will be desugared to become the language-part of a DocumentFilter, so "fooLang" is like { language: "fooLang" }.
    3. -
  3. A DocumentFilter will be matched against the document by comparing its parts with the document. The following rules apply:
      -
    1. When the DocumentFilter is empty ({}) the result is 0
      2. -
    2. When scheme, language, or pattern are defined but one doesn’t match, the result is 0
      3. -
    3. Matching against * gives a score of 5, matching via equality or via a glob-pattern gives a score of 10
      4. -
    4. The result is the maximum value of each match
      5. -
    -
    4. -
-

Samples:

- -
// default document from disk (file-scheme)
-doc.uri; //'file:///my/file.js'
-doc.languageId; // 'javascript'
-match('javascript', doc); // 10;
-match({language: 'javascript'}, doc); // 10;
-match({language: 'javascript', scheme: 'file'}, doc); // 10;
-match('*', doc); // 5
-match('fooLang', doc); // 0
-match(['fooLang', '*'], doc); // 5
-
-// virtual document, e.g. from git-index
-doc.uri; // 'git:/my/file.js'
-doc.languageId; // 'javascript'
-match('javascript', doc); // 10;
-match({language: 'javascript', scheme: 'git'}, doc); // 10;
-match('*', doc); // 5
-
-
-
- - - - - - -
ParameterDescription
selector: DocumentSelector

A document selector.

-
document: TextDocument

A text document.

-
ReturnsDescription
number

A number >0 when the selector matches and 0 when the selector does not match.

-
-
-
- - - -registerCallHierarchyProvider(selector: DocumentSelector, provider: CallHierarchyProvider): Disposable -
-

Register a call hierarchy provider.

-
-
- - - - - - -
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

-
provider: CallHierarchyProvider

A call hierarchy provider.

-
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

-
-
-
- - - -registerCodeActionsProvider(selector: DocumentSelector, provider: CodeActionProvider, metadata?: CodeActionProviderMetadata): Disposable -
-

Register a code action provider.

-

Multiple providers can be registered for a language. In that case providers are asked in -parallel and the results are merged. A failing provider (rejected promise or exception) will -not cause a failure of the whole operation.

-
-
- - - - - - - -
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

-
provider: CodeActionProvider

A code action provider.

-
metadata?: CodeActionProviderMetadata

Metadata about the kind of code actions the provider provides.

-
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

-
-
-
- - - -registerCodeLensProvider(selector: DocumentSelector, provider: CodeLensProvider): Disposable -
-

Register a code lens provider.

-

Multiple providers can be registered for a language. In that case providers are asked in -parallel and the results are merged. A failing provider (rejected promise or exception) will -not cause a failure of the whole operation.

-
-
- - - - - - -
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

-
provider: CodeLensProvider

A code lens provider.

-
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

-
-
-
- - - -registerColorProvider(selector: DocumentSelector, provider: DocumentColorProvider): Disposable -
-

Register a color provider.

-

Multiple providers can be registered for a language. In that case providers are asked in -parallel and the results are merged. A failing provider (rejected promise or exception) will -not cause a failure of the whole operation.

-
-
- - - - - - -
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

-
provider: DocumentColorProvider

A color provider.

-
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

-
-
-
- - - -registerCompletionItemProvider(selector: DocumentSelector, provider: CompletionItemProvider, ...triggerCharacters: string[]): Disposable -
-

Register a completion provider.

-

Multiple providers can be registered for a language. In that case providers are sorted -by their score and groups of equal score are sequentially asked for -completion items. The process stops when one or many providers of a group return a -result. A failing provider (rejected promise or exception) will not fail the whole -operation.

-

A completion item provider can be associated with a set of triggerCharacters. When trigger -characters are being typed, completions are requested but only from providers that registered -the typed character. Because of that trigger characters should be different than word characters, -a common trigger character is . to trigger member completions.

-
-
- - - - - - - -
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

-
provider: CompletionItemProvider

A completion provider.

-
...triggerCharacters: string[]

Trigger completion when the user types one of the characters.

-
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

-
-
-
- - - -registerDeclarationProvider(selector: DocumentSelector, provider: DeclarationProvider): Disposable -
-

Register a declaration provider.

-

Multiple providers can be registered for a language. In that case providers are asked in -parallel and the results are merged. A failing provider (rejected promise or exception) will -not cause a failure of the whole operation.

-
-
- - - - - - -
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

-
provider: DeclarationProvider

A declaration provider.

-
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

-
-
-
- - - -registerDefinitionProvider(selector: DocumentSelector, provider: DefinitionProvider): Disposable -
-

Register a definition provider.

-

Multiple providers can be registered for a language. In that case providers are asked in -parallel and the results are merged. A failing provider (rejected promise or exception) will -not cause a failure of the whole operation.

-
-
- - - - - - -
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

-
provider: DefinitionProvider

A definition provider.

-
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

-
-
-
- - - -registerDocumentFormattingEditProvider(selector: DocumentSelector, provider: DocumentFormattingEditProvider): Disposable -
-

Register a formatting provider for a document.

-

Multiple providers can be registered for a language. In that case providers are sorted -by their score and the best-matching provider is used. Failure -of the selected provider will cause a failure of the whole operation.

-
-
- - - - - - -
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

-
provider: DocumentFormattingEditProvider

A document formatting edit provider.

-
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

-
-
-
- - - -registerDocumentHighlightProvider(selector: DocumentSelector, provider: DocumentHighlightProvider): Disposable -
-

Register a document highlight provider.

-

Multiple providers can be registered for a language. In that case providers are sorted -by their score and groups sequentially asked for document highlights. -The process stops when a provider returns a non-falsy or non-failure result.

-
-
- - - - - - -
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

-
provider: DocumentHighlightProvider

A document highlight provider.

-
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

-
-
-
- - - -registerDocumentLinkProvider(selector: DocumentSelector, provider: DocumentLinkProvider): Disposable -
-

Register a document link provider.

-

Multiple providers can be registered for a language. In that case providers are asked in -parallel and the results are merged. A failing provider (rejected promise or exception) will -not cause a failure of the whole operation.

-
-
- - - - - - -
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

-
provider: DocumentLinkProvider

A document link provider.

-
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

-
-
-
- - - -registerDocumentRangeFormattingEditProvider(selector: DocumentSelector, provider: DocumentRangeFormattingEditProvider): Disposable -
-

Register a formatting provider for a document range.

-

Note: A document range provider is also a document formatter -which means there is no need to register a document -formatter when also registering a range provider.

-

Multiple providers can be registered for a language. In that case providers are sorted -by their score and the best-matching provider is used. Failure -of the selected provider will cause a failure of the whole operation.

-
-
- - - - - - -
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

-
provider: DocumentRangeFormattingEditProvider

A document range formatting edit provider.

-
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

-
-
-
- - - -registerDocumentRangeSemanticTokensProvider(selector: DocumentSelector, provider: DocumentRangeSemanticTokensProvider, legend: SemanticTokensLegend): Disposable -
-

Register a semantic tokens provider for a document range.

-

Note: If a document has both a DocumentSemanticTokensProvider and a DocumentRangeSemanticTokensProvider, -the range provider will be invoked only initially, for the time in which the full document provider takes -to resolve the first request. Once the full document provider resolves the first request, the semantic tokens -provided via the range provider will be discarded and from that point forward, only the document provider -will be used.

-

Multiple providers can be registered for a language. In that case providers are sorted -by their score and the best-matching provider is used. Failure -of the selected provider will cause a failure of the whole operation.

-
-
- - - - - - - -
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

-
provider: DocumentRangeSemanticTokensProvider

A document range semantic tokens provider.

-
legend: SemanticTokensLegend
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

-
-
-
- - - -registerDocumentSemanticTokensProvider(selector: DocumentSelector, provider: DocumentSemanticTokensProvider, legend: SemanticTokensLegend): Disposable -
-

Register a semantic tokens provider for a whole document.

-

Multiple providers can be registered for a language. In that case providers are sorted -by their score and the best-matching provider is used. Failure -of the selected provider will cause a failure of the whole operation.

-
-
- - - - - - - -
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

-
provider: DocumentSemanticTokensProvider

A document semantic tokens provider.

-
legend: SemanticTokensLegend
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

-
-
-
- - - -registerDocumentSymbolProvider(selector: DocumentSelector, provider: DocumentSymbolProvider, metaData?: DocumentSymbolProviderMetadata): Disposable -
-

Register a document symbol provider.

-

Multiple providers can be registered for a language. In that case providers are asked in -parallel and the results are merged. A failing provider (rejected promise or exception) will -not cause a failure of the whole operation.

-
-
- - - - - - - -
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

-
provider: DocumentSymbolProvider

A document symbol provider.

-
metaData?: DocumentSymbolProviderMetadata

metadata about the provider

-
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

-
-
-
- - - -registerEvaluatableExpressionProvider(selector: DocumentSelector, provider: EvaluatableExpressionProvider): Disposable -
-

Register a provider that locates evaluatable expressions in text documents. -VS Code will evaluate the expression in the active debug session and will show the result in the debug hover.

-

If multiple providers are registered for a language an arbitrary provider will be used.

-
-
- - - - - - -
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

-
provider: EvaluatableExpressionProvider

An evaluatable expression provider.

-
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

-
-
-
- - - -registerFoldingRangeProvider(selector: DocumentSelector, provider: FoldingRangeProvider): Disposable -
-

Register a folding range provider.

-

Multiple providers can be registered for a language. In that case providers are asked in -parallel and the results are merged. -If multiple folding ranges start at the same position, only the range of the first registered provider is used. -If a folding range overlaps with an other range that has a smaller position, it is also ignored.

-

A failing provider (rejected promise or exception) will -not cause a failure of the whole operation.

-
-
- - - - - - -
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

-
provider: FoldingRangeProvider

A folding range provider.

-
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

-
-
-
- - - -registerHoverProvider(selector: DocumentSelector, provider: HoverProvider): Disposable -
-

Register a hover provider.

-

Multiple providers can be registered for a language. In that case providers are asked in -parallel and the results are merged. A failing provider (rejected promise or exception) will -not cause a failure of the whole operation.

-
-
- - - - - - -
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

-
provider: HoverProvider

A hover provider.

-
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

-
-
-
- - - -registerImplementationProvider(selector: DocumentSelector, provider: ImplementationProvider): Disposable -
-

Register an implementation provider.

-

Multiple providers can be registered for a language. In that case providers are asked in -parallel and the results are merged. A failing provider (rejected promise or exception) will -not cause a failure of the whole operation.

-
-
- - - - - - -
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

-
provider: ImplementationProvider

An implementation provider.

-
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

-
-
-
- - - -registerOnTypeFormattingEditProvider(selector: DocumentSelector, provider: OnTypeFormattingEditProvider, firstTriggerCharacter: string, ...moreTriggerCharacter: string[]): Disposable -
-

Register a formatting provider that works on type. The provider is active when the user enables the setting editor.formatOnType.

-

Multiple providers can be registered for a language. In that case providers are sorted -by their score and the best-matching provider is used. Failure -of the selected provider will cause a failure of the whole operation.

-
-
- - - - - - - - -
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

-
provider: OnTypeFormattingEditProvider

An on type formatting edit provider.

-
firstTriggerCharacter: string

A character on which formatting should be triggered, like }.

-
...moreTriggerCharacter: string[]

More trigger characters.

-
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

-
-
-
- - - -registerReferenceProvider(selector: DocumentSelector, provider: ReferenceProvider): Disposable -
-

Register a reference provider.

-

Multiple providers can be registered for a language. In that case providers are asked in -parallel and the results are merged. A failing provider (rejected promise or exception) will -not cause a failure of the whole operation.

-
-
- - - - - - -
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

-
provider: ReferenceProvider

A reference provider.

-
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

-
-
-
- - - -registerRenameProvider(selector: DocumentSelector, provider: RenameProvider): Disposable -
-

Register a rename provider.

-

Multiple providers can be registered for a language. In that case providers are sorted -by their score and asked in sequence. The first provider producing a result -defines the result of the whole operation.

-
-
- - - - - - -
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

-
provider: RenameProvider

A rename provider.

-
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

-
-
-
- - - -registerSelectionRangeProvider(selector: DocumentSelector, provider: SelectionRangeProvider): Disposable -
-

Register a selection range provider.

-

Multiple providers can be registered for a language. In that case providers are asked in -parallel and the results are merged. A failing provider (rejected promise or exception) will -not cause a failure of the whole operation.

-
-
- - - - - - -
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

-
provider: SelectionRangeProvider

A selection range provider.

-
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

-
-
-
- - - -registerSignatureHelpProvider(selector: DocumentSelector, provider: SignatureHelpProvider, ...triggerCharacters: string[]): Disposable -
-

Register a signature help provider.

-

Multiple providers can be registered for a language. In that case providers are sorted -by their score and called sequentially until a provider returns a -valid result.

-
-
- - - - - - - -
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

-
provider: SignatureHelpProvider

A signature help provider.

-
...triggerCharacters: string[]

Trigger signature help when the user types one of the characters, like , or (.

-
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

-
-
-
- - - -registerSignatureHelpProvider(selector: DocumentSelector, provider: SignatureHelpProvider, metadata: SignatureHelpProviderMetadata): Disposable -
-
-
- - - - - - - -
ParameterDescription
selector: DocumentSelector
provider: SignatureHelpProvider
metadata: SignatureHelpProviderMetadata
ReturnsDescription
Disposable
-
-
- - - -registerTypeDefinitionProvider(selector: DocumentSelector, provider: TypeDefinitionProvider): Disposable -
-

Register a type definition provider.

-

Multiple providers can be registered for a language. In that case providers are asked in -parallel and the results are merged. A failing provider (rejected promise or exception) will -not cause a failure of the whole operation.

-
-
- - - - - - -
ParameterDescription
selector: DocumentSelector

A selector that defines the documents this provider is applicable to.

-
provider: TypeDefinitionProvider

A type definition provider.

-
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

-
-
-
- - - -registerWorkspaceSymbolProvider(provider: WorkspaceSymbolProvider): Disposable -
-

Register a workspace symbol provider.

-

Multiple providers can be registered. In that case providers are asked in parallel and -the results are merged. A failing provider (rejected promise or exception) will not cause -a failure of the whole operation.

-
-
- - - - - -
ParameterDescription
provider: WorkspaceSymbolProvider

A workspace symbol provider.

-
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

-
-
-
- - - -setLanguageConfiguration(language: string, configuration: LanguageConfiguration): Disposable -
-

Set a language configuration for a language.

-
-
- - - - - - -
ParameterDescription
language: string

A language identifier like typescript.

-
configuration: LanguageConfiguration

Language configuration.

-
ReturnsDescription
Disposable

A disposable that unsets this configuration.

-
-
-
- - - -setTextDocumentLanguage(document: TextDocument, languageId: string): Thenable<TextDocument> -
-

Set (and change) the language that is associated -with the given document.

-

Note that calling this function will trigger the onDidCloseTextDocument event -followed by the onDidOpenTextDocument event.

-
-
- - - - - - -
ParameterDescription
document: TextDocument

The document which language is to be changed

-
languageId: string

The new language identifier.

-
ReturnsDescription
Thenable<TextDocument>

A thenable that resolves with the updated document.

-
-
-
- -## scm - - - -
- -#### Variables - - - -inputBox: SourceControlInputBox -
-

The input box for the last source control -created by the extension.

-
    -
  • deprecated - Use SourceControl.inputBox instead
    • -
-
-
- -#### Functions - - - -createSourceControl(id: string, label: string, rootUri?: Uri): SourceControl -
-

Creates a new source control instance.

-
-
- - - - - - - -
ParameterDescription
id: string

An id for the source control. Something short, e.g.: git.

-
label: string

A human-readable string for the source control. E.g.: Git.

-
rootUri?: Uri

An optional Uri of the root of the source control. E.g.: Uri.parse(workspaceRoot).

-
ReturnsDescription
SourceControl

An instance of source control.

-
-
-
- -## tasks - - - -

Namespace for tasks functionality.

-
- -#### Variables - - - -taskExecutions: ReadonlyArray<TaskExecution> -
-

The currently active task executions or an empty array.

-
-
- -#### Events - - - -onDidEndTask: Event<TaskEndEvent> -
-

Fires when a task ends.

-
-
- - - -onDidEndTaskProcess: Event<TaskProcessEndEvent> -
-

Fires when the underlying process has ended. -This event will not fire for tasks that don't -execute an underlying process.

-
-
- - - -onDidStartTask: Event<TaskStartEvent> -
-

Fires when a task starts.

-
-
- - - -onDidStartTaskProcess: Event<TaskProcessStartEvent> -
-

Fires when the underlying process has been started. -This event will not fire for tasks that don't -execute an underlying process.

-
-
- -#### Functions - - - -executeTask(task: Task): Thenable<TaskExecution> -
-

Executes a task that is managed by VS Code. The returned -task execution can be used to terminate the task.

-
    -
  • throws - When running a ShellExecution or a ProcessExecution -task in an environment where a new process cannot be started. -In such an environment, only CustomExecution tasks can be run.
    • -
-
-
- - - - - -
ParameterDescription
task: Task

the task to execute

-
ReturnsDescription
Thenable<TaskExecution>
-
-
- - - -fetchTasks(filter?: TaskFilter): Thenable<Task[]> -
-

Fetches all tasks available in the systems. This includes tasks -from tasks.json files as well as tasks from task providers -contributed through extensions.

-
-
- - - - - -
ParameterDescription
filter?: TaskFilter

Optional filter to select tasks of a certain type or version.

-
ReturnsDescription
Thenable<Task[]>
-
-
- - - -registerTaskProvider(type: string, provider: TaskProvider): Disposable -
-

Register a task provider.

-
-
- - - - - - -
ParameterDescription
type: string

The task kind type this provider is registered for.

-
provider: TaskProvider

A task provider.

-
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

-
-
-
- -## window - - - -

Namespace for dealing with the current window of the editor. That is visible -and active editors, as well as, UI elements to show messages, selections, and -asking for user input.

-
- -#### Variables - - - -activeColorTheme: ColorTheme -
-

The currently active color theme as configured in the settings. The active -theme can be changed via the workbench.colorTheme setting.

-
-
- - - -activeTerminal: Terminal | undefined -
-

The currently active terminal or undefined. The active terminal is the one that -currently has focus or most recently had focus.

-
-
- - - -activeTextEditor: TextEditor | undefined -
-

The currently active editor or undefined. The active editor is the one -that currently has focus or, when none has focus, the one that has changed -input most recently.

-
-
- - - -state: WindowState -
-

Represents the current window's state.

-
-
- - - -terminals: ReadonlyArray<Terminal> -
-

The currently opened terminals or an empty array.

-
-
- - - -visibleTextEditors: TextEditor[] -
-

The currently visible editors or an empty array.

-
-
- -#### Events - - - -onDidChangeActiveColorTheme: Event<ColorTheme> -
-

An event which fires when the active color theme is changed or has changes.

-
-
- - - -onDidChangeActiveTerminal: Event<Terminal | undefined> -
-

An event which fires when the active terminal -has changed. Note that the event also fires when the active terminal changes -to undefined.

-
-
- - - -onDidChangeActiveTextEditor: Event<TextEditor | undefined> -
-

An event which fires when the active editor -has changed. Note that the event also fires when the active editor changes -to undefined.

-
-
- - - -onDidChangeTextEditorOptions: Event<TextEditorOptionsChangeEvent> -
-

An event which fires when the options of an editor have changed.

-
-
- - - -onDidChangeTextEditorSelection: Event<TextEditorSelectionChangeEvent> -
-

An event which fires when the selection in an editor has changed.

-
-
- - - -onDidChangeTextEditorViewColumn: Event<TextEditorViewColumnChangeEvent> -
-

An event which fires when the view column of an editor has changed.

-
-
- - - -onDidChangeTextEditorVisibleRanges: Event<TextEditorVisibleRangesChangeEvent> -
-

An event which fires when the visible ranges of an editor has changed.

-
-
- - - -onDidChangeVisibleTextEditors: Event<TextEditor[]> -
-

An event which fires when the array of visible editors -has changed.

-
-
- - - -onDidChangeWindowState: Event<WindowState> -
-

An event which fires when the focus state of the current window -changes. The value of the event represents whether the window is focused.

-
-
- - - -onDidCloseTerminal: Event<Terminal> -
-

An event which fires when a terminal is disposed.

-
-
- - - -onDidOpenTerminal: Event<Terminal> -
-

An event which fires when a terminal has been created, either through the -createTerminal API or commands.

-
-
- -#### Functions - - - -createInputBox(): InputBox -
-

Creates a InputBox to let the user enter some text input.

-

Note that in 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.

-
-
- - - -
ReturnsDescription
InputBox

A new InputBox.

-
-
-
- - - -createOutputChannel(name: string): OutputChannel -
-

Creates a new output channel with the given name.

-
-
- - - - - -
ParameterDescription
name: string

Human-readable string which will be used to represent the channel in the UI.

-
ReturnsDescription
OutputChannel
-
-
- - - -createQuickPick<T extends QuickPickItem>(): QuickPick<T> -
-

Creates a QuickPick to let the user pick an item from a list -of items of type T.

-

Note that in many cases the more convenient window.showQuickPick -is easier to use. window.createQuickPick should be used -when window.showQuickPick does not offer the required flexibility.

-
-
- - - -
ReturnsDescription
QuickPick<T>

A new QuickPick.

-
-
-
- - - -createStatusBarItem(alignment?: StatusBarAlignment, priority?: number): StatusBarItem -
-

Creates a status bar item.

-
-
- - - - - - -
ParameterDescription
alignment?: StatusBarAlignment

The alignment of the item.

-
priority?: number

The priority of the item. Higher values mean the item should be shown more to the left.

-
ReturnsDescription
StatusBarItem

A new status bar item.

-
-
-
- - - -createTerminal(name?: string, shellPath?: string, shellArgs?: string[] | string): Terminal -
-

Creates a Terminal with a backing shell process. The cwd of the terminal will be the workspace -directory if it exists.

-
    -
  • throws - When running in an environment where a new process cannot be started.
    • -
-
-
- - - - - - - -
ParameterDescription
name?: string

Optional human-readable string which will be used to represent the terminal in the UI.

-
shellPath?: string

Optional path to a custom shell executable to be used in the terminal.

-
shellArgs?: string[] | string

Optional args for the custom shell executable. A string can be used on Windows only which -allows specifying shell args in -command-line format.

-
ReturnsDescription
Terminal

A new Terminal.

-
-
-
- - - -createTerminal(options: TerminalOptions): Terminal -
-

Creates a Terminal with a backing shell process.

-
    -
  • throws - When running in an environment where a new process cannot be started.
    • -
-
-
- - - - - -
ParameterDescription
options: TerminalOptions

A TerminalOptions object describing the characteristics of the new terminal.

-
ReturnsDescription
Terminal

A new Terminal.

-
-
-
- - - -createTerminal(options: ExtensionTerminalOptions): Terminal -
-

Creates a Terminal where an extension controls its input and output.

-
-
- - - - - -
ParameterDescription
options: ExtensionTerminalOptions

An ExtensionTerminalOptions object describing -the characteristics of the new terminal.

-
ReturnsDescription
Terminal

A new Terminal.

-
-
-
- - - -createTextEditorDecorationType(options: DecorationRenderOptions): TextEditorDecorationType -
-

Create a TextEditorDecorationType that can be used to add decorations to text editors.

-
-
- - - - - -
ParameterDescription
options: DecorationRenderOptions

Rendering options for the decoration type.

-
ReturnsDescription
TextEditorDecorationType

A new decoration type instance.

-
-
-
- - - -createTreeView<T>(viewId: string, options: TreeViewOptions<T>): TreeView<T> -
-

Create a TreeView for the view contributed using the extension point views.

-
-
- - - - - - -
ParameterDescription
viewId: string

Id of the view contributed using the extension point views.

-
options: TreeViewOptions<T>

Options for creating the TreeView

-
ReturnsDescription
TreeView<T>

a TreeView.

-
-
-
- - - -createWebviewPanel(viewType: string, title: string, showOptions: ViewColumn | {preserveFocus: boolean, viewColumn: ViewColumn}, options?: WebviewPanelOptions & WebviewOptions): WebviewPanel -
-

Create and show a new webview panel.

-
-
- - - - - - - - -
ParameterDescription
viewType: string

Identifies the type of the webview panel.

-
title: string

Title of the panel.

-
showOptions: ViewColumn | {preserveFocus: boolean, viewColumn: ViewColumn}

Where to show the webview in the editor. If preserveFocus is set, the new webview will not take focus.

-
options?: WebviewPanelOptions & WebviewOptions

Settings for the new panel.

-
ReturnsDescription
WebviewPanel

New webview panel.

-
-
-
- - - -registerCustomEditorProvider(viewType: string, provider: CustomTextEditorProvider | CustomReadonlyEditorProvider | CustomEditorProvider, options?: {supportsMultipleEditorsPerDocument: boolean, webviewOptions: WebviewPanelOptions}): Disposable -
-

Register a provider for custom editors for the viewType contributed by the customEditors extension point.

-

When a custom editor is opened, VS Code fires an onCustomEditor:viewType activation event. Your extension -must register a CustomTextEditorProvider, CustomReadonlyEditorProvider, -CustomEditorProviderfor viewType as part of activation.

-
-
- - - - - - - -
ParameterDescription
viewType: string

Unique identifier for the custom editor provider. This should match the viewType from the - customEditors contribution point.

-
provider: CustomTextEditorProvider | CustomReadonlyEditorProvider | CustomEditorProvider

Provider that resolves custom editors.

-
options?: {supportsMultipleEditorsPerDocument: boolean, webviewOptions: WebviewPanelOptions}

Options for the provider.

-
ReturnsDescription
Disposable

Disposable that unregisters the provider.

-
-
-
- - - -registerTerminalLinkProvider(provider: TerminalLinkProvider): Disposable -
-

Register provider that enables the detection and handling of links within the terminal.

-
-
- - - - - -
ParameterDescription
provider: TerminalLinkProvider

The provider that provides the terminal links.

-
ReturnsDescription
Disposable

Disposable that unregisters the provider.

-
-
-
- - - -registerTreeDataProvider<T>(viewId: string, treeDataProvider: TreeDataProvider<T>): Disposable -
-

Register a TreeDataProvider for the view contributed using the extension point views. -This will allow you to contribute data to the TreeView and update if the data changes.

-

Note: To get access to the TreeView and perform operations on it, use createTreeView.

-
-
- - - - - - -
ParameterDescription
viewId: string

Id of the view contributed using the extension point views.

-
treeDataProvider: TreeDataProvider<T>

A TreeDataProvider that provides tree data for the view

-
ReturnsDescription
Disposable
-
-
- - - -registerUriHandler(handler: UriHandler): Disposable -
-

Registers a uri handler capable of handling system-wide uris. -In case there are multiple windows open, the topmost window will handle the uri. -A uri handler is scoped to the extension it is contributed from; it will only -be able to handle uris which are directed to the extension itself. A uri must respect -the following rules:

-
    -
  • The uri-scheme must be vscode.env.uriScheme;
    • -
  • The uri-authority must be the extension id (e.g. my.extension);
    • -
  • The uri-path, -query and -fragment parts are arbitrary.
    • -
-

For example, if the my.extension extension registers a uri handler, it will only -be allowed to handle uris with the prefix product-name://my.extension.

-

An extension can only register a single uri handler in its entire activation lifetime.

-
    -
  • Note: There is an activation event onUri that fires when a uri directed for -the current extension is about to be handled.
    • -
-
-
- - - - - -
ParameterDescription
handler: UriHandler

The uri handler to register for this extension.

-
ReturnsDescription
Disposable
-
-
- - - -registerWebviewPanelSerializer(viewType: string, serializer: WebviewPanelSerializer): Disposable -
-

Registers a webview panel serializer.

-

Extensions that support reviving should have an "onWebviewPanel:viewType" activation event and -make sure that registerWebviewPanelSerializer is called during activation.

-

Only a single serializer may be registered at a time for a given viewType.

-
-
- - - - - - -
ParameterDescription
viewType: string

Type of the webview panel that can be serialized.

-
serializer: WebviewPanelSerializer

Webview serializer.

-
ReturnsDescription
Disposable
-
-
- - - -registerWebviewViewProvider(viewId: string, provider: WebviewViewProvider, options?: {webviewOptions: {retainContextWhenHidden: boolean}}): Disposable -
-

Register a new provider for webview views.

-
-
- - - - - - - -
ParameterDescription
viewId: string

Unique id of the view. This should match the id from the - views contribution in the package.json.

-
provider: WebviewViewProvider

Provider for the webview views.

-
options?: {webviewOptions: {retainContextWhenHidden: boolean}}
ReturnsDescription
Disposable

Disposable that unregisters the provider.

-
-
-
- - - -setStatusBarMessage(text: string, hideAfterTimeout: number): Disposable -
-

Set a message to the status bar. This is a short hand for the more powerful -status bar items.

-
-
- - - - - - -
ParameterDescription
text: string

The message to show, supports icon substitution as in status bar items.

-
hideAfterTimeout: number

Timeout in milliseconds after which the message will be disposed.

-
ReturnsDescription
Disposable

A disposable which hides the status bar message.

-
-
-
- - - -setStatusBarMessage(text: string, hideWhenDone: Thenable<any>): Disposable -
-

Set a message to the status bar. This is a short hand for the more powerful -status bar items.

-
-
- - - - - - -
ParameterDescription
text: string

The message to show, supports icon substitution as in status bar items.

-
hideWhenDone: Thenable<any>

Thenable on which completion (resolve or reject) the message will be disposed.

-
ReturnsDescription
Disposable

A disposable which hides the status bar message.

-
-
-
- - - -setStatusBarMessage(text: string): Disposable -
-

Set a message to the status bar. This is a short hand for the more powerful -status bar items.

-

Note that status bar messages stack and that they must be disposed when no -longer used.

-
-
- - - - - -
ParameterDescription
text: string

The message to show, supports icon substitution as in status bar items.

-
ReturnsDescription
Disposable

A disposable which hides the status bar message.

-
-
-
- - - -showErrorMessage(message: string, ...items: string[]): Thenable<string | undefined> -
-

Show an error message.

- -
-
- - - - - - -
ParameterDescription
message: string

The message to show.

-
...items: string[]

A set of items that will be rendered as actions in the message.

-
ReturnsDescription
Thenable<string | undefined>

A thenable that resolves to the selected item or undefined when being dismissed.

-
-
-
- - - -showErrorMessage(message: string, options: MessageOptions, ...items: string[]): Thenable<string | undefined> -
-

Show an error message.

- -
-
- - - - - - - -
ParameterDescription
message: string

The message to show.

-
options: MessageOptions

Configures the behaviour of the message.

-
...items: string[]

A set of items that will be rendered as actions in the message.

-
ReturnsDescription
Thenable<string | undefined>

A thenable that resolves to the selected item or undefined when being dismissed.

-
-
-
- - - -showErrorMessage<T extends MessageItem>(message: string, ...items: T[]): Thenable<T | undefined> -
-

Show an error message.

- -
-
- - - - - - -
ParameterDescription
message: string

The message to show.

-
...items: T[]

A set of items that will be rendered as actions in the message.

-
ReturnsDescription
Thenable<T | undefined>

A thenable that resolves to the selected item or undefined when being dismissed.

-
-
-
- - - -showErrorMessage<T extends MessageItem>(message: string, options: MessageOptions, ...items: T[]): Thenable<T | undefined> -
-

Show an error message.

- -
-
- - - - - - - -
ParameterDescription
message: string

The message to show.

-
options: MessageOptions

Configures the behaviour of the message.

-
...items: T[]

A set of items that will be rendered as actions in the message.

-
ReturnsDescription
Thenable<T | undefined>

A thenable that resolves to the selected item or undefined when being dismissed.

-
-
-
- - - -showInformationMessage(message: string, ...items: string[]): Thenable<string | undefined> -
-

Show an information message to users. Optionally provide an array of items which will be presented as -clickable buttons.

-
-
- - - - - - -
ParameterDescription
message: string

The message to show.

-
...items: string[]

A set of items that will be rendered as actions in the message.

-
ReturnsDescription
Thenable<string | undefined>

A thenable that resolves to the selected item or undefined when being dismissed.

-
-
-
- - - -showInformationMessage(message: string, options: MessageOptions, ...items: string[]): Thenable<string | undefined> -
-

Show an information message to users. Optionally provide an array of items which will be presented as -clickable buttons.

-
-
- - - - - - - -
ParameterDescription
message: string

The message to show.

-
options: MessageOptions

Configures the behaviour of the message.

-
...items: string[]

A set of items that will be rendered as actions in the message.

-
ReturnsDescription
Thenable<string | undefined>

A thenable that resolves to the selected item or undefined when being dismissed.

-
-
-
- - - -showInformationMessage<T extends MessageItem>(message: string, ...items: T[]): Thenable<T | undefined> -
-

Show an information message.

- -
-
- - - - - - -
ParameterDescription
message: string

The message to show.

-
...items: T[]

A set of items that will be rendered as actions in the message.

-
ReturnsDescription
Thenable<T | undefined>

A thenable that resolves to the selected item or undefined when being dismissed.

-
-
-
- - - -showInformationMessage<T extends MessageItem>(message: string, options: MessageOptions, ...items: T[]): Thenable<T | undefined> -
-

Show an information message.

- -
-
- - - - - - - -
ParameterDescription
message: string

The message to show.

-
options: MessageOptions

Configures the behaviour of the message.

-
...items: T[]

A set of items that will be rendered as actions in the message.

-
ReturnsDescription
Thenable<T | undefined>

A thenable that resolves to the selected item or undefined when being dismissed.

-
-
-
- - - -showInputBox(options?: InputBoxOptions, token?: CancellationToken): Thenable<string | undefined> -
-

Opens an input box to ask the user for input.

-

The returned value will be undefined if the input box was canceled (e.g. pressing ESC). Otherwise the -returned value will be the string typed by the user or an empty string if the user did not type -anything but dismissed the input box with OK.

-
-
- - - - - - -
ParameterDescription
options?: InputBoxOptions

Configures the behavior of the input box.

-
token?: CancellationToken

A token that can be used to signal cancellation.

-
ReturnsDescription
Thenable<string | undefined>

A promise that resolves to a string the user provided or to undefined in case of dismissal.

-
-
-
- - - -showOpenDialog(options?: OpenDialogOptions): Thenable<Uri[] | undefined> -
-

Shows a file open dialog to the user which allows to select a file -for opening-purposes.

-
-
- - - - - -
ParameterDescription
options?: OpenDialogOptions

Options that control the dialog.

-
ReturnsDescription
Thenable<Uri[] | undefined>

A promise that resolves to the selected resources or undefined.

-
-
-
- - - -showQuickPick(items: string[] | Thenable<string[]>, options: QuickPickOptions & {canPickMany: true}, token?: CancellationToken): Thenable<string[] | undefined> -
-

Shows a selection list allowing multiple selections.

-
-
- - - - - - - -
ParameterDescription
items: string[] | Thenable<string[]>

An array of strings, or a promise that resolves to an array of strings.

-
options: QuickPickOptions & {canPickMany: true}

Configures the behavior of the selection list.

-
token?: CancellationToken

A token that can be used to signal cancellation.

-
ReturnsDescription
Thenable<string[] | undefined>

A promise that resolves to the selected items or undefined.

-
-
-
- - - -showQuickPick(items: string[] | Thenable<string[]>, options?: QuickPickOptions, token?: CancellationToken): Thenable<string | undefined> -
-

Shows a selection list.

-
-
- - - - - - - -
ParameterDescription
items: string[] | Thenable<string[]>

An array of strings, or a promise that resolves to an array of strings.

-
options?: QuickPickOptions

Configures the behavior of the selection list.

-
token?: CancellationToken

A token that can be used to signal cancellation.

-
ReturnsDescription
Thenable<string | undefined>

A promise that resolves to the selection or undefined.

-
-
-
- - - -showQuickPick<T extends QuickPickItem>(items: T[] | Thenable<T[]>, options: QuickPickOptions & {canPickMany: true}, token?: CancellationToken): Thenable<T[] | undefined> -
-

Shows a selection list allowing multiple selections.

-
-
- - - - - - - -
ParameterDescription
items: T[] | Thenable<T[]>

An array of items, or a promise that resolves to an array of items.

-
options: QuickPickOptions & {canPickMany: true}

Configures the behavior of the selection list.

-
token?: CancellationToken

A token that can be used to signal cancellation.

-
ReturnsDescription
Thenable<T[] | undefined>

A promise that resolves to the selected items or undefined.

-
-
-
- - - -showQuickPick<T extends QuickPickItem>(items: T[] | Thenable<T[]>, options?: QuickPickOptions, token?: CancellationToken): Thenable<T | undefined> -
-

Shows a selection list.

-
-
- - - - - - - -
ParameterDescription
items: T[] | Thenable<T[]>

An array of items, or a promise that resolves to an array of items.

-
options?: QuickPickOptions

Configures the behavior of the selection list.

-
token?: CancellationToken

A token that can be used to signal cancellation.

-
ReturnsDescription
Thenable<T | undefined>

A promise that resolves to the selected item or undefined.

-
-
-
- - - -showSaveDialog(options?: SaveDialogOptions): Thenable<Uri | undefined> -
-

Shows a file save dialog to the user which allows to select a file -for saving-purposes.

-
-
- - - - - -
ParameterDescription
options?: SaveDialogOptions

Options that control the dialog.

-
ReturnsDescription
Thenable<Uri | undefined>

A promise that resolves to the selected resource or undefined.

-
-
-
- - - -showTextDocument(document: TextDocument, column?: ViewColumn, preserveFocus?: boolean): Thenable<TextEditor> -
-

Show the given document in a text editor. A column can be provided -to control where the editor is being shown. Might change the active editor.

-
-
- - - - - - - -
ParameterDescription
document: TextDocument

A text document to be shown.

-
column?: ViewColumn

A view column in which the editor should be shown. The default is the active, other values -are adjusted to be Min(column, columnCount + 1), the active-column is not adjusted. Use ViewColumn.Beside -to open the editor to the side of the currently active one.

-
preserveFocus?: boolean

When true the editor will not take focus.

-
ReturnsDescription
Thenable<TextEditor>

A promise that resolves to an editor.

-
-
-
- - - -showTextDocument(document: TextDocument, options?: TextDocumentShowOptions): Thenable<TextEditor> -
-

Show the given document in a text editor. Options can be provided -to control options of the editor is being shown. Might change the active editor.

-
-
- - - - - - -
ParameterDescription
document: TextDocument

A text document to be shown.

-
options?: TextDocumentShowOptions

(#TextDocumentShowOptions) to configure the behavior of showing the editor.

-
ReturnsDescription
Thenable<TextEditor>

A promise that resolves to an editor.

-
-
-
- - - -showTextDocument(uri: Uri, options?: TextDocumentShowOptions): Thenable<TextEditor> -
-

A short-hand for openTextDocument(uri).then(document => showTextDocument(document, options)).

- -
-
- - - - - - -
ParameterDescription
uri: Uri

A resource identifier.

-
options?: TextDocumentShowOptions

(#TextDocumentShowOptions) to configure the behavior of showing the editor.

-
ReturnsDescription
Thenable<TextEditor>

A promise that resolves to an editor.

-
-
-
- - - -showWarningMessage(message: string, ...items: string[]): Thenable<string | undefined> -
-

Show a warning message.

- -
-
- - - - - - -
ParameterDescription
message: string

The message to show.

-
...items: string[]

A set of items that will be rendered as actions in the message.

-
ReturnsDescription
Thenable<string | undefined>

A thenable that resolves to the selected item or undefined when being dismissed.

-
-
-
- - - -showWarningMessage(message: string, options: MessageOptions, ...items: string[]): Thenable<string | undefined> -
-

Show a warning message.

- -
-
- - - - - - - -
ParameterDescription
message: string

The message to show.

-
options: MessageOptions

Configures the behaviour of the message.

-
...items: string[]

A set of items that will be rendered as actions in the message.

-
ReturnsDescription
Thenable<string | undefined>

A thenable that resolves to the selected item or undefined when being dismissed.

-
-
-
- - - -showWarningMessage<T extends MessageItem>(message: string, ...items: T[]): Thenable<T | undefined> -
-

Show a warning message.

- -
-
- - - - - - -
ParameterDescription
message: string

The message to show.

-
...items: T[]

A set of items that will be rendered as actions in the message.

-
ReturnsDescription
Thenable<T | undefined>

A thenable that resolves to the selected item or undefined when being dismissed.

-
-
-
- - - -showWarningMessage<T extends MessageItem>(message: string, options: MessageOptions, ...items: T[]): Thenable<T | undefined> -
-

Show a warning message.

- -
-
- - - - - - - -
ParameterDescription
message: string

The message to show.

-
options: MessageOptions

Configures the behaviour of the message.

-
...items: T[]

A set of items that will be rendered as actions in the message.

-
ReturnsDescription
Thenable<T | undefined>

A thenable that resolves to the selected item or undefined when being dismissed.

-
-
-
- - - -showWorkspaceFolderPick(options?: WorkspaceFolderPickOptions): Thenable<WorkspaceFolder | undefined> -
-

Shows a selection list of workspace folders to pick from. -Returns undefined if no folder is open.

-
-
- - - - - -
ParameterDescription
options?: WorkspaceFolderPickOptions

Configures the behavior of the workspace folder list.

-
ReturnsDescription
Thenable<WorkspaceFolder | undefined>

A promise that resolves to the workspace folder or undefined.

-
-
-
- - - -withProgress<R>(options: ProgressOptions, task: (progress: Progress<{increment: number, message: string}>, token: CancellationToken) => Thenable<R>): Thenable<R> -
-

Show progress in the editor. Progress is shown while running the given callback -and while the promise it returned isn't resolved nor rejected. The location at which -progress should show (and other details) is defined via the passed ProgressOptions.

-
-
- - - - - - -
ParameterDescription
options: ProgressOptions
task: (progress: Progress<{increment: number, message: string}>, token: CancellationToken) => Thenable<R>

A callback returning a promise. Progress state can be reported with -the provided progress-object.

-

To report discrete progress, use increment to indicate how much work has been completed. Each call with -a increment value will be summed up and reflected as overall progress until 100% is reached (a value of -e.g. 10 accounts for 10% of work done). -Note that currently only ProgressLocation.Notification is capable of showing discrete progress.

-

To monitor if the operation has been cancelled by the user, use the provided CancellationToken. -Note that currently only ProgressLocation.Notification is supporting to show a cancel button to cancel the -long running operation.

-
ReturnsDescription
Thenable<R>

The thenable the task-callback returned.

-
-
-
- - - -withScmProgress<R>(task: (progress: Progress<number>) => Thenable<R>): Thenable<R> -
-

Show progress in the Source Control viewlet while running the given callback and while -its returned promise isn't resolve or rejected.

-
    -
  • deprecated - Use withProgress instead.
    • -
-
-
- - - - - -
ParameterDescription
task: (progress: Progress<number>) => Thenable<R>

A callback returning a promise. Progress increments can be reported with -the provided progress-object.

-
ReturnsDescription
Thenable<R>

The thenable the task did return.

-
-
-
- -## workspace - - - -

Namespace for dealing with the current workspace. A workspace is the representation -of the folder that has been opened. There is no workspace when just a file but not a -folder has been opened.

-

The workspace offers support for listening to fs -events and for finding files. Both perform well and run outside -the editor-process so that they should be always used instead of nodejs-equivalents.

-
- -#### Variables - - - -fs: FileSystem -
-

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: string | undefined -
-

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

-
-
- - - -rootPath: string | undefined -
-

The folder that is open in the editor. undefined when no folder -has been opened.

- -
-
- - - -textDocuments: ReadonlyArray<TextDocument> -
-

All text documents currently known to the system.

-
-
- - - -workspaceFile: Uri | undefined -
-

The location of the workspace file, for example:

-

file:///Users/name/Development/myProject.code-workspace

-

or

-

untitled:1555503116870

-

for a workspace that is untitled and not yet saved.

-

Depending on the workspace that is opened, the value will be:

-
    -
  • undefined when no workspace or a single folder is opened
    • -
  • the path of the workspace file as Uri otherwise. if the workspace -is untitled, the returned URI will use the untitled: scheme
    • -
-

The location can e.g. be used with the vscode.openFolder command to -open the workspace again after it has been closed.

-

Example:

- -
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<WorkspaceFolder> | undefined -
-

List of workspace folders or undefined when no folder is open. -Note that the first entry corresponds to the value of rootPath.

-
-
- -#### Events - - - -onDidChangeConfiguration: Event<ConfigurationChangeEvent> -
-

An event that is emitted when the configuration changed.

-
-
- - - -onDidChangeTextDocument: Event<TextDocumentChangeEvent> -
-

An event that is emitted when a text document is changed. This usually happens -when the contents changes but also when other things like the -dirty-state changes.

-
-
- - - -onDidChangeWorkspaceFolders: Event<WorkspaceFoldersChangeEvent> -
-

An event that is emitted when a workspace folder is added or removed.

-
-
- - - -onDidCloseTextDocument: Event<TextDocument> -
-

An event that is emitted when a text document is disposed or when the language ID -of a text document has been changed.

-

Note 1: There is no guarantee that this event fires when an editor tab is closed, use the -onDidChangeVisibleTextEditors-event to know when editors change.

-

Note 2: A document can be open but not shown in an editor which means this event can fire -for a document that has not been shown in an editor.

-
-
- - - -onDidCreateFiles: Event<FileCreateEvent> -
-

An event that is emitted when files have been created.

-

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.

-
-
- - - -onDidDeleteFiles: Event<FileDeleteEvent> -
-

An event that is emitted when files have been deleted.

-

Note 1: This event is triggered by user gestures, like deleting 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.

-

Note 2: When deleting a folder with children only one event is fired.

-
-
- - - -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:

- -
-
- - - -onDidRenameFiles: Event<FileRenameEvent> -
-

An event that is emitted when files have been renamed.

-

Note 1: This event is triggered by user gestures, like renaming a file from the -explorer, and 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.

-

Note 2: When renaming a folder with children only one event is fired.

-
-
- - - -onDidSaveTextDocument: Event<TextDocument> -
-

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

-
-
- - - -onWillCreateFiles: Event<FileWillCreateEvent> -
-

An event that is emitted when files are being created.

-

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.

-
-
- - - -onWillDeleteFiles: Event<FileWillDeleteEvent> -
-

An event that is emitted when files are being deleted.

-

Note 1: This event is triggered by user gestures, like deleting 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.

-

Note 2: When deleting a folder with children only one event is fired.

-
-
- - - -onWillRenameFiles: Event<FileWillRenameEvent> -
-

An event that is emitted when files are being renamed.

-

Note 1: This event is triggered by user gestures, like renaming a file from the -explorer, and 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.

-

Note 2: When renaming a folder with children only one event is fired.

-
-
- - - -onWillSaveTextDocument: Event<TextDocumentWillSaveEvent> -
-

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.

-
-
- -#### Functions - - - -applyEdit(edit: WorkspaceEdit): Thenable<boolean> -
-

Make changes to one or many resources or create, delete, and rename resources as defined by the given -workspace edit.

-

All changes of a workspace edit are applied in the same order in which they have been added. If -multiple textual inserts are made at the same position, these strings appear in the resulting text -in the order the 'inserts' were made, unless that are interleaved with resource edits. Invalid sequences -like 'delete file a' -> 'insert text in file a' cause failure of the operation.

-

When applying a workspace edit that consists only of text edits an 'all-or-nothing'-strategy is used. -A workspace edit with resource creations or deletions aborts the operation, e.g. consecutive edits will -not be attempted, when a single edit fails.

-
-
- - - - - -
ParameterDescription
edit: WorkspaceEdit

A workspace edit.

-
ReturnsDescription
Thenable<boolean>

A thenable that resolves when the edit could be applied.

-
-
-
- - - -asRelativePath(pathOrUri: string | Uri, includeWorkspaceFolder?: boolean): string -
-

Returns a path that is relative to the workspace folder or folders.

-

When there are no workspace folders or when the path -is not contained in them, the input is returned.

-
-
- - - - - - -
ParameterDescription
pathOrUri: string | Uri

A path or uri. When a uri is given its fsPath is used.

-
includeWorkspaceFolder?: boolean

When true and when the given path is contained inside a -workspace folder the name of the workspace is prepended. Defaults to true when there are -multiple workspace folders and false otherwise.

-
ReturnsDescription
string

A path relative to the root or the input.

-
-
-
- - - -createFileSystemWatcher(globPattern: GlobPattern, ignoreCreateEvents?: boolean, ignoreChangeEvents?: boolean, ignoreDeleteEvents?: boolean): FileSystemWatcher -
-

Creates a file system watcher.

-

A glob pattern that filters the file events on their absolute path must be provided. Optionally, -flags to ignore certain kinds of events can be provided. To stop listening to events the watcher must be disposed.

-

Note that only files within the current workspace folders can be watched.

-
-
- - - - - - - - -
ParameterDescription
globPattern: 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.

-
ignoreCreateEvents?: boolean

Ignore when files have been created.

-
ignoreChangeEvents?: boolean

Ignore when files have been changed.

-
ignoreDeleteEvents?: boolean

Ignore when files have been deleted.

-
ReturnsDescription
FileSystemWatcher

A new file system watcher instance.

-
-
-
- - - -findFiles(include: GlobPattern, exclude?: GlobPattern | null, maxResults?: number, token?: CancellationToken): Thenable<Uri[]> -
-

Find files across all workspace folders in the workspace.

-
    -
  • example - findFiles('/*.js', '/node_modules/**', 10)
    • -
-
-
- - - - - - - - -
ParameterDescription
include: GlobPattern

A glob pattern that defines the files to search for. The glob pattern -will be matched against the file paths of resulting matches relative to their workspace. Use a relative pattern -to restrict the search results to a workspace folder.

-
exclude?: GlobPattern | null

A glob pattern that defines files and folders to exclude. The glob pattern -will be matched against the file paths of resulting matches relative to their workspace. When undefined only default excludes will -apply, when null no excludes will apply.

-
maxResults?: number

An upper-bound for the result.

-
token?: CancellationToken

A token that can be used to signal cancellation to the underlying search engine.

-
ReturnsDescription
Thenable<Uri[]>

A thenable that resolves to an array of resource identifiers. Will return no results if no -workspace folders are opened.

-
-
-
- - - -getConfiguration(section?: string | undefined, scope?: ConfigurationScope | null): WorkspaceConfiguration -
-

Get a workspace configuration object.

-

When a section-identifier is provided only that part of the configuration -is returned. Dots in the section-identifier are interpreted as child-access, -like { myExt: { setting: { doIt: true }}} and getConfiguration('myExt.setting').get('doIt') === true.

-

When a scope is provided configuration confined to that scope is returned. Scope can be a resource or a language identifier or both.

-
-
- - - - - - -
ParameterDescription
section?: string | undefined

A dot-separated identifier.

-
scope?: ConfigurationScope | null

A scope for which the configuration is asked for.

-
ReturnsDescription
WorkspaceConfiguration

The full configuration or a subset.

-
-
-
- - - -getWorkspaceFolder(uri: Uri): WorkspaceFolder | undefined -
-

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
    • -
-
-
- - - - - -
ParameterDescription
uri: Uri

An uri.

-
ReturnsDescription
WorkspaceFolder | undefined

A workspace folder or undefined

-
-
-
- - - -openTextDocument(uri: Uri): 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.

-
-
- - - - - -
ParameterDescription
uri: Uri

Identifies the resource to open.

-
ReturnsDescription
Thenable<TextDocument>

A promise that resolves to a document.

-
-
-
- - - -openTextDocument(fileName: string): Thenable<TextDocument> -
-

A short-hand for openTextDocument(Uri.file(fileName)).

- -
-
- - - - - -
ParameterDescription
fileName: string

A name of a file on disk.

-
ReturnsDescription
Thenable<TextDocument>

A promise that resolves to a document.

-
-
-
- - - -openTextDocument(options?: {content: string, language: string}): Thenable<TextDocument> -
-

Opens an untitled text document. The editor will prompt the user for a file -path when the document is to be saved. The options parameter allows to -specify the language and/or the content of the document.

-
-
- - - - - -
ParameterDescription
options?: {content: string, language: string}

Options to control how the document will be created.

-
ReturnsDescription
Thenable<TextDocument>

A promise that resolves to a document.

-
-
-
- - - -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.

-
-
- - - - - - - -
ParameterDescription
scheme: string

The uri-scheme the provider registers for.

-
provider: FileSystemProvider

The filesystem provider.

-
options?: {isCaseSensitive: boolean, isReadonly: boolean}

Immutable metadata about the provider.

-
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

-
-
-
- - - -registerTaskProvider(type: string, provider: TaskProvider): Disposable -
-

Register a task provider.

-
    -
  • deprecated - Use the corresponding function on the tasks namespace instead
    • -
-
-
- - - - - - -
ParameterDescription
type: string

The task kind type this provider is registered for.

-
provider: TaskProvider

A task provider.

-
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

-
-
-
- - - -registerTextDocumentContentProvider(scheme: string, provider: TextDocumentContentProvider): Disposable -
-

Register a text document content provider.

-

Only one provider can be registered per scheme.

-
-
- - - - - - -
ParameterDescription
scheme: string

The uri-scheme to register for.

-
provider: TextDocumentContentProvider

A content provider.

-
ReturnsDescription
Disposable

A disposable that unregisters this provider when being disposed.

-
-
-
- - - -saveAll(includeUntitled?: boolean): Thenable<boolean> -
-

Save all dirty files.

-
-
- - - - - -
ParameterDescription
includeUntitled?: boolean

Also save files that have been created during this session.

-
ReturnsDescription
Thenable<boolean>

A thenable that resolves when the files have been saved.

-
-
-
- - - -updateWorkspaceFolders(start: number, deleteCount: number | undefined | null, ...workspaceFoldersToAdd: {name: string, uri: Uri}[]): boolean -
-

This method replaces deleteCount workspace folders starting at index start -by an optional set of workspaceFoldersToAdd on the vscode.workspace.workspaceFolders array. This "splice" -behavior can be used to add, remove and change workspace folders in a single operation.

-

If the first workspace folder is added, removed or changed, the currently executing extensions (including the -one that called this method) will be terminated and restarted so that the (deprecated) rootPath property is -updated to point to the first workspace folder.

-

Use the onDidChangeWorkspaceFolders() event to get notified when the -workspace folders have been updated.

-

Example: adding a new workspace folder at the end of workspace folders

- -
workspace.updateWorkspaceFolders(workspace.workspaceFolders ? workspace.workspaceFolders.length : 0, null, { uri: ...});
-
-

Example: removing the first workspace folder

- -
workspace.updateWorkspaceFolders(0, 1);
-
-

Example: replacing an existing workspace folder with a new one

- -
workspace.updateWorkspaceFolders(0, 1, { uri: ...});
-
-

It is valid to remove an existing workspace folder and add it again with a different name -to rename that folder.

-

Note: it is not valid to call updateWorkspaceFolders() multiple times -without waiting for the onDidChangeWorkspaceFolders() to fire.

-
-
- - - - - - - -
ParameterDescription
start: number

the zero-based location in the list of currently opened workspace folders -from which to start deleting workspace folders.

-
deleteCount: number | undefined | null

the optional number of workspace folders to remove.

-
...workspaceFoldersToAdd: {name: string, uri: Uri}[]

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.

-
ReturnsDescription
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).

-
-
-
- -### AccessibilityInformation - - - -

Accessibility information which controls screen reader behavior.

-
- -#### Properties - - - -label: string -
-

Label to be read out by a screen reader once the item has focus.

-
-
- - - -role?: string -
-

Role of the widget which defines how a screen reader interacts with it. -The role should be set in special cases when for example a tree-like element behaves like a checkbox. -If role is not specified VS Code will pick the appropriate role automatically. -More about aria roles can be found here https://w3c.github.io/aria/#widget_roles

-
-
- -### AuthenticationGetSessionOptions - - - -

Options to be used when getting an AuthenticationSession from an AuthenticationProvider.

-
- -#### Properties - - - -clearSessionPreference?: boolean -
-

Whether the existing user session preference should be cleared.

-

For authentication providers that support being signed into multiple accounts at once, the user will be -prompted to select an account to use when getSession is called. This preference -is remembered until getSession is called with this flag.

-

Defaults to false.

-
-
- - - -createIfNone?: boolean -
-

Whether login should be performed if there is no matching session.

-

If true, a modal dialog will be shown asking the user to sign in. If false, a numbered badge will be shown -on the accounts activity bar icon. An entry for the extension will be added under the menu to sign in. This -allows quietly prompting the user to sign in.

-

Defaults to false.

-
-
- -### AuthenticationProviderInformation - - - -

Basic information about an authenticationProvider

-
- -#### Properties - - - -id: string -
-

The unique identifier of the authentication provider.

-
-
- - - -label: string -
-

The human-readable name of the authentication provider.

-
-
- -### AuthenticationSession - - - -

Represents a session of a currently logged in user.

-
- -#### Properties - - - -accessToken: string -
-

The access token.

-
-
- - - -account: AuthenticationSessionAccountInformation -
-

The account associated with the session.

-
-
- - - -id: string -
-

The identifier of the authentication session.

-
-
- - - -scopes: ReadonlyArray<string> -
-

The permissions granted by the session's access token. Available scopes -are defined by the AuthenticationProvider.

-
-
- -### AuthenticationSessionAccountInformation - - - -

The information of an account associated with an AuthenticationSession.

-
- -#### Properties - - - -id: string -
-

The unique identifier of the account.

-
-
- - - -label: string -
-

The human-readable name of the account.

-
-
- -### AuthenticationSessionsChangeEvent - - - -

An event which fires when an AuthenticationSession is added, removed, or changed.

-
- -#### Properties - - - -provider: AuthenticationProviderInformation -
-

The authenticationProvider that has had its sessions change.

-
-
- -### Breakpoint - - - -

The base class of all breakpoint types.

-
- -#### Constructors - - - -new Breakpoint(enabled?: boolean, condition?: string, hitCondition?: string, logMessage?: string): Breakpoint -
-
-
- - - - - - - - -
ParameterDescription
enabled?: boolean
condition?: string
hitCondition?: string
logMessage?: string
ReturnsDescription
Breakpoint
-
-
- -#### Properties - - - -condition?: string -
-

An optional expression for conditional breakpoints.

-
-
- - - -enabled: boolean -
-

Is breakpoint enabled.

-
-
- - - -hitCondition?: string -
-

An optional expression that controls how many hits of the breakpoint are ignored.

-
-
- - - -id: string -
-

The unique ID of the breakpoint.

-
-
- - - -logMessage?: string -
-

An optional message that gets logged when this breakpoint is hit. Embedded expressions within {} are interpolated by the debug adapter.

-
-
- -### BreakpointsChangeEvent - - - -

An event describing the changes to the set of breakpoints.

-
- -#### Properties - - - -added: ReadonlyArray<Breakpoint> -
-

Added breakpoints.

-
-
- - - -changed: ReadonlyArray<Breakpoint> -
-

Changed breakpoints.

-
-
- - - -removed: ReadonlyArray<Breakpoint> -
-

Removed breakpoints.

-
-
- -### CallHierarchyIncomingCall - - - -

Represents an incoming call, e.g. a caller of a method or constructor.

-
- -#### Constructors - - - -new CallHierarchyIncomingCall(item: CallHierarchyItem, fromRanges: Range[]): CallHierarchyIncomingCall -
-

Create a new call object.

-
-
- - - - - - -
ParameterDescription
item: CallHierarchyItem

The item making the call.

-
fromRanges: Range[]

The ranges at which the calls appear.

-
ReturnsDescription
CallHierarchyIncomingCall
-
-
- -#### Properties - - - -from: CallHierarchyItem -
-

The item that makes the call.

-
-
- - - -fromRanges: Range[] -
-

The range at which at which the calls appears. This is relative to the caller -denoted by this.from.

-
-
- -### CallHierarchyItem - - - -

Represents programming constructs like functions or constructors in the context -of call hierarchy.

-
- -#### Constructors - - - -new CallHierarchyItem(kind: SymbolKind, name: string, detail: string, uri: Uri, range: Range, selectionRange: Range): CallHierarchyItem -
-

Creates a new call hierarchy item.

-
-
- - - - - - - - - - -
ParameterDescription
kind: SymbolKind
name: string
detail: string
uri: Uri
range: Range
selectionRange: Range
ReturnsDescription
CallHierarchyItem
-
-
- -#### Properties - - - -detail?: string -
-

More detail for this item, e.g. the signature of a function.

-
-
- - - -kind: SymbolKind -
-

The kind of this item.

-
-
- - - -name: string -
-

The name of this item.

-
-
- - - -range: Range -
-

The range enclosing this symbol not including leading/trailing whitespace but everything else, e.g. comments and code.

-
-
- - - -selectionRange: Range -
-

The range that should be selected and revealed when this symbol is being picked, e.g. the name of a function. -Must be contained by the range.

-
-
- - - -tags?: ReadonlyArray<SymbolTag> -
-

Tags for this item.

-
-
- - - -uri: Uri -
-

The resource identifier of this item.

-
-
- -### CallHierarchyOutgoingCall - - - -

Represents an outgoing call, e.g. calling a getter from a method or a method from a constructor etc.

-
- -#### Constructors - - - -new CallHierarchyOutgoingCall(item: CallHierarchyItem, fromRanges: Range[]): CallHierarchyOutgoingCall -
-

Create a new call object.

-
-
- - - - - - -
ParameterDescription
item: CallHierarchyItem

The item being called

-
fromRanges: Range[]

The ranges at which the calls appear.

-
ReturnsDescription
CallHierarchyOutgoingCall
-
-
- -#### Properties - - - -fromRanges: Range[] -
-

The range at which this item is called. This is the range relative to the caller, e.g the item -passed to provideCallHierarchyOutgoingCalls -and not this.to.

-
-
- - - -to: CallHierarchyItem -
-

The item that is called.

-
-
- -### CallHierarchyProvider - - - -

The call hierarchy provider interface describes the contract between extensions -and the call hierarchy feature which allows to browse calls and caller of function, -methods, constructor etc.

-
- -#### Methods - - - -prepareCallHierarchy(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<CallHierarchyItem | CallHierarchyItem[]> -
-

Bootstraps call hierarchy by returning the item that is denoted by the given document -and position. This item will be used as entry into the call graph. Providers should -return undefined or null when there is no item at the given location.

-
-
- - - - - - - -
ParameterDescription
document: TextDocument

The document in which the command was invoked.

-
position: Position

The position at which the command was invoked.

-
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<CallHierarchyItem | CallHierarchyItem[]>

A call hierarchy item or a thenable that resolves to such. The lack of a result can be -signaled by returning undefined or null.

-
-
-
- - - -provideCallHierarchyIncomingCalls(item: CallHierarchyItem, token: CancellationToken): ProviderResult<CallHierarchyIncomingCall[]> -
-

Provide all incoming calls for an item, e.g all callers for a method. In graph terms this describes directed -and annotated edges inside the call graph, e.g the given item is the starting node and the result is the nodes -that can be reached.

-
-
- - - - - - -
ParameterDescription
item: CallHierarchyItem

The hierarchy item for which incoming calls should be computed.

-
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<CallHierarchyIncomingCall[]>

A set of incoming calls or a thenable that resolves to such. The lack of a result can be -signaled by returning undefined or null.

-
-
-
- - - -provideCallHierarchyOutgoingCalls(item: CallHierarchyItem, token: CancellationToken): ProviderResult<CallHierarchyOutgoingCall[]> -
-

Provide all outgoing calls for an item, e.g call calls to functions, methods, or constructors from the given item. In -graph terms this describes directed and annotated edges inside the call graph, e.g the given item is the starting -node and the result is the nodes that can be reached.

-
-
- - - - - - -
ParameterDescription
item: CallHierarchyItem

The hierarchy item for which outgoing calls should be computed.

-
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<CallHierarchyOutgoingCall[]>

A set of outgoing calls or a thenable that resolves to such. The lack of a result can be -signaled by returning undefined or null.

-
-
-
- -### CancellationToken - - - -

A cancellation token is passed to an asynchronous or long running -operation to request cancellation, like cancelling a request -for completion items because the user continued to type.

-

To get an instance of a CancellationToken use a -CancellationTokenSource.

-
- -#### Properties - - - -isCancellationRequested: boolean -
-

Is true when the token has been cancelled, false otherwise.

-
-
- - - -onCancellationRequested: Event<any> -
-

An event which fires upon cancellation.

-
-
- -### CancellationTokenSource - - - -

A cancellation source creates and controls a cancellation token.

-
- -#### Properties - - - -token: CancellationToken -
-

The cancellation token of this source.

-
-
- -#### Methods - - - -cancel(): void -
-

Signal cancellation on the token.

-
-
- - - -
ReturnsDescription
void
-
-
- - - -dispose(): void -
-

Dispose object and free resources.

-
-
- - - -
ReturnsDescription
void
-
-
- -### CharacterPair - - - -

A tuple of two characters, like a pair of -opening and closing brackets.

-
- - - -CharacterPair: [string, string] - -### Clipboard - - - -

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

-
- -#### Methods - - - -readText(): Thenable<string> -
-

Read the current clipboard contents as text.

-
-
- - - -
ReturnsDescription
Thenable<string>

A thenable that resolves to a string.

-
-
-
- - - -writeText(value: string): Thenable<void> -
-

Writes text into the clipboard.

-
-
- - - - - -
ParameterDescription
value: string
ReturnsDescription
Thenable<void>

A thenable that resolves when writing happened.

-
-
-
- -### CodeAction - - - -

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

-

A CodeAction must set either edit and/or a command. If both are supplied, the edit is applied first, then the command is executed.

-
- -#### Constructors - - - -new CodeAction(title: string, kind?: CodeActionKind): CodeAction -
-

Creates a new code action.

-

A code action must have at least a title and edits -and/or a command.

-
-
- - - - - - -
ParameterDescription
title: string

The title of the code action.

-
kind?: CodeActionKind

The kind of the code action.

-
ReturnsDescription
CodeAction
-
-
- -#### Properties - - - -command?: Command -
-

A command this code action executes.

-

If this command throws an exception, VS Code displays the exception message to users in the editor at the -current cursor position.

-
-
- - - -diagnostics?: Diagnostic[] -
-

Diagnostics that this code action resolves.

-
-
- - - -disabled?: {reason: string} -
-

Marks that the code action cannot currently be applied.

-
    -

  • Disabled code actions are not shown in automatic lightbulb -code action menu.

    -
    • -

  • Disabled actions are shown as faded out in the code action menu when the user request a more specific type -of code action, such as refactorings.

    -
    • -

  • If the user has a keybinding -that auto applies a code action and only a disabled code actions are returned, VS Code will show the user an -error message with reason in the editor.

    -
    • -
-
-
- - - -edit?: WorkspaceEdit -
-

A workspace edit this code action performs.

-
-
- - - -isPreferred?: boolean -
-

Marks this as a preferred action. Preferred actions are used by the auto fix command and can be targeted -by keybindings.

-

A quick fix should be marked preferred if it properly addresses the underlying error. -A refactoring should be marked preferred if it is the most reasonable choice of actions to take.

-
-
- - - -kind?: CodeActionKind -
-

Kind of the code action.

-

Used to filter code actions.

-
-
- - - -title: string -
-

A short, human-readable, title for this code action.

-
-
- -### CodeActionContext - - - -

Contains additional diagnostic information about the context in which -a code action is run.

-
- -#### Properties - - - -diagnostics: ReadonlyArray<Diagnostic> -
-

An array of diagnostics.

-
-
- - - -only?: CodeActionKind -
-

Requested kind of actions to return.

-

Actions not of this kind are filtered out before being shown by the lightbulb.

-
-
- -### CodeActionKind - - - -

Kind of a code action.

-

Kinds are a hierarchical list of identifiers separated by ., e.g. "refactor.extract.function".

-

Code action kinds are used by VS Code for UI elements such as the refactoring context menu. Users -can also trigger code actions with a specific kind with the editor.action.codeAction command.

-
- -#### Static - - - -Empty: CodeActionKind -
-

Empty kind.

-
-
- - - -QuickFix: CodeActionKind -
-

Base kind for quickfix actions: quickfix.

-

Quick fix actions address a problem in the code and are shown in the normal code action context menu.

-
-
- - - -Refactor: CodeActionKind -
-

Base kind for refactoring actions: refactor

-

Refactoring actions are shown in the refactoring context menu.

-
-
- - - -RefactorExtract: CodeActionKind -
-

Base kind for refactoring extraction actions: refactor.extract

-

Example extract actions:

-
    -
  • Extract method
    • -
  • Extract function
    • -
  • Extract variable
    • -
  • Extract interface from class
    • -
  • ...
    • -
-
-
- - - -RefactorInline: CodeActionKind -
-

Base kind for refactoring inline actions: refactor.inline

-

Example inline actions:

-
    -
  • Inline function
    • -
  • Inline variable
    • -
  • Inline constant
    • -
  • ...
    • -
-
-
- - - -RefactorRewrite: CodeActionKind -
-

Base kind for refactoring rewrite actions: refactor.rewrite

-

Example rewrite actions:

-
    -
  • Convert JavaScript function to class
    • -
  • Add or remove parameter
    • -
  • Encapsulate field
    • -
  • Make method static
    • -
  • Move method to base class
    • -
  • ...
    • -
-
-
- - - -Source: CodeActionKind -
-

Base kind for source actions: source

-

Source code actions apply to the entire file. They must be explicitly requested and will not show in the -normal lightbulb menu. Source actions -can be run on save using editor.codeActionsOnSave and are also shown in the source context menu.

-
-
- - - -SourceFixAll: CodeActionKind -
-

Base kind for auto-fix source actions: source.fixAll.

-

Fix all actions automatically fix errors that have a clear fix that do not require user input. -They should not suppress errors or perform unsafe fixes such as generating new types or classes.

-
-
- - - -SourceOrganizeImports: CodeActionKind -
-

Base kind for an organize imports source action: source.organizeImports.

-
-
- -#### Constructors - - - -new CodeActionKind(value: string): CodeActionKind -
-
-
- - - - - -
ParameterDescription
value: string
ReturnsDescription
CodeActionKind
-
-
- -#### Properties - - - -value: string -
-

String value of the kind, e.g. "refactor.extract.function".

-
-
- -#### Methods - - - -append(parts: string): CodeActionKind -
-

Create a new kind by appending a more specific selector to the current kind.

-

Does not modify the current kind.

-
-
- - - - - -
ParameterDescription
parts: string
ReturnsDescription
CodeActionKind
-
-
- - - -contains(other: CodeActionKind): boolean -
-

Checks if other is a sub-kind of this CodeActionKind.

-

The kind "refactor.extract" for example contains "refactor.extract" and `"refactor.extract.function", -but not "unicorn.refactor.extract", or "refactor.extractAll" or refactor.

-
-
- - - - - -
ParameterDescription
other: CodeActionKind

Kind to check.

-
ReturnsDescription
boolean
-
-
- - - -intersects(other: CodeActionKind): boolean -
-

Checks if this code action kind intersects other.

-

The kind "refactor.extract" for example intersects refactor, "refactor.extract" and `"refactor.extract.function", -but not "unicorn.refactor.extract", or "refactor.extractAll".

-
-
- - - - - -
ParameterDescription
other: CodeActionKind

Kind to check.

-
ReturnsDescription
boolean
-
-
- -### CodeActionProvider<T> - - - -

The code action interface defines the contract between extensions and -the lightbulb feature.

-

A code action can be any command that is known to the system.

-
- -#### Methods - - - -provideCodeActions(document: TextDocument, range: Range | Selection, context: CodeActionContext, token: CancellationToken): ProviderResult<Command | CodeAction[]> -
-

Provide commands for the given document and range.

-
-
- - - - - - - - -
ParameterDescription
document: TextDocument

The document in which the command was invoked.

-
range: Range | Selection

The selector or range for which the command was invoked. This will always be a selection if -there is a currently active editor.

-
context: CodeActionContext

Context carrying additional information.

-
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<Command | CodeAction[]>

An array of commands, quick fixes, or refactorings or a thenable of such. The lack of a result can be -signaled by returning undefined, null, or an empty array.

-
-
-
- - - -resolveCodeAction(codeAction: T, token: CancellationToken): ProviderResult<T> -
-

Given a code action fill in its edit-property. Changes to -all other properties, like title, are ignored. A code action that has an edit -will not be resolved.

-

Note that a code action provider that returns commands, not code actions, cannot successfully -implement this function. Returning commands is deprecated and instead code actions should be -returned.

-
-
- - - - - - -
ParameterDescription
codeAction: T

A code action.

-
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<T>

The resolved code action or a thenable that resolves to such. It is OK to return the given -item. When no result is returned, the given item will be used.

-
-
-
- -### CodeActionProviderMetadata - - - -

Metadata about the type of code actions that a CodeActionProvider provides.

-
- -#### Properties - - - -documentation?: ReadonlyArray<{command: Command, kind: CodeActionKind}> -
-

Static documentation for a class of code actions.

-

Documentation from the provider is shown in the code actions menu if either:

-
    -

  • Code actions of kind are requested by VS Code. In this case, VS Code will show the documentation that -most closely matches the requested code action kind. For example, if a provider has documentation for -both Refactor and RefactorExtract, when the user requests code actions for RefactorExtract, -VS Code will use the documentation for RefactorExtract instead of the documentation for Refactor.

    -
    • -

  • Any code actions of kind are returned by the provider.

    -
    • -
-

At most one documentation entry will be shown per provider.

-
-
- - - -providedCodeActionKinds?: ReadonlyArray<CodeActionKind> -
-

List of CodeActionKinds that a CodeActionProvider may return.

-

This list is used to determine if a given CodeActionProvider should be invoked or not. -To avoid unnecessary computation, every CodeActionProvider should list use providedCodeActionKinds. The -list of kinds may either be generic, such as [CodeActionKind.Refactor], or list out every kind provided, -such as [CodeActionKind.Refactor.Extract.append('function'), CodeActionKind.Refactor.Extract.append('constant'), ...].

-
-
- -### CodeLens - - - -

A code lens represents a command that should be shown along with -source text, like the number of references, a way to run tests, etc.

-

A code lens is unresolved when no command is associated to it. For performance -reasons the creation of a code lens and resolving should be done to two stages.

- - -
- -#### Constructors - - - -new CodeLens(range: Range, command?: Command): CodeLens -
-

Creates a new code lens object.

-
-
- - - - - - -
ParameterDescription
range: Range

The range to which this code lens applies.

-
command?: Command

The command associated to this code lens.

-
ReturnsDescription
CodeLens
-
-
- -#### Properties - - - -command?: Command -
-

The command this code lens represents.

-
-
- - - -isResolved: boolean -
-

true when there is a command associated.

-
-
- - - -range: Range -
-

The range in which this code lens is valid. Should only span a single line.

-
-
- -### CodeLensProvider<T> - - - -

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

-
- -#### Events - - - -onDidChangeCodeLenses?: Event<void> -
-

An optional event to signal that the code lenses from this provider have changed.

-
-
- -#### Methods - - - -provideCodeLenses(document: TextDocument, token: CancellationToken): ProviderResult<T[]> -
-

Compute a list of lenses. This call should return as fast as possible and if -computing the commands is expensive implementors should only return code lens objects with the -range set and implement resolve.

-
-
- - - - - - -
ParameterDescription
document: TextDocument

The document in which the command was invoked.

-
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<T[]>

An array of code lenses or a thenable that resolves to such. The lack of a result can be -signaled by returning undefined, null, or an empty array.

-
-
-
- - - -resolveCodeLens(codeLens: T, token: CancellationToken): ProviderResult<T> -
-

This function will be called for each visible code lens, usually when scrolling and after -calls to compute-lenses.

-
-
- - - - - - -
ParameterDescription
codeLens: T

Code lens that must be resolved.

-
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<T>

The given, resolved code lens or thenable that resolves to such.

-
-
-
- -### Color - - - -

Represents a color in RGBA space.

-
- -#### Constructors - - - -new Color(red: number, green: number, blue: number, alpha: number): Color -
-

Creates a new color instance.

-
-
- - - - - - - - -
ParameterDescription
red: number

The red component.

-
green: number

The green component.

-
blue: number

The blue component.

-
alpha: number

The alpha component.

-
ReturnsDescription
Color
-
-
- -#### Properties - - - -alpha: number -
-

The alpha component of this color in the range [0-1].

-
-
- - - -blue: number -
-

The blue component of this color in the range [0-1].

-
-
- - - -green: number -
-

The green component of this color in the range [0-1].

-
-
- - - -red: number -
-

The red component of this color in the range [0-1].

-
-
- -### ColorInformation - - - -

Represents a color range from a document.

-
- -#### Constructors - - - -new ColorInformation(range: Range, color: Color): ColorInformation -
-

Creates a new color range.

-
-
- - - - - - -
ParameterDescription
range: Range

The range the color appears in. Must not be empty.

-
color: Color

The value of the color.

-
ReturnsDescription
ColorInformation
-
-
- -#### Properties - - - -color: Color -
-

The actual color value for this color range.

-
-
- - - -range: Range -
-

The range in the document where this color appears.

-
-
- -### ColorPresentation - - - -

A color presentation object describes how a color should be represented as text and what -edits are required to refer to it from source code.

-

For some languages one color can have multiple presentations, e.g. css can represent the color red with -the constant Red, the hex-value #ff0000, or in rgba and hsla forms. In csharp other representations -apply, e.g. System.Drawing.Color.Red.

-
- -#### Constructors - - - -new ColorPresentation(label: string): ColorPresentation -
-

Creates a new color presentation.

-
-
- - - - - -
ParameterDescription
label: string

The label of this color presentation.

-
ReturnsDescription
ColorPresentation
-
-
- -#### Properties - - - -additionalTextEdits?: TextEdit[] -
-

An optional array of additional text edits that are applied when -selecting this color presentation. Edits must not overlap with the main edit nor with themselves.

-
-
- - - -label: string -
-

The label of this color presentation. It will be shown on the color -picker header. By default this is also the text that is inserted when selecting -this color presentation.

-
-
- - - -textEdit?: TextEdit -
-

An edit which is applied to a document when selecting -this presentation for the color. When falsy the label -is used.

-
-
- -### ColorTheme - - - -

Represents a color theme.

-
- -#### Properties - - - -kind: ColorThemeKind -
-

The kind of this color theme: light, dark or high contrast.

-
-
- -### ColorThemeKind - - - -

Represents a color theme kind.

-
- -#### Enumeration members - - - -Dark -
-2 -
- - - -HighContrast -
-3 -
- - - -Light -
-1 -
- -### 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.

-
- -#### Properties - - - -arguments?: any[] -
-

Arguments that the command handler should be -invoked with.

-
-
- - - -command: string -
-

The identifier of the actual command handler.

- -
-
- - - -title: string -
-

Title of the command, like save.

-
-
- - - -tooltip?: string -
-

A tooltip for the command, when represented in the UI.

-
-
- -### Comment - - - -

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

-
- -#### Properties - - - -author: CommentAuthorInformation -
-

The author information of the comment

-
-
- - - -body: string | MarkdownString -
-

The human-readable comment body

-
-
- - - -contextValue?: string -
-

Context value of the comment. This can be used to contribute comment specific actions. -For example, a comment is given a context value as editable. When contributing actions to comments/comment/title -using menus extension point, you can specify context value for key comment in when expression like comment == editable.

- -
    "contributes": {
-        "menus": {
-            "comments/comment/title": [
-                {
-                    "command": "extension.deleteComment",
-                    "when": "comment == editable"
-                }
-            ]
-        }
-    }
-
-

This will show action extension.deleteComment only for comments with contextValue is editable.

-
-
- - - -label?: string -
-

Optional label describing the Comment -Label will be rendered next to authorName if exists.

-
-
- - - -mode: CommentMode -
-

Comment mode of the comment

-
-
- - - -reactions?: CommentReaction[] -
-

Optional reactions of the comment

-
-
- -### CommentAuthorInformation - - - -

Author information of a comment

-
- -#### Properties - - - -iconPath?: Uri -
-

The optional icon path for the author

-
-
- - - -name: string -
-

The display name of the author of the comment

-
-
- -### CommentController - - - -

A comment controller is able to provide comments support to the editor and -provide users various ways to interact with comments.

-
- -#### Properties - - - -commentingRangeProvider?: CommentingRangeProvider -
-

Optional commenting range provider. Provide a list ranges which support commenting to any given resource uri.

-

If not provided, users can leave comments in any document opened in the editor.

-
-
- - - -id: string -
-

The id of this comment controller.

-
-
- - - -label: string -
-

The human-readable label of this comment controller.

-
-
- - - -options?: CommentOptions -
-

Comment controller options

-
-
- - - -reactionHandler?: (comment: Comment, reaction: CommentReaction) => Promise<void> -
-

Optional reaction handler for creating and deleting reactions on a comment.

-
-
- -#### Methods - - - -createCommentThread(uri: Uri, range: Range, comments: Comment[]): CommentThread -
-

Create a comment thread. The comment thread will be displayed in visible text editors (if the resource matches) -and Comments Panel once created.

-
-
- - - - - - - -
ParameterDescription
uri: Uri

The uri of the document the thread has been created on.

-
range: Range

The range the comment thread is located within the document.

-
comments: Comment[]

The ordered comments of the thread.

-
ReturnsDescription
CommentThread
-
-
- - - -dispose(): void -
-

Dispose this comment controller.

-

Once disposed, all comment threads created by this comment controller will also be removed from the editor -and Comments Panel.

-
-
- - - -
ReturnsDescription
void
-
-
- -### CommentingRangeProvider - - - -

Commenting range provider for a comment controller.

-
- -#### Methods - - - -provideCommentingRanges(document: TextDocument, token: CancellationToken): ProviderResult<Range[]> -
-

Provide a list of ranges which allow new comment threads creation or null for a given document

-
-
- - - - - - -
ParameterDescription
document: TextDocument
token: CancellationToken
ReturnsDescription
ProviderResult<Range[]>
-
-
- -### CommentMode - - - -

Comment mode of a comment

-
- -#### Enumeration members - - - -Editing -
-0 -
- - - -Preview -
-1 -
- -### CommentOptions - - - -

Represents a comment controller's options.

-
- -#### Properties - - - -placeHolder?: string -
-

An optional string to show as placeholder in the comment input box when it's focused.

-
-
- - - -prompt?: string -
-

An optional string to show on the comment input box when it's collapsed.

-
-
- -### CommentReaction - - - -

Reactions of a comment

-
- -#### Properties - - - -authorHasReacted: boolean -
-

Whether the author of the comment has reacted to this reaction

-
-
- - - -count: number -
-

The number of users who have reacted to this reaction

-
-
- - - -iconPath: string | Uri -
-

Icon for the reaction shown in UI.

-
-
- - - -label: string -
-

The human-readable label for the reaction

-
-
- -### CommentReply - - - -

Command argument for actions registered in comments/commentThread/context.

-
- -#### Properties - - - -text: string -
-

The value in the comment editor

-
-
- - - -thread: CommentThread -
-

The active comment thread

-
-
- -### CommentRule - - - -

Describes how comments for a language work.

-
- -#### Properties - - - -blockComment?: CharacterPair -
-

The block comment character pair, like /* block comment *&#47;

-
-
- - - -lineComment?: string -
-

The line comment token, like // this is a comment

-
-
- -### CommentThread - - - -

A collection of comments representing a conversation at a particular range in a document.

-
- -#### Properties - - - -canReply: boolean -
-

Whether the thread supports reply. -Defaults to true.

-
-
- - - -collapsibleState: CommentThreadCollapsibleState -
-

Whether the thread should be collapsed or expanded when opening the document. -Defaults to Collapsed.

-
-
- - - -comments: ReadonlyArray<Comment> -
-

The ordered comments of the thread.

-
-
- - - -contextValue?: string -
-

Context value of the comment thread. This can be used to contribute thread specific actions. -For example, a comment thread is given a context value as editable. When contributing actions to comments/commentThread/title -using menus extension point, you can specify context value for key commentThread in when expression like commentThread == editable.

- -
    "contributes": {
-        "menus": {
-            "comments/commentThread/title": [
-                {
-                    "command": "extension.deleteCommentThread",
-                    "when": "commentThread == editable"
-                }
-            ]
-        }
-    }
-

This will show action extension.deleteCommentThread only for comment threads with contextValue is editable.

-
-
- - - -label?: string -
-

The optional human-readable label describing the Comment Thread

-
-
- - - -range: Range -
-

The range the comment thread is located within the document. The thread icon will be shown -at the first line of the range.

-
-
- - - -uri: Uri -
-

The uri of the document the thread has been created on.

-
-
- -#### Methods - - - -dispose(): void -
-

Dispose this comment thread.

-

Once disposed, this comment thread will be removed from visible editors and Comment Panel when appropriate.

-
-
- - - -
ReturnsDescription
void
-
-
- -### CommentThreadCollapsibleState - - - -

Collapsible state of a comment thread

-
- -#### Enumeration members - - - -Collapsed -
-0 -
- - - -Expanded -
-1 -
- -### CompletionContext - - - -

Contains additional information about the context in which -completion provider is triggered.

-
- -#### Properties - - - -triggerCharacter?: string -
-

Character that triggered the completion item provider.

-

undefined if provider was not triggered by a character.

-

The trigger character is already in the document when the completion provider is triggered.

-
-
- - - -triggerKind: CompletionTriggerKind -
-

How the completion was triggered.

-
-
- -### CompletionItem - - - -

A completion item represents a text snippet that is proposed to complete text that is being typed.

-

It is sufficient to create a completion item from just a label. In that -case the completion item will replace the word -until the cursor with the given label or insertText. Otherwise the -given edit is used.

-

When selecting a completion item in the editor its defined or synthesized text edit will be applied -to all cursors/selections whereas additionalTextEdits will be -applied as provided.

- - -
- -#### Constructors - - - -new CompletionItem(label: string, kind?: CompletionItemKind): CompletionItem -
-

Creates a new completion item.

-

Completion items must have at least a label which then -will be used as insert text as well as for sorting and filtering.

-
-
- - - - - - -
ParameterDescription
label: string

The label of the completion.

-
kind?: CompletionItemKind

The kind of the completion.

-
ReturnsDescription
CompletionItem
-
-
- -#### Properties - - - -additionalTextEdits?: TextEdit[] -
-

An optional array of additional text edits that are applied when -selecting this completion. Edits must not overlap with the main edit -nor with themselves.

-
-
- - - -command?: Command -
-

An optional command that is executed after inserting this completion. Note that -additional modifications to the current document should be described with the -additionalTextEdits-property.

-
-
- - - -commitCharacters?: string[] -
-

An optional set of characters that when pressed while this completion is active will accept it first and -then type that character. Note that all commit characters should have length=1 and that superfluous -characters will be ignored.

-
-
- - - -detail?: string -
-

A human-readable string with additional information -about this item, like type or symbol information.

-
-
- - - -documentation?: string | MarkdownString -
-

A human-readable string that represents a doc-comment.

-
-
- - - -filterText?: string -
-

A string that should be used when filtering a set of -completion items. When falsy the label -is used.

-

Note that the filter text is matched against the leading word (prefix) which is defined -by the range-property. -prefix.

-
-
- - - -insertText?: string | SnippetString -
-

A string or snippet that should be inserted in a document when selecting -this completion. When falsy the label -is used.

-
-
- - - -keepWhitespace?: boolean -
-

Keep whitespace of the insertText as is. By default, the editor adjusts leading -whitespace of new lines so that they match the indentation of the line for which the item is accepted - setting -this to true will prevent that.

-
-
- - - -kind?: CompletionItemKind -
-

The kind of this completion item. Based on the kind -an icon is chosen by the editor.

-
-
- - - -label: string -
-

The label of this completion item. By default -this is also the text that is inserted when selecting -this completion.

-
-
- - - -preselect?: boolean -
-

Select this item when showing. Note that only one completion item can be selected and -that the editor decides which item that is. The rule is that the first item of those -that match best is selected.

-
-
- - - -range?: Range | {inserting: Range, replacing: Range} -
-

A range or a insert and replace range selecting the text that should be replaced by this completion item.

-

When omitted, the range of the current word is used as replace-range -and as insert-range the start of the current word to the -current position is used.

-

Note 1: A range must be a single line and it must -contain the position at which completion has been requested. -Note 2: A insert range must be a prefix of a replace range, that means it must be contained and starting at the same position.

-
-
- - - -sortText?: string -
-

A string that should be used when comparing this item -with other items. When falsy the label -is used.

-

Note that sortText is only used for the initial ordering of completion -items. When having a leading word (prefix) ordering is based on how -well completion match that prefix and the initial ordering is only used -when completions match equal. The prefix is defined by the -range-property and can therefore be different -for each completion.

-
-
- - - -tags?: ReadonlyArray<CompletionItemTag> -
-

Tags for this completion item.

-
-
- - - -textEdit?: TextEdit -
-
    -
  • deprecated - Use CompletionItem.insertText and CompletionItem.range instead.
    • -
-

An edit which is applied to a document when selecting -this completion. When an edit is provided the value of -insertText is ignored.

-

The range of the edit must be single-line and on the same -line completions were requested at.

-
-
- -### CompletionItemKind - - - -

Completion item kinds.

-
- -#### Enumeration members - - - -Class -
-6 -
- - - -Color -
-15 -
- - - -Constant -
-20 -
- - - -Constructor -
-3 -
- - - -Enum -
-12 -
- - - -EnumMember -
-19 -
- - - -Event -
-22 -
- - - -Field -
-4 -
- - - -File -
-16 -
- - - -Folder -
-18 -
- - - -Function -
-2 -
- - - -Interface -
-7 -
- - - -Issue -
-26 -
- - - -Keyword -
-13 -
- - - -Method -
-1 -
- - - -Module -
-8 -
- - - -Operator -
-23 -
- - - -Property -
-9 -
- - - -Reference -
-17 -
- - - -Snippet -
-14 -
- - - -Struct -
-21 -
- - - -Text -
-0 -
- - - -TypeParameter -
-24 -
- - - -Unit -
-10 -
- - - -User -
-25 -
- - - -Value -
-11 -
- - - -Variable -
-5 -
- -### CompletionItemProvider<T> - - - -

The completion item provider interface defines the contract between extensions and -IntelliSense.

-

Providers can delay the computation of the detail -and documentation properties by implementing the -resolveCompletionItem-function. However, 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.

-
- -#### Methods - - - -provideCompletionItems(document: TextDocument, position: Position, token: CancellationToken, context: CompletionContext): ProviderResult<T[] | CompletionList<T>> -
-

Provide completion items for the given position and document.

-
-
- - - - - - - - -
ParameterDescription
document: TextDocument

The document in which the command was invoked.

-
position: Position

The position at which the command was invoked.

-
token: CancellationToken

A cancellation token.

-
context: CompletionContext

How the completion was triggered.

-
ReturnsDescription
ProviderResult<T[] | CompletionList<T>>

An array of completions, a completion list, or a thenable that resolves to either. -The lack of a result can be signaled by returning undefined, null, or an empty array.

-
-
-
- - - -resolveCompletionItem(item: T, token: CancellationToken): ProviderResult<T> -
-

Given a completion item fill in more data, like doc-comment -or details.

-

The editor will only resolve a completion item once.

-

Note that this function is called when completion items are already showing in the UI or when an item has been -selected for insertion. Because of that, no property that changes the presentation (label, sorting, filtering etc) -or the (primary) insert behaviour (insertText) can be changed.

-

This function may fill in additionalTextEdits. However, that means an item might be -inserted before resolving is done and in that case the editor will do a best effort to still apply those additional -text edits.

-
-
- - - - - - -
ParameterDescription
item: T

A completion item currently active in the UI.

-
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<T>

The resolved completion item or a thenable that resolves to of such. It is OK to return the given -item. When no result is returned, the given item will be used.

-
-
-
- -### CompletionItemTag - - - -

Completion item tags are extra annotations that tweak the rendering of a completion -item.

-
- -#### Enumeration members - - - -Deprecated -
-1 -
- -### CompletionList<T> - - - -

Represents a collection of completion items to be presented -in the editor.

-
- -#### Constructors - - - -new CompletionList(items?: T[], isIncomplete?: boolean): CompletionList -
-

Creates a new completion list.

-
-
- - - - - - -
ParameterDescription
items?: T[]

The completion items.

-
isIncomplete?: boolean

The list is not complete.

-
ReturnsDescription
CompletionList
-
-
- -#### Properties - - - -isIncomplete?: boolean -
-

This list is not complete. Further typing should result in recomputing -this list.

-
-
- - - -items: T[] -
-

The completion items.

-
-
- -### CompletionTriggerKind - - - -

How a completion provider was triggered

-
- -#### Enumeration members - - - -Invoke -
-0 -
- - - -TriggerCharacter -
-1 -
- - - -TriggerForIncompleteCompletions -
-2 -
- -### ConfigurationChangeEvent - - - -

An event describing the change in Configuration

-
- -#### Methods - - - -affectsConfiguration(section: string, scope?: ConfigurationScope): boolean -
-

Checks if the given section has changed. -If scope is provided, checks if the section has changed for resources under the given scope.

-
-
- - - - - - -
ParameterDescription
section: string

Configuration name, supports dotted names.

-
scope?: ConfigurationScope

A scope in which to check.

-
ReturnsDescription
boolean

true if the given section has changed.

-
-
-
- -### ConfigurationScope - - - -

The configuration scope which can be a -a 'resource' or a languageId or both or -a 'TextDocument' or -a 'WorkspaceFolder'

-
- - - -ConfigurationScope: Uri | TextDocument | WorkspaceFolder | {languageId: string, uri: Uri} - -### ConfigurationTarget - - - -

The configuration target

-
- -#### Enumeration members - - - -Global -
-1 -
- - - -Workspace -
-2 -
- - - -WorkspaceFolder -
-3 -
- -### CustomDocument - - - -

Represents a custom document used by a CustomEditorProvider.

-

Custom documents are only used within a given CustomEditorProvider. The lifecycle of a CustomDocument is -managed by VS Code. When no more references remain to a CustomDocument, it is disposed of.

-
- -#### Properties - - - -uri: Uri -
-

The associated uri for this document.

-
-
- -#### Methods - - - -dispose(): void -
-

Dispose of the custom document.

-

This is invoked by VS Code when there are no more references to a given CustomDocument (for example when -all editors associated with the document have been closed.)

-
-
- - - -
ReturnsDescription
void
-
-
- -### CustomDocumentBackup - - - -

A backup for an CustomDocument.

-
- -#### Properties - - - -id: string -
-

Unique identifier for the backup.

-

This id is passed back to your extension in openCustomDocument when opening a custom editor from a backup.

-
-
- -#### Methods - - - -delete(): void -
-

Delete the current backup.

-

This is called by VS Code when it is clear the current backup is no longer needed, such as when a new backup -is made or when the file is saved.

-
-
- - - -
ReturnsDescription
void
-
-
- -### CustomDocumentBackupContext - - - -

Additional information used to implement CustomEditableDocument.backup.

-
- -#### Properties - - - -destination: Uri -
-

Suggested file location to write the new backup.

-

Note that your extension is free to ignore this and use its own strategy for backup.

-

If the editor is for a resource from the current workspace, destination will point to a file inside -ExtensionContext.storagePath. The parent folder of destination may not exist, so make sure to created it -before writing the backup to this location.

-
-
- -### CustomDocumentContentChangeEvent<T> - - - -

Event triggered by extensions to signal to VS Code that the content of a CustomDocument -has changed.

- -
- -#### Properties - - - -document: T -
-

The document that the change is for.

-
-
- -### CustomDocumentEditEvent<T> - - - -

Event triggered by extensions to signal to VS Code that an edit has occurred on an CustomDocument.

- -
- -#### Properties - - - -document: T -
-

The document that the edit is for.

-
-
- - - -label?: string -
-

Display name describing the edit.

-

This will be shown to users in the UI for undo/redo operations.

-
-
- -#### Methods - - - -redo(): Thenable<void> | void -
-

Redo the edit operation.

-

This is invoked by VS Code when the user redoes this edit. To implement redo, your -extension should restore the document and editor to the state they were in just after this -edit was added to VS Code's internal edit stack by onDidChangeCustomDocument.

-
-
- - - -
ReturnsDescription
Thenable<void> | void
-
-
- - - -undo(): Thenable<void> | void -
-

Undo the edit operation.

-

This is invoked by VS Code when the user undoes this edit. To implement undo, your -extension should restore the document and editor to the state they were in just before this -edit was added to VS Code's internal edit stack by onDidChangeCustomDocument.

-
-
- - - -
ReturnsDescription
Thenable<void> | void
-
-
- -### CustomDocumentOpenContext - - - -

Additional information about the opening custom document.

-
- -#### Properties - - - -backupId?: string -
-

The id of the backup to restore the document from or undefined if there is no backup.

-

If this is provided, your extension should restore the editor from the backup instead of reading the file -from the user's workspace.

-
-
- -### CustomEditorProvider<T> - - - -

Provider for editable custom editors that use a custom document model.

-

Custom editors use CustomDocument as their document model instead of a TextDocument. -This gives extensions full control over actions such as edit, save, and backup.

-

You should use this type of custom editor when dealing with binary files or more complex scenarios. For simple -text based documents, use CustomTextEditorProvider instead.

-
- -#### Events - - - -onDidChangeCustomDocument: Event<CustomDocumentEditEvent<T>> | Event<CustomDocumentContentChangeEvent<T>> -
-

Signal that an edit has occurred inside a custom editor.

-

This event must be fired by your extension whenever an edit happens in a custom editor. An edit can be -anything from changing some text, to cropping an image, to reordering a list. Your extension is free to -define what an edit is and what data is stored on each edit.

-

Firing onDidChange causes VS Code to mark the editors as being dirty. This is cleared when the user either -saves or reverts the file.

-

Editors that support undo/redo must fire a CustomDocumentEditEvent whenever an edit happens. This allows -users to undo and redo the edit using VS Code's standard VS Code keyboard shortcuts. VS Code will also mark -the editor as no longer being dirty if the user undoes all edits to the last saved state.

-

Editors that support editing but cannot use VS Code's standard undo/redo mechanism must fire a CustomDocumentContentChangeEvent. -The only way for a user to clear the dirty state of an editor that does not support undo/redo is to either -save or revert the file.

-

An editor should only ever fire CustomDocumentEditEvent events, or only ever fire CustomDocumentContentChangeEvent events.

-
-
- -#### Methods - - - -backupCustomDocument(document: T, context: CustomDocumentBackupContext, cancellation: CancellationToken): Thenable<CustomDocumentBackup> -
-

Back up a dirty custom document.

-

Backups are used for hot exit and to prevent data loss. Your backup method should persist the resource in -its current state, i.e. with the edits applied. Most commonly this means saving the resource to disk in -the ExtensionContext.storagePath. When VS Code reloads and your custom editor is opened for a resource, -your extension should first check to see if any backups exist for the resource. If there is a backup, your -extension should load the file contents from there instead of from the resource in the workspace.

-

backup is triggered approximately one second after the user stops editing the document. If the user -rapidly edits the document, backup will not be invoked until the editing stops.

-

backup is not invoked when auto save is enabled (since auto save already persists the resource).

-
-
- - - - - - - -
ParameterDescription
document: T

Document to backup.

-
context: CustomDocumentBackupContext

Information that can be used to backup the document.

-
cancellation: CancellationToken

Token that signals the current backup since a new backup is coming in. It is up to your -extension to decided how to respond to cancellation. If for example your extension is backing up a large file -in an operation that takes time to complete, your extension may decide to finish the ongoing backup rather -than cancelling it to ensure that VS Code has some valid backup.

-
ReturnsDescription
Thenable<CustomDocumentBackup>
-
-
- - - -openCustomDocument(uri: Uri, openContext: CustomDocumentOpenContext, token: CancellationToken): Thenable<T> | T -
-

Create a new document for a given resource.

-

openCustomDocument is called when the first time an editor for a given resource is opened. The opened -document is then passed to resolveCustomEditor so that the editor can be shown to the user.

-

Already opened CustomDocument are re-used if the user opened additional editors. When all editors for a -given resource are closed, the CustomDocument is disposed of. Opening an editor at this point will -trigger another call to openCustomDocument.

-
-
- - - - - - - -
ParameterDescription
uri: Uri

Uri of the document to open.

-
openContext: CustomDocumentOpenContext

Additional information about the opening custom document.

-
token: CancellationToken

A cancellation token that indicates the result is no longer needed.

-
ReturnsDescription
Thenable<T> | T

The custom document.

-
-
-
- - - -resolveCustomEditor(document: T, webviewPanel: WebviewPanel, token: CancellationToken): Thenable<void> | void -
-

Resolve a custom editor for a given resource.

-

This is called whenever the user opens a new editor for this CustomEditorProvider.

-
-
- - - - - - - -
ParameterDescription
document: T

Document for the resource being resolved.

-
webviewPanel: WebviewPanel

The webview panel used to display the editor UI for this resource.

-

During resolve, the provider must fill in the initial html for the content webview panel and hook up all -the event listeners on it that it is interested in. The provider can also hold onto the WebviewPanel to -use later for example in a command. See WebviewPanel for additional details.

-
token: CancellationToken

A cancellation token that indicates the result is no longer needed.

-
ReturnsDescription
Thenable<void> | void

Optional thenable indicating that the custom editor has been resolved.

-
-
-
- - - -revertCustomDocument(document: T, cancellation: CancellationToken): Thenable<void> -
-

Revert a custom document to its last saved state.

-

This method is invoked by VS Code when the user triggers File: Revert File in a custom editor. (Note that -this is only used using VS Code's File: Revert File command and not on a git revert of the file).

-

To implement revert, the implementer must make sure all editor instances (webviews) for document -are displaying the document in the same state is saved in. This usually means reloading the file from the -workspace.

-
-
- - - - - - -
ParameterDescription
document: T

Document to revert.

-
cancellation: CancellationToken

Token that signals the revert is no longer required.

-
ReturnsDescription
Thenable<void>

Thenable signaling that the change has completed.

-
-
-
- - - -saveCustomDocument(document: T, cancellation: CancellationToken): Thenable<void> -
-

Save a custom document.

-

This method is invoked by VS Code when the user saves a custom editor. This can happen when the user -triggers save while the custom editor is active, by commands such as save all, or by auto save if enabled.

-

To implement save, the implementer must persist the custom editor. This usually means writing the -file data for the custom document to disk. After save completes, any associated editor instances will -no longer be marked as dirty.

-
-
- - - - - - -
ParameterDescription
document: T

Document to save.

-
cancellation: CancellationToken

Token that signals the save is no longer required (for example, if another save was triggered).

-
ReturnsDescription
Thenable<void>

Thenable signaling that saving has completed.

-
-
-
- - - -saveCustomDocumentAs(document: T, destination: Uri, cancellation: CancellationToken): Thenable<void> -
-

Save a custom document to a different location.

-

This method is invoked by VS Code when the user triggers 'save as' on a custom editor. The implementer must -persist the custom editor to destination.

-

When the user accepts save as, the current editor is be replaced by an non-dirty editor for the newly saved file.

-
-
- - - - - - - -
ParameterDescription
document: T

Document to save.

-
destination: Uri

Location to save to.

-
cancellation: CancellationToken

Token that signals the save is no longer required.

-
ReturnsDescription
Thenable<void>

Thenable signaling that saving has completed.

-
-
-
- -### CustomExecution - - - -

Class used to execute an extension callback as a task.

-
- -#### Constructors - - - -new CustomExecution(callback: (resolvedDefinition: TaskDefinition) => Thenable<Pseudoterminal>): CustomExecution -
-

Constructs a CustomExecution task object. The callback will be executed the task is run, at which point the -extension should return the Pseudoterminal it will "run in". The task should wait to do further execution until -Pseudoterminal.open is called. Task cancellation should be handled using -Pseudoterminal.close. When the task is complete fire -Pseudoterminal.onDidClose.

-
-
- - - - - -
ParameterDescription
callback: (resolvedDefinition: TaskDefinition) => Thenable<Pseudoterminal>

The callback that will be called when the task is started by a user. Any ${} style variables that -were in the task definition will be resolved and passed into the callback.

-
ReturnsDescription
CustomExecution
-
-
- -### CustomReadonlyEditorProvider<T> - - - -

Provider for readonly custom editors that use a custom document model.

-

Custom editors use CustomDocument as their document model instead of a TextDocument.

-

You should use this type of custom editor when dealing with binary files or more complex scenarios. For simple -text based documents, use CustomTextEditorProvider instead.

-
- -#### Methods - - - -openCustomDocument(uri: Uri, openContext: CustomDocumentOpenContext, token: CancellationToken): Thenable<T> | T -
-

Create a new document for a given resource.

-

openCustomDocument is called when the first time an editor for a given resource is opened. The opened -document is then passed to resolveCustomEditor so that the editor can be shown to the user.

-

Already opened CustomDocument are re-used if the user opened additional editors. When all editors for a -given resource are closed, the CustomDocument is disposed of. Opening an editor at this point will -trigger another call to openCustomDocument.

-
-
- - - - - - - -
ParameterDescription
uri: Uri

Uri of the document to open.

-
openContext: CustomDocumentOpenContext

Additional information about the opening custom document.

-
token: CancellationToken

A cancellation token that indicates the result is no longer needed.

-
ReturnsDescription
Thenable<T> | T

The custom document.

-
-
-
- - - -resolveCustomEditor(document: T, webviewPanel: WebviewPanel, token: CancellationToken): Thenable<void> | void -
-

Resolve a custom editor for a given resource.

-

This is called whenever the user opens a new editor for this CustomEditorProvider.

-
-
- - - - - - - -
ParameterDescription
document: T

Document for the resource being resolved.

-
webviewPanel: WebviewPanel

The webview panel used to display the editor UI for this resource.

-

During resolve, the provider must fill in the initial html for the content webview panel and hook up all -the event listeners on it that it is interested in. The provider can also hold onto the WebviewPanel to -use later for example in a command. See WebviewPanel for additional details.

-
token: CancellationToken

A cancellation token that indicates the result is no longer needed.

-
ReturnsDescription
Thenable<void> | void

Optional thenable indicating that the custom editor has been resolved.

-
-
-
- -### CustomTextEditorProvider - - - -

Provider for text based custom editors.

-

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.

-
- -#### Methods - - - -resolveCustomTextEditor(document: TextDocument, webviewPanel: WebviewPanel, token: CancellationToken): Thenable<void> | void -
-

Resolve a custom editor for a given text resource.

-

This is called when a user first opens a resource for a CustomTextEditorProvider, or if they reopen an -existing editor using this CustomTextEditorProvider.

-
-
- - - - - - - -
ParameterDescription
document: TextDocument

Document for the resource to resolve.

-
webviewPanel: WebviewPanel

The webview panel used to display the editor UI for this resource.

-

During resolve, the provider must fill in the initial html for the content webview panel and hook up all -the event listeners on it that it is interested in. The provider can also hold onto the WebviewPanel to -use later for example in a command. See WebviewPanel for additional details.

-
token: CancellationToken

A cancellation token that indicates the result is no longer needed.

-
ReturnsDescription
Thenable<void> | void

Thenable indicating that the custom editor has been resolved.

-
-
-
- -### DebugAdapter - - - -

A debug adapter that implements the Debug Adapter Protocol can be registered with VS Code if it implements the DebugAdapter interface.

-
- -#### Events - - - -onDidSendMessage: Event<DebugProtocolMessage> -
-

An event which fires after the debug adapter has sent a Debug Adapter Protocol message to VS Code. -Messages can be requests, responses, or events.

-
-
- -#### Static - - - -from(...disposableLikes: {dispose: () => any}[]): Disposable -
-

Combine many disposable-likes into one. Use this method -when having objects with a dispose function which are not -instances of Disposable.

-
-
- - - - - -
ParameterDescription
...disposableLikes: {dispose: () => any}[]

Objects that have at least a dispose-function member.

-
ReturnsDescription
Disposable

Returns a new disposable which, upon dispose, will -dispose all provided disposables.

-
-
-
- -#### Constructors - - - -new DebugAdapter(callOnDispose: Function): DebugAdapter -
-

Creates a new Disposable calling the provided function -on dispose.

-
-
- - - - - -
ParameterDescription
callOnDispose: Function

Function that disposes something.

-
ReturnsDescription
DebugAdapter
-
-
- -#### Methods - - - -dispose(): any -
-

Dispose this object.

-
-
- - - -
ReturnsDescription
any
-
-
- - - -handleMessage(message: DebugProtocolMessage): void -
-

Handle a Debug Adapter Protocol message. -Messages can be requests, responses, or events. -Results or errors are returned via onSendMessage events.

-
-
- - - - - -
ParameterDescription
message: DebugProtocolMessage

A Debug Adapter Protocol message

-
ReturnsDescription
void
-
-
- -### DebugAdapterDescriptor - - - -
- - - -DebugAdapterDescriptor: DebugAdapterExecutable | DebugAdapterServer | DebugAdapterNamedPipeServer | DebugAdapterInlineImplementation - -### DebugAdapterDescriptorFactory - - - -
- -#### Methods - - - -createDebugAdapterDescriptor(session: DebugSession, executable: DebugAdapterExecutable | undefined): ProviderResult<DebugAdapterDescriptor> -
-

'createDebugAdapterDescriptor' is called at the start of a debug session to provide details about the debug adapter to use. -These details must be returned as objects of type DebugAdapterDescriptor. -Currently two types of debug adapters are supported:

-
    -
  • a debug adapter executable is specified as a command path and arguments (see DebugAdapterExecutable),
    • -
  • a debug adapter server reachable via a communication port (see DebugAdapterServer). -If the method is not implemented the default behavior is this: -createDebugAdapter(session: DebugSession, executable: DebugAdapterExecutable) { - if (typeof session.configuration.debugServer === 'number') { -
      return new DebugAdapterServer(session.configuration.debugServer);
-
    } - return executable; -}
    • -
-
-
- - - - - - -
ParameterDescription
session: DebugSession

The debug session for which the debug adapter will be used.

-
executable: DebugAdapterExecutable | undefined

The debug adapter's executable information as specified in the package.json (or undefined if no such information exists).

-
ReturnsDescription
ProviderResult<DebugAdapterDescriptor>

a debug adapter descriptor or undefined.

-
-
-
- -### DebugAdapterExecutable - - - -

Represents a debug adapter executable and optional arguments and runtime options passed to it.

-
- -#### Constructors - - - -new DebugAdapterExecutable(command: string, args?: string[], options?: DebugAdapterExecutableOptions): DebugAdapterExecutable -
-

Creates a description for a debug adapter based on an executable program.

-
-
- - - - - - - -
ParameterDescription
command: string

The command or executable path that implements the debug adapter.

-
args?: string[]

Optional arguments to be passed to the command or executable.

-
options?: DebugAdapterExecutableOptions

Optional options to be used when starting the command or executable.

-
ReturnsDescription
DebugAdapterExecutable
-
-
- -#### Properties - - - -args: string[] -
-

The arguments passed to the debug adapter executable. Defaults to an empty array.

-
-
- - - -command: string -
-

The command or path of the debug adapter executable. -A command must be either an absolute path of an executable or the name of an command to be looked up via the PATH environment variable. -The special value 'node' will be mapped to VS Code's built-in Node.js runtime.

-
-
- - - -options?: DebugAdapterExecutableOptions -
-

Optional options to be used when the debug adapter is started. -Defaults to undefined.

-
-
- -### DebugAdapterExecutableOptions - - - -

Options for a debug adapter executable.

-
- -#### Properties - - - -cwd?: string -
-

The current working directory for the executed debug adapter.

-
-
- - - -env?: -
-

The additional environment of the executed program or shell. If omitted -the parent process' environment is used. If provided it is merged with -the parent process' environment.

-
-
- -### DebugAdapterInlineImplementation - - - -

A debug adapter descriptor for an inline implementation.

-
- -#### Constructors - - - -new DebugAdapterInlineImplementation(implementation: DebugAdapter): DebugAdapterInlineImplementation -
-

Create a descriptor for an inline implementation of a debug adapter.

-
-
- - - - - -
ParameterDescription
implementation: DebugAdapter
ReturnsDescription
DebugAdapterInlineImplementation
-
-
- -### DebugAdapterNamedPipeServer - - - -

Represents a debug adapter running as a Named Pipe (on Windows)/UNIX Domain Socket (on non-Windows) based server.

-
- -#### Constructors - - - -new DebugAdapterNamedPipeServer(path: string): DebugAdapterNamedPipeServer -
-

Create a description for a debug adapter running as a socket based server.

-
-
- - - - - -
ParameterDescription
path: string
ReturnsDescription
DebugAdapterNamedPipeServer
-
-
- -#### Properties - - - -path: string -
-

The path to the NamedPipe/UNIX Domain Socket.

-
-
- -### DebugAdapterServer - - - -

Represents a debug adapter running as a socket based server.

-
- -#### Constructors - - - -new DebugAdapterServer(port: number, host?: string): DebugAdapterServer -
-

Create a description for a debug adapter running as a socket based server.

-
-
- - - - - - -
ParameterDescription
port: number
host?: string
ReturnsDescription
DebugAdapterServer
-
-
- -#### Properties - - - -host?: string -
-

The host.

-
-
- - - -port: number -
-

The port.

-
-
- -### DebugAdapterTracker - - - -

A Debug Adapter Tracker is a means to track the communication between VS Code and a Debug Adapter.

-
- -#### Events - - - -onDidSendMessage(message: any): void -
-

The debug adapter has sent a Debug Adapter Protocol message to VS Code.

-
-
- - - - - -
ParameterDescription
message: any
ReturnsDescription
void
-
-
- - - -onWillReceiveMessage(message: any): void -
-

The debug adapter is about to receive a Debug Adapter Protocol message from VS Code.

-
-
- - - - - -
ParameterDescription
message: any
ReturnsDescription
void
-
-
- - - -onWillStartSession(): void -
-

A session with the debug adapter is about to be started.

-
-
- - - -
ReturnsDescription
void
-
-
- - - -onWillStopSession(): void -
-

The debug adapter session is about to be stopped.

-
-
- - - -
ReturnsDescription
void
-
-
- -#### Methods - - - -onError(error: Error): void -
-

An error with the debug adapter has occurred.

-
-
- - - - - -
ParameterDescription
error: Error
ReturnsDescription
void
-
-
- - - -onExit(code: number | undefined, signal: string | undefined): void -
-

The debug adapter has exited with the given exit code or signal.

-
-
- - - - - - -
ParameterDescription
code: number | undefined
signal: string | undefined
ReturnsDescription
void
-
-
- -### DebugAdapterTrackerFactory - - - -
- -#### Methods - - - -createDebugAdapterTracker(session: DebugSession): ProviderResult<DebugAdapterTracker> -
-

The method 'createDebugAdapterTracker' is called at the start of a debug session in order -to return a "tracker" object that provides read-access to the communication between VS Code and a debug adapter.

-
-
- - - - - -
ParameterDescription
session: DebugSession

The debug session for which the debug adapter tracker will be used.

-
ReturnsDescription
ProviderResult<DebugAdapterTracker>

A debug adapter tracker or undefined.

-
-
-
- -### DebugConfiguration - - - -

Configuration for a debug session.

-
- -#### Properties - - - -name: string -
-

The name of the debug session.

-
-
- - - -request: string -
-

The request type of the debug session.

-
-
- - - -type: string -
-

The type of the debug session.

-
-
- -### DebugConfigurationProvider - - - -

A debug configuration provider allows to add debug configurations to the debug service -and to resolve launch configurations before they are used to start a debug session. -A debug configuration provider is registered via #debug.registerDebugConfigurationProvider.

-
- -#### Methods - - - -provideDebugConfigurations(folder: WorkspaceFolder | undefined, token?: CancellationToken): ProviderResult<DebugConfiguration[]> -
-

Provides debug configuration to the debug service. If more than one debug configuration provider is -registered for the same type, debug configurations are concatenated in arbitrary order.

-
-
- - - - - - -
ParameterDescription
folder: WorkspaceFolder | undefined

The workspace folder for which the configurations are used or undefined for a folderless setup.

-
token?: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<DebugConfiguration[]>

An array of debug configurations.

-
-
-
- - - -resolveDebugConfiguration(folder: WorkspaceFolder | undefined, debugConfiguration: DebugConfiguration, token?: CancellationToken): ProviderResult<DebugConfiguration> -
-

Resolves a debug configuration by filling in missing values or by adding/changing/removing attributes. -If more than one debug configuration provider is registered for the same type, the resolveDebugConfiguration calls are chained -in arbitrary order and the initial debug configuration is piped through the chain. -Returning the value 'undefined' prevents the debug session from starting. -Returning the value 'null' prevents the debug session from starting and opens the underlying debug configuration instead.

-
-
- - - - - - - -
ParameterDescription
folder: WorkspaceFolder | undefined

The workspace folder from which the configuration originates from or undefined for a folderless setup.

-
debugConfiguration: DebugConfiguration

The debug configuration to resolve.

-
token?: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<DebugConfiguration>

The resolved debug configuration or undefined or null.

-
-
-
- - - -resolveDebugConfigurationWithSubstitutedVariables(folder: WorkspaceFolder | undefined, debugConfiguration: DebugConfiguration, token?: CancellationToken): ProviderResult<DebugConfiguration> -
-

This hook is directly called after 'resolveDebugConfiguration' but with all variables substituted. -It can be used to resolve or verify a debug configuration by filling in missing values or by adding/changing/removing attributes. -If more than one debug configuration provider is registered for the same type, the 'resolveDebugConfigurationWithSubstitutedVariables' calls are chained -in arbitrary order and the initial debug configuration is piped through the chain. -Returning the value 'undefined' prevents the debug session from starting. -Returning the value 'null' prevents the debug session from starting and opens the underlying debug configuration instead.

-
-
- - - - - - - -
ParameterDescription
folder: WorkspaceFolder | undefined

The workspace folder from which the configuration originates from or undefined for a folderless setup.

-
debugConfiguration: DebugConfiguration

The debug configuration to resolve.

-
token?: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<DebugConfiguration>

The resolved debug configuration or undefined or null.

-
-
-
- -### DebugConfigurationProviderTriggerKind - - - -

A DebugConfigurationProviderTriggerKind specifies when the provideDebugConfigurations method of a DebugConfigurationProvider is triggered. -Currently there are two situations: to provide the initial debug configurations for a newly created launch.json or -to provide dynamically generated debug configurations when the user asks for them through the UI (e.g. via the "Select and Start Debugging" command). -A trigger kind is used when registering a DebugConfigurationProvider with #debug.registerDebugConfigurationProvider.

-
- -#### Enumeration members - - - -Dynamic -
-2 -
- - - -Initial -
-1 -
- -### DebugConsole - - - -

Represents the debug console.

-
- -#### Methods - - - -append(value: string): void -
-

Append the given value to the debug console.

-
-
- - - - - -
ParameterDescription
value: string

A string, falsy values will not be printed.

-
ReturnsDescription
void
-
-
- - - -appendLine(value: string): void -
-

Append the given value and a line feed character -to the debug console.

-
-
- - - - - -
ParameterDescription
value: string

A string, falsy values will be printed.

-
ReturnsDescription
void
-
-
- -### DebugConsoleMode - - - -

Debug console mode used by debug session, see options.

-
- -#### Enumeration members - - - -MergeWithParent -
-1 -
- - - -Separate -
-0 -
- -### DebugProtocolBreakpoint - - - -

A DebugProtocolBreakpoint is an opaque stand-in type for the Breakpoint type defined in the Debug Adapter Protocol.

-
- -### DebugProtocolMessage - - - -

A DebugProtocolMessage is an opaque stand-in type for the ProtocolMessage type defined in the Debug Adapter Protocol.

-
- -### DebugProtocolSource - - - -

A DebugProtocolSource is an opaque stand-in type for the Source type defined in the Debug Adapter Protocol.

-
- -### DebugSession - - - -

A debug session.

-
- -#### Properties - - - -configuration: DebugConfiguration -
-

The "resolved" debug configuration of this session. -"Resolved" means that

-
    -
  • all variables have been substituted and
    • -
  • platform specific attribute sections have been "flattened" for the matching platform and removed for non-matching platforms.
    • -
-
-
- - - -id: string -
-

The unique ID of this debug session.

-
-
- - - -name: string -
-

The debug session's name is initially taken from the debug configuration. -Any changes will be properly reflected in the UI.

-
-
- - - -type: string -
-

The debug session's type from the debug configuration.

-
-
- - - -workspaceFolder: WorkspaceFolder | undefined -
-

The workspace folder of this session or undefined for a folderless setup.

-
-
- -#### Methods - - - -customRequest(command: string, args?: any): Thenable<any> -
-

Send a custom request to the debug adapter.

-
-
- - - - - - -
ParameterDescription
command: string
args?: any
ReturnsDescription
Thenable<any>
-
-
- - - -getDebugProtocolBreakpoint(breakpoint: Breakpoint): Thenable<DebugProtocolBreakpoint | undefined> -
-

Maps a VS Code breakpoint to the corresponding Debug Adapter Protocol (DAP) breakpoint that is managed by the debug adapter of the debug session. -If no DAP breakpoint exists (either because the VS Code breakpoint was not yet registered or because the debug adapter is not interested in the breakpoint), the value undefined is returned.

-
-
- - - - - -
ParameterDescription
breakpoint: Breakpoint

A VS Code breakpoint.

-
ReturnsDescription
Thenable<DebugProtocolBreakpoint | undefined>

A promise that resolves to the Debug Adapter Protocol breakpoint or undefined.

-
-
-
- -### DebugSessionCustomEvent - - - -

A custom Debug Adapter Protocol event received from a debug session.

-
- -#### Properties - - - -body?: any -
-

Event specific information.

-
-
- - - -event: string -
-

Type of event.

-
-
- - - -session: DebugSession -
-

The debug session for which the custom event was received.

-
-
- -### DebugSessionOptions - - - -

Options for starting a debug session.

-
- -#### Properties - - - -compact?: boolean -
-

Controls if the debug session's parent session is shown in the CALL STACK view even if it has only a single child. -By default, the debug session will never hide its parent. -If compact is true, debug sessions with a single child are hidden in the CALL STACK view to make the tree more compact.

-
-
- - - -consoleMode?: DebugConsoleMode -
-

Controls whether this session should have a separate debug console or share it -with the parent session. Has no effect for sessions which do not have a parent session. -Defaults to Separate.

-
-
- - - -noDebug?: boolean -
-

Controls whether this session should run without debugging, thus ignoring breakpoints. -When this property is not specified, the value from the parent session (if there is one) is used.

-
-
- - - -parentSession?: DebugSession -
-

When specified the newly created debug session is registered as a "child" session of this -"parent" debug session.

-
-
- -### Declaration - - - -

The declaration of a symbol representation as one or many locations -or location links.

-
- - - -Declaration: Location | Location[] | LocationLink[] - -### DeclarationProvider - - - -

The declaration provider interface defines the contract between extensions and -the go to declaration feature.

-
- -#### Methods - - - -provideDeclaration(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<Declaration> -
-

Provide the declaration of the symbol at the given position and document.

-
-
- - - - - - - -
ParameterDescription
document: TextDocument

The document in which the command was invoked.

-
position: Position

The position at which the command was invoked.

-
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<Declaration>

A declaration or a thenable that resolves to such. The lack of a result can be -signaled by returning undefined or null.

-
-
-
- -### DecorationInstanceRenderOptions - - - -
- -#### Properties - - - -after?: ThemableDecorationAttachmentRenderOptions -
-

Defines the rendering options of the attachment that is inserted after the decorated text.

-
-
- - - -before?: ThemableDecorationAttachmentRenderOptions -
-

Defines the rendering options of the attachment that is inserted before the decorated text.

-
-
- - - -dark?: ThemableDecorationInstanceRenderOptions -
-

Overwrite options for dark themes.

-
-
- - - -light?: ThemableDecorationInstanceRenderOptions -
-

Overwrite options for light themes.

-
-
- -### DecorationOptions - - - -

Represents options for a specific decoration in a decoration set.

-
- -#### Properties - - - -hoverMessage?: MarkedString | MarkedString[] -
-

A message that should be rendered when hovering over the decoration.

-
-
- - - -range: Range -
-

Range to which this decoration is applied. The range must not be empty.

-
-
- - - -renderOptions?: DecorationInstanceRenderOptions -
-

Render options applied to the current decoration. For performance reasons, keep the -number of decoration specific options small, and use decoration types wherever possible.

-
-
- -### DecorationRangeBehavior - - - -

Describes the behavior of decorations when typing/editing at their edges.

-
- -#### Enumeration members - - - -ClosedClosed -
-1 -
- - - -ClosedOpen -
-3 -
- - - -OpenClosed -
-2 -
- - - -OpenOpen -
-0 -
- -### DecorationRenderOptions - - - -

Represents rendering styles for a text editor decoration.

-
- -#### Properties - - - -after?: ThemableDecorationAttachmentRenderOptions -
-

Defines the rendering options of the attachment that is inserted after the decorated text.

-
-
- - - -backgroundColor?: string | ThemeColor -
-

Background color of the decoration. Use rgba() and define transparent background colors to play well with other decorations. -Alternatively a color from the color registry can be referenced.

-
-
- - - -before?: ThemableDecorationAttachmentRenderOptions -
-

Defines the rendering options of the attachment that is inserted before the decorated text.

-
-
- - - -border?: string -
-

CSS styling property that will be applied to text enclosed by a decoration.

-
-
- - - -borderColor?: string | ThemeColor -
-

CSS styling property that will be applied to text enclosed by a decoration. -Better use 'border' for setting one or more of the individual border properties.

-
-
- - - -borderRadius?: string -
-

CSS styling property that will be applied to text enclosed by a decoration. -Better use 'border' for setting one or more of the individual border properties.

-
-
- - - -borderSpacing?: string -
-

CSS styling property that will be applied to text enclosed by a decoration. -Better use 'border' for setting one or more of the individual border properties.

-
-
- - - -borderStyle?: string -
-

CSS styling property that will be applied to text enclosed by a decoration. -Better use 'border' for setting one or more of the individual border properties.

-
-
- - - -borderWidth?: string -
-

CSS styling property that will be applied to text enclosed by a decoration. -Better use 'border' for setting one or more of the individual border properties.

-
-
- - - -color?: string | ThemeColor -
-

CSS styling property that will be applied to text enclosed by a decoration.

-
-
- - - -cursor?: string -
-

CSS styling property that will be applied to text enclosed by a decoration.

-
-
- - - -dark?: ThemableDecorationRenderOptions -
-

Overwrite options for dark themes.

-
-
- - - -fontStyle?: string -
-

CSS styling property that will be applied to text enclosed by a decoration.

-
-
- - - -fontWeight?: string -
-

CSS styling property that will be applied to text enclosed by a decoration.

-
-
- - - -gutterIconPath?: string | Uri -
-

An absolute path or an URI to an image to be rendered in the gutter.

-
-
- - - -gutterIconSize?: string -
-

Specifies the size of the gutter icon. -Available values are 'auto', 'contain', 'cover' and any percentage value. -For further information: https://msdn.microsoft.com/en-us/library/jj127316(v=vs.85).aspx

-
-
- - - -isWholeLine?: boolean -
-

Should the decoration be rendered also on the whitespace after the line text. -Defaults to false.

-
-
- - - -letterSpacing?: string -
-

CSS styling property that will be applied to text enclosed by a decoration.

-
-
- - - -light?: ThemableDecorationRenderOptions -
-

Overwrite options for light themes.

-
-
- - - -opacity?: string -
-

CSS styling property that will be applied to text enclosed by a decoration.

-
-
- - - -outline?: string -
-

CSS styling property that will be applied to text enclosed by a decoration.

-
-
- - - -outlineColor?: string | ThemeColor -
-

CSS styling property that will be applied to text enclosed by a decoration. -Better use 'outline' for setting one or more of the individual outline properties.

-
-
- - - -outlineStyle?: string -
-

CSS styling property that will be applied to text enclosed by a decoration. -Better use 'outline' for setting one or more of the individual outline properties.

-
-
- - - -outlineWidth?: string -
-

CSS styling property that will be applied to text enclosed by a decoration. -Better use 'outline' for setting one or more of the individual outline properties.

-
-
- - - -overviewRulerColor?: string | ThemeColor -
-

The color of the decoration in the overview ruler. Use rgba() and define transparent colors to play well with other decorations.

-
-
- - - -overviewRulerLane?: OverviewRulerLane -
-

The position in the overview ruler where the decoration should be rendered.

-
-
- - - -rangeBehavior?: DecorationRangeBehavior -
-

Customize the growing behavior of the decoration when edits occur at the edges of the decoration's range. -Defaults to DecorationRangeBehavior.OpenOpen.

-
-
- - - -textDecoration?: string -
-

CSS styling property that will be applied to text enclosed by a decoration.

-
-
- -### Definition - - - -

The definition of a symbol represented as one or many locations. -For most programming languages there is only one location at which a symbol is -defined.

-
- - - -Definition: Location | Location[] - -### DefinitionLink - - - -

Information about where a symbol is defined.

-

Provides additional metadata over normal location definitions, including the range of -the defining symbol

-
- - - -DefinitionLink: LocationLink - -### DefinitionProvider - - - -

The definition provider interface defines the contract between extensions and -the go to definition -and peek definition features.

-
- -#### Methods - - - -provideDefinition(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<Definition | DefinitionLink[]> -
-

Provide the definition of the symbol at the given position and document.

-
-
- - - - - - - -
ParameterDescription
document: TextDocument

The document in which the command was invoked.

-
position: Position

The position at which the command was invoked.

-
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<Definition | DefinitionLink[]>

A definition or a thenable that resolves to such. The lack of a result can be -signaled by returning undefined or null.

-
-
-
- -### Diagnostic - - - -

Represents a diagnostic, such as a compiler error or warning. Diagnostic objects -are only valid in the scope of a file.

-
- -#### Constructors - - - -new Diagnostic(range: Range, message: string, severity?: DiagnosticSeverity): Diagnostic -
-

Creates a new diagnostic object.

-
-
- - - - - - - -
ParameterDescription
range: Range

The range to which this diagnostic applies.

-
message: string

The human-readable message.

-
severity?: DiagnosticSeverity

The severity, default is error.

-
ReturnsDescription
Diagnostic
-
-
- -#### Properties - - - -code?: string | number | {target: Uri, value: string | number} -
-

A code or identifier for this diagnostic. -Should be used for later processing, e.g. when providing code actions.

-
-
- - - -message: string -
-

The human-readable message.

-
-
- - - -range: Range -
-

The range to which this diagnostic applies.

-
-
- - - -relatedInformation?: DiagnosticRelatedInformation[] -
-

An array of related diagnostic information, e.g. when symbol-names within -a scope collide all definitions can be marked via this property.

-
-
- - - -severity: DiagnosticSeverity -
-

The severity, default is error.

-
-
- - - -source?: string -
-

A human-readable string describing the source of this -diagnostic, e.g. 'typescript' or 'super lint'.

-
-
- - - -tags?: DiagnosticTag[] -
-

Additional metadata about the diagnostic.

-
-
- -### DiagnosticChangeEvent - - - -

The event that is fired when diagnostics change.

-
- -#### Properties - - - -uris: ReadonlyArray<Uri> -
-

An array of resources for which diagnostics have changed.

-
-
- -### DiagnosticCollection - - - -

A diagnostics collection is a container that manages a set of -diagnostics. Diagnostics are always scopes to a -diagnostics collection and a resource.

-

To get an instance of a DiagnosticCollection use -createDiagnosticCollection.

-
- -#### Properties - - - -name: string -
-

The name of this diagnostic collection, for instance typescript. Every diagnostic -from this collection will be associated with this name. Also, the task framework uses this -name when defining problem matchers.

-
-
- -#### Methods - - - -clear(): void -
-

Remove all diagnostics from this collection. The same -as calling #set(undefined);

-
-
- - - -
ReturnsDescription
void
-
-
- - - -delete(uri: Uri): void -
-

Remove all diagnostics from this collection that belong -to the provided uri. The same as #set(uri, undefined).

-
-
- - - - - -
ParameterDescription
uri: Uri

A resource identifier.

-
ReturnsDescription
void
-
-
- - - -dispose(): void -
-

Dispose and free associated resources. Calls -clear.

-
-
- - - -
ReturnsDescription
void
-
-
- - - -forEach(callback: (uri: Uri, diagnostics: ReadonlyArray<Diagnostic>, collection: DiagnosticCollection) => any, thisArg?: any): void -
-

Iterate over each entry in this collection.

-
-
- - - - - - -
ParameterDescription
callback: (uri: Uri, diagnostics: ReadonlyArray<Diagnostic>, collection: DiagnosticCollection) => any

Function to execute for each entry.

-
thisArg?: any

The this context used when invoking the handler function.

-
ReturnsDescription
void
-
-
- - - -get(uri: Uri): ReadonlyArray<Diagnostic> | undefined -
-

Get the diagnostics for a given resource. Note that you cannot -modify the diagnostics-array returned from this call.

-
-
- - - - - -
ParameterDescription
uri: Uri

A resource identifier.

-
ReturnsDescription
ReadonlyArray<Diagnostic> | undefined

An immutable array of diagnostics or undefined.

-
-
-
- - - -has(uri: Uri): boolean -
-

Check if this collection contains diagnostics for a -given resource.

-
-
- - - - - -
ParameterDescription
uri: Uri

A resource identifier.

-
ReturnsDescription
boolean

true if this collection has diagnostic for the given resource.

-
-
-
- - - -set(uri: Uri, diagnostics: ReadonlyArray<Diagnostic> | undefined): void -
-

Assign diagnostics for given resource. Will replace -existing diagnostics for that resource.

-
-
- - - - - - -
ParameterDescription
uri: Uri

A resource identifier.

-
diagnostics: ReadonlyArray<Diagnostic> | undefined

Array of diagnostics or undefined

-
ReturnsDescription
void
-
-
- - - -set(entries: ReadonlyArray<[Uri, ReadonlyArray<Diagnostic> | undefined]>): void -
-

Replace all entries in this collection.

-

Diagnostics of multiple tuples of the same uri will be merged, e.g -[[file1, [d1]], [file1, [d2]]] is equivalent to [[file1, [d1, d2]]]. -If a diagnostics item is undefined as in [file1, undefined] -all previous but not subsequent diagnostics are removed.

-
-
- - - - - -
ParameterDescription
entries: ReadonlyArray<[Uri, ReadonlyArray<Diagnostic> | undefined]>

An array of tuples, like [[file1, [d1, d2]], [file2, [d3, d4, d5]]], or undefined.

-
ReturnsDescription
void
-
-
- -### DiagnosticRelatedInformation - - - -

Represents a related message and source code location for a diagnostic. This should be -used to point to code locations that cause or related to a diagnostics, e.g. when duplicating -a symbol in a scope.

-
- -#### Constructors - - - -new DiagnosticRelatedInformation(location: Location, message: string): DiagnosticRelatedInformation -
-

Creates a new related diagnostic information object.

-
-
- - - - - - -
ParameterDescription
location: Location

The location.

-
message: string

The message.

-
ReturnsDescription
DiagnosticRelatedInformation
-
-
- -#### Properties - - - -location: Location -
-

The location of this related diagnostic information.

-
-
- - - -message: string -
-

The message of this related diagnostic information.

-
-
- -### DiagnosticSeverity - - - -

Represents the severity of diagnostics.

-
- -#### Enumeration members - - - -Error -
-0 -
- - - -Hint -
-3 -
- - - -Information -
-2 -
- - - -Warning -
-1 -
- -### DiagnosticTag - - - -

Additional metadata about the type of a diagnostic.

-
- -#### Enumeration members - - - -Deprecated -
-2 -
- - - -Unnecessary -
-1 -
- -### Disposable - - - -

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

-
- -#### Static - - - -from(...disposableLikes: {dispose: () => any}[]): Disposable -
-

Combine many disposable-likes into one. Use this method -when having objects with a dispose function which are not -instances of Disposable.

-
-
- - - - - -
ParameterDescription
...disposableLikes: {dispose: () => any}[]

Objects that have at least a dispose-function member.

-
ReturnsDescription
Disposable

Returns a new disposable which, upon dispose, will -dispose all provided disposables.

-
-
-
- -#### Constructors - - - -new Disposable(callOnDispose: Function): Disposable -
-

Creates a new Disposable calling the provided function -on dispose.

-
-
- - - - - -
ParameterDescription
callOnDispose: Function

Function that disposes something.

-
ReturnsDescription
Disposable
-
-
- -#### Methods - - - -dispose(): any -
-

Dispose this object.

-
-
- - - -
ReturnsDescription
any
-
-
- -### DocumentColorProvider - - - -

The document color provider defines the contract between extensions and feature of -picking and modifying colors in the editor.

-
- -#### Methods - - - -provideColorPresentations(color: Color, context: {document: TextDocument, range: Range}, token: CancellationToken): ProviderResult<ColorPresentation[]> -
-

Provide representations for a color.

-
-
- - - - - - - -
ParameterDescription
color: Color

The color to show and insert.

-
context: {document: TextDocument, range: Range}

A context object with additional information

-
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<ColorPresentation[]>

An array of color presentations or a thenable that resolves to such. The lack of a result -can be signaled by returning undefined, null, or an empty array.

-
-
-
- - - -provideDocumentColors(document: TextDocument, token: CancellationToken): ProviderResult<ColorInformation[]> -
-

Provide colors for the given document.

-
-
- - - - - - -
ParameterDescription
document: TextDocument

The document in which the command was invoked.

-
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<ColorInformation[]>

An array of color information or a thenable that resolves to such. The lack of a result -can be signaled by returning undefined, null, or an empty array.

-
-
-
- -### DocumentFilter - - - -

A document filter denotes a document by different properties like -the language, the scheme of -its resource, or a glob-pattern that is applied to the path.

- - -
- -#### Properties - - - -language?: string -
-

A language ID, like typescript.

-
-
- - - -pattern?: GlobPattern -
-

A glob pattern that is matched on the absolute path of the document. Use a relative pattern -to filter documents to a workspace folder.

-
-
- - - -scheme?: string -
-

A Uri scheme, like file or untitled.

-
-
- -### DocumentFormattingEditProvider - - - -

The document formatting provider interface defines the contract between extensions and -the formatting-feature.

-
- -#### Methods - - - -provideDocumentFormattingEdits(document: TextDocument, options: FormattingOptions, token: CancellationToken): ProviderResult<TextEdit[]> -
-

Provide formatting edits for a whole document.

-
-
- - - - - - - -
ParameterDescription
document: TextDocument

The document in which the command was invoked.

-
options: FormattingOptions

Options controlling formatting.

-
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<TextEdit[]>

A set of text edits or a thenable that resolves to such. The lack of a result can be -signaled by returning undefined, null, or an empty array.

-
-
-
- -### DocumentHighlight - - - -

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

-
- -#### Constructors - - - -new DocumentHighlight(range: Range, kind?: DocumentHighlightKind): DocumentHighlight -
-

Creates a new document highlight object.

-
-
- - - - - - -
ParameterDescription
range: Range

The range the highlight applies to.

-
kind?: DocumentHighlightKind

The highlight kind, default is text.

-
ReturnsDescription
DocumentHighlight
-
-
- -#### Properties - - - -kind?: DocumentHighlightKind -
-

The highlight kind, default is text.

-
-
- - - -range: Range -
-

The range this highlight applies to.

-
-
- -### DocumentHighlightKind - - - -

A document highlight kind.

-
- -#### Enumeration members - - - -Read -
-1 -
- - - -Text -
-0 -
- - - -Write -
-2 -
- -### DocumentHighlightProvider - - - -

The document highlight provider interface defines the contract between extensions and -the word-highlight-feature.

-
- -#### Methods - - - -provideDocumentHighlights(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<DocumentHighlight[]> -
-

Provide a set of document highlights, like all occurrences of a variable or -all exit-points of a function.

-
-
- - - - - - - -
ParameterDescription
document: TextDocument

The document in which the command was invoked.

-
position: Position

The position at which the command was invoked.

-
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<DocumentHighlight[]>

An array of document highlights or a thenable that resolves to such. The lack of a result can be -signaled by returning undefined, null, or an empty array.

-
-
-
- -### DocumentLink - - - -

A document link is a range in a text document that links to an internal or external resource, like another -text document or a web site.

-
- -#### Constructors - - - -new DocumentLink(range: Range, target?: Uri): DocumentLink -
-

Creates a new document link.

-
-
- - - - - - -
ParameterDescription
range: Range

The range the document link applies to. Must not be empty.

-
target?: Uri

The uri the document link points to.

-
ReturnsDescription
DocumentLink
-
-
- -#### Properties - - - -range: Range -
-

The range this link applies to.

-
-
- - - -target?: Uri -
-

The uri this link points to.

-
-
- - - -tooltip?: string -
-

The tooltip text when you hover over this link.

-

If a tooltip is provided, is will be displayed in a string that includes instructions on how to -trigger the link, such as {0} (ctrl + click). The specific instructions vary depending on OS, -user settings, and localization.

-
-
- -### DocumentLinkProvider<T> - - - -

The document link provider defines the contract between extensions and feature of showing -links in the editor.

-
- -#### Methods - - - -provideDocumentLinks(document: TextDocument, token: CancellationToken): ProviderResult<T[]> -
-

Provide links for the given document. Note that the editor ships with a default provider that detects -http(s) and file links.

-
-
- - - - - - -
ParameterDescription
document: TextDocument

The document in which the command was invoked.

-
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<T[]>

An array of document links or a thenable that resolves to such. The lack of a result -can be signaled by returning undefined, null, or an empty array.

-
-
-
- - - -resolveDocumentLink(link: T, token: CancellationToken): ProviderResult<T> -
-

Given a link fill in its target. This method is called when an incomplete -link is selected in the UI. Providers can implement this method and return incomplete links -(without target) from the provideDocumentLinks method which -often helps to improve performance.

-
-
- - - - - - -
ParameterDescription
link: T

The link that is to be resolved.

-
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<T>
-
-
- -### DocumentRangeFormattingEditProvider - - - -

The document formatting provider interface defines the contract between extensions and -the formatting-feature.

-
- -#### Methods - - - -provideDocumentRangeFormattingEdits(document: TextDocument, range: Range, options: FormattingOptions, token: CancellationToken): ProviderResult<TextEdit[]> -
-

Provide formatting edits for a range in a document.

-

The given range is a hint and providers can decide to format a smaller -or larger range. Often this is done by adjusting the start and end -of the range to full syntax nodes.

-
-
- - - - - - - - -
ParameterDescription
document: TextDocument

The document in which the command was invoked.

-
range: Range

The range which should be formatted.

-
options: FormattingOptions

Options controlling formatting.

-
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<TextEdit[]>

A set of text edits or a thenable that resolves to such. The lack of a result can be -signaled by returning undefined, null, or an empty array.

-
-
-
- -### DocumentRangeSemanticTokensProvider - - - -

The document range semantic tokens provider interface defines the contract between extensions and -semantic tokens.

-
- -#### Methods - - - -provideDocumentRangeSemanticTokens(document: TextDocument, range: Range, token: CancellationToken): ProviderResult<SemanticTokens> -
-
-
-
- - - - - - - -
ParameterDescription
document: TextDocument
range: Range
token: CancellationToken
ReturnsDescription
ProviderResult<SemanticTokens>
-
-
- -### DocumentSelector - - - -

A language selector is the combination of one or many language identifiers -and language filters.

-

Note that a document selector that is just a language identifier selects all -documents, even those that are not saved on disk. Only use such selectors when -a feature works without further context, e.g. without the need to resolve related -'files'.

- -
- - - -DocumentSelector: DocumentFilter | string | ReadonlyArray<DocumentFilter | string> - -### DocumentSemanticTokensProvider - - - -

The document semantic tokens provider interface defines the contract between extensions and -semantic tokens.

-
- -#### Events - - - -onDidChangeSemanticTokens?: Event<void> -
-

An optional event to signal that the semantic tokens from this provider have changed.

-
-
- -#### Methods - - - -provideDocumentSemanticTokens(document: TextDocument, token: CancellationToken): ProviderResult<SemanticTokens> -
-

Tokens in a file are represented as an array of integers. The position of each token is expressed relative to -the token before it, because most tokens remain stable relative to each other when edits are made in a file.

-
-

In short, each token takes 5 integers to represent, so a specific token i in the file consists of the following array indices:

-
    -
  • at index 5*i - deltaLine: token line number, relative to the previous token
    • -
  • at index 5*i+1 - deltaStart: token start character, relative to the previous token (relative to 0 or the previous token's start if they are on the same line)
    • -
  • at index 5*i+2 - length: the length of the token. A token cannot be multiline.
    • -
  • at index 5*i+3 - tokenType: will be looked up in SemanticTokensLegend.tokenTypes. We currently ask that tokenType < 65536.
    • -
  • at index 5*i+4 - tokenModifiers: each set bit will be looked up in SemanticTokensLegend.tokenModifiers
    • -
-
-

How to encode tokens

-

Here is an example for encoding a file with 3 tokens in a uint32 array:

- -
   { line: 2, startChar:  5, length: 3, tokenType: "property",  tokenModifiers: ["private", "static"] },
-   { line: 2, startChar: 10, length: 4, tokenType: "type",      tokenModifiers: [] },
-   { line: 5, startChar:  2, length: 7, tokenType: "class",     tokenModifiers: [] }
-
    -

  1. First of all, a legend must be devised. This legend must be provided up-front and capture all possible token types. -For this example, we will choose the following legend which must be passed in when registering the provider:

    - -
    tokenTypes: ['property', 'type', 'class'],
-tokenModifiers: ['private', 'static']
-
    2. -

  2. The first transformation step is to encode tokenType and tokenModifiers as integers using the legend. Token types are looked -up by index, so a tokenType value of 1 means tokenTypes[1]. Multiple token modifiers can be set by using bit flags, -so a tokenModifier value of 3 is first viewed as binary 0b00000011, which means [tokenModifiers[0], tokenModifiers[1]] because -bits 0 and 1 are set. Using this legend, the tokens now are:

    - -
    { line: 2, startChar:  5, length: 3, tokenType: 0, tokenModifiers: 3 },
-{ line: 2, startChar: 10, length: 4, tokenType: 1, tokenModifiers: 0 },
-{ line: 5, startChar:  2, length: 7, tokenType: 2, tokenModifiers: 0 }
-
    3. -

  3. The next step is to represent each token relative to the previous token in the file. In this case, the second token -is on the same line as the first token, so the startChar of the second token is made relative to the startChar -of the first token, so it will be 10 - 5. The third token is on a different line than the second token, so the -startChar of the third token will not be altered:

    - -
    { deltaLine: 2, deltaStartChar: 5, length: 3, tokenType: 0, tokenModifiers: 3 },
-{ deltaLine: 0, deltaStartChar: 5, length: 4, tokenType: 1, tokenModifiers: 0 },
-{ deltaLine: 3, deltaStartChar: 2, length: 7, tokenType: 2, tokenModifiers: 0 }
-
    4. -

  4. Finally, the last step is to inline each of the 5 fields for a token in a single array, which is a memory friendly representation:

    - -
    // 1st token,  2nd token,  3rd token
-[  2,5,3,0,3,  0,5,4,1,0,  3,2,7,2,0 ]
-
    5. -
-
    -
  • see - SemanticTokensBuilder for a helper to encode tokens as integers. -NOTE: When doing edits, it is possible that multiple edits occur until VS Code decides to invoke the semantic tokens provider. -NOTE: If the provider cannot temporarily compute semantic tokens, it can indicate this by throwing an error with the message 'Busy'.
    • -
-
-
- - - - - - -
ParameterDescription
document: TextDocument
token: CancellationToken
ReturnsDescription
ProviderResult<SemanticTokens>
-
-
- - - -provideDocumentSemanticTokensEdits(document: TextDocument, previousResultId: string, token: CancellationToken): ProviderResult<SemanticTokens | SemanticTokensEdits> -
-

Instead of always returning all the tokens in a file, it is possible for a DocumentSemanticTokensProvider to implement -this method (provideDocumentSemanticTokensEdits) and then return incremental updates to the previously provided semantic tokens.

-
-

How tokens change when the document changes

-

Suppose that provideDocumentSemanticTokens has previously returned the following semantic tokens:

- -
   // 1st token,  2nd token,  3rd token
-   [  2,5,3,0,3,  0,5,4,1,0,  3,2,7,2,0 ]
-

Also suppose that after some edits, the new semantic tokens in a file are:

- -
   // 1st token,  2nd token,  3rd token
-   [  3,5,3,0,3,  0,5,4,1,0,  3,2,7,2,0 ]
-

It is possible to express these new tokens in terms of an edit applied to the previous tokens:

- -
   [  2,5,3,0,3,  0,5,4,1,0,  3,2,7,2,0 ] // old tokens
-   [  3,5,3,0,3,  0,5,4,1,0,  3,2,7,2,0 ] // new tokens
-
-   edit: { start:  0, deleteCount: 1, data: [3] } // replace integer at offset 0 with 3
-

NOTE: If the provider cannot compute SemanticTokensEdits, it can "give up" and return all the tokens in the document again. -NOTE: All edits in SemanticTokensEdits contain indices in the old integers array, so they all refer to the previous result state.

-
-
- - - - - - - -
ParameterDescription
document: TextDocument
previousResultId: string
token: CancellationToken
ReturnsDescription
ProviderResult<SemanticTokens | SemanticTokensEdits>
-
-
- -### DocumentSymbol - - - -

Represents programming constructs like variables, classes, interfaces etc. that appear in a document. Document -symbols can be hierarchical and they have two ranges: one that encloses its definition and one that points to -its most interesting range, e.g. the range of an identifier.

-
- -#### Constructors - - - -new DocumentSymbol(name: string, detail: string, kind: SymbolKind, range: Range, selectionRange: Range): DocumentSymbol -
-

Creates a new document symbol.

-
-
- - - - - - - - - -
ParameterDescription
name: string

The name of the symbol.

-
detail: string

Details for the symbol.

-
kind: SymbolKind

The kind of the symbol.

-
range: Range

The full range of the symbol.

-
selectionRange: Range

The range that should be reveal.

-
ReturnsDescription
DocumentSymbol
-
-
- -#### Properties - - - -children: DocumentSymbol[] -
-

Children of this symbol, e.g. properties of a class.

-
-
- - - -detail: string -
-

More detail for this symbol, e.g. the signature of a function.

-
-
- - - -kind: SymbolKind -
-

The kind of this symbol.

-
-
- - - -name: string -
-

The name of this symbol.

-
-
- - - -range: Range -
-

The range enclosing this symbol not including leading/trailing whitespace but everything else, e.g. comments and code.

-
-
- - - -selectionRange: Range -
-

The range that should be selected and reveal when this symbol is being picked, e.g. the name of a function. -Must be contained by the range.

-
-
- - - -tags?: ReadonlyArray<SymbolTag> -
-

Tags for this symbol.

-
-
- -### DocumentSymbolProvider - - - -

The document symbol provider interface defines the contract between extensions and -the go to symbol-feature.

-
- -#### Methods - - - -provideDocumentSymbols(document: TextDocument, token: CancellationToken): ProviderResult<SymbolInformation[] | DocumentSymbol[]> -
-

Provide symbol information for the given document.

-
-
- - - - - - -
ParameterDescription
document: TextDocument

The document in which the command was invoked.

-
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<SymbolInformation[] | DocumentSymbol[]>

An array of document highlights or a thenable that resolves to such. The lack of a result can be -signaled by returning undefined, null, or an empty array.

-
-
-
- -### DocumentSymbolProviderMetadata - - - -

Metadata about a document symbol provider.

-
- -#### Properties - - - -label?: string -
-

A human-readable string that is shown when multiple outlines trees show for one document.

-
-
- -### EndOfLine - - - -

Represents an end of line character sequence in a document.

-
- -#### Enumeration members - - - -CRLF -
-2 -
- - - -LF -
-1 -
- -### EnterAction - - - -

Describes what to do when pressing Enter.

-
- -#### Properties - - - -appendText?: string -
-

Describes text to be appended after the new line and after the indentation.

-
-
- - - -indentAction: IndentAction -
-

Describe what to do with the indentation.

-
-
- - - -removeText?: number -
-

Describes the number of characters to remove from the new line's indentation.

-
-
- -### EnvironmentVariableCollection - - - -

A collection of mutations that an extension can apply to a process environment.

-
- -#### Properties - - - -persistent: boolean -
-

Whether the collection should be cached for the workspace and applied to the terminal -across window reloads. When true the collection will be active immediately such when the -window reloads. Additionally, this API will return the cached version if it exists. The -collection will be invalidated when the extension is uninstalled or when the collection -is cleared. Defaults to true.

-
-
- -#### Methods - - - -append(variable: string, value: string): void -
-

Append a value to an environment variable.

-

Note that an extension can only make a single change to any one variable, so this will -overwrite any previous calls to replace, append or prepend.

-
-
- - - - - - -
ParameterDescription
variable: string

The variable to append to.

-
value: string

The value to append to the variable.

-
ReturnsDescription
void
-
-
- - - -clear(): void -
-

Clears all mutators from this collection.

-
-
- - - -
ReturnsDescription
void
-
-
- - - -delete(variable: string): void -
-

Deletes this collection's mutator for a variable.

-
-
- - - - - -
ParameterDescription
variable: string

The variable to delete the mutator for.

-
ReturnsDescription
void
-
-
- - - -forEach(callback: (variable: string, mutator: EnvironmentVariableMutator, collection: EnvironmentVariableCollection) => any, thisArg?: any): void -
-

Iterate over each mutator in this collection.

-
-
- - - - - - -
ParameterDescription
callback: (variable: string, mutator: EnvironmentVariableMutator, collection: EnvironmentVariableCollection) => any

Function to execute for each entry.

-
thisArg?: any

The this context used when invoking the handler function.

-
ReturnsDescription
void
-
-
- - - -get(variable: string): EnvironmentVariableMutator | undefined -
-

Gets the mutator that this collection applies to a variable, if any.

-
-
- - - - - -
ParameterDescription
variable: string

The variable to get the mutator for.

-
ReturnsDescription
EnvironmentVariableMutator | undefined
-
-
- - - -prepend(variable: string, value: string): void -
-

Prepend a value to an environment variable.

-

Note that an extension can only make a single change to any one variable, so this will -overwrite any previous calls to replace, append or prepend.

-
-
- - - - - - -
ParameterDescription
variable: string

The variable to prepend.

-
value: string

The value to prepend to the variable.

-
ReturnsDescription
void
-
-
- - - -replace(variable: string, value: string): void -
-

Replace an environment variable with a value.

-

Note that an extension can only make a single change to any one variable, so this will -overwrite any previous calls to replace, append or prepend.

-
-
- - - - - - -
ParameterDescription
variable: string

The variable to replace.

-
value: string

The value to replace the variable with.

-
ReturnsDescription
void
-
-
- -### EnvironmentVariableMutator - - - -

A type of mutation and its value to be applied to an environment variable.

-
- -#### Properties - - - -type: EnvironmentVariableMutatorType -
-

The type of mutation that will occur to the variable.

-
-
- - - -value: string -
-

The value to use for the variable.

-
-
- -### EnvironmentVariableMutatorType - - - -

A type of mutation that can be applied to an environment variable.

-
- -#### Enumeration members - - - -Append -
-2 -
- - - -Prepend -
-3 -
- - - -Replace -
-1 -
- -### EvaluatableExpression - - - -

An EvaluatableExpression represents an expression in a document that can be evaluated by an active debugger or runtime. -The result of this evaluation is shown in a tooltip-like widget. -If only a range is specified, the expression will be extracted from the underlying document. -An optional expression can be used to override the extracted expression. -In this case the range is still used to highlight the range in the document.

-
- -#### Constructors - - - -new EvaluatableExpression(range: Range, expression?: string): EvaluatableExpression -
-

Creates a new evaluatable expression object.

-
-
- - - - - - -
ParameterDescription
range: Range

The range in the underlying document from which the evaluatable expression is extracted.

-
expression?: string

If specified overrides the extracted expression.

-
ReturnsDescription
EvaluatableExpression
-
-
- -#### Properties - - - -expression?: string -
-
-
- - - -range: Range -
-
-
- -### EvaluatableExpressionProvider - - - -

The evaluatable expression provider interface defines the contract between extensions and -the debug hover. In this contract the provider returns an evaluatable expression for a given position -in a document and VS Code evaluates this expression in the active debug session and shows the result in a debug hover.

-
- -#### Methods - - - -provideEvaluatableExpression(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<EvaluatableExpression> -
-

Provide an evaluatable expression for the given document and position. -VS Code will evaluate this expression in the active debug session and will show the result in the debug hover. -The expression can be implicitly specified by the range in the underlying document or by explicitly returning an expression.

-
-
- - - - - - - -
ParameterDescription
document: TextDocument

The document for which the debug hover is about to appear.

-
position: Position

The line and character position in the document where the debug hover is about to appear.

-
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<EvaluatableExpression>

An EvaluatableExpression or a thenable that resolves to such. The lack of a result can be -signaled by returning undefined or null.

-
-
-
- -### Event<T> - - - -

Represents a typed event.

-

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

- -
- - - -(listener: (e: T) => any, thisArgs?: any, disposables?: Disposable[]): Disposable -
-

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

-

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

-
-
- - - - - - - -
ParameterDescription
listener: (e: T) => any

The listener function will be called when the event happens.

-
thisArgs?: any

The this-argument which will be used when calling the event listener.

-
disposables?: Disposable[]

An array to which a disposable will be added.

-
ReturnsDescription
Disposable

A disposable which unsubscribes the event listener.

-
-
-
- -### EventEmitter<T> - - - -

An event emitter 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.

-
- -#### Properties - - - -event: Event<T> -
-

The event listeners can subscribe to.

-
-
- -#### Methods - - - -dispose(): void -
-

Dispose this object and free resources.

-
-
- - - -
ReturnsDescription
void
-
-
- - - -fire(data: T): void -
-

Notify all subscribers of the event. Failure -of one or more listener will not fail this function call.

-
-
- - - - - -
ParameterDescription
data: T

The event object.

-
ReturnsDescription
void
-
-
- -### Extension<T> - - - -

Represents an extension.

-

To get an instance of an Extension use getExtension.

-
- -#### Properties - - - -exports: T -
-

The public API exported by this extension. It is an invalid action -to access this field before this extension has been activated.

-
-
- - - -extensionKind: ExtensionKind -
-

The extension kind describes if an extension runs where the UI runs -or if an extension runs where the remote extension host runs. The extension kind -is defined in the package.json-file of extensions but can also be refined -via the remote.extensionKind-setting. When no remote extension host exists, -the value is ExtensionKind.UI.

-
-
- - - -extensionPath: string -
-

The absolute file path of the directory containing this extension. Shorthand -notation for Extension.extensionUri.fsPath (independent of the uri scheme).

-
-
- - - -extensionUri: Uri -
-

The uri of the directory containing the extension.

-
-
- - - -id: string -
-

The canonical extension identifier in the form of: publisher.name.

-
-
- - - -isActive: boolean -
-

true if the extension has been activated.

-
-
- - - -packageJSON: any -
-

The parsed contents of the extension's package.json.

-
-
- -#### Methods - - - -activate(): Thenable<T> -
-

Activates this extension and returns its public API.

-
-
- - - -
ReturnsDescription
Thenable<T>

A promise that will resolve when this extension has been activated.

-
-
-
- -### ExtensionContext - - - -

An extension context is a collection of utilities private to an -extension.

-

An instance of an ExtensionContext is provided as the first -parameter to the activate-call of an extension.

-
- -#### Properties - - - -environmentVariableCollection: EnvironmentVariableCollection -
-

Gets the extension's environment variable collection for this workspace, enabling changes -to be applied to terminal environment variables.

-
-
- - - -extensionMode: ExtensionMode -
-

The mode the extension is running in. This is specific to the current -extension. One extension may be in ExtensionMode.Development while -other extensions in the host run in ExtensionMode.Release.

-
-
- - - -extensionPath: string -
-

The absolute file path of the directory containing the extension. Shorthand -notation for ExtensionContext.extensionUri.fsPath (independent of the uri scheme).

-
-
- - - -extensionUri: Uri -
-

The uri of the directory containing the extension.

-
-
- - - -globalState: Memento & {setKeysForSync} -
-

A memento object that stores state independent -of the current opened workspace.

-
-
- - - -globalStoragePath: string -
-

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 to store key value data.

- -
-
- - - -globalStorageUri: Uri -
-

The uri of a directory 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 to store key value data.

-
    -
  • see - workspace.fs for how to read and write files and folders from -an uri.
    • -
-
-
- - - -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.

-
    -
  • deprecated - Use logUri instead.
    • -
-
-
- - - -logUri: Uri -
-

The uri 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.

-
    -
  • see - workspace.fs for how to read and write files and folders from -an uri.
    • -
-
-
- - - -storagePath: string | undefined -
-

An absolute file path of a workspace specific directory in which the extension -can store private 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 workspaceState or -globalState to store key value data.

- -
-
- - - -storageUri: Uri | undefined -
-

The uri of a workspace specific directory in which the extension -can store private state. The directory might not exist and creation is -up to the extension. However, the parent directory is guaranteed to be existent. -The value is undefined when no workspace nor folder has been opened.

-

Use workspaceState or -globalState to store key value data.

-
    -
  • see - workspace.fs for how to read and write files and folders from -an uri.
    • -
-
-
- - - -subscriptions: {dispose}[] -
-

An array to which disposables can be added. When this -extension is deactivated the disposables will be disposed.

-
-
- - - -workspaceState: Memento -
-

A memento object that stores state in the context -of the currently opened workspace.

-
-
- -#### Methods - - - -asAbsolutePath(relativePath: string): string -
-

Get the absolute path of a resource contained in the extension.

-

Note that an absolute uri can be constructed via Uri.joinPath and -extensionUri, e.g. vscode.Uri.joinPath(context.extensionUri, relativePath);

-
-
- - - - - -
ParameterDescription
relativePath: string

A relative path to a resource contained in the extension.

-
ReturnsDescription
string

The absolute path of the resource.

-
-
-
- -### ExtensionKind - - - -

In a remote window the extension kind describes if an extension -runs where the UI (window) runs or if an extension runs remotely.

-
- -#### Enumeration members - - - -UI -
-1 -
- - - -Workspace -
-2 -
- -### ExtensionMode - - - -

The ExtensionMode is provided on the ExtensionContext and indicates the -mode the specific extension is running in.

-
- -#### Enumeration members - - - -Development -
-2 -
- - - -Production -
-1 -
- - - -Test -
-3 -
- -### ExtensionTerminalOptions - - - -

Value-object describing what options a virtual process terminal should use.

-
- -#### Properties - - - -name: string -
-

A human-readable string which will be used to represent the terminal in the UI.

-
-
- - - -pty: Pseudoterminal -
-

An implementation of Pseudoterminal that allows an extension to -control a terminal.

-
-
- -### FileChangeEvent - - - -

The event filesystem providers must use to signal a file change.

-
- -#### Properties - - - -type: FileChangeType -
-

The type of change.

-
-
- - - -uri: Uri -
-

The uri of the file that has changed.

-
-
- -### FileChangeType - - - -

Enumeration of file change types.

-
- -#### Enumeration members - - - -Changed -
-1 -
- - - -Created -
-2 -
- - - -Deleted -
-3 -
- -### FileCreateEvent - - - -

An event that is fired after files are created.

-
- -#### Properties - - - -files: ReadonlyArray<Uri> -
-

The files that got created.

-
-
- -### FileDeleteEvent - - - -

An event that is fired after files are deleted.

-
- -#### Properties - - - -files: ReadonlyArray<Uri> -
-

The files that got deleted.

-
-
- -### FileRenameEvent - - - -

An event that is fired after files are renamed.

-
- -#### Properties - - - -files: ReadonlyArray<{newUri: Uri, oldUri: Uri}> -
-

The files that got renamed.

-
-
- -### FileStat - - - -

The FileStat-type represents metadata about a file

-
- -#### Properties - - - -ctime: number -
-

The creation timestamp in milliseconds elapsed since January 1, 1970 00:00:00 UTC.

-
-
- - - -mtime: number -
-

The modification timestamp in milliseconds elapsed since January 1, 1970 00:00:00 UTC.

-

Note: If the file changed, it is important to provide an updated mtime that advanced -from the previous value. Otherwise there may be optimizations in place that will not show -the updated file contents in an editor for example.

-
-
- - - -size: number -
-

The size in bytes.

-

Note: If the file changed, it is important to provide an updated size. Otherwise there -may be optimizations in place that will not show the updated file contents in an editor for -example.

-
-
- - - -type: FileType -
-

The type of the file, e.g. is a regular file, a directory, or symbolic link -to a file.

-

Note: This value might be a bitmask, e.g. FileType.File | FileType.SymbolicLink.

-
-
- -### 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.

-
- -#### Methods - - - -copy(source: Uri, target: Uri, options?: {overwrite: boolean}): Thenable<void> -
-

Copy files or folders.

-
-
- - - - - - - -
ParameterDescription
source: Uri

The existing file.

-
target: Uri
options?: {overwrite: boolean}

Defines if existing files should be overwritten.

-
ReturnsDescription
Thenable<void>
-
-
- - - -createDirectory(uri: Uri): Thenable<void> -
-

Create a new directory (Note, that new files are created via write-calls).

-

Note that missing directories are created automatically, e.g this call has -mkdirp semantics.

-
-
- - - - - -
ParameterDescription
uri: Uri

The uri of the new folder.

-
ReturnsDescription
Thenable<void>
-
-
- - - -delete(uri: Uri, options?: {recursive: boolean, useTrash: boolean}): Thenable<void> -
-

Delete a file.

-
-
- - - - - - -
ParameterDescription
uri: Uri

The resource that is to be deleted.

-
options?: {recursive: boolean, useTrash: boolean}

Defines if trash can should be used and if deletion of folders is recursive

-
ReturnsDescription
Thenable<void>
-
-
- - - -readDirectory(uri: Uri): Thenable<[string, FileType][]> -
-

Retrieve all entries of a directory.

-
-
- - - - - -
ParameterDescription
uri: Uri

The uri of the folder.

-
ReturnsDescription
Thenable<[string, FileType][]>

An array of name/type-tuples or a thenable that resolves to such.

-
-
-
- - - -readFile(uri: Uri): Thenable<Uint8Array> -
-

Read the entire contents of a file.

-
-
- - - - - -
ParameterDescription
uri: Uri

The uri of the file.

-
ReturnsDescription
Thenable<Uint8Array>

An array of bytes or a thenable that resolves to such.

-
-
-
- - - -rename(source: Uri, target: Uri, options?: {overwrite: boolean}): Thenable<void> -
-

Rename a file or folder.

-
-
- - - - - - - -
ParameterDescription
source: Uri
target: Uri
options?: {overwrite: boolean}

Defines if existing files should be overwritten.

-
ReturnsDescription
Thenable<void>
-
-
- - - -stat(uri: Uri): Thenable<FileStat> -
-

Retrieve metadata about a file.

-
-
- - - - - -
ParameterDescription
uri: Uri

The uri of the file to retrieve metadata about.

-
ReturnsDescription
Thenable<FileStat>

The file metadata about the file.

-
-
-
- - - -writeFile(uri: Uri, content: Uint8Array): Thenable<void> -
-

Write data to a file, replacing its entire contents.

-
-
- - - - - - -
ParameterDescription
uri: Uri

The uri of the file.

-
content: Uint8Array

The new content of the file.

-
ReturnsDescription
Thenable<void>
-
-
- -### FileSystemError - - - -

A type that filesystem providers should use to signal errors.

-

This class has factory methods for common error-cases, like FileNotFound when -a file or folder doesn't exist, use them like so: throw vscode.FileSystemError.FileNotFound(someUri);

-
- -#### Static - - - -Error: ErrorConstructor -
-
-
- - - -FileExists(messageOrUri?: string | Uri): FileSystemError -
-

Create an error to signal that a file or folder already exists, e.g. when -creating but not overwriting a file.

-
-
- - - - - -
ParameterDescription
messageOrUri?: string | Uri

Message or uri.

-
ReturnsDescription
FileSystemError
-
-
- - - -FileIsADirectory(messageOrUri?: string | Uri): FileSystemError -
-

Create an error to signal that a file is a folder.

-
-
- - - - - -
ParameterDescription
messageOrUri?: string | Uri

Message or uri.

-
ReturnsDescription
FileSystemError
-
-
- - - -FileNotADirectory(messageOrUri?: string | Uri): FileSystemError -
-

Create an error to signal that a file is not a folder.

-
-
- - - - - -
ParameterDescription
messageOrUri?: string | Uri

Message or uri.

-
ReturnsDescription
FileSystemError
-
-
- - - -FileNotFound(messageOrUri?: string | Uri): FileSystemError -
-

Create an error to signal that a file or folder wasn't found.

-
-
- - - - - -
ParameterDescription
messageOrUri?: string | Uri

Message or uri.

-
ReturnsDescription
FileSystemError
-
-
- - - -NoPermissions(messageOrUri?: string | Uri): FileSystemError -
-

Create an error to signal that an operation lacks required permissions.

-
-
- - - - - -
ParameterDescription
messageOrUri?: string | Uri

Message or uri.

-
ReturnsDescription
FileSystemError
-
-
- - - -Unavailable(messageOrUri?: string | Uri): FileSystemError -
-

Create an error to signal that the file system is unavailable or too busy to -complete a request.

-
-
- - - - - -
ParameterDescription
messageOrUri?: string | Uri

Message or uri.

-
ReturnsDescription
FileSystemError
-
-
- -#### Constructors - - - -new FileSystemError(messageOrUri?: string | Uri): FileSystemError -
-

Creates a new filesystem error.

-
-
- - - - - -
ParameterDescription
messageOrUri?: string | Uri

Message or uri.

-
ReturnsDescription
FileSystemError
-
-
- -#### Properties - - - -code: string -
-

A code that identifies this error.

-

Possible values are names of errors, like FileNotFound, -or Unknown for unspecified errors.

-
-
- - - -message: string -
-
-
- - - -name: string -
-
-
- - - -stack?: string -
-
-
- -### FileSystemProvider - - - -

The filesystem provider defines what the editor needs to read, write, discover, -and to manage files and folders. It allows extensions to serve files from remote places, -like ftp-servers, and to seamlessly integrate those into the editor.

- -
- -#### Events - - - -onDidChangeFile: Event<FileChangeEvent[]> -
-

An event to signal that a resource has been created, changed, or deleted. This -event should fire for resources that are being watched -by clients of this provider.

-

Note: It is important that the metadata of the file that changed provides an -updated mtime that advanced from the previous value in the stat and a -correct size value. Otherwise there may be optimizations in place that will not show -the change in an editor for example.

-
-
- -#### Methods - - - -copy(source: Uri, destination: Uri, options: {overwrite: boolean}): void | Thenable<void> -
-

Copy files or folders. Implementing this function is optional but it will speedup -the copy operation.

- -
    -
  • throws - FileNotFound when parent of destination doesn't exist, e.g. no mkdirp-logic required.
    • -
-
    -
  • throws - FileExists when destination exists and when the overwrite option is not true.
    • -
- -
-
- - - - - - - -
ParameterDescription
source: Uri

The existing file.

-
destination: Uri

The destination location.

-
options: {overwrite: boolean}

Defines if existing files should be overwritten.

-
ReturnsDescription
void | Thenable<void>
-
-
- - - -createDirectory(uri: Uri): void | Thenable<void> -
-

Create a new directory (Note, that new files are created via write-calls).

-
    -
  • throws - FileNotFound when the parent of uri doesn't exist, e.g. no mkdirp-logic required.
    • -
- - -
-
- - - - - -
ParameterDescription
uri: Uri

The uri of the new folder.

-
ReturnsDescription
void | Thenable<void>
-
-
- - - -delete(uri: Uri, options: {recursive: boolean}): void | Thenable<void> -
-

Delete a file.

- - -
-
- - - - - - -
ParameterDescription
uri: Uri

The resource that is to be deleted.

-
options: {recursive: boolean}

Defines if deletion of folders is recursive.

-
ReturnsDescription
void | Thenable<void>
-
-
- - - -readDirectory(uri: Uri): [string, FileType][] | Thenable<[string, FileType][]> -
-

Retrieve all entries of a directory.

- -
-
- - - - - -
ParameterDescription
uri: Uri

The uri of the folder.

-
ReturnsDescription
[string, FileType][] | Thenable<[string, FileType][]>

An array of name/type-tuples or a thenable that resolves to such.

-
-
-
- - - -readFile(uri: Uri): Uint8Array | Thenable<Uint8Array> -
-

Read the entire contents of a file.

- -
-
- - - - - -
ParameterDescription
uri: Uri

The uri of the file.

-
ReturnsDescription
Uint8Array | Thenable<Uint8Array>

An array of bytes or a thenable that resolves to such.

-
-
-
- - - -rename(oldUri: Uri, newUri: Uri, options: {overwrite: boolean}): void | Thenable<void> -
-

Rename a file or folder.

- -
    -
  • throws - FileNotFound when parent of newUri doesn't exist, e.g. no mkdirp-logic required.
    • -
-
    -
  • throws - FileExists when newUri exists and when the overwrite option is not true.
    • -
- -
-
- - - - - - - -
ParameterDescription
oldUri: Uri

The existing file.

-
newUri: Uri

The new location.

-
options: {overwrite: boolean}

Defines if existing files should be overwritten.

-
ReturnsDescription
void | Thenable<void>
-
-
- - - -stat(uri: Uri): FileStat | Thenable<FileStat> -
-

Retrieve metadata about a file.

-

Note that the metadata for symbolic links should be the metadata of the file they refer to. -Still, the SymbolicLink-type must be used in addition to the actual type, e.g. -FileType.SymbolicLink | FileType.Directory.

- -
-
- - - - - -
ParameterDescription
uri: Uri

The uri of the file to retrieve metadata about.

-
ReturnsDescription
FileStat | Thenable<FileStat>

The file metadata about the file.

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

Subscribe to events in the file or folder denoted by uri.

-

The editor will call this function for files and folders. In the latter case, the -options differ from defaults, e.g. what files/folders to exclude from watching -and if subfolders, sub-subfolder, etc. should be watched (recursive).

-
-
- - - - - - -
ParameterDescription
uri: Uri

The uri of the file to be watched.

-
options: {excludes: string[], recursive: boolean}

Configures the watch.

-
ReturnsDescription
Disposable

A disposable that tells the provider to stop watching the uri.

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

Write data to a file, replacing its entire contents.

-
    -
  • throws - FileNotFound when uri doesn't exist and create is not set.
    • -
-
    -
  • throws - FileNotFound when the parent of uri doesn't exist and create is set, e.g. no mkdirp-logic required.
    • -
-
    -
  • throws - FileExists when uri already exists, create is set but overwrite is not set.
    • -
- -
-
- - - - - - - -
ParameterDescription
uri: Uri

The uri of the file.

-
content: Uint8Array

The new content of the file.

-
options: {create: boolean, overwrite: boolean}

Defines if missing files should or must be created.

-
ReturnsDescription
void | Thenable<void>
-
-
- -### FileSystemWatcher - - - -

A file system watcher notifies about changes to files and folders -on disk or from other FileSystemProviders.

-

To get an instance of a FileSystemWatcher use -createFileSystemWatcher.

-
- -#### Events - - - -onDidChange: Event<Uri> -
-

An event which fires on file/folder change.

-
-
- - - -onDidCreate: Event<Uri> -
-

An event which fires on file/folder creation.

-
-
- - - -onDidDelete: Event<Uri> -
-

An event which fires on file/folder deletion.

-
-
- -#### Static - - - -from(...disposableLikes: {dispose: () => any}[]): Disposable -
-

Combine many disposable-likes into one. Use this method -when having objects with a dispose function which are not -instances of Disposable.

-
-
- - - - - -
ParameterDescription
...disposableLikes: {dispose: () => any}[]

Objects that have at least a dispose-function member.

-
ReturnsDescription
Disposable

Returns a new disposable which, upon dispose, will -dispose all provided disposables.

-
-
-
- -#### Constructors - - - -new FileSystemWatcher(callOnDispose: Function): FileSystemWatcher -
-

Creates a new Disposable calling the provided function -on dispose.

-
-
- - - - - -
ParameterDescription
callOnDispose: Function

Function that disposes something.

-
ReturnsDescription
FileSystemWatcher
-
-
- -#### Properties - - - -ignoreChangeEvents: boolean -
-

true if this file system watcher has been created such that -it ignores change file system events.

-
-
- - - -ignoreCreateEvents: boolean -
-

true if this file system watcher has been created such that -it ignores creation file system events.

-
-
- - - -ignoreDeleteEvents: boolean -
-

true if this file system watcher has been created such that -it ignores delete file system events.

-
-
- -#### Methods - - - -dispose(): any -
-

Dispose this object.

-
-
- - - -
ReturnsDescription
any
-
-
- -### 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.

-
- -#### Enumeration members - - - -Directory -
-2 -
- - - -File -
-1 -
- - - -SymbolicLink -
-64 -
- - - -Unknown -
-0 -
- -### FileWillCreateEvent - - - -

An event that is fired when files are going to be created.

-

To make modifications to the workspace before the files are created, -call the `waitUntil-function with a -thenable that resolves to a workspace edit.

-
- -#### Properties - - - -files: ReadonlyArray<Uri> -
-

The files that are going to be created.

-
-
- -#### Methods - - - -waitUntil(thenable: Thenable<WorkspaceEdit>): void -
-

Allows to pause the event and to apply a workspace edit.

-

Note: This function can only be called during event dispatch and not -in an asynchronous manner:

- -
workspace.onWillCreateFiles(event => {
-    // async, will *throw* an error
-    setTimeout(() => event.waitUntil(promise));
-
-    // sync, OK
-    event.waitUntil(promise);
-})
-
-
-
- - - - - -
ParameterDescription
thenable: Thenable<WorkspaceEdit>

A thenable that delays saving.

-
ReturnsDescription
void
-
-
- - - -waitUntil(thenable: Thenable<any>): void -
-

Allows to pause the event until the provided thenable resolves.

-

Note: This function can only be called during event dispatch.

-
-
- - - - - -
ParameterDescription
thenable: Thenable<any>

A thenable that delays saving.

-
ReturnsDescription
void
-
-
- -### FileWillDeleteEvent - - - -

An event that is fired when files are going to be deleted.

-

To make modifications to the workspace before the files are deleted, -call the `waitUntil-function with a -thenable that resolves to a workspace edit.

-
- -#### Properties - - - -files: ReadonlyArray<Uri> -
-

The files that are going to be deleted.

-
-
- -#### Methods - - - -waitUntil(thenable: Thenable<WorkspaceEdit>): void -
-

Allows to pause the event and to apply a workspace edit.

-

Note: This function can only be called during event dispatch and not -in an asynchronous manner:

- -
workspace.onWillCreateFiles(event => {
-    // async, will *throw* an error
-    setTimeout(() => event.waitUntil(promise));
-
-    // sync, OK
-    event.waitUntil(promise);
-})
-
-
-
- - - - - -
ParameterDescription
thenable: Thenable<WorkspaceEdit>

A thenable that delays saving.

-
ReturnsDescription
void
-
-
- - - -waitUntil(thenable: Thenable<any>): void -
-

Allows to pause the event until the provided thenable resolves.

-

Note: This function can only be called during event dispatch.

-
-
- - - - - -
ParameterDescription
thenable: Thenable<any>

A thenable that delays saving.

-
ReturnsDescription
void
-
-
- -### FileWillRenameEvent - - - -

An event that is fired when files are going to be renamed.

-

To make modifications to the workspace before the files are renamed, -call the `waitUntil-function with a -thenable that resolves to a workspace edit.

-
- -#### Properties - - - -files: ReadonlyArray<{newUri: Uri, oldUri: Uri}> -
-

The files that are going to be renamed.

-
-
- -#### Methods - - - -waitUntil(thenable: Thenable<WorkspaceEdit>): void -
-

Allows to pause the event and to apply a workspace edit.

-

Note: This function can only be called during event dispatch and not -in an asynchronous manner:

- -
workspace.onWillCreateFiles(event => {
-    // async, will *throw* an error
-    setTimeout(() => event.waitUntil(promise));
-
-    // sync, OK
-    event.waitUntil(promise);
-})
-
-
-
- - - - - -
ParameterDescription
thenable: Thenable<WorkspaceEdit>

A thenable that delays saving.

-
ReturnsDescription
void
-
-
- - - -waitUntil(thenable: Thenable<any>): void -
-

Allows to pause the event until the provided thenable resolves.

-

Note: This function can only be called during event dispatch.

-
-
- - - - - -
ParameterDescription
thenable: Thenable<any>

A thenable that delays saving.

-
ReturnsDescription
void
-
-
- -### FoldingContext - - - -

Folding context (for future use)

-
- -### FoldingRange - - - -

A line based folding range. To be valid, start and end line must be bigger than zero and smaller than the number of lines in the document. -Invalid ranges will be ignored.

-
- -#### Constructors - - - -new FoldingRange(start: number, end: number, kind?: FoldingRangeKind): FoldingRange -
-

Creates a new folding range.

-
-
- - - - - - - -
ParameterDescription
start: number

The start line of the folded range.

-
end: number

The end line of the folded range.

-
kind?: FoldingRangeKind

The kind of the folding range.

-
ReturnsDescription
FoldingRange
-
-
- -#### Properties - - - -end: number -
-

The zero-based end line of the range to fold. The folded area ends with the line's last character. -To be valid, the end must be zero or larger and smaller than the number of lines in the document.

-
-
- - - -kind?: FoldingRangeKind -
-

Describes the Kind of the folding range such as Comment or -Region. The kind is used to categorize folding ranges and used by commands -like 'Fold all comments'. See -FoldingRangeKind for an enumeration of all kinds. -If not set, the range is originated from a syntax element.

-
-
- - - -start: number -
-

The zero-based start line of the range to fold. The folded area starts after the line's last character. -To be valid, the end must be zero or larger and smaller than the number of lines in the document.

-
-
- -### FoldingRangeKind - - - -

An enumeration of specific folding range kinds. The kind is an optional field of a FoldingRange -and is used to distinguish specific folding ranges such as ranges originated from comments. The kind is used by commands like -Fold all comments or Fold all regions. -If the kind is not set on the range, the range originated from a syntax element other than comments, imports or region markers.

-
- -#### Enumeration members - - - -Comment -
-1 -
- - - -Imports -
-2 -
- - - -Region -
-3 -
- -### FoldingRangeProvider - - - -

The folding range provider interface defines the contract between extensions and -Folding in the editor.

-
- -#### Methods - - - -provideFoldingRanges(document: TextDocument, context: FoldingContext, token: CancellationToken): ProviderResult<FoldingRange[]> -
-

Returns a list of folding ranges or null and undefined if the provider -does not want to participate or was cancelled.

-
-
- - - - - - - -
ParameterDescription
document: TextDocument

The document in which the command was invoked.

-
context: FoldingContext

Additional context information (for future use)

-
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<FoldingRange[]>
-
-
- -### FormattingOptions - - - -

Value-object describing what options formatting should use.

-
- -#### Properties - - - -insertSpaces: boolean -
-

Prefer spaces over tabs.

-
-
- - - -tabSize: number -
-

Size of a tab in spaces.

-
-
- -### FunctionBreakpoint - - - -

A breakpoint specified by a function name.

-
- -#### Constructors - - - -new FunctionBreakpoint(functionName: string, enabled?: boolean, condition?: string, hitCondition?: string, logMessage?: string): FunctionBreakpoint -
-

Create a new function breakpoint.

-
-
- - - - - - - - - -
ParameterDescription
functionName: string
enabled?: boolean
condition?: string
hitCondition?: string
logMessage?: string
ReturnsDescription
FunctionBreakpoint
-
-
- -#### Properties - - - -condition?: string -
-

An optional expression for conditional breakpoints.

-
-
- - - -enabled: boolean -
-

Is breakpoint enabled.

-
-
- - - -functionName: string -
-

The name of the function to which this breakpoint is attached.

-
-
- - - -hitCondition?: string -
-

An optional expression that controls how many hits of the breakpoint are ignored.

-
-
- - - -id: string -
-

The unique ID of the breakpoint.

-
-
- - - -logMessage?: string -
-

An optional message that gets logged when this breakpoint is hit. Embedded expressions within {} are interpolated by the debug adapter.

-
-
- -### GlobPattern - - - -

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:

- -

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.

-
- - - -GlobPattern: string | RelativePattern - -### Hover - - - -

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

-
- -#### Constructors - - - -new Hover(contents: MarkedString | MarkedString[], range?: Range): Hover -
-

Creates a new hover object.

-
-
- - - - - - -
ParameterDescription
contents: MarkedString | MarkedString[]

The contents of the hover.

-
range?: Range

The range to which the hover applies.

-
ReturnsDescription
Hover
-
-
- -#### Properties - - - -contents: MarkedString[] -
-

The contents of this hover.

-
-
- - - -range?: Range -
-

The range to which this hover applies. When missing, the -editor will use the range at the current position or the -current position itself.

-
-
- -### HoverProvider - - - -

The hover provider interface defines the contract between extensions and -the hover-feature.

-
- -#### Methods - - - -provideHover(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<Hover> -
-

Provide a hover for the given position and document. Multiple hovers at the same -position will be merged by the editor. A hover can have a range which defaults -to the word range at the position when omitted.

-
-
- - - - - - - -
ParameterDescription
document: TextDocument

The document in which the command was invoked.

-
position: Position

The position at which the command was invoked.

-
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<Hover>

A hover or a thenable that resolves to such. The lack of a result can be -signaled by returning undefined or null.

-
-
-
- -### ImplementationProvider - - - -

The implementation provider interface defines the contract between extensions and -the go to implementation feature.

-
- -#### Methods - - - -provideImplementation(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<Definition | DefinitionLink[]> -
-

Provide the implementations of the symbol at the given position and document.

-
-
- - - - - - - -
ParameterDescription
document: TextDocument

The document in which the command was invoked.

-
position: Position

The position at which the command was invoked.

-
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<Definition | DefinitionLink[]>

A definition or a thenable that resolves to such. The lack of a result can be -signaled by returning undefined or null.

-
-
-
- -### IndentAction - - - -

Describes what to do with the indentation when pressing Enter.

-
- -#### Enumeration members - - - -Indent -
-1 -
- - - -IndentOutdent -
-2 -
- - - -None -
-0 -
- - - -Outdent -
-3 -
- -### IndentationRule - - - -

Describes indentation rules for a language.

-
- -#### Properties - - - -decreaseIndentPattern: RegExp -
-

If a line matches this pattern, then all the lines after it should be unindented once (until another rule matches).

-
-
- - - -increaseIndentPattern: RegExp -
-

If a line matches this pattern, then all the lines after it should be indented once (until another rule matches).

-
-
- - - -indentNextLinePattern?: RegExp -
-

If a line matches this pattern, then only the next line after it should be indented once.

-
-
- - - -unIndentedLinePattern?: RegExp -
-

If a line matches this pattern, then its indentation should not be changed and it should not be evaluated against the other rules.

-
-
- -### InputBox - - - -

A concrete QuickInput to let the user input a text value.

-

Note that in 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.

-
- -#### Events - - - -onDidAccept: Event<void> -
-

An event signaling when the user indicated acceptance of the input value.

-
-
- - - -onDidChangeValue: Event<string> -
-

An event signaling when the value has changed.

-
-
- - - -onDidHide: Event<void> -
-

An event signaling when this input UI is hidden.

-

There are several reasons why this UI might have to be hidden and -the extension will be notified through QuickInput.onDidHide. -(Examples include: an explicit call to QuickInput.hide, -the user pressing Esc, some other input UI opening, etc.)

-
-
- - - -onDidTriggerButton: Event<QuickInputButton> -
-

An event signaling when a button was triggered.

-
-
- -#### Properties - - - -busy: 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.

-
-
- - - -buttons: ReadonlyArray<QuickInputButton> -
-

Buttons for actions in the UI.

-
-
- - - -enabled: boolean -
-

If the UI should allow for user input. Defaults to true.

-

Change this to false, e.g., while validating user input or -loading data for the next step in user input.

-
-
- - - -ignoreFocusOut: boolean -
-

If the UI should stay open even when losing UI focus. Defaults to false.

-
-
- - - -password: boolean -
-

If the input value should be hidden. Defaults to false.

-
-
- - - -placeholder: string | undefined -
-

Optional placeholder in the filter text.

-
-
- - - -prompt: string | undefined -
-

An optional prompt text providing some ask or explanation to the user.

-
-
- - - -step: number | undefined -
-

An optional current step count.

-
-
- - - -title: string | undefined -
-

An optional title.

-
-
- - - -totalSteps: number | undefined -
-

An optional total step count.

-
-
- - - -validationMessage: string | undefined -
-

An optional validation message indicating a problem with the current input value.

-
-
- - - -value: string -
-

Current input value.

-
-
- -#### Methods - - - -dispose(): void -
-

Dispose of this input UI and any associated resources. If it is still -visible, it is first hidden. After this call the input UI is no longer -functional and no additional methods or properties on it should be -accessed. Instead a new input UI should be created.

-
-
- - - -
ReturnsDescription
void
-
-
- - - -hide(): void -
-

Hides this input UI. This will also fire an QuickInput.onDidHide -event.

-
-
- - - -
ReturnsDescription
void
-
-
- - - -show(): void -
-

Makes the input UI visible in its current configuration. Any other input -UI will first fire an QuickInput.onDidHide event.

-
-
- - - -
ReturnsDescription
void
-
-
- -### InputBoxOptions - - - -

Options to configure the behavior of the input box UI.

-
- -#### Properties - - - -ignoreFocusOut?: boolean -
-

Set to true to keep the input box open when focus moves to another part of the editor or to another window.

-
-
- - - -password?: boolean -
-

Controls if a password input is shown. Password input hides the typed text.

-
-
- - - -placeHolder?: string -
-

An optional string to show as placeholder in the input box to guide the user what to type.

-
-
- - - -prompt?: string -
-

The text to display underneath the input box.

-
-
- - - -value?: string -
-

The value to prefill in the input box.

-
-
- - - -valueSelection?: [number, number] -
-

Selection of the prefilled value. Defined as tuple of two number where the -first is the inclusive start index and the second the exclusive end index. When undefined the whole -word will be selected, when empty (start equals end) only the cursor will be set, -otherwise the defined range will be selected.

-
-
- -#### Methods - - - -validateInput(value: string): string | undefined | null | Thenable<string | undefined | null> -
-

An optional function that will be called to validate input and to give a hint -to the user.

-
-
- - - - - -
ParameterDescription
value: string

The current value of the input box.

-
ReturnsDescription
string | undefined | null | Thenable<string | undefined | null>

A human-readable string which is presented as diagnostic message. -Return undefined, null, or the empty string when 'value' is valid.

-
-
-
- -### LanguageConfiguration - - - -

The language configuration interfaces defines the contract between extensions -and various editor features, like automatic bracket insertion, automatic indentation etc.

-
- -#### Properties - - - -__characterPairSupport?: {autoClosingPairs: {close: string, notIn: string[], open: string}[]} -
-

Deprecated Do not use.

-
    -
  • deprecated - * Use the autoClosingPairs property in the language configuration file instead.
    • -
-
-
- - - -__electricCharacterSupport?: {brackets: any, docComment: {close: string, lineStart: string, open: string, scope: string}} -
-

Deprecated Do not use.

-
    -
  • deprecated - Will be replaced by a better API soon.
    • -
-
-
- - - -brackets?: CharacterPair[] -
-

The language's brackets. -This configuration implicitly affects pressing Enter around these brackets.

-
-
- - - -comments?: CommentRule -
-

The language's comment settings.

-
-
- - - -indentationRules?: IndentationRule -
-

The language's indentation settings.

-
-
- - - -onEnterRules?: OnEnterRule[] -
-

The language's rules to be evaluated when pressing Enter.

-
-
- - - -wordPattern?: RegExp -
-

The language's word definition. -If the language supports Unicode identifiers (e.g. JavaScript), it is preferable -to provide a word definition that uses exclusion of known separators. -e.g.: A regex that matches anything except known separators (and dot is allowed to occur in a floating point number): - /(-?\d.\d\w)|([^`~!\@@#\%\^\&*()-\=+[{]}\|\;\:\'\"\,.\<>\/\?\s]+)/g

-
-
- -### Location - - - -

Represents a location inside a resource, such as a line -inside a text file.

-
- -#### Constructors - - - -new Location(uri: Uri, rangeOrPosition: Range | Position): Location -
-

Creates a new location object.

-
-
- - - - - - -
ParameterDescription
uri: Uri

The resource identifier.

-
rangeOrPosition: Range | Position

The range or position. Positions will be converted to an empty range.

-
ReturnsDescription
Location
-
-
- -#### Properties - - - -range: Range -
-

The document range of this location.

-
-
- - - -uri: Uri -
-

The resource identifier of this location.

-
-
- -### LocationLink - - - -

Represents the connection of two locations. Provides additional metadata over normal locations, -including an origin range.

-
- -#### Properties - - - -originSelectionRange?: Range -
-

Span of the origin of this link.

-

Used as the underlined span for mouse definition hover. Defaults to the word range at -the definition position.

-
-
- - - -targetRange: Range -
-

The full target range of this link.

-
-
- - - -targetSelectionRange?: Range -
-

The span of this link.

-
-
- - - -targetUri: Uri -
-

The target resource identifier of this link.

-
-
- -### MarkdownString - - - -

The MarkdownString represents human-readable text that supports formatting via the -markdown syntax. Standard markdown is supported, also tables, but no embedded html.

-

When created with supportThemeIcons then rendering of theme icons via -the $(<name>)-syntax is supported.

-
- -#### Constructors - - - -new MarkdownString(value?: string, supportThemeIcons?: boolean): MarkdownString -
-

Creates a new markdown string with the given value.

-
-
- - - - - - -
ParameterDescription
value?: string

Optional, initial value.

-
supportThemeIcons?: boolean

Optional, Specifies whether ThemeIcons are supported within the MarkdownString.

-
ReturnsDescription
MarkdownString
-
-
- -#### Properties - - - -isTrusted?: boolean -
-

Indicates that this markdown string is from a trusted source. Only trusted -markdown supports links that execute commands, e.g. [Run it](command:myCommandId).

-
-
- - - -supportThemeIcons?: boolean -
-

Indicates that this markdown string can contain ThemeIcons, e.g. $(zap).

-
-
- - - -value: string -
-

The markdown string.

-
-
- -#### Methods - - - -appendCodeblock(value: string, language?: string): MarkdownString -
-

Appends the given string as codeblock using the provided language.

-
-
- - - - - - -
ParameterDescription
value: string

A code snippet.

-
language?: string

An optional language identifier.

-
ReturnsDescription
MarkdownString
-
-
- - - -appendMarkdown(value: string): MarkdownString -
-

Appends the given string 'as is' to this markdown string. When supportThemeIcons is true, ThemeIcons in the value will be iconified.

-
-
- - - - - -
ParameterDescription
value: string

Markdown string.

-
ReturnsDescription
MarkdownString
-
-
- - - -appendText(value: string): MarkdownString -
-

Appends and escapes the given string to this markdown string.

-
-
- - - - - -
ParameterDescription
value: string

Plain text.

-
ReturnsDescription
MarkdownString
-
-
- -### MarkedString - - - -

MarkedString can be used to render human-readable text. It is either a markdown string -or a code-block that provides a language and a code snippet. Note that -markdown strings will be sanitized - that means html will be escaped.

- -
- - - -MarkedString: MarkdownString | string | {language: string, value: string} - -### Memento - - - -

A memento represents a storage utility. It can store and retrieve -values.

-
- -#### Methods - - - -get<T>(key: string): T | undefined -
-

Return a value.

-
-
- - - - - -
ParameterDescription
key: string

A string.

-
ReturnsDescription
T | undefined

The stored value or undefined.

-
-
-
- - - -get<T>(key: string, defaultValue: T): T -
-

Return a value.

-
-
- - - - - - -
ParameterDescription
key: string

A string.

-
defaultValue: T

A value that should be returned when there is no -value (undefined) with the given key.

-
ReturnsDescription
T

The stored value or the defaultValue.

-
-
-
- - - -update(key: string, value: any): Thenable<void> -
-

Store a value. The value must be JSON-stringifyable.

-
-
- - - - - - -
ParameterDescription
key: string

A string.

-
value: any

A value. MUST not contain cyclic references.

-
ReturnsDescription
Thenable<void>
-
-
- -### MessageItem - - - -

Represents an action that is shown with an information, warning, or -error message.

- - - -
- -#### Properties - - - -isCloseAffordance?: boolean -
-

A hint for modal dialogs that the item should be triggered -when the user cancels the dialog (e.g. by pressing the ESC -key).

-

Note: this option is ignored for non-modal messages.

-
-
- - - -title: string -
-

A short title like 'Retry', 'Open Log' etc.

-
-
- -### MessageOptions - - - -

Options to configure the behavior of the message.

- - - -
- -#### Properties - - - -modal?: boolean -
-

Indicates that this message should be modal.

-
-
- -### OnEnterRule - - - -

Describes a rule to be evaluated when pressing Enter.

-
- -#### Properties - - - -action: EnterAction -
-

The action to execute.

-
-
- - - -afterText?: RegExp -
-

This rule will only execute if the text after the cursor matches this regular expression.

-
-
- - - -beforeText: RegExp -
-

This rule will only execute if the text before the cursor matches this regular expression.

-
-
- -### OnTypeFormattingEditProvider - - - -

The document formatting provider interface defines the contract between extensions and -the formatting-feature.

-
- -#### Methods - - - -provideOnTypeFormattingEdits(document: TextDocument, position: Position, ch: string, options: FormattingOptions, token: CancellationToken): ProviderResult<TextEdit[]> -
-

Provide formatting edits after a character has been typed.

-

The given position and character should hint to the provider -what range the position to expand to, like find the matching { -when } has been entered.

-
-
- - - - - - - - - -
ParameterDescription
document: TextDocument

The document in which the command was invoked.

-
position: Position

The position at which the command was invoked.

-
ch: string

The character that has been typed.

-
options: FormattingOptions

Options controlling formatting.

-
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<TextEdit[]>

A set of text edits or a thenable that resolves to such. The lack of a result can be -signaled by returning undefined, null, or an empty array.

-
-
-
- -### OpenDialogOptions - - - -

Options to configure the behaviour of a file open dialog.

- -
- -#### Properties - - - -canSelectFiles?: boolean -
-

Allow to select files, defaults to true.

-
-
- - - -canSelectFolders?: boolean -
-

Allow to select folders, defaults to false.

-
-
- - - -canSelectMany?: boolean -
-

Allow to select many files or folders.

-
-
- - - -defaultUri?: Uri -
-

The resource the dialog shows when opened.

-
-
- - - -filters?: -
-

A set of file filters that are used by the dialog. Each entry is a human-readable label, -like "TypeScript", and an array of extensions, e.g.

- -
{
-    'Images': ['png', 'jpg']
-    'TypeScript': ['ts', 'tsx']
-}
-
-
-
- - - -openLabel?: string -
-

A human-readable string for the open button.

-
-
- - - -title?: string -
-

Dialog title.

-

This parameter might be ignored, as not all operating systems display a title on open dialogs -(for example, macOS).

-
-
- -### OutputChannel - - - -

An output channel is a container for readonly textual information.

-

To get an instance of an OutputChannel use -createOutputChannel.

-
- -#### Properties - - - -name: string -
-

The human-readable name of this output channel.

-
-
- -#### Methods - - - -append(value: string): void -
-

Append the given value to the channel.

-
-
- - - - - -
ParameterDescription
value: string

A string, falsy values will not be printed.

-
ReturnsDescription
void
-
-
- - - -appendLine(value: string): void -
-

Append the given value and a line feed character -to the channel.

-
-
- - - - - -
ParameterDescription
value: string

A string, falsy values will be printed.

-
ReturnsDescription
void
-
-
- - - -clear(): void -
-

Removes all output from the channel.

-
-
- - - -
ReturnsDescription
void
-
-
- - - -dispose(): void -
-

Dispose and free associated resources.

-
-
- - - -
ReturnsDescription
void
-
-
- - - -hide(): void -
-

Hide this channel from the UI.

-
-
- - - -
ReturnsDescription
void
-
-
- - - -show(preserveFocus?: boolean): void -
-

Reveal this channel in the UI.

-
-
- - - - - -
ParameterDescription
preserveFocus?: boolean

When true the channel will not take focus.

-
ReturnsDescription
void
-
-
- - - -show(column?: ViewColumn, preserveFocus?: boolean): void -
-

Reveal this channel in the UI.

-
    -
  • deprecated - Use the overload with just one parameter (show(preserveFocus?: boolean): void).
    • -
-
-
- - - - - - -
ParameterDescription
column?: ViewColumn

This argument is deprecated and will be ignored.

-
preserveFocus?: boolean

When true the channel will not take focus.

-
ReturnsDescription
void
-
-
- -### OverviewRulerLane - - - -

Represents different positions for rendering a decoration in an overview ruler. -The overview ruler supports three lanes.

-
- -#### Enumeration members - - - -Center -
-2 -
- - - -Full -
-7 -
- - - -Left -
-1 -
- - - -Right -
-4 -
- -### ParameterInformation - - - -

Represents a parameter of a callable-signature. A parameter can -have a label and a doc-comment.

-
- -#### Constructors - - - -new ParameterInformation(label: string | [number, number], documentation?: string | MarkdownString): ParameterInformation -
-

Creates a new parameter information object.

-
-
- - - - - - -
ParameterDescription
label: string | [number, number]

A label string or inclusive start and exclusive end offsets within its containing signature label.

-
documentation?: string | MarkdownString

A doc string.

-
ReturnsDescription
ParameterInformation
-
-
- -#### Properties - - - -documentation?: string | MarkdownString -
-

The human-readable doc-comment of this signature. Will be shown -in the UI but can be omitted.

-
-
- - - -label: string | [number, number] -
-

The label of this signature.

-

Either a string or inclusive start and exclusive end offsets within its containing -signature label. Note: A label of type string must be -a substring of its containing signature information's label.

-
-
- -### 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.

-
- -#### Constructors - - - -new Position(line: number, character: number): Position -
-
-
- - - - - - -
ParameterDescription
line: number

A zero-based line value.

-
character: number

A zero-based character value.

-
ReturnsDescription
Position
-
-
- -#### Properties - - - -character: number -
-

The zero-based character value.

-
-
- - - -line: number -
-

The zero-based line value.

-
-
- -#### Methods - - - -compareTo(other: Position): number -
-

Compare this to other.

-
-
- - - - - -
ParameterDescription
other: Position

A position.

-
ReturnsDescription
number

A number smaller than zero if this position is before the given position, -a number greater than zero if this position is after the given position, or zero when -this and the given position are equal.

-
-
-
- - - -isAfter(other: Position): boolean -
-

Check if this position is after other.

-
-
- - - - - -
ParameterDescription
other: Position

A position.

-
ReturnsDescription
boolean

true if position is on a greater line -or on the same line on a greater character.

-
-
-
- - - -isAfterOrEqual(other: Position): boolean -
-

Check if this position is after or equal to other.

-
-
- - - - - -
ParameterDescription
other: Position

A position.

-
ReturnsDescription
boolean

true if position is on a greater line -or on the same line on a greater or equal character.

-
-
-
- - - -isBefore(other: Position): boolean -
-

Check if this position is before other.

-
-
- - - - - -
ParameterDescription
other: Position

A position.

-
ReturnsDescription
boolean

true if position is on a smaller line -or on the same line on a smaller character.

-
-
-
- - - -isBeforeOrEqual(other: Position): boolean -
-

Check if this position is before or equal to other.

-
-
- - - - - -
ParameterDescription
other: Position

A position.

-
ReturnsDescription
boolean

true if position is on a smaller line -or on the same line on a smaller or equal character.

-
-
-
- - - -isEqual(other: Position): boolean -
-

Check if this position is equal to other.

-
-
- - - - - -
ParameterDescription
other: Position

A position.

-
ReturnsDescription
boolean

true if the line and character of the given position are equal to -the line and character of this position.

-
-
-
- - - -translate(lineDelta?: number, characterDelta?: number): Position -
-

Create a new position relative to this position.

-
-
- - - - - - -
ParameterDescription
lineDelta?: number

Delta value for the line value, default is 0.

-
characterDelta?: number

Delta value for the character value, default is 0.

-
ReturnsDescription
Position

A position which line and character is the sum of the current line and -character and the corresponding deltas.

-
-
-
- - - -translate(change: {characterDelta: number, lineDelta: number}): Position -
-

Derived a new position relative to this position.

-
-
- - - - - -
ParameterDescription
change: {characterDelta: number, lineDelta: number}

An object that describes a delta to this position.

-
ReturnsDescription
Position

A position that reflects the given delta. Will return this position if the change -is not changing anything.

-
-
-
- - - -with(line?: number, character?: number): Position -
-

Create a new position derived from this position.

-
-
- - - - - - -
ParameterDescription
line?: number

Value that should be used as line value, default is the existing value

-
character?: number

Value that should be used as character value, default is the existing value

-
ReturnsDescription
Position

A position where line and character are replaced by the given values.

-
-
-
- - - -with(change: {character: number, line: number}): Position -
-

Derived a new position from this position.

-
-
- - - - - -
ParameterDescription
change: {character: number, line: number}

An object that describes a change to this position.

-
ReturnsDescription
Position

A position that reflects the given change. Will return this position if the change -is not changing anything.

-
-
-
- -### ProcessExecution - - - -

The execution of a task happens as an external process -without shell interaction.

-
- -#### Constructors - - - -new ProcessExecution(process: string, options?: ProcessExecutionOptions): ProcessExecution -
-

Creates a process execution.

-
-
- - - - - - -
ParameterDescription
process: string

The process to start.

-
options?: ProcessExecutionOptions

Optional options for the started process.

-
ReturnsDescription
ProcessExecution
-
-
- - - -new ProcessExecution(process: string, args: string[], options?: ProcessExecutionOptions): ProcessExecution -
-

Creates a process execution.

-
-
- - - - - - - -
ParameterDescription
process: string

The process to start.

-
args: string[]

Arguments to be passed to the process.

-
options?: ProcessExecutionOptions

Optional options for the started process.

-
ReturnsDescription
ProcessExecution
-
-
- -#### Properties - - - -args: string[] -
-

The arguments passed to the process. Defaults to an empty array.

-
-
- - - -options?: ProcessExecutionOptions -
-

The process options used when the process is executed. -Defaults to undefined.

-
-
- - - -process: string -
-

The process to be executed.

-
-
- -### ProcessExecutionOptions - - - -

Options for a process execution

-
- -#### Properties - - - -cwd?: string -
-

The current working directory of the executed program or shell. -If omitted the tools current workspace root is used.

-
-
- - - -env?: -
-

The additional environment of the executed program or shell. If omitted -the parent process' environment is used. If provided it is merged with -the parent process' environment.

-
-
- -### Progress<T> - - - -

Defines a generalized way of reporting progress updates.

-
- -#### Methods - - - -report(value: T): void -
-

Report a progress update.

-
-
- - - - - -
ParameterDescription
value: T

A progress item, like a message and/or an -report on how much work finished

-
ReturnsDescription
void
-
-
- -### ProgressLocation - - - -

A location in the editor at which progress information can be shown. It depends on the -location how progress is visually represented.

-
- -#### Enumeration members - - - -Notification -
-15 -
- - - -SourceControl -
-1 -
- - - -Window -
-10 -
- -### ProgressOptions - - - -

Value-object describing where and how progress should show.

-
- -#### Properties - - - -cancellable?: boolean -
-

Controls if a cancel button should show to allow the user to -cancel the long running operation. Note that currently only -ProgressLocation.Notification is supporting to show a cancel -button.

-
-
- - - -location: ProgressLocation | {viewId: string} -
-

The location at which progress should show.

-
-
- - - -title?: string -
-

A human-readable string which will be used to describe the -operation.

-
-
- -### ProviderResult<T> - - - -

A provider result represents the values a provider, like the HoverProvider, -may return. For once 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.

-

The snippets below are all valid implementations of the HoverProvider:

- -
let a: HoverProvider = {
-    provideHover(doc, pos, token): ProviderResult<Hover> {
-        return new Hover('Hello World');
-    }
-}
-
-let b: HoverProvider = {
-    provideHover(doc, pos, token): ProviderResult<Hover> {
-        return new Promise(resolve => {
-            resolve(new Hover('Hello World'));
-         });
-    }
-}
-
-let c: HoverProvider = {
-    provideHover(doc, pos, token): ProviderResult<Hover> {
-        return; // undefined
-    }
-}
-
-
- - - -ProviderResult: T | undefined | null | Thenable<T | undefined | null> - -### Pseudoterminal - - - -

Defines the interface of a terminal pty, enabling extensions to control a terminal.

-
- -#### Events - - - -onDidClose?: Event<void | number> -
-

An event that when fired will signal that the pty is closed and dispose of the terminal.

-

A number can be used to provide an exit code for the terminal. Exit codes must be -positive and a non-zero exit codes signals failure which shows a notification for a -regular terminal and allows dependent tasks to proceed when used with the -CustomExecution API.

-

Example: Exit the terminal when "y" is pressed, otherwise show a notification.

- -
const writeEmitter = new vscode.EventEmitter<string>();
-const closeEmitter = new vscode.EventEmitter<vscode.TerminalDimensions>();
-const pty: vscode.Pseudoterminal = {
-  onDidWrite: writeEmitter.event,
-  onDidClose: closeEmitter.event,
-  open: () => writeEmitter.fire('Press y to exit successfully'),
-  close: () => {},
-  handleInput: data => {
-    if (data !== 'y') {
-      vscode.window.showInformationMessage('Something went wrong');
-    }
-    closeEmitter.fire();
-  }
-};
-vscode.window.createTerminal({ name: 'Exit example', pty });
-
-
-
- - - -onDidOverrideDimensions?: Event<TerminalDimensions | undefined> -
-

An event that when fired allows overriding the dimensions of the -terminal. Note that when set, the overridden dimensions will only take effect when they -are lower than the actual dimensions of the terminal (ie. there will never be a scroll -bar). Set to undefined for the terminal to go back to the regular dimensions (fit to -the size of the panel).

-

Example: Override the dimensions of a terminal to 20 columns and 10 rows

- -
const dimensionsEmitter = new vscode.EventEmitter<vscode.TerminalDimensions>();
-const pty: vscode.Pseudoterminal = {
-  onDidWrite: writeEmitter.event,
-  onDidOverrideDimensions: dimensionsEmitter.event,
-  open: () => {
-    dimensionsEmitter.fire({
-      columns: 20,
-      rows: 10
-    });
-  },
-  close: () => {}
-};
-vscode.window.createTerminal({ name: 'My terminal', pty });
-
-
-
- - - -onDidWrite: Event<string> -
-

An event that when fired will write data to the terminal. Unlike -Terminal.sendText which sends text to the underlying child -pseudo-device (the child), this will write the text to parent pseudo-device (the -terminal itself).

-

Note writing \n will just move the cursor down 1 row, you need to write \r as well -to move the cursor to the left-most cell.

-

Example: Write red text to the terminal

- -
const writeEmitter = new vscode.EventEmitter<string>();
-const pty: vscode.Pseudoterminal = {
-  onDidWrite: writeEmitter.event,
-  open: () => writeEmitter.fire('\x1b[31mHello world\x1b[0m'),
-  close: () => {}
-};
-vscode.window.createTerminal({ name: 'My terminal', pty });
-
-

Example: Move the cursor to the 10th row and 20th column and write an asterisk

- -
writeEmitter.fire('\x1b[10;20H*');
-
-
-
- -#### Methods - - - -close(): void -
-

Implement to handle when the terminal is closed by an act of the user.

-
-
- - - -
ReturnsDescription
void
-
-
- - - -handleInput(data: string): void -
-

Implement to handle incoming keystrokes in the terminal or when an extension calls -Terminal.sendText. data contains the keystrokes/text serialized into -their corresponding VT sequence representation.

-
-
- - - - - -
ParameterDescription
data: string

The incoming data.

-

Example: Echo input in the terminal. The sequence for enter (\r) is translated to -CRLF to go to a new line and move the cursor to the start of the line.

- -
const writeEmitter = new vscode.EventEmitter<string>();
-const pty: vscode.Pseudoterminal = {
-  onDidWrite: writeEmitter.event,
-  open: () => {},
-  close: () => {},
-  handleInput: data => writeEmitter.fire(data === '\r' ? '\r\n' : data)
-};
-vscode.window.createTerminal({ name: 'Local echo', pty });
-
-
ReturnsDescription
void
-
-
- - - -open(initialDimensions: TerminalDimensions | undefined): void -
-

Implement to handle when the pty is open and ready to start firing events.

-
-
- - - - - -
ParameterDescription
initialDimensions: TerminalDimensions | undefined

The dimensions of the terminal, this will be undefined if the -terminal panel has not been opened before this is called.

-
ReturnsDescription
void
-
-
- - - -setDimensions(dimensions: TerminalDimensions): void -
-

Implement to handle when the number of rows and columns that fit into the terminal panel -changes, for example when font size changes or when the panel is resized. The initial -state of a terminal's dimensions should be treated as undefined until this is triggered -as the size of a terminal isn't know until it shows up in the user interface.

-

When dimensions are overridden by -onDidOverrideDimensions, setDimensions will -continue to be called with the regular panel dimensions, allowing the extension continue -to react dimension changes.

-
-
- - - - - -
ParameterDescription
dimensions: TerminalDimensions

The new dimensions.

-
ReturnsDescription
void
-
-
- -### QuickDiffProvider - - - -
- -#### Methods - - - -provideOriginalResource(uri: Uri, token: CancellationToken): ProviderResult<Uri> -
-

Provide a uri to the original resource of any given resource uri.

-
-
- - - - - - -
ParameterDescription
uri: Uri

The uri of the resource open in a text editor.

-
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<Uri>

A thenable that resolves to uri of the matching original resource.

-
-
-
- -### QuickInput - - - -

A light-weight user input UI that is initially not visible. After -configuring it through its properties the extension can make it -visible by calling QuickInput.show.

-

There are several reasons why this UI might have to be hidden and -the extension will be notified through QuickInput.onDidHide. -(Examples include: an explicit call to QuickInput.hide, -the user pressing Esc, some other input UI opening, etc.)

-

A user pressing Enter or some other gesture implying acceptance -of the current state does not automatically hide this UI component. -It is up to the extension to decide whether to accept the user's input -and if the UI should indeed be hidden through a call to QuickInput.hide.

-

When the extension no longer needs this input UI, it should -QuickInput.dispose it to allow for freeing up -any resources associated with it.

-

See QuickPick and InputBox for concrete UIs.

-
- -#### Events - - - -onDidHide: Event<void> -
-

An event signaling when this input UI is hidden.

-

There are several reasons why this UI might have to be hidden and -the extension will be notified through QuickInput.onDidHide. -(Examples include: an explicit call to QuickInput.hide, -the user pressing Esc, some other input UI opening, etc.)

-
-
- -#### Properties - - - -busy: 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.

-
-
- - - -enabled: boolean -
-

If the UI should allow for user input. Defaults to true.

-

Change this to false, e.g., while validating user input or -loading data for the next step in user input.

-
-
- - - -ignoreFocusOut: boolean -
-

If the UI should stay open even when losing UI focus. Defaults to false.

-
-
- - - -step: number | undefined -
-

An optional current step count.

-
-
- - - -title: string | undefined -
-

An optional title.

-
-
- - - -totalSteps: number | undefined -
-

An optional total step count.

-
-
- -#### Methods - - - -dispose(): void -
-

Dispose of this input UI and any associated resources. If it is still -visible, it is first hidden. After this call the input UI is no longer -functional and no additional methods or properties on it should be -accessed. Instead a new input UI should be created.

-
-
- - - -
ReturnsDescription
void
-
-
- - - -hide(): void -
-

Hides this input UI. This will also fire an QuickInput.onDidHide -event.

-
-
- - - -
ReturnsDescription
void
-
-
- - - -show(): void -
-

Makes the input UI visible in its current configuration. Any other input -UI will first fire an QuickInput.onDidHide event.

-
-
- - - -
ReturnsDescription
void
-
-
- -### QuickInputButton - - - -

Button for an action in a QuickPick or InputBox.

-
- -#### Properties - - - -iconPath: Uri | {dark: Uri, light: Uri} | ThemeIcon -
-

Icon for the button.

-
-
- - - -tooltip?: string | undefined -
-

An optional tooltip.

-
-
- -### QuickInputButtons - - - -

Predefined buttons for QuickPick and InputBox.

-
- -#### Static - - - -Back: QuickInputButton -
-

A back button for QuickPick and InputBox.

-

When a navigation 'back' button is needed this one should be used for consistency. -It comes with a predefined icon, tooltip and location.

-
-
- -### QuickPick<T> - - - -

A concrete QuickInput to let the user pick an item from a -list of items of type T. The items can be filtered through a filter text field and -there is an option canSelectMany to allow for -selecting multiple items.

-

Note that in many cases the more convenient window.showQuickPick -is easier to use. window.createQuickPick should be used -when window.showQuickPick does not offer the required flexibility.

-
- -#### Events - - - -onDidAccept: Event<void> -
-

An event signaling when the user indicated acceptance of the selected item(s).

-
-
- - - -onDidChangeActive: Event<T[]> -
-

An event signaling when the active items have changed.

-
-
- - - -onDidChangeSelection: Event<T[]> -
-

An event signaling when the selected items have changed.

-
-
- - - -onDidChangeValue: Event<string> -
-

An event signaling when the value of the filter text has changed.

-
-
- - - -onDidHide: Event<void> -
-

An event signaling when this input UI is hidden.

-

There are several reasons why this UI might have to be hidden and -the extension will be notified through QuickInput.onDidHide. -(Examples include: an explicit call to QuickInput.hide, -the user pressing Esc, some other input UI opening, etc.)

-
-
- - - -onDidTriggerButton: Event<QuickInputButton> -
-

An event signaling when a button was triggered.

-
-
- -#### Properties - - - -activeItems: ReadonlyArray<T> -
-

Active items. This can be read and updated by the extension.

-
-
- - - -busy: 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.

-
-
- - - -buttons: ReadonlyArray<QuickInputButton> -
-

Buttons for actions in the UI.

-
-
- - - -canSelectMany: boolean -
-

If multiple items can be selected at the same time. Defaults to false.

-
-
- - - -enabled: boolean -
-

If the UI should allow for user input. Defaults to true.

-

Change this to false, e.g., while validating user input or -loading data for the next step in user input.

-
-
- - - -ignoreFocusOut: boolean -
-

If the UI should stay open even when losing UI focus. Defaults to false.

-
-
- - - -items: ReadonlyArray<T> -
-

Items to pick from.

-
-
- - - -matchOnDescription: boolean -
-

If the filter text should also be matched against the description of the items. Defaults to false.

-
-
- - - -matchOnDetail: boolean -
-

If the filter text should also be matched against the detail of the items. Defaults to false.

-
-
- - - -placeholder: string | undefined -
-

Optional placeholder in the filter text.

-
-
- - - -selectedItems: ReadonlyArray<T> -
-

Selected items. This can be read and updated by the extension.

-
-
- - - -step: number | undefined -
-

An optional current step count.

-
-
- - - -title: string | undefined -
-

An optional title.

-
-
- - - -totalSteps: number | undefined -
-

An optional total step count.

-
-
- - - -value: string -
-

Current value of the filter text.

-
-
- -#### Methods - - - -dispose(): void -
-

Dispose of this input UI and any associated resources. If it is still -visible, it is first hidden. After this call the input UI is no longer -functional and no additional methods or properties on it should be -accessed. Instead a new input UI should be created.

-
-
- - - -
ReturnsDescription
void
-
-
- - - -hide(): void -
-

Hides this input UI. This will also fire an QuickInput.onDidHide -event.

-
-
- - - -
ReturnsDescription
void
-
-
- - - -show(): void -
-

Makes the input UI visible in its current configuration. Any other input -UI will first fire an QuickInput.onDidHide event.

-
-
- - - -
ReturnsDescription
void
-
-
- -### QuickPickItem - - - -

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

-
- -#### Properties - - - -alwaysShow?: boolean -
-

Always show this item.

-
-
- - - -description?: string -
-

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

-
-
- - - -detail?: string -
-

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

-
-
- - - -label: string -
-

A human-readable string which is rendered prominent. Supports rendering of theme icons via -the $(<name>)-syntax.

-
-
- - - -picked?: boolean -
-

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

- -
-
- -### QuickPickOptions - - - -

Options to configure the behavior of the quick pick UI.

-
- -#### Events - - - -onDidSelectItem(item: QuickPickItem | string): any -
-

An optional function that is invoked whenever an item is selected.

-
-
- - - - - -
ParameterDescription
item: QuickPickItem | string
ReturnsDescription
any
-
-
- -#### Properties - - - -canPickMany?: boolean -
-

An optional flag to make the picker accept multiple selections, if true the result is an array of picks.

-
-
- - - -ignoreFocusOut?: boolean -
-

Set to true to keep the picker open when focus moves to another part of the editor or to another window.

-
-
- - - -matchOnDescription?: boolean -
-

An optional flag to include the description when filtering the picks.

-
-
- - - -matchOnDetail?: boolean -
-

An optional flag to include the detail when filtering the picks.

-
-
- - - -placeHolder?: string -
-

An optional string to show as placeholder in the input box to guide the user what to pick on.

-
-
- -### Range - - - -

A range represents an ordered pair of two positions. -It is guaranteed that start.isBeforeOrEqual(end)

-

Range objects are immutable. Use the with, -intersection, or union methods -to derive new ranges from an existing range.

-
- -#### Constructors - - - -new Range(start: Position, end: Position): Range -
-

Create a new range from two positions. If start is not -before or equal to end, the values will be swapped.

-
-
- - - - - - -
ParameterDescription
start: Position

A position.

-
end: Position

A position.

-
ReturnsDescription
Range
-
-
- - - -new Range(startLine: number, startCharacter: number, endLine: number, endCharacter: number): Range -
-

Create a new range from number coordinates. It is a shorter equivalent of -using new Range(new Position(startLine, startCharacter), new Position(endLine, endCharacter))

-
-
- - - - - - - - -
ParameterDescription
startLine: number

A zero-based line value.

-
startCharacter: number

A zero-based character value.

-
endLine: number

A zero-based line value.

-
endCharacter: number

A zero-based character value.

-
ReturnsDescription
Range
-
-
- -#### Properties - - - -end: Position -
-

The end position. It is after or equal to start.

-
-
- - - -isEmpty: boolean -
-

true if start and end are equal.

-
-
- - - -isSingleLine: boolean -
-

true if start.line and end.line are equal.

-
-
- - - -start: Position -
-

The start position. It is before or equal to end.

-
-
- -#### Methods - - - -contains(positionOrRange: Position | Range): boolean -
-

Check if a position or a range is contained in this range.

-
-
- - - - - -
ParameterDescription
positionOrRange: Position | Range

A position or a range.

-
ReturnsDescription
boolean

true if the position or range is inside or equal -to this range.

-
-
-
- - - -intersection(range: Range): Range | undefined -
-

Intersect range with this range and returns a new range or undefined -if the ranges have no overlap.

-
-
- - - - - -
ParameterDescription
range: Range

A range.

-
ReturnsDescription
Range | undefined

A range of the greater start and smaller end positions. Will -return undefined when there is no overlap.

-
-
-
- - - -isEqual(other: Range): boolean -
-

Check if other equals this range.

-
-
- - - - - -
ParameterDescription
other: Range

A range.

-
ReturnsDescription
boolean

true when start and end are equal to -start and end of this range.

-
-
-
- - - -union(other: Range): Range -
-

Compute the union of other with this range.

-
-
- - - - - -
ParameterDescription
other: Range

A range.

-
ReturnsDescription
Range

A range of smaller start position and the greater end position.

-
-
-
- - - -with(start?: Position, end?: Position): Range -
-

Derived a new range from this range.

-
-
- - - - - - -
ParameterDescription
start?: Position

A position that should be used as start. The default value is the current start.

-
end?: Position

A position that should be used as end. The default value is the current end.

-
ReturnsDescription
Range

A range derived from this range with the given start and end position. -If start and end are not different this range will be returned.

-
-
-
- - - -with(change: {end: Position, start: Position}): Range -
-

Derived a new range from this range.

-
-
- - - - - -
ParameterDescription
change: {end: Position, start: Position}

An object that describes a change to this range.

-
ReturnsDescription
Range

A range that reflects the given change. Will return this range if the change -is not changing anything.

-
-
-
- -### ReferenceContext - - - -

Value-object that contains additional information when -requesting references.

-
- -#### Properties - - - -includeDeclaration: boolean -
-

Include the declaration of the current symbol.

-
-
- -### ReferenceProvider - - - -

The reference provider interface defines the contract between extensions and -the find references-feature.

-
- -#### Methods - - - -provideReferences(document: TextDocument, position: Position, context: ReferenceContext, token: CancellationToken): ProviderResult<Location[]> -
-

Provide a set of project-wide references for the given position and document.

-
-
- - - - - - - - -
ParameterDescription
document: TextDocument

The document in which the command was invoked.

-
position: Position

The position at which the command was invoked.

-
context: ReferenceContext
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<Location[]>

An array of locations or a thenable that resolves to such. The lack of a result can be -signaled by returning undefined, null, or an empty array.

-
-
-
- -### RelativePattern - - - -

A relative pattern is a helper to construct glob patterns that are matched -relatively to a base path. The base path can either be an absolute file path -or a workspace folder.

-
- -#### Constructors - - - -new RelativePattern(base: WorkspaceFolder | string, pattern: string): RelativePattern -
-

Creates a new relative pattern object with a base path and pattern to match. This pattern -will be matched on file paths relative to the base path.

-
-
- - - - - - -
ParameterDescription
base: WorkspaceFolder | string

A base file path to which this pattern will be matched against relatively.

-
pattern: string

A file glob pattern like *.{ts,js} that will be matched on file paths -relative to the base path.

-
ReturnsDescription
RelativePattern
-
-
- -#### Properties - - - -base: string -
-

A base file path to which this pattern will be matched against relatively.

-
-
- - - -pattern: string -
-

A file glob pattern like *.{ts,js} that will be matched on file paths -relative to the base path.

-

Example: Given a base of /home/work/folder and a file path of /home/work/folder/index.js, -the file glob pattern will match on index.js.

-
-
- -### RenameProvider - - - -

The rename provider interface defines the contract between extensions and -the rename-feature.

-
- -#### Methods - - - -prepareRename(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<Range | {placeholder: string, range: Range}> -
-

Optional function for resolving and validating a position before running rename. The result can -be a range or a range and a placeholder text. The placeholder text should be the identifier of the symbol -which is being renamed - when omitted the text in the returned range is used.

-

Note: This function should throw an error or return a rejected thenable when the provided location -doesn't allow for a rename.

-
-
- - - - - - - -
ParameterDescription
document: TextDocument

The document in which rename will be invoked.

-
position: Position

The position at which rename will be invoked.

-
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<Range | {placeholder: string, range: Range}>

The range or range and placeholder text of the identifier that is to be renamed. The lack of a result can signaled by returning undefined or null.

-
-
-
- - - -provideRenameEdits(document: TextDocument, position: Position, newName: string, token: CancellationToken): ProviderResult<WorkspaceEdit> -
-

Provide an edit that describes changes that have to be made to one -or many resources to rename a symbol to a different name.

-
-
- - - - - - - - -
ParameterDescription
document: TextDocument

The document in which the command was invoked.

-
position: Position

The position at which the command was invoked.

-
newName: string

The new name of the symbol. If the given name is not valid, the provider must return a rejected promise.

-
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<WorkspaceEdit>

A workspace edit or a thenable that resolves to such. The lack of a result can be -signaled by returning undefined or null.

-
-
-
- -### RunOptions - - - -

Run options for a task.

-
- -#### Properties - - - -reevaluateOnRerun?: boolean -
-

Controls whether task variables are re-evaluated on rerun.

-
-
- -### SaveDialogOptions - - - -

Options to configure the behaviour of a file save dialog.

-
- -#### Properties - - - -defaultUri?: Uri -
-

The resource the dialog shows when opened.

-
-
- - - -filters?: -
-

A set of file filters that are used by the dialog. Each entry is a human-readable label, -like "TypeScript", and an array of extensions, e.g.

- -
{
-    'Images': ['png', 'jpg']
-    'TypeScript': ['ts', 'tsx']
-}
-
-
-
- - - -saveLabel?: string -
-

A human-readable string for the save button.

-
-
- - - -title?: string -
-

Dialog title.

-

This parameter might be ignored, as not all operating systems display a title on save dialogs -(for example, macOS).

-
-
- -### Selection - - - -

Represents a text selection in an editor.

-
- -#### Constructors - - - -new Selection(anchor: Position, active: Position): Selection -
-

Create a selection from two positions.

-
-
- - - - - - -
ParameterDescription
anchor: Position

A position.

-
active: Position

A position.

-
ReturnsDescription
Selection
-
-
- - - -new Selection(anchorLine: number, anchorCharacter: number, activeLine: number, activeCharacter: number): Selection -
-

Create a selection from four coordinates.

-
-
- - - - - - - - -
ParameterDescription
anchorLine: number

A zero-based line value.

-
anchorCharacter: number

A zero-based character value.

-
activeLine: number

A zero-based line value.

-
activeCharacter: number

A zero-based character value.

-
ReturnsDescription
Selection
-
-
- -#### Properties - - - -active: Position -
-

The position of the cursor. -This position might be before or after anchor.

-
-
- - - -anchor: Position -
-

The position at which the selection starts. -This position might be before or after active.

-
-
- - - -end: Position -
-

The end position. It is after or equal to start.

-
-
- - - -isEmpty: boolean -
-

true if start and end are equal.

-
-
- - - -isReversed: boolean -
-

A selection is reversed if active.isBefore(anchor).

-
-
- - - -isSingleLine: boolean -
-

true if start.line and end.line are equal.

-
-
- - - -start: Position -
-

The start position. It is before or equal to end.

-
-
- -#### Methods - - - -contains(positionOrRange: Position | Range): boolean -
-

Check if a position or a range is contained in this range.

-
-
- - - - - -
ParameterDescription
positionOrRange: Position | Range

A position or a range.

-
ReturnsDescription
boolean

true if the position or range is inside or equal -to this range.

-
-
-
- - - -intersection(range: Range): Range | undefined -
-

Intersect range with this range and returns a new range or undefined -if the ranges have no overlap.

-
-
- - - - - -
ParameterDescription
range: Range

A range.

-
ReturnsDescription
Range | undefined

A range of the greater start and smaller end positions. Will -return undefined when there is no overlap.

-
-
-
- - - -isEqual(other: Range): boolean -
-

Check if other equals this range.

-
-
- - - - - -
ParameterDescription
other: Range

A range.

-
ReturnsDescription
boolean

true when start and end are equal to -start and end of this range.

-
-
-
- - - -union(other: Range): Range -
-

Compute the union of other with this range.

-
-
- - - - - -
ParameterDescription
other: Range

A range.

-
ReturnsDescription
Range

A range of smaller start position and the greater end position.

-
-
-
- - - -with(start?: Position, end?: Position): Range -
-

Derived a new range from this range.

-
-
- - - - - - -
ParameterDescription
start?: Position

A position that should be used as start. The default value is the current start.

-
end?: Position

A position that should be used as end. The default value is the current end.

-
ReturnsDescription
Range

A range derived from this range with the given start and end position. -If start and end are not different this range will be returned.

-
-
-
- - - -with(change: {end: Position, start: Position}): Range -
-

Derived a new range from this range.

-
-
- - - - - -
ParameterDescription
change: {end: Position, start: Position}

An object that describes a change to this range.

-
ReturnsDescription
Range

A range that reflects the given change. Will return this range if the change -is not changing anything.

-
-
-
- -### SelectionRange - - - -

A selection range represents a part of a selection hierarchy. A selection range -may have a parent selection range that contains it.

-
- -#### Constructors - - - -new SelectionRange(range: Range, parent?: SelectionRange): SelectionRange -
-

Creates a new selection range.

-
-
- - - - - - -
ParameterDescription
range: Range

The range of the selection range.

-
parent?: SelectionRange

The parent of the selection range.

-
ReturnsDescription
SelectionRange
-
-
- -#### Properties - - - -parent?: SelectionRange -
-

The parent selection range containing this range.

-
-
- - - -range: Range -
-

The range of this selection range.

-
-
- -### SelectionRangeProvider - - - -
- -#### Methods - - - -provideSelectionRanges(document: TextDocument, positions: Position[], token: CancellationToken): ProviderResult<SelectionRange[]> -
-

Provide selection ranges for the given positions.

-

Selection ranges should be computed individually and independent for each position. The editor will merge -and deduplicate ranges but providers must return hierarchies of selection ranges so that a range -is contained by its parent.

-
-
- - - - - - - -
ParameterDescription
document: TextDocument

The document in which the command was invoked.

-
positions: Position[]

The positions at which the command was invoked.

-
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<SelectionRange[]>

Selection ranges or a thenable that resolves to such. The lack of a result can be -signaled by returning undefined or null.

-
-
-
- -### SemanticTokens - - - -

Represents semantic tokens, either in a range or in an entire document.

- - -
- -#### Constructors - - - -new SemanticTokens(data: Uint32Array, resultId?: string): SemanticTokens -
-
-
- - - - - - -
ParameterDescription
data: Uint32Array
resultId?: string
ReturnsDescription
SemanticTokens
-
-
- -#### Properties - - - -data: Uint32Array -
-

The actual tokens data.

- -
-
- - - -resultId?: string -
-

The result id of the tokens.

-

This is the id that will be passed to DocumentSemanticTokensProvider.provideDocumentSemanticTokensEdits (if implemented).

-
-
- -### SemanticTokensBuilder - - - -

A semantic tokens builder can help with creating a SemanticTokens instance -which contains delta encoded semantic tokens.

-
- -#### Constructors - - - -new SemanticTokensBuilder(legend?: SemanticTokensLegend): SemanticTokensBuilder -
-
-
- - - - - -
ParameterDescription
legend?: SemanticTokensLegend
ReturnsDescription
SemanticTokensBuilder
-
-
- -#### Methods - - - -build(resultId?: string): SemanticTokens -
-

Finish and create a SemanticTokens instance.

-
-
- - - - - -
ParameterDescription
resultId?: string
ReturnsDescription
SemanticTokens
-
-
- - - -push(line: number, char: number, length: number, tokenType: number, tokenModifiers?: number): void -
-

Add another token.

-
-
- - - - - - - - - -
ParameterDescription
line: number

The token start line number (absolute value).

-
char: number

The token start character (absolute value).

-
length: number

The token length in characters.

-
tokenType: number

The encoded token type.

-
tokenModifiers?: number

The encoded token modifiers.

-
ReturnsDescription
void
-
-
- - - -push(range: Range, tokenType: string, tokenModifiers?: string[]): void -
-

Add another token. Use only when providing a legend.

-
-
- - - - - - - -
ParameterDescription
range: Range

The range of the token. Must be single-line.

-
tokenType: string

The token type.

-
tokenModifiers?: string[]

The token modifiers.

-
ReturnsDescription
void
-
-
- -### SemanticTokensEdit - - - -

Represents an edit to semantic tokens.

- -
- -#### Constructors - - - -new SemanticTokensEdit(start: number, deleteCount: number, data?: Uint32Array): SemanticTokensEdit -
-
-
- - - - - - - -
ParameterDescription
start: number
deleteCount: number
data?: Uint32Array
ReturnsDescription
SemanticTokensEdit
-
-
- -#### Properties - - - -data?: Uint32Array -
-

The elements to insert.

-
-
- - - -deleteCount: number -
-

The count of elements to remove.

-
-
- - - -start: number -
-

The start offset of the edit.

-
-
- -### SemanticTokensEdits - - - -

Represents edits to semantic tokens.

- -
- -#### Constructors - - - -new SemanticTokensEdits(edits: SemanticTokensEdit[], resultId?: string): SemanticTokensEdits -
-
-
- - - - - - -
ParameterDescription
edits: SemanticTokensEdit[]
resultId?: string
ReturnsDescription
SemanticTokensEdits
-
-
- -#### Properties - - - -edits: SemanticTokensEdit[] -
-

The edits to the tokens data. -All edits refer to the initial data state.

-
-
- - - -resultId?: string -
-

The result id of the tokens.

-

This is the id that will be passed to DocumentSemanticTokensProvider.provideDocumentSemanticTokensEdits (if implemented).

-
-
- -### SemanticTokensLegend - - - -

A semantic tokens legend contains the needed information to decipher -the integer encoded representation of semantic tokens.

-
- -#### Constructors - - - -new SemanticTokensLegend(tokenTypes: string[], tokenModifiers?: string[]): SemanticTokensLegend -
-
-
- - - - - - -
ParameterDescription
tokenTypes: string[]
tokenModifiers?: string[]
ReturnsDescription
SemanticTokensLegend
-
-
- -#### Properties - - - -tokenModifiers: string[] -
-

The possible token modifiers.

-
-
- - - -tokenTypes: string[] -
-

The possible token types.

-
-
- -### ShellExecution - - - -
- -#### Constructors - - - -new ShellExecution(commandLine: string, options?: ShellExecutionOptions): ShellExecution -
-

Creates a shell execution with a full command line.

-
-
- - - - - - -
ParameterDescription
commandLine: string

The command line to execute.

-
options?: ShellExecutionOptions

Optional options for the started the shell.

-
ReturnsDescription
ShellExecution
-
-
- - - -new ShellExecution(command: string | ShellQuotedString, args: string | ShellQuotedString[], options?: ShellExecutionOptions): ShellExecution -
-

Creates a shell execution with a command and arguments. For the real execution VS Code will -construct a command line from the command and the arguments. This is subject to interpretation -especially when it comes to quoting. If full control over the command line is needed please -use the constructor that creates a ShellExecution with the full command line.

-
-
- - - - - - - -
ParameterDescription
command: string | ShellQuotedString

The command to execute.

-
args: string | ShellQuotedString[]

The command arguments.

-
options?: ShellExecutionOptions

Optional options for the started the shell.

-
ReturnsDescription
ShellExecution
-
-
- -#### Properties - - - -args: string | ShellQuotedString[] -
-

The shell args. Is undefined if created with a full command line.

-
-
- - - -command: string | ShellQuotedString -
-

The shell command. Is undefined if created with a full command line.

-
-
- - - -commandLine: string | undefined -
-

The shell command line. Is undefined if created with a command and arguments.

-
-
- - - -options?: ShellExecutionOptions -
-

The shell options used when the command line is executed in a shell. -Defaults to undefined.

-
-
- -### ShellExecutionOptions - - - -

Options for a shell execution

-
- -#### Properties - - - -cwd?: string -
-

The current working directory of the executed shell. -If omitted the tools current workspace root is used.

-
-
- - - -env?: -
-

The additional environment of the executed shell. If omitted -the parent process' environment is used. If provided it is merged with -the parent process' environment.

-
-
- - - -executable?: string -
-

The shell executable.

-
-
- - - -shellArgs?: string[] -
-

The arguments to be passed to the shell executable used to run the task. Most shells -require special arguments to execute a command. For example bash requires the -c -argument to execute a command, PowerShell requires -Command and cmd requires both -/d and /c.

-
-
- - - -shellQuoting?: ShellQuotingOptions -
-

The shell quotes supported by this shell.

-
-
- -### ShellQuotedString - - - -

A string that will be quoted depending on the used shell.

-
- -#### Properties - - - -quoting: ShellQuoting -
-

The quoting style to use.

-
-
- - - -value: string -
-

The actual string value.

-
-
- -### ShellQuoting - - - -

Defines how an argument should be quoted if it contains -spaces or unsupported characters.

-
- -#### Enumeration members - - - -Escape -
-1 -
- - - -Strong -
-2 -
- - - -Weak -
-3 -
- -### ShellQuotingOptions - - - -

The shell quoting options.

-
- -#### Properties - - - -escape?: string | {charsToEscape: string, escapeChar: string} -
-

The character used to do character escaping. If a string is provided only spaces -are escaped. If a { escapeChar, charsToEscape } literal is provide all characters -in charsToEscape are escaped using the escapeChar.

-
-
- - - -strong?: string -
-

The character used for strong quoting. The string's length must be 1.

-
-
- - - -weak?: string -
-

The character used for weak quoting. The string's length must be 1.

-
-
- -### SignatureHelp - - - -

Signature help represents the signature of something -callable. There can be multiple signatures but only one -active and only one active parameter.

-
- -#### Properties - - - -activeParameter: number -
-

The active parameter of the active signature.

-
-
- - - -activeSignature: number -
-

The active signature.

-
-
- - - -signatures: SignatureInformation[] -
-

One or more signatures.

-
-
- -### SignatureHelpContext - - - -

Additional information about the context in which a -SignatureHelpProvider was triggered.

-
- -#### Properties - - - -activeSignatureHelp?: SignatureHelp -
-

The currently active SignatureHelp.

-

The activeSignatureHelp has its [SignatureHelp.activeSignature] field updated based on -the user arrowing through available signatures.

-
-
- - - -isRetrigger: boolean -
-

true if signature help was already showing when it was triggered.

-

Retriggers occur when the signature help is already active and can be caused by actions such as -typing a trigger character, a cursor move, or document content changes.

-
-
- - - -triggerCharacter?: string -
-

Character that caused signature help to be triggered.

-

This is undefined when signature help is not triggered by typing, such as when manually invoking -signature help or when moving the cursor.

-
-
- - - -triggerKind: SignatureHelpTriggerKind -
-

Action that caused signature help to be triggered.

-
-
- -### SignatureHelpProvider - - - -

The signature help provider interface defines the contract between extensions and -the parameter hints-feature.

-
- -#### Methods - - - -provideSignatureHelp(document: TextDocument, position: Position, token: CancellationToken, context: SignatureHelpContext): ProviderResult<SignatureHelp> -
-

Provide help for the signature at the given position and document.

-
-
- - - - - - - - -
ParameterDescription
document: TextDocument

The document in which the command was invoked.

-
position: Position

The position at which the command was invoked.

-
token: CancellationToken

A cancellation token.

-
context: SignatureHelpContext

Information about how signature help was triggered.

-
ReturnsDescription
ProviderResult<SignatureHelp>

Signature help or a thenable that resolves to such. The lack of a result can be -signaled by returning undefined or null.

-
-
-
- -### SignatureHelpProviderMetadata - - - -

Metadata about a registered SignatureHelpProvider.

-
- -#### Properties - - - -retriggerCharacters: ReadonlyArray<string> -
-

List of characters that re-trigger signature help.

-

These trigger characters are only active when signature help is already showing. All trigger characters -are also counted as re-trigger characters.

-
-
- - - -triggerCharacters: ReadonlyArray<string> -
-

List of characters that trigger signature help.

-
-
- -### SignatureHelpTriggerKind - - - -

How a SignatureHelpProvider was triggered.

-
- -#### Enumeration members - - - -ContentChange -
-3 -
- - - -Invoke -
-1 -
- - - -TriggerCharacter -
-2 -
- -### SignatureInformation - - - -

Represents the signature of something callable. A signature -can have a label, like a function-name, a doc-comment, and -a set of parameters.

-
- -#### Constructors - - - -new SignatureInformation(label: string, documentation?: string | MarkdownString): SignatureInformation -
-

Creates a new signature information object.

-
-
- - - - - - -
ParameterDescription
label: string

A label string.

-
documentation?: string | MarkdownString

A doc string.

-
ReturnsDescription
SignatureInformation
-
-
- -#### Properties - - - -activeParameter?: number -
-

The index of the active parameter.

-

If provided, this is used in place of SignatureHelp.activeSignature.

-
-
- - - -documentation?: string | MarkdownString -
-

The human-readable doc-comment of this signature. Will be shown -in the UI but can be omitted.

-
-
- - - -label: string -
-

The label of this signature. Will be shown in -the UI.

-
-
- - - -parameters: ParameterInformation[] -
-

The parameters of this signature.

-
-
- -### SnippetString - - - -

A snippet string is a template which allows to insert text -and to control the editor cursor when insertion happens.

-

A snippet can define tab stops and placeholders with $1, $2 -and ${3:foo}. $0 defines the final tab stop, it defaults to -the end of the snippet. Variables are defined with $name and -${name:default value}. The full snippet syntax is documented -here.

-
- -#### Constructors - - - -new SnippetString(value?: string): SnippetString -
-
-
- - - - - -
ParameterDescription
value?: string
ReturnsDescription
SnippetString
-
-
- -#### Properties - - - -value: string -
-

The snippet string.

-
-
- -#### Methods - - - -appendChoice(values: string[], number?: number): SnippetString -
-

Builder-function that appends a choice (${1|a,b,c}) to -the value of this snippet string.

-
-
- - - - - - -
ParameterDescription
values: string[]

The values for choices - the array of strings

-
number?: number

The number of this tabstop, defaults to an auto-increment -value starting at 1.

-
ReturnsDescription
SnippetString

This snippet string.

-
-
-
- - - -appendPlaceholder(value: string | (snippet: SnippetString) => any, number?: number): SnippetString -
-

Builder-function that appends a placeholder (${1:value}) to -the value of this snippet string.

-
-
- - - - - - -
ParameterDescription
value: string | (snippet: SnippetString) => any

The value of this placeholder - either a string or a function -with which a nested snippet can be created.

-
number?: number

The number of this tabstop, defaults to an auto-increment -value starting at 1.

-
ReturnsDescription
SnippetString

This snippet string.

-
-
-
- - - -appendTabstop(number?: number): SnippetString -
-

Builder-function that appends a tabstop ($1, $2 etc) to -the value of this snippet string.

-
-
- - - - - -
ParameterDescription
number?: number

The number of this tabstop, defaults to an auto-increment -value starting at 1.

-
ReturnsDescription
SnippetString

This snippet string.

-
-
-
- - - -appendText(string: string): SnippetString -
-

Builder-function that appends the given string to -the value of this snippet string.

-
-
- - - - - -
ParameterDescription
string: string

A value to append 'as given'. The string will be escaped.

-
ReturnsDescription
SnippetString

This snippet string.

-
-
-
- - - -appendVariable(name: string, defaultValue: string | (snippet: SnippetString) => any): SnippetString -
-

Builder-function that appends a variable (${VAR}) to -the value of this snippet string.

-
-
- - - - - - -
ParameterDescription
name: string

The name of the variable - excluding the $.

-
defaultValue: string | (snippet: SnippetString) => any

The default value which is used when the variable name cannot -be resolved - either a string or a function with which a nested snippet can be created.

-
ReturnsDescription
SnippetString

This snippet string.

-
-
-
- -### SourceBreakpoint - - - -

A breakpoint specified by a source location.

-
- -#### Constructors - - - -new SourceBreakpoint(location: Location, enabled?: boolean, condition?: string, hitCondition?: string, logMessage?: string): SourceBreakpoint -
-

Create a new breakpoint for a source location.

-
-
- - - - - - - - - -
ParameterDescription
location: Location
enabled?: boolean
condition?: string
hitCondition?: string
logMessage?: string
ReturnsDescription
SourceBreakpoint
-
-
- -#### Properties - - - -condition?: string -
-

An optional expression for conditional breakpoints.

-
-
- - - -enabled: boolean -
-

Is breakpoint enabled.

-
-
- - - -hitCondition?: string -
-

An optional expression that controls how many hits of the breakpoint are ignored.

-
-
- - - -id: string -
-

The unique ID of the breakpoint.

-
-
- - - -location: Location -
-

The source and line position of this breakpoint.

-
-
- - - -logMessage?: string -
-

An optional message that gets logged when this breakpoint is hit. Embedded expressions within {} are interpolated by the debug adapter.

-
-
- -### SourceControl - - - -

An source control is able to provide resource states -to the editor and interact with the editor in several source control related ways.

-
- -#### Properties - - - -acceptInputCommand?: Command -
-

Optional accept input command.

-

This command will be invoked when the user accepts the value -in the Source Control input.

-
-
- - - -commitTemplate?: string -
-

Optional commit template string.

-

The Source Control viewlet will populate the Source Control -input with this value when appropriate.

-
-
- - - -count?: number -
-

The UI-visible count of resource states of -this source control.

-

Equals to the total number of resource state -of this source control, if undefined.

-
-
- - - -id: string -
-

The id of this source control.

-
-
- - - -inputBox: SourceControlInputBox -
-

The input box for this source control.

-
-
- - - -label: string -
-

The human-readable label of this source control.

-
-
- - - -quickDiffProvider?: QuickDiffProvider -
-

An optional quick diff provider.

-
-
- - - -rootUri: Uri | undefined -
-

The (optional) Uri of the root of this source control.

-
-
- - - -statusBarCommands?: Command[] -
-

Optional status bar commands.

-

These commands will be displayed in the editor's status bar.

-
-
- -#### Methods - - - -createResourceGroup(id: string, label: string): SourceControlResourceGroup -
-

Create a new resource group.

-
-
- - - - - - -
ParameterDescription
id: string
label: string
ReturnsDescription
SourceControlResourceGroup
-
-
- - - -dispose(): void -
-

Dispose this source control.

-
-
- - - -
ReturnsDescription
void
-
-
- -### SourceControlInputBox - - - -

Represents the input box in the Source Control viewlet.

-
- -#### Properties - - - -placeholder: string -
-

A string to show as placeholder in the input box to guide the user.

-
-
- - - -value: string -
-

Setter and getter for the contents of the input box.

-
-
- - - -visible: boolean -
-

Controls whether the input box is visible (default is true).

-
-
- -### SourceControlResourceDecorations - - - -

The decorations for a source control resource state. -Can be independently specified for light and dark themes.

-
- -#### Properties - - - -dark?: SourceControlResourceThemableDecorations -
-

The dark theme decorations.

-
-
- - - -faded?: boolean -
-

Whether the source control resource state should -be faded in the UI.

-
-
- - - -iconPath?: string | Uri -
-

The icon path for a specific -source control resource state.

-
-
- - - -light?: SourceControlResourceThemableDecorations -
-

The light theme decorations.

-
-
- - - -strikeThrough?: boolean -
-

Whether the source control resource state should -be striked-through in the UI.

-
-
- - - -tooltip?: string -
-

The title for a specific -source control resource state.

-
-
- -### SourceControlResourceGroup - - - -

A source control resource group is a collection of -source control resource states.

-
- -#### Properties - - - -hideWhenEmpty?: boolean -
-

Whether this source control resource group is hidden when it contains -no source control resource states.

-
-
- - - -id: string -
-

The id of this source control resource group.

-
-
- - - -label: string -
-

The label of this source control resource group.

-
-
- - - -resourceStates: SourceControlResourceState[] -
-

This group's collection of -source control resource states.

-
-
- -#### Methods - - - -dispose(): void -
-

Dispose this source control resource group.

-
-
- - - -
ReturnsDescription
void
-
-
- -### SourceControlResourceState - - - -

An source control resource state represents the state of an underlying workspace -resource within a certain source control group.

-
- -#### Properties - - - -command?: Command -
-

The command which should be run when the resource -state is open in the Source Control viewlet.

-
-
- - - -contextValue?: string -
-

Context value of the resource state. This can be used to contribute resource specific actions. -For example, if a resource is given a context value as diffable. When contributing actions to scm/resourceState/context -using menus extension point, you can specify context value for key scmResourceState in when expressions, like scmResourceState == diffable.

- -
    "contributes": {
-        "menus": {
-            "scm/resourceState/context": [
-                {
-                    "command": "extension.diff",
-                    "when": "scmResourceState == diffable"
-                }
-            ]
-        }
-    }
-

This will show action extension.diff only for resources with contextValue is diffable.

-
-
- - - -decorations?: SourceControlResourceDecorations -
-

The decorations for this source control -resource state.

-
-
- - - -resourceUri: Uri -
-

The uri of the underlying resource inside the workspace.

-
-
- -### SourceControlResourceThemableDecorations - - - -

The theme-aware decorations for a -source control resource state.

-
- -#### Properties - - - -iconPath?: string | Uri -
-

The icon path for a specific -source control resource state.

-
-
- -### StatusBarAlignment - - - -

Represents the alignment of status bar items.

-
- -#### Enumeration members - - - -Left -
-1 -
- - - -Right -
-2 -
- -### StatusBarItem - - - -

A status bar item is a status bar contribution that can -show text and icons and run a command on click.

-
- -#### Properties - - - -accessibilityInformation?: AccessibilityInformation -
-

Accessibility information used when screen reader interacts with this StatusBar item

-
-
- - - -alignment: StatusBarAlignment -
-

The alignment of this item.

-
-
- - - -color: string | ThemeColor | undefined -
-

The foreground color for this entry.

-
-
- - - -command: string | Command | undefined -
-

Command or identifier of a command to run on click.

-

The command must be known.

-

Note that if this is a Command object, only the command and arguments -are used by VS Code.

-
-
- - - -priority?: number -
-

The priority of this item. Higher value means the item should -be shown more to the left.

-
-
- - - -text: string -
-

The text to show for the entry. You can embed icons in the text by leveraging the syntax:

-

My text $(icon-name) contains icons like $(icon-name) this one.

-

Where the icon-name is taken from the codicon icon set, e.g. -light-bulb, thumbsup, zap etc.

-
-
- - - -tooltip: string | undefined -
-

The tooltip text when you hover over this entry.

-
-
- -#### Methods - - - -dispose(): void -
-

Dispose and free associated resources. Call -hide.

-
-
- - - -
ReturnsDescription
void
-
-
- - - -hide(): void -
-

Hide the entry in the status bar.

-
-
- - - -
ReturnsDescription
void
-
-
- - - -show(): void -
-

Shows the entry in the status bar.

-
-
- - - -
ReturnsDescription
void
-
-
- -### SymbolInformation - - - -

Represents information about programming constructs like variables, classes, -interfaces etc.

-
- -#### Constructors - - - -new SymbolInformation(name: string, kind: SymbolKind, containerName: string, location: Location): SymbolInformation -
-

Creates a new symbol information object.

-
-
- - - - - - - - -
ParameterDescription
name: string

The name of the symbol.

-
kind: SymbolKind

The kind of the symbol.

-
containerName: string

The name of the symbol containing the symbol.

-
location: Location

The location of the symbol.

-
ReturnsDescription
SymbolInformation
-
-
- - - -new SymbolInformation(name: string, kind: SymbolKind, range: Range, uri?: Uri, containerName?: string): SymbolInformation -
-

Creates a new symbol information object.

-
    -
  • deprecated - Please use the constructor taking a location object.
    • -
-
-
- - - - - - - - - -
ParameterDescription
name: string

The name of the symbol.

-
kind: SymbolKind

The kind of the symbol.

-
range: Range

The range of the location of the symbol.

-
uri?: Uri

The resource of the location of symbol, defaults to the current document.

-
containerName?: string

The name of the symbol containing the symbol.

-
ReturnsDescription
SymbolInformation
-
-
- -#### Properties - - - -containerName: string -
-

The name of the symbol containing this symbol.

-
-
- - - -kind: SymbolKind -
-

The kind of this symbol.

-
-
- - - -location: Location -
-

The location of this symbol.

-
-
- - - -name: string -
-

The name of this symbol.

-
-
- - - -tags?: ReadonlyArray<SymbolTag> -
-

Tags for this symbol.

-
-
- -### SymbolKind - - - -

A symbol kind.

-
- -#### Enumeration members - - - -Array -
-17 -
- - - -Boolean -
-16 -
- - - -Class -
-4 -
- - - -Constant -
-13 -
- - - -Constructor -
-8 -
- - - -Enum -
-9 -
- - - -EnumMember -
-21 -
- - - -Event -
-23 -
- - - -Field -
-7 -
- - - -File -
-0 -
- - - -Function -
-11 -
- - - -Interface -
-10 -
- - - -Key -
-19 -
- - - -Method -
-5 -
- - - -Module -
-1 -
- - - -Namespace -
-2 -
- - - -Null -
-20 -
- - - -Number -
-15 -
- - - -Object -
-18 -
- - - -Operator -
-24 -
- - - -Package -
-3 -
- - - -Property -
-6 -
- - - -String -
-14 -
- - - -Struct -
-22 -
- - - -TypeParameter -
-25 -
- - - -Variable -
-12 -
- -### SymbolTag - - - -

Symbol tags are extra annotations that tweak the rendering of a symbol.

-
- -#### Enumeration members - - - -Deprecated -
-1 -
- -### Task - - - -

A task to execute

-
- -#### Constructors - - - -new Task(taskDefinition: TaskDefinition, scope: WorkspaceFolder | Global | Workspace, name: string, source: string, execution?: ProcessExecution | ShellExecution | CustomExecution, problemMatchers?: string | string[]): Task -
-

Creates a new task.

-
-
- - - - - - - - - - -
ParameterDescription
taskDefinition: TaskDefinition
scope: WorkspaceFolder | Global | Workspace

Specifies the task's scope. It is either a global or a workspace task or a task for a specific workspace folder. Global tasks are currently not supported.

-
name: string

The task's name. Is presented in the user interface.

-
source: string

The task's source (e.g. 'gulp', 'npm', ...). Is presented in the user interface.

-
execution?: ProcessExecution | ShellExecution | CustomExecution

The process or shell execution.

-
problemMatchers?: string | string[]

the names of problem matchers to use, like '$tsc' - or '$eslint'. Problem matchers can be contributed by an extension using - the problemMatchers extension point.

-
ReturnsDescription
Task
-
-
- - - -new Task(taskDefinition: TaskDefinition, name: string, source: string, execution?: ProcessExecution | ShellExecution, problemMatchers?: string | string[]): Task -
-

Creates a new task.

-
    -
  • deprecated - Use the new constructors that allow specifying a scope for the task.
    • -
-
-
- - - - - - - - - -
ParameterDescription
taskDefinition: TaskDefinition
name: string

The task's name. Is presented in the user interface.

-
source: string

The task's source (e.g. 'gulp', 'npm', ...). Is presented in the user interface.

-
execution?: ProcessExecution | ShellExecution

The process or shell execution.

-
problemMatchers?: string | string[]

the names of problem matchers to use, like '$tsc' - or '$eslint'. Problem matchers can be contributed by an extension using - the problemMatchers extension point.

-
ReturnsDescription
Task
-
-
- -#### Properties - - - -definition: TaskDefinition -
-

The task's definition.

-
-
- - - -detail?: string -
-

A human-readable string which is rendered less prominently on a separate line in places -where the task's name is displayed. Supports rendering of theme icons -via the $(<name>)-syntax.

-
-
- - - -execution?: ProcessExecution | ShellExecution | CustomExecution -
-

The task's execution engine

-
-
- - - -group?: TaskGroup -
-

The task group this tasks belongs to. See TaskGroup -for a predefined set of available groups. -Defaults to undefined meaning that the task doesn't -belong to any special group.

-
-
- - - -isBackground: boolean -
-

Whether the task is a background task or not.

-
-
- - - -name: string -
-

The task's name

-
-
- - - -presentationOptions: TaskPresentationOptions -
-

The presentation options. Defaults to an empty literal.

-
-
- - - -problemMatchers: string[] -
-

The problem matchers attached to the task. Defaults to an empty -array.

-
-
- - - -runOptions: RunOptions -
-

Run options for the task

-
-
- - - -scope?: Global | Workspace | WorkspaceFolder -
-

The task's scope.

-
-
- - - -source: string -
-

A human-readable string describing the source of this shell task, e.g. 'gulp' -or 'npm'. Supports rendering of theme icons via the $(<name>)-syntax.

-
-
- -### TaskDefinition - - - -

A structure that defines a task kind in the system. -The value must be JSON-stringifyable.

-
- -#### Properties - - - -type: string -
-

The task definition describing the task provided by an extension. -Usually a task provider defines more properties to identify -a task. They need to be defined in the package.json of the -extension under the 'taskDefinitions' extension point. The npm -task definition for example looks like this

- -
interface NpmTaskDefinition extends TaskDefinition {
-    script: string;
-}
-
-

Note that type identifier starting with a '$' are reserved for internal -usages and shouldn't be used by extensions.

-
-
- -### TaskEndEvent - - - -

An event signaling the end of an executed task.

-

This interface is not intended to be implemented.

-
- -#### Properties - - - -execution: TaskExecution -
-

The task item representing the task that finished.

-
-
- -### TaskExecution - - - -

An object representing an executed Task. It can be used -to terminate a task.

-

This interface is not intended to be implemented.

-
- -#### Properties - - - -task: Task -
-

The task that got started.

-
-
- -#### Methods - - - -terminate(): void -
-

Terminates the task execution.

-
-
- - - -
ReturnsDescription
void
-
-
- -### TaskFilter - - - -
- -#### Properties - - - -type?: string -
-

The task type to return;

-
-
- - - -version?: string -
-

The task version as used in the tasks.json file. -The string support the package.json semver notation.

-
-
- -### TaskGroup - - - -

A grouping for tasks. The editor by default supports the -'Clean', 'Build', 'RebuildAll' and 'Test' group.

-
- -#### Static - - - -Build: TaskGroup -
-

The build task group;

-
-
- - - -Clean: TaskGroup -
-

The clean task group;

-
-
- - - -Rebuild: TaskGroup -
-

The rebuild all task group;

-
-
- - - -Test: TaskGroup -
-

The test all task group;

-
-
- -#### Constructors - - - -new TaskGroup(id: string, label: string): TaskGroup -
-
-
- - - - - - -
ParameterDescription
id: string
label: string
ReturnsDescription
TaskGroup
-
-
- -### TaskPanelKind - - - -

Controls how the task channel is used between tasks

-
- -#### Enumeration members - - - -Dedicated -
-2 -
- - - -New -
-3 -
- - - -Shared -
-1 -
- -### TaskPresentationOptions - - - -

Controls how the task is presented in the UI.

-
- -#### Properties - - - -clear?: boolean -
-

Controls whether the terminal is cleared before executing the task.

-
-
- - - -echo?: boolean -
-

Controls whether the command associated with the task is echoed -in the user interface.

-
-
- - - -focus?: boolean -
-

Controls whether the panel showing the task output is taking focus.

-
-
- - - -panel?: TaskPanelKind -
-

Controls if the task panel is used for this task only (dedicated), -shared between tasks (shared) or if a new panel is created on -every task execution (new). Defaults to TaskInstanceKind.Shared

-
-
- - - -reveal?: TaskRevealKind -
-

Controls whether the task output is reveal in the user interface. -Defaults to RevealKind.Always.

-
-
- - - -showReuseMessage?: boolean -
-

Controls whether to show the "Terminal will be reused by tasks, press any key to close it" message.

-
-
- -### TaskProcessEndEvent - - - -

An event signaling the end of a process execution -triggered through a task

-
- -#### Properties - - - -execution: TaskExecution -
-

The task execution for which the process got started.

-
-
- - - -exitCode: number -
-

The process's exit code.

-
-
- -### TaskProcessStartEvent - - - -

An event signaling the start of a process execution -triggered through a task

-
- -#### Properties - - - -execution: TaskExecution -
-

The task execution for which the process got started.

-
-
- - - -processId: number -
-

The underlying process id.

-
-
- -### TaskProvider<T> - - - -

A task provider allows to add tasks to the task service. -A task provider is registered via #tasks.registerTaskProvider.

-
- -#### Methods - - - -provideTasks(token: CancellationToken): ProviderResult<T[]> -
-

Provides tasks.

-
-
- - - - - -
ParameterDescription
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<T[]>

an array of tasks

-
-
-
- - - -resolveTask(task: T, token: CancellationToken): ProviderResult<T> -
-

Resolves a task that has no execution set. Tasks are -often created from information found in the tasks.json-file. Such tasks miss -the information on how to execute them and a task provider must fill in -the missing information in the resolveTask-method. This method will not be -called for tasks returned from the above provideTasks method since those -tasks are always fully resolved. A valid default implementation for the -resolveTask method is to return undefined.

-
-
- - - - - - -
ParameterDescription
task: T

The task to resolve.

-
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<T>

The resolved task

-
-
-
- -### TaskRevealKind - - - -

Controls the behaviour of the terminal's visibility.

-
- -#### Enumeration members - - - -Always -
-1 -
- - - -Never -
-3 -
- - - -Silent -
-2 -
- -### TaskScope - - - -

The scope of a task.

-
- -#### Enumeration members - - - -Global -
-1 -
- - - -Workspace -
-2 -
- -### TaskStartEvent - - - -

An event signaling the start of a task execution.

-

This interface is not intended to be implemented.

-
- -#### Properties - - - -execution: TaskExecution -
-

The task item representing the task that got started.

-
-
- -### Terminal - - - -

An individual terminal instance within the integrated terminal.

-
- -#### Properties - - - -creationOptions: Readonly<TerminalOptions | ExtensionTerminalOptions> -
-

The object used to initialize the terminal, this is useful for example to detecting the -shell type of when the terminal was not launched by this extension or for detecting what -folder the shell was launched in.

-
-
- - - -exitStatus: TerminalExitStatus | undefined -
-

The exit status of the terminal, this will be undefined while the terminal is active.

-

Example: Show a notification with the exit code when the terminal exits with a -non-zero exit code.

- -
window.onDidCloseTerminal(t => {
-  if (t.exitStatus && t.exitStatus.code) {
-      vscode.window.showInformationMessage(`Exit code: ${t.exitStatus.code}`);
-  }
-});
-
-
-
- - - -name: string -
-

The name of the terminal.

-
-
- - - -processId: Thenable<number | undefined> -
-

The process ID of the shell process.

-
-
- -#### Methods - - - -dispose(): void -
-

Dispose and free associated resources.

-
-
- - - -
ReturnsDescription
void
-
-
- - - -hide(): void -
-

Hide the terminal panel if this terminal is currently showing.

-
-
- - - -
ReturnsDescription
void
-
-
- - - -sendText(text: string, addNewLine?: boolean): void -
-

Send text to the terminal. The text is written to the stdin of the underlying pty process -(shell) of the terminal.

-
-
- - - - - - -
ParameterDescription
text: string

The text to send.

-
addNewLine?: boolean

Whether to add a new line to the text being sent, this is normally -required to run a command in the terminal. The character(s) added are \n or \r\n -depending on the platform. This defaults to true.

-
ReturnsDescription
void
-
-
- - - -show(preserveFocus?: boolean): void -
-

Show the terminal panel and reveal this terminal in the UI.

-
-
- - - - - -
ParameterDescription
preserveFocus?: boolean

When true the terminal will not take focus.

-
ReturnsDescription
void
-
-
- -### TerminalDimensions - - - -

Represents the dimensions of a terminal.

-
- -#### Properties - - - -columns: number -
-

The number of columns in the terminal.

-
-
- - - -rows: number -
-

The number of rows in the terminal.

-
-
- -### TerminalExitStatus - - - -

Represents how a terminal exited.

-
- -#### Properties - - - -code: number | undefined -
-

The exit code that a terminal exited with, it can have the following values:

-
    -
  • Zero: the terminal process or custom execution succeeded.
    • -
  • Non-zero: the terminal process or custom execution failed.
    • -
  • undefined: the user forcibly closed the terminal or a custom execution exited -without providing an exit code.
    • -
-
-
- -### TerminalLink - - - -

A link on a terminal line.

-
- -#### Properties - - - -length: number -
-

The length of the link on [TerminalLinkContext.line](#TerminalLinkContext.line]

-
-
- - - -startIndex: number -
-

The start index of the link on [TerminalLinkContext.line](#TerminalLinkContext.line].

-
-
- - - -tooltip?: string -
-

The tooltip text when you hover over this link.

-

If a tooltip is provided, is will be displayed in a string that includes instructions on -how to trigger the link, such as {0} (ctrl + click). The specific instructions vary -depending on OS, user settings, and localization.

-
-
- -### TerminalLinkContext - - - -

Provides information on a line in a terminal in order to provide links for it.

-
- -#### Properties - - - -line: string -
-

This is the text from the unwrapped line in the terminal.

-
-
- - - -terminal: Terminal -
-

The terminal the link belongs to.

-
-
- -### TerminalLinkProvider<T> - - - -

A provider that enables detection and handling of links within terminals.

-
- -#### Methods - - - -handleTerminalLink(link: T): ProviderResult<void> -
-

Handle an activated terminal link.

-
-
- - - - - -
ParameterDescription
link: T

The link to handle.

-
ReturnsDescription
ProviderResult<void>
-
-
- - - -provideTerminalLinks(context: TerminalLinkContext, token: CancellationToken): ProviderResult<T[]> -
-

Provide terminal links for the given context. Note that this can be called multiple times -even before previous calls resolve, make sure to not share global objects (eg. RegExp) -that could have problems when asynchronous usage may overlap.

-
-
- - - - - - -
ParameterDescription
context: TerminalLinkContext

Information about what links are being provided for.

-
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<T[]>

A list of terminal links for the given line.

-
-
-
- -### TerminalOptions - - - -

Value-object describing what options a terminal should use.

-
- -#### Properties - - - -cwd?: string | Uri -
-

A path or Uri for the current working directory to be used for the terminal.

-
-
- - - -env?: -
-

Object with environment variables that will be added to the VS Code process.

-
-
- - - -hideFromUser?: boolean -
-

When enabled the terminal will run the process as normal but not be surfaced to the user -until Terminal.show is called. The typical usage for this is when you need to run -something that may need interactivity but only want to tell the user about it when -interaction is needed. Note that the terminals will still be exposed to all extensions -as normal.

-
-
- - - -name?: string -
-

A human-readable string which will be used to represent the terminal in the UI.

-
-
- - - -shellArgs?: string[] | string -
-

Args for the custom shell executable. A string can be used on Windows only which allows -specifying shell args in command-line format.

-
-
- - - -shellPath?: string -
-

A path to a custom shell executable to be used in the terminal.

-
-
- - - -strictEnv?: boolean -
-

Whether the terminal process environment should be exactly as provided in -TerminalOptions.env. When this is false (default), the environment will be based on the -window's environment and also apply configured platform settings like -terminal.integrated.windows.env on top. When this is true, the complete environment -must be provided as nothing will be inherited from the process or any configuration.

-
-
- -### TextDocument - - - -

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

-
- -#### Properties - - - -eol: EndOfLine -
-

The end of line sequence that is predominately -used in this document.

-
-
- - - -fileName: string -
-

The file system path of the associated resource. Shorthand -notation for TextDocument.uri.fsPath. Independent of the uri scheme.

-
-
- - - -isClosed: boolean -
-

true if the document has been closed. A closed document isn't synchronized anymore -and won't be re-used when the same resource is opened again.

-
-
- - - -isDirty: boolean -
-

true if there are unpersisted changes.

-
-
- - - -isUntitled: boolean -
-

Is this document representing an untitled file which has never been saved yet. Note that -this does not mean the document will be saved to disk, use uri.scheme -to figure out where a document will be saved, e.g. file, ftp etc.

-
-
- - - -languageId: string -
-

The identifier of the language associated with this document.

-
-
- - - -lineCount: number -
-

The number of lines in this document.

-
-
- - - -uri: Uri -
-

The associated uri for this document.

-

Note that most documents use the file-scheme, which means they are files on disk. However, not all documents are -saved on disk and therefore the scheme must be checked before trying to access the underlying file or siblings on disk.

- - -
-
- - - -version: number -
-

The version number of this document (it will strictly increase after each -change, including undo/redo).

-
-
- -#### Methods - - - -getText(range?: Range): string -
-

Get the text of this document. A substring can be retrieved by providing -a range. The range will be adjusted.

-
-
- - - - - -
ParameterDescription
range?: Range

Include only the text included by the range.

-
ReturnsDescription
string

The text inside the provided range or the entire text.

-
-
-
- - - -getWordRangeAtPosition(position: Position, regex?: RegExp): Range | undefined -
-

Get a word-range at the given position. By default words are defined by -common separators, like space, -, _, etc. In addition, per language custom -word definitions can be defined. It -is also possible to provide a custom regular expression.

-
    -
  • Note 1: A custom regular expression must not match the empty string and -if it does, it will be ignored.
    • -
  • Note 2: A custom regular expression will fail to match multiline strings -and in the name of speed regular expressions should not match words with -spaces. Use TextLine.text for more complex, non-wordy, scenarios.
    • -
-

The position will be adjusted.

-
-
- - - - - - -
ParameterDescription
position: Position

A position.

-
regex?: RegExp

Optional regular expression that describes what a word is.

-
ReturnsDescription
Range | undefined

A range spanning a word, or undefined.

-
-
-
- - - -lineAt(line: number): TextLine -
-

Returns a text line denoted by the line number. Note -that the returned object is not live and changes to the -document are not reflected.

-
-
- - - - - -
ParameterDescription
line: number

A line number in [0, lineCount).

-
ReturnsDescription
TextLine

A line.

-
-
-
- - - -lineAt(position: Position): TextLine -
-

Returns a text line denoted by the position. Note -that the returned object is not live and changes to the -document are not reflected.

-

The position will be adjusted.

- -
-
- - - - - -
ParameterDescription
position: Position

A position.

-
ReturnsDescription
TextLine

A line.

-
-
-
- - - -offsetAt(position: Position): number -
-

Converts the position to a zero-based offset.

-

The position will be adjusted.

-
-
- - - - - -
ParameterDescription
position: Position

A position.

-
ReturnsDescription
number

A valid zero-based offset.

-
-
-
- - - -positionAt(offset: number): Position -
-

Converts a zero-based offset to a position.

-
-
- - - - - -
ParameterDescription
offset: number

A zero-based offset.

-
ReturnsDescription
Position

A valid position.

-
-
-
- - - -save(): Thenable<boolean> -
-

Save the underlying file.

-
-
- - - -
ReturnsDescription
Thenable<boolean>

A promise that will resolve to true when the file -has been saved. If the file was not dirty or the save failed, -will return false.

-
-
-
- - - -validatePosition(position: Position): Position -
-

Ensure a position is contained in the range of this document.

-
-
- - - - - -
ParameterDescription
position: Position

A position.

-
ReturnsDescription
Position

The given position or a new, adjusted position.

-
-
-
- - - -validateRange(range: Range): Range -
-

Ensure a range is completely contained in this document.

-
-
- - - - - -
ParameterDescription
range: Range

A range.

-
ReturnsDescription
Range

The given range or a new, adjusted range.

-
-
-
- -### TextDocumentChangeEvent - - - -

An event describing a transactional document change.

-
- -#### Properties - - - -contentChanges: ReadonlyArray<TextDocumentContentChangeEvent> -
-

An array of content changes.

-
-
- - - -document: TextDocument -
-

The affected document.

-
-
- -### TextDocumentContentChangeEvent - - - -

An event describing an individual change in the text of a document.

-
- -#### Properties - - - -range: Range -
-

The range that got replaced.

-
-
- - - -rangeLength: number -
-

The length of the range that got replaced.

-
-
- - - -rangeOffset: number -
-

The offset of the range that got replaced.

-
-
- - - -text: string -
-

The new text for the range.

-
-
- -### TextDocumentContentProvider - - - -

A text document content provider allows to add readonly documents -to the editor, such as source from a dll or generated html from md.

-

Content providers are registered -for a uri-scheme. When a uri with that scheme is to -be loaded the content provider is -asked.

-
- -#### Events - - - -onDidChange?: Event<Uri> -
-

An event to signal a resource has changed.

-
-
- -#### Methods - - - -provideTextDocumentContent(uri: Uri, token: CancellationToken): ProviderResult<string> -
-

Provide textual content for a given uri.

-

The editor will use the returned string-content to create a readonly -document. Resources allocated should be released when -the corresponding document has been closed.

-

Note: The contents of the created document might not be -identical to the provided text due to end-of-line-sequence normalization.

-
-
- - - - - - -
ParameterDescription
uri: Uri

An uri which scheme matches the scheme this provider was registered for.

-
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<string>

A string or a thenable that resolves to such.

-
-
-
- -### TextDocumentSaveReason - - - -

Represents reasons why a text document is saved.

-
- -#### Enumeration members - - - -AfterDelay -
-2 -
- - - -FocusOut -
-3 -
- - - -Manual -
-1 -
- -### TextDocumentShowOptions - - - -

Represents options to configure the behavior of showing a document in an editor.

-
- -#### Properties - - - -preserveFocus?: boolean -
-

An optional flag that when true will stop the editor from taking focus.

-
-
- - - -preview?: boolean -
-

An optional flag that controls if an editor-tab will be replaced -with the next editor or if it will be kept.

-
-
- - - -selection?: Range -
-

An optional selection to apply for the document in the editor.

-
-
- - - -viewColumn?: ViewColumn -
-

An optional view column in which the editor should be shown. -The default is the active, other values are adjusted to -be Min(column, columnCount + 1), the active-column is -not adjusted. Use ViewColumn.Beside to open the -editor to the side of the currently active one.

-
-
- -### 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 -
-

The document that will be saved.

-
-
- - - -reason: TextDocumentSaveReason -
-

The reason why save was triggered.

-
-
- -#### Methods - - - -waitUntil(thenable: Thenable<TextEdit[]>): void -
-

Allows to pause the event loop and to apply pre-save-edits. -Edits of subsequent calls to this function will be applied in order. The -edits will be ignored if concurrent modifications of the document happened.

-

Note: This function can only be called during event dispatch and not -in an asynchronous manner:

- -
workspace.onWillSaveTextDocument(event => {
-    // async, will *throw* an error
-    setTimeout(() => event.waitUntil(promise));
-
-    // sync, OK
-    event.waitUntil(promise);
-})
-
-
-
- - - - - -
ParameterDescription
thenable: Thenable<TextEdit[]>

A thenable that resolves to pre-save-edits.

-
ReturnsDescription
void
-
-
- - - -waitUntil(thenable: Thenable<any>): void -
-

Allows to pause the event loop until the provided thenable resolved.

-

Note: This function can only be called during event dispatch.

-
-
- - - - - -
ParameterDescription
thenable: Thenable<any>

A thenable that delays saving.

-
ReturnsDescription
void
-
-
- -### TextEdit - - - -

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

-
- -#### Static - - - -delete(range: Range): TextEdit -
-

Utility to create a delete edit.

-
-
- - - - - -
ParameterDescription
range: Range

A range.

-
ReturnsDescription
TextEdit

A new text edit object.

-
-
-
- - - -insert(position: Position, newText: string): TextEdit -
-

Utility to create an insert edit.

-
-
- - - - - - -
ParameterDescription
position: Position

A position, will become an empty range.

-
newText: string

A string.

-
ReturnsDescription
TextEdit

A new text edit object.

-
-
-
- - - -replace(range: Range, newText: string): TextEdit -
-

Utility to create a replace edit.

-
-
- - - - - - -
ParameterDescription
range: Range

A range.

-
newText: string

A string.

-
ReturnsDescription
TextEdit

A new text edit object.

-
-
-
- - - -setEndOfLine(eol: EndOfLine): TextEdit -
-

Utility to create an eol-edit.

-
-
- - - - - -
ParameterDescription
eol: EndOfLine

An eol-sequence

-
ReturnsDescription
TextEdit

A new text edit object.

-
-
-
- -#### Constructors - - - -new TextEdit(range: Range, newText: string): TextEdit -
-

Create a new TextEdit.

-
-
- - - - - - -
ParameterDescription
range: Range

A range.

-
newText: string

A string.

-
ReturnsDescription
TextEdit
-
-
- -#### Properties - - - -newEol?: EndOfLine -
-

The eol-sequence used in the document.

-

Note that the eol-sequence will be applied to the -whole document.

-
-
- - - -newText: string -
-

The string this edit will insert.

-
-
- - - -range: Range -
-

The range this edit applies to.

-
-
- -### TextEditor - - - -

Represents an editor that is attached to a document.

-
- -#### Properties - - - -document: TextDocument -
-

The document associated with this text editor. The document will be the same for the entire lifetime of this text editor.

-
-
- - - -options: TextEditorOptions -
-

Text editor options.

-
-
- - - -selection: Selection -
-

The primary selection on this text editor. Shorthand for TextEditor.selections[0].

-
-
- - - -selections: Selection[] -
-

The selections in this text editor. The primary selection is always at index 0.

-
-
- - - -viewColumn?: ViewColumn -
-

The column in which this editor shows. Will be undefined in case this -isn't one of the main editors, e.g. an embedded editor, or when the editor -column is larger than three.

-
-
- - - -visibleRanges: Range[] -
-

The current visible ranges in the editor (vertically). -This accounts only for vertical scrolling, and not for horizontal scrolling.

-
-
- -#### Methods - - - -edit(callback: (editBuilder: TextEditorEdit) => void, options?: {undoStopAfter: boolean, undoStopBefore: boolean}): Thenable<boolean> -
-

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.

-
-
- - - - - - -
ParameterDescription
callback: (editBuilder: TextEditorEdit) => void

A function which can create edits using an edit-builder.

-
options?: {undoStopAfter: boolean, undoStopBefore: boolean}

The undo/redo behavior around this edit. By default, undo stops will be created before and after this edit.

-
ReturnsDescription
Thenable<boolean>

A promise that resolves with a value indicating if the edits could be applied.

-
-
-
- - - -hide(): void -
-

Hide the text editor.

-
    -
  • deprecated - Use the command workbench.action.closeActiveEditor instead. -This method shows unexpected behavior and will be removed in the next major update.
    • -
-
-
- - - -
ReturnsDescription
void
-
-
- - - -insertSnippet(snippet: SnippetString, location?: Position | Range | ReadonlyArray<Position> | ReadonlyArray<Range>, options?: {undoStopAfter: boolean, undoStopBefore: boolean}): Thenable<boolean> -
-

Insert a snippet and put the editor into snippet mode. "Snippet mode" -means the editor adds placeholders and additional cursors so that the user can complete -or accept the snippet.

-
-
- - - - - - - -
ParameterDescription
snippet: SnippetString

The snippet to insert in this edit.

-
location?: Position | Range | ReadonlyArray<Position> | ReadonlyArray<Range>

Position or range at which to insert the snippet, defaults to the current editor selection or selections.

-
options?: {undoStopAfter: boolean, undoStopBefore: boolean}

The undo/redo behavior around this edit. By default, undo stops will be created before and after this edit.

-
ReturnsDescription
Thenable<boolean>

A promise that resolves with a value indicating if the snippet could be inserted. Note that the promise does not signal -that the snippet is completely filled-in or accepted.

-
-
-
- - - -revealRange(range: Range, revealType?: TextEditorRevealType): void -
-

Scroll as indicated by revealType in order to reveal the given range.

-
-
- - - - - - -
ParameterDescription
range: Range

A range.

-
revealType?: TextEditorRevealType

The scrolling strategy for revealing range.

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

Adds a set of decorations to the text editor. If a set of decorations already exists with -the given decoration type, they will be replaced.

- -
-
- - - - - - -
ParameterDescription
decorationType: TextEditorDecorationType

A decoration type.

-
rangesOrOptions: Range[] | DecorationOptions[]

Either ranges or more detailed options.

-
ReturnsDescription
void
-
-
- - - -show(column?: ViewColumn): void -
-

Show the text editor.

- -
-
- - - - - -
ParameterDescription
column?: ViewColumn

The column in which to show this editor. -This method shows unexpected behavior and will be removed in the next major update.

-
ReturnsDescription
void
-
-
- -### TextEditorCursorStyle - - - -

Rendering style of the cursor.

-
- -#### Enumeration members - - - -Block -
-2 -
- - - -BlockOutline -
-5 -
- - - -Line -
-1 -
- - - -LineThin -
-4 -
- - - -Underline -
-3 -
- - - -UnderlineThin -
-6 -
- -### TextEditorDecorationType - - - -

Represents a handle to a set of decorations -sharing the same styling options in a text editor.

-

To get an instance of a TextEditorDecorationType use -createTextEditorDecorationType.

-
- -#### Properties - - - -key: string -
-

Internal representation of the handle.

-
-
- -#### Methods - - - -dispose(): void -
-

Remove this decoration type and all decorations on all text editors using it.

-
-
- - - -
ReturnsDescription
void
-
-
- -### 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.

-
- -#### Methods - - - -delete(location: Range | Selection): void -
-

Delete a certain text region.

-
-
- - - - - -
ParameterDescription
location: Range | Selection

The range this operation should remove.

-
ReturnsDescription
void
-
-
- - - -insert(location: Position, value: string): void -
-

Insert text at a location. -You can use \r\n or \n in value and they will be normalized to the current document. -Although the equivalent text edit can be made with replace, insert will produce a different resulting selection (it will get moved).

-
-
- - - - - - -
ParameterDescription
location: Position

The position where the new text should be inserted.

-
value: string

The new text this operation should insert.

-
ReturnsDescription
void
-
-
- - - -replace(location: Position | Range | Selection, value: string): void -
-

Replace a certain text region with a new value. -You can use \r\n or \n in value and they will be normalized to the current document.

-
-
- - - - - - -
ParameterDescription
location: Position | Range | Selection

The range this operation should remove.

-
value: string

The new text this operation should insert after removing location.

-
ReturnsDescription
void
-
-
- - - -setEndOfLine(endOfLine: EndOfLine): void -
-

Set the end of line sequence.

-
-
- - - - - -
ParameterDescription
endOfLine: EndOfLine

The new end of line for the document.

-
ReturnsDescription
void
-
-
- -### TextEditorLineNumbersStyle - - - -

Rendering style of the line numbers.

-
- -#### Enumeration members - - - -Off -
-0 -
- - - -On -
-1 -
- - - -Relative -
-2 -
- -### TextEditorOptions - - - -

Represents a text editor's options.

-
- -#### Properties - - - -cursorStyle?: TextEditorCursorStyle -
-

The rendering style of the cursor in this editor. -When getting a text editor's options, this property will always be present. -When setting a text editor's options, this property is optional.

-
-
- - - -insertSpaces?: boolean | string -
-

When pressing Tab insert n spaces. -When getting a text editor's options, this property will always be a boolean (resolved). -When setting a text editor's options, this property is optional and it can be a boolean or "auto".

-
-
- - - -lineNumbers?: TextEditorLineNumbersStyle -
-

Render relative line numbers w.r.t. the current line number. -When getting a text editor's options, this property will always be present. -When setting a text editor's options, this property is optional.

-
-
- - - -tabSize?: number | string -
-

The size in spaces a tab takes. This is used for two purposes:

-
    -
  • the rendering width of a tab character;
    • -
  • the number of spaces to insert when insertSpaces is true.
    • -
-

When getting a text editor's options, this property will always be a number (resolved). -When setting a text editor's options, this property is optional and it can be a number or "auto".

-
-
- -### TextEditorOptionsChangeEvent - - - -

Represents an event describing the change in a text editor's options.

-
- -#### Properties - - - -options: TextEditorOptions -
-

The new value for the text editor's options.

-
-
- - - -textEditor: TextEditor -
-

The text editor for which the options have changed.

-
-
- -### TextEditorRevealType - - - -

Represents different reveal strategies in a text editor.

-
- -#### Enumeration members - - - -AtTop -
-3 -
- - - -Default -
-0 -
- - - -InCenter -
-1 -
- - - -InCenterIfOutsideViewport -
-2 -
- -### TextEditorSelectionChangeEvent - - - -

Represents an event describing the change in a text editor's selections.

-
- -#### Properties - - - -kind?: TextEditorSelectionChangeKind -
-

The change kind which has triggered this -event. Can be undefined.

-
-
- - - -selections: ReadonlyArray<Selection> -
-

The new value for the text editor's selections.

-
-
- - - -textEditor: TextEditor -
-

The text editor for which the selections have changed.

-
-
- -### TextEditorSelectionChangeKind - - - -

Represents sources that can cause selection change events.

-
- -#### Enumeration members - - - -Command -
-3 -
- - - -Keyboard -
-1 -
- - - -Mouse -
-2 -
- -### TextEditorViewColumnChangeEvent - - - -

Represents an event describing the change of a text editor's view column.

-
- -#### Properties - - - -textEditor: TextEditor -
-

The text editor for which the view column has changed.

-
-
- - - -viewColumn: ViewColumn -
-

The new value for the text editor's view column.

-
-
- -### TextEditorVisibleRangesChangeEvent - - - -

Represents an event describing the change in a text editor's visible ranges.

-
- -#### Properties - - - -textEditor: TextEditor -
-

The text editor for which the visible ranges have changed.

-
-
- - - -visibleRanges: ReadonlyArray<Range> -
-

The new value for the text editor's visible ranges.

-
-
- -### TextLine - - - -

Represents a line of text, such as a line of source code.

-

TextLine objects are immutable. When a document changes, -previously retrieved lines will not represent the latest state.

-
- -#### Properties - - - -firstNonWhitespaceCharacterIndex: number -
-

The offset of the first character which is not a whitespace character as defined -by /\s/. Note that if a line is all whitespace the length of the line is returned.

-
-
- - - -isEmptyOrWhitespace: boolean -
-

Whether this line is whitespace only, shorthand -for TextLine.firstNonWhitespaceCharacterIndex === TextLine.text.length.

-
-
- - - -lineNumber: number -
-

The zero-based line number.

-
-
- - - -range: Range -
-

The range this line covers without the line separator characters.

-
-
- - - -rangeIncludingLineBreak: Range -
-

The range this line covers with the line separator characters.

-
-
- - - -text: string -
-

The text of this line without the line separator characters.

-
-
- -### ThemableDecorationAttachmentRenderOptions - - - -
- -#### Properties - - - -backgroundColor?: string | ThemeColor -
-

CSS styling property that will be applied to the decoration attachment.

-
-
- - - -border?: string -
-

CSS styling property that will be applied to the decoration attachment.

-
-
- - - -borderColor?: string | ThemeColor -
-

CSS styling property that will be applied to text enclosed by a decoration.

-
-
- - - -color?: string | ThemeColor -
-

CSS styling property that will be applied to the decoration attachment.

-
-
- - - -contentIconPath?: string | Uri -
-

An absolute path or an URI to an image to be rendered in the attachment. Either an icon -or a text can be shown, but not both.

-
-
- - - -contentText?: string -
-

Defines a text content that is shown in the attachment. Either an icon or a text can be shown, but not both.

-
-
- - - -fontStyle?: string -
-

CSS styling property that will be applied to the decoration attachment.

-
-
- - - -fontWeight?: string -
-

CSS styling property that will be applied to the decoration attachment.

-
-
- - - -height?: string -
-

CSS styling property that will be applied to the decoration attachment.

-
-
- - - -margin?: string -
-

CSS styling property that will be applied to the decoration attachment.

-
-
- - - -textDecoration?: string -
-

CSS styling property that will be applied to the decoration attachment.

-
-
- - - -width?: string -
-

CSS styling property that will be applied to the decoration attachment.

-
-
- -### ThemableDecorationInstanceRenderOptions - - - -
- -#### Properties - - - -after?: ThemableDecorationAttachmentRenderOptions -
-

Defines the rendering options of the attachment that is inserted after the decorated text.

-
-
- - - -before?: ThemableDecorationAttachmentRenderOptions -
-

Defines the rendering options of the attachment that is inserted before the decorated text.

-
-
- -### ThemableDecorationRenderOptions - - - -

Represents theme specific rendering styles for a text editor decoration.

-
- -#### Properties - - - -after?: ThemableDecorationAttachmentRenderOptions -
-

Defines the rendering options of the attachment that is inserted after the decorated text.

-
-
- - - -backgroundColor?: string | ThemeColor -
-

Background color of the decoration. Use rgba() and define transparent background colors to play well with other decorations. -Alternatively a color from the color registry can be referenced.

-
-
- - - -before?: ThemableDecorationAttachmentRenderOptions -
-

Defines the rendering options of the attachment that is inserted before the decorated text.

-
-
- - - -border?: string -
-

CSS styling property that will be applied to text enclosed by a decoration.

-
-
- - - -borderColor?: string | ThemeColor -
-

CSS styling property that will be applied to text enclosed by a decoration. -Better use 'border' for setting one or more of the individual border properties.

-
-
- - - -borderRadius?: string -
-

CSS styling property that will be applied to text enclosed by a decoration. -Better use 'border' for setting one or more of the individual border properties.

-
-
- - - -borderSpacing?: string -
-

CSS styling property that will be applied to text enclosed by a decoration. -Better use 'border' for setting one or more of the individual border properties.

-
-
- - - -borderStyle?: string -
-

CSS styling property that will be applied to text enclosed by a decoration. -Better use 'border' for setting one or more of the individual border properties.

-
-
- - - -borderWidth?: string -
-

CSS styling property that will be applied to text enclosed by a decoration. -Better use 'border' for setting one or more of the individual border properties.

-
-
- - - -color?: string | ThemeColor -
-

CSS styling property that will be applied to text enclosed by a decoration.

-
-
- - - -cursor?: string -
-

CSS styling property that will be applied to text enclosed by a decoration.

-
-
- - - -fontStyle?: string -
-

CSS styling property that will be applied to text enclosed by a decoration.

-
-
- - - -fontWeight?: string -
-

CSS styling property that will be applied to text enclosed by a decoration.

-
-
- - - -gutterIconPath?: string | Uri -
-

An absolute path or an URI to an image to be rendered in the gutter.

-
-
- - - -gutterIconSize?: string -
-

Specifies the size of the gutter icon. -Available values are 'auto', 'contain', 'cover' and any percentage value. -For further information: https://msdn.microsoft.com/en-us/library/jj127316(v=vs.85).aspx

-
-
- - - -letterSpacing?: string -
-

CSS styling property that will be applied to text enclosed by a decoration.

-
-
- - - -opacity?: string -
-

CSS styling property that will be applied to text enclosed by a decoration.

-
-
- - - -outline?: string -
-

CSS styling property that will be applied to text enclosed by a decoration.

-
-
- - - -outlineColor?: string | ThemeColor -
-

CSS styling property that will be applied to text enclosed by a decoration. -Better use 'outline' for setting one or more of the individual outline properties.

-
-
- - - -outlineStyle?: string -
-

CSS styling property that will be applied to text enclosed by a decoration. -Better use 'outline' for setting one or more of the individual outline properties.

-
-
- - - -outlineWidth?: string -
-

CSS styling property that will be applied to text enclosed by a decoration. -Better use 'outline' for setting one or more of the individual outline properties.

-
-
- - - -overviewRulerColor?: string | ThemeColor -
-

The color of the decoration in the overview ruler. Use rgba() and define transparent colors to play well with other decorations.

-
-
- - - -textDecoration?: string -
-

CSS styling property that will be applied to text enclosed by a decoration.

-
-
- -### ThemeColor - - - -

A reference to one of the workbench colors as defined in https://code.visualstudio.com/docs/getstarted/theme-color-reference. -Using a theme color is preferred over a custom color as it gives theme authors and users the possibility to change the color.

-
- -#### Constructors - - - -new ThemeColor(id: string): ThemeColor -
-

Creates a reference to a theme color.

-
-
- - - - - -
ParameterDescription
id: string

of the color. The available colors are listed in https://code.visualstudio.com/docs/getstarted/theme-color-reference.

-
ReturnsDescription
ThemeColor
-
-
- -### ThemeIcon - - - -

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 $(<name>)-syntax, for instance quickPick.label = "Hello World $(globe)".

-
- -#### Static - - - -File: ThemeIcon -
-

Reference to an icon representing a file. The icon is taken from the current file icon theme or a placeholder icon is used.

-
-
- - - -Folder: ThemeIcon -
-

Reference to an icon representing a folder. The icon is taken from the current file icon theme or a placeholder icon is used.

-
-
- -#### Constructors - - - -new ThemeIcon(id: string, color?: ThemeColor): ThemeIcon -
-

Creates a reference to a theme icon.

-
-
- - - - - - -
ParameterDescription
id: string

id of the icon. The available icons are listed in https://microsoft.github.io/vscode-codicons/dist/codicon.html.

-
color?: ThemeColor

optional ThemeColor for the icon. The color is currently only used in TreeItem.

-
ReturnsDescription
ThemeIcon
-
-
- -#### Properties - - - -color?: ThemeColor -
-

The optional ThemeColor of the icon. The color is currently only used in TreeItem.

-
-
- - - -id: string -
-

The id of the icon. The available icons are listed in https://microsoft.github.io/vscode-codicons/dist/codicon.html.

-
-
- -### TreeDataProvider<T> - - - -

A data provider that provides tree data

-
- -#### Events - - - -onDidChangeTreeData?: Event<T | undefined | null | void> -
-

An optional event to signal that an element or root has changed. -This will trigger the view to update the changed element/root and its children recursively (if shown). -To signal that root has changed, do not pass any argument or pass undefined or null.

-
-
- -#### Methods - - - -getChildren(element?: T): ProviderResult<T[]> -
-

Get the children of element or root if no element is passed.

-
-
- - - - - -
ParameterDescription
element?: T

The element from which the provider gets children. Can be undefined.

-
ReturnsDescription
ProviderResult<T[]>

Children of element or root if no element is passed.

-
-
-
- - - -getParent(element: T): ProviderResult<T> -
-

Optional method to return the parent of element. -Return null or undefined if element is a child of root.

-

NOTE: This method should be implemented in order to access reveal API.

-
-
- - - - - -
ParameterDescription
element: T

The element for which the parent has to be returned.

-
ReturnsDescription
ProviderResult<T>

Parent of element.

-
-
-
- - - -getTreeItem(element: T): TreeItem | Thenable<TreeItem> -
-

Get TreeItem representation of the element

-
-
- - - - - -
ParameterDescription
element: T

The element for which TreeItem representation is asked for.

-
ReturnsDescription
TreeItem | Thenable<TreeItem>

(#TreeItem) representation of the element

-
-
-
- -### TreeItem - - - -
- -#### Constructors - - - -new TreeItem(label: string, collapsibleState?: TreeItemCollapsibleState): TreeItem -
-
-
- - - - - - -
ParameterDescription
label: string

A human-readable string describing this item

-
collapsibleState?: TreeItemCollapsibleState

(#TreeItemCollapsibleState) of the tree item. Default is TreeItemCollapsibleState.None

-
ReturnsDescription
TreeItem
-
-
- - - -new TreeItem(resourceUri: Uri, collapsibleState?: TreeItemCollapsibleState): TreeItem -
-
-
- - - - - - -
ParameterDescription
resourceUri: Uri

The uri of the resource representing this item.

-
collapsibleState?: TreeItemCollapsibleState

(#TreeItemCollapsibleState) of the tree item. Default is TreeItemCollapsibleState.None

-
ReturnsDescription
TreeItem
-
-
- -#### Properties - - - -accessibilityInformation?: AccessibilityInformation -
-

Accessibility information used when screen reader interacts with this tree item. -Generally, a TreeItem has no need to set the role of the accessibilityInformation; -however, there are cases where a TreeItem is not displayed in a tree-like way where setting the role may make sense.

-
-
- - - -collapsibleState?: TreeItemCollapsibleState -
-

TreeItemCollapsibleState of the tree item.

-
-
- - - -command?: Command -
-

The command that should be executed when the tree item is selected.

-
-
- - - -contextValue?: string -
-

Context value of the tree item. This can be used to contribute item specific actions in the tree. -For example, a tree item is given a context value as folder. When contributing actions to view/item/context -using menus extension point, you can specify context value for key viewItem in when expression like viewItem == folder.

- -
    "contributes": {
-        "menus": {
-            "view/item/context": [
-                {
-                    "command": "extension.deleteFolder",
-                    "when": "viewItem == folder"
-                }
-            ]
-        }
-    }
-

This will show action extension.deleteFolder only for items with contextValue is folder.

-
-
- - - -description?: string | boolean -
-

A human-readable string which is rendered less prominent. -When true, it is derived from resourceUri and when falsy, it is not shown.

-
-
- - - -iconPath?: string | Uri | {dark: string | Uri, light: string | Uri} | ThemeIcon -
-

The icon path or ThemeIcon for the tree item. -When falsy, Folder Theme Icon is assigned, if item is collapsible otherwise File Theme Icon. -When a file or folder ThemeIcon is specified, icon is derived from the current file icon theme for the specified theme icon using resourceUri (if provided).

-
-
- - - -id?: string -
-

Optional id for the tree item that has to be unique across tree. The id is used to preserve the selection and expansion state of the tree item.

-

If not provided, an id is generated using the tree item's label. Note that when labels change, ids will change and that selection and expansion state cannot be kept stable anymore.

-
-
- - - -label?: string -
-

A human-readable string describing this item. When falsy, it is derived from resourceUri.

-
-
- - - -resourceUri?: Uri -
-

The uri of the resource representing this item.

-

Will be used to derive the label, when it is not provided. -Will be used to derive the icon from current file icon theme, when iconPath has ThemeIcon value.

-
-
- - - -tooltip?: string | undefined -
-

The tooltip text when you hover over this item.

-
-
- -### TreeItemCollapsibleState - - - -

Collapsible state of the tree item

-
- -#### Enumeration members - - - -Collapsed -
-1 -
- - - -Expanded -
-2 -
- - - -None -
-0 -
- -### TreeView<T> - - - -

Represents a Tree view

-
- -#### Events - - - -onDidChangeSelection: Event<TreeViewSelectionChangeEvent<T>> -
-

Event that is fired when the selection has changed

-
-
- - - -onDidChangeVisibility: Event<TreeViewVisibilityChangeEvent> -
-

Event that is fired when visibility has changed

-
-
- - - -onDidCollapseElement: Event<TreeViewExpansionEvent<T>> -
-

Event that is fired when an element is collapsed

-
-
- - - -onDidExpandElement: Event<TreeViewExpansionEvent<T>> -
-

Event that is fired when an element is expanded

-
-
- -#### Static - - - -from(...disposableLikes: {dispose: () => any}[]): Disposable -
-

Combine many disposable-likes into one. Use this method -when having objects with a dispose function which are not -instances of Disposable.

-
-
- - - - - -
ParameterDescription
...disposableLikes: {dispose: () => any}[]

Objects that have at least a dispose-function member.

-
ReturnsDescription
Disposable

Returns a new disposable which, upon dispose, will -dispose all provided disposables.

-
-
-
- -#### Constructors - - - -new TreeView(callOnDispose: Function): TreeView -
-

Creates a new Disposable calling the provided function -on dispose.

-
-
- - - - - -
ParameterDescription
callOnDispose: Function

Function that disposes something.

-
ReturnsDescription
TreeView
-
-
- -#### Properties - - - -description?: string -
-

An optional human-readable description which is rendered less prominently in the title of the view. -Setting the title description to null, undefined, or empty string will remove the description from the view.

-
-
- - - -message?: string -
-

An optional human-readable message that will be rendered in the view. -Setting the message to null, undefined, or empty string will remove the message from the view.

-
-
- - - -selection: T[] -
-

Currently selected elements.

-
-
- - - -title?: string -
-

The tree view title is initially taken from the extension package.json -Changes to the title property will be properly reflected in the UI in the title of the view.

-
-
- - - -visible: boolean -
-

true if the tree view is visible otherwise false.

-
-
- -#### Methods - - - -dispose(): any -
-

Dispose this object.

-
-
- - - -
ReturnsDescription
any
-
-
- - - -reveal(element: T, options?: {expand: boolean | number, focus: boolean, select: boolean}): Thenable<void> -
-

Reveals the given element in the tree view. -If the tree view is not visible then the tree view is shown and element is revealed.

-

By default revealed element is selected. -In order to not to select, set the option select to false. -In order to focus, set the option focus to true. -In order to expand the revealed element, set the option expand to true. To expand recursively set expand to the number of levels to expand. -NOTE: You can expand only to 3 levels maximum.

-

NOTE: The TreeDataProvider that the TreeView is registered with with must implement getParent method to access this API.

-
-
- - - - - - -
ParameterDescription
element: T
options?: {expand: boolean | number, focus: boolean, select: boolean}
ReturnsDescription
Thenable<void>
-
-
- -### TreeViewExpansionEvent<T> - - - -

The event that is fired when an element in the TreeView is expanded or collapsed

-
- -#### Properties - - - -element: T -
-

Element that is expanded or collapsed.

-
-
- -### TreeViewOptions<T> - - - -

Options for creating a TreeView

-
- -#### Properties - - - -canSelectMany?: boolean -
-

Whether the tree supports multi-select. When the tree supports multi-select and a command is executed from the tree, -the first argument to the command is the tree item that the command was executed on and the second argument is an -array containing all selected tree items.

-
-
- - - -showCollapseAll?: boolean -
-

Whether to show collapse all action or not.

-
-
- - - -treeDataProvider: TreeDataProvider<T> -
-

A data provider that provides tree data.

-
-
- -### TreeViewSelectionChangeEvent<T> - - - -

The event that is fired when there is a change in tree view's selection

-
- -#### Properties - - - -selection: T[] -
-

Selected elements.

-
-
- -### TreeViewVisibilityChangeEvent - - - -

The event that is fired when there is a change in tree view's visibility

-
- -#### Properties - - - -visible: boolean -
-

true if the tree view is visible otherwise false.

-
-
- -### TypeDefinitionProvider - - - -

The type definition provider defines the contract between extensions and -the go to type definition feature.

-
- -#### Methods - - - -provideTypeDefinition(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<Definition | DefinitionLink[]> -
-

Provide the type definition of the symbol at the given position and document.

-
-
- - - - - - - -
ParameterDescription
document: TextDocument

The document in which the command was invoked.

-
position: Position

The position at which the command was invoked.

-
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<Definition | DefinitionLink[]>

A definition or a thenable that resolves to such. The lack of a result can be -signaled by returning undefined or null.

-
-
-
- -### UIKind - - - -

Possible kinds of UI that can use extensions.

-
- -#### Enumeration members - - - -Desktop -
-1 -
- - - -Web -
-2 -
- -### Uri - - - -

A universal resource identifier representing either a file on disk -or another resource, like untitled resources.

-
- -#### Static - - - -file(path: string): Uri -
-

Create an URI from a file system path. The scheme -will be file.

-

The difference between Uri#parse and Uri#file is that the latter treats the argument -as path, not as stringified-uri. E.g. Uri.file(path) is not the same as -Uri.parse('file://' + path) because the path might contain characters that are -interpreted (# and ?). See the following sample:

- -
const good = URI.file('/coding/c#/project1');
-good.scheme === 'file';
-good.path === '/coding/c#/project1';
-good.fragment === '';
-
-const bad = URI.parse('file://' + '/coding/c#/project1');
-bad.scheme === 'file';
-bad.path === '/coding/c'; // path is now broken
-bad.fragment === '/project1';
-
-
-
- - - - - -
ParameterDescription
path: string

A file system or UNC path.

-
ReturnsDescription
Uri

A new Uri instance.

-
-
-
- - - -joinPath(base: Uri, ...pathSegments: string[]): Uri -
-

Create a new uri which path is the result of joining -the path of the base uri with the provided path segments.

-
    -
  • Note 1: joinPath only affects the path component -and all other components (scheme, authority, query, and fragment) are -left as they are.
    • -
  • Note 2: The base uri must have a path; an error is thrown otherwise.
    • -
-

The path segments are normalized in the following ways:

-
    -
  • sequences of path separators (/ or \) are replaced with a single separator
    • -
  • for file-uris on windows, the backslash-character (\) is considered a path-separator
    • -
  • the ..-segment denotes the parent segment, the . denotes the current segment
    • -
  • paths have a root which always remains, for instance on windows drive-letters are roots -so that is true: joinPath(Uri.file('file:///c:/root'), '../../other').fsPath === 'c:/other'
    • -
-
-
- - - - - - -
ParameterDescription
base: Uri

An uri. Must have a path.

-
...pathSegments: string[]

One more more path fragments

-
ReturnsDescription
Uri

A new uri which path is joined with the given fragments

-
-
-
- - - -parse(value: string, strict?: boolean): Uri -
-

Create an URI from a string, e.g. http://www.msft.com/some/path, -file:///usr/home, or scheme:with/path.

-

Note that for a while uris without a scheme were accepted. That is not correct -as all uris should have a scheme. To avoid breakage of existing code the optional -strict-argument has been added. We strongly advise to use it, e.g. Uri.parse('my:uri', true)

- -
-
- - - - - - -
ParameterDescription
value: string

The string value of an Uri.

-
strict?: boolean

Throw an error when value is empty or when no scheme can be parsed.

-
ReturnsDescription
Uri

A new Uri instance.

-
-
-
- -#### Constructors - - - -new Uri(scheme: string, authority: string, path: string, query: string, fragment: string): Uri -
-

Use the file and parse factory functions to create new Uri objects.

-
-
- - - - - - - - - -
ParameterDescription
scheme: string
authority: string
path: string
query: string
fragment: string
ReturnsDescription
Uri
-
-
- -#### Properties - - - -authority: string -
-

Authority is the www.msft.com part of http://www.msft.com/some/path?query#fragment. -The part between the first double slashes and the next slash.

-
-
- - - -fragment: string -
-

Fragment is the fragment part of http://www.msft.com/some/path?query#fragment.

-
-
- - - -fsPath: string -
-

The string representing the corresponding file system path of this Uri.

-

Will handle UNC paths and normalize windows drive letters to lower-case. Also -uses the platform specific path separator.

-
    -
  • Will not validate the path for invalid characters and semantics.
    • -
  • Will not look at the scheme of this Uri.
    • -
  • The resulting string shall not be used for display purposes but -for disk operations, like readFile et al.
    • -
-

The difference to the path-property is the use of the platform specific -path separator and the handling of UNC paths. The sample below outlines the difference:

- -
const u = URI.parse('file://server/c$/folder/file.txt')
-u.authority === 'server'
-u.path === '/shares/c$/file.txt'
-u.fsPath === '\\server\c$\folder\file.txt'
-
-
-
- - - -path: string -
-

Path is the /some/path part of http://www.msft.com/some/path?query#fragment.

-
-
- - - -query: string -
-

Query is the query part of http://www.msft.com/some/path?query#fragment.

-
-
- - - -scheme: string -
-

Scheme is the http part of http://www.msft.com/some/path?query#fragment. -The part before the first colon.

-
-
- -#### Methods - - - -toJSON(): any -
-

Returns a JSON representation of this Uri.

-
-
- - - -
ReturnsDescription
any

An object.

-
-
-
- - - -toString(skipEncoding?: boolean): string -
-

Returns a string representation of this Uri. The representation and normalization -of a URI depends on the scheme.

-
    -
  • The resulting string can be safely used with Uri.parse.
    • -
  • The resulting string shall not be used for display purposes.
    • -
-

Note that the implementation will encode aggressive which often leads to unexpected, -but not incorrect, results. For instance, colons are encoded to %3A which might be unexpected -in file-uri. Also & and = will be encoded which might be unexpected for http-uris. For stability -reasons this cannot be changed anymore. If you suffer from too aggressive encoding you should use -the skipEncoding-argument: uri.toString(true).

-
-
- - - - - -
ParameterDescription
skipEncoding?: boolean

Do not percentage-encode the result, defaults to false. Note that - the # and ? characters occurring in the path will always be encoded.

-
ReturnsDescription
string

A string representation of this Uri.

-
-
-
- - - -with(change: {authority: string, fragment: string, path: string, query: string, scheme: string}): Uri -
-

Derive a new Uri from this Uri.

- -
let file = Uri.parse('before:some/file/path');
-let other = file.with({ scheme: 'after' });
-assert.ok(other.toString() === 'after:some/file/path');
-
-
-
- - - - - -
ParameterDescription
change: {authority: string, fragment: string, path: string, query: string, scheme: string}

An object that describes a change to this Uri. To unset components use null or - the empty string.

-
ReturnsDescription
Uri

A new Uri that reflects the given change. Will return this Uri if the change - is not changing anything.

-
-
-
- -### UriHandler - - - -

A uri handler is responsible for handling system-wide uris.

- -
- -#### Methods - - - -handleUri(uri: Uri): ProviderResult<void> -
-

Handle the provided system-wide uri.

- -
-
- - - - - -
ParameterDescription
uri: Uri
ReturnsDescription
ProviderResult<void>
-
-
- -### ViewColumn - - - -

Denotes a location of an editor in the window. Editors can be arranged in a grid -and each column represents one editor location in that grid by counting the editors -in order of their appearance.

-
- -#### Enumeration members - - - -Active -
- -1 -
- - - -Beside -
- -2 -
- - - -Eight -
-8 -
- - - -Five -
-5 -
- - - -Four -
-4 -
- - - -Nine -
-9 -
- - - -One -
-1 -
- - - -Seven -
-7 -
- - - -Six -
-6 -
- - - -Three -
-3 -
- - - -Two -
-2 -
- -### Webview - - - -

Displays html content, similarly to an iframe.

-
- -#### Events - - - -onDidReceiveMessage: Event<any> -
-

Fired when the webview content posts a message.

-

Webview content can post strings or json serializable objects back to a VS Code extension. They cannot -post Blob, File, ImageData and other DOM specific objects since the extension that receives the -message does not run in a browser environment.

-
-
- -#### Properties - - - -cspSource: string -
-

Content security policy source for webview resources.

-

This is the origin that should be used in a content security policy rule:

- -
img-src https: ${webview.cspSource} ...;
-
-
- - - -html: string -
-

HTML contents of the webview.

-

This should be a complete, valid html document. Changing this property causes the webview to be reloaded.

-

Webviews are sandboxed from normal extension process, so all communication with the webview must use -message passing. To send a message from the extension to the webview, use postMessage. -To send message from the webview back to an extension, use the acquireVsCodeApi function inside the webview -to get a handle to VS Code's api and then call .postMessage():

- -
<script>
-    const vscode = acquireVsCodeApi(); // acquireVsCodeApi can only be invoked once
-    vscode.postMessage({ message: 'hello!' });
-</script>
-
-

To load a resources from the workspace inside a webview, use the [asWebviewUri](#Webview.asWebviewUri) method -and ensure the resource's directory is listed in WebviewOptions.localResourceRoots.

-

Keep in mind that even though webviews are sandboxed, they still allow running scripts and loading arbitrary content, -so extensions must follow all standard web security best practices when working with webviews. This includes -properly sanitizing all untrusted input (including content from the workspace) and -setting a content security policy.

-
-
- - - -options: WebviewOptions -
-

Content settings for the webview.

-
-
- -#### Methods - - - -asWebviewUri(localResource: Uri): Uri -
-

Convert a uri for the local file system to one that can be used inside webviews.

-

Webviews cannot directly load resources from the workspace or local file system using file: uris. The -asWebviewUri function takes a local file: uri and converts it into a uri that can be used inside of -a webview to load the same resource:

- -
webview.html = `<img src="${webview.asWebviewUri(vscode.Uri.file('/Users/codey/workspace/cat.gif'))}">`
-
-
-
- - - - - -
ParameterDescription
localResource: Uri
ReturnsDescription
Uri
-
-
- - - -postMessage(message: any): Thenable<boolean> -
-

Post a message to the webview content.

-

Messages are only delivered if the webview is live (either visible or in the -background with retainContextWhenHidden).

-
-
- - - - - -
ParameterDescription
message: any

Body of the message. This must be a string or other json serializable object.

-
ReturnsDescription
Thenable<boolean>
-
-
- -### WebviewOptions - - - -

Content settings for a webview.

-
- -#### Properties - - - -enableCommandUris?: boolean -
-

Controls whether command uris are enabled in webview content or not.

-

Defaults to false.

-
-
- - - -enableScripts?: boolean -
-

Controls whether scripts are enabled in the webview content or not.

-

Defaults to false (scripts-disabled).

-
-
- - - -localResourceRoots?: ReadonlyArray<Uri> -
-

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.

-
-
- - - -portMapping?: ReadonlyArray<WebviewPortMapping> -
-

Mappings of localhost ports used inside the webview.

-

Port mapping allow webviews to transparently define how localhost ports are resolved. This can be used -to allow using a static localhost port inside the webview that is resolved to random port that a service is -running on.

-

If a webview accesses localhost content, we recommend that you specify port mappings even if -the webviewPort and extensionHostPort ports are the same.

-

Note that port mappings only work for http or https urls. Websocket urls (e.g. ws://localhost:3000) -cannot be mapped to another port.

-
-
- -### WebviewPanel - - - -

A panel that contains a webview.

-
- -#### Events - - - -onDidChangeViewState: Event<WebviewPanelOnDidChangeViewStateEvent> -
-

Fired when the panel's view state changes.

-
-
- - - -onDidDispose: Event<void> -
-

Fired when the panel is disposed.

-

This may be because the user closed the panel or because .dispose() was -called on it.

-

Trying to use the panel after it has been disposed throws an exception.

-
-
- -#### Properties - - - -active: boolean -
-

Whether the panel is active (focused by the user).

-
-
- - - -iconPath?: Uri | {dark: Uri, light: Uri} -
-

Icon for the panel shown in UI.

-
-
- - - -options: WebviewPanelOptions -
-

Content settings for the webview panel.

-
-
- - - -title: string -
-

Title of the panel shown in UI.

-
-
- - - -viewColumn?: ViewColumn -
-

Editor position of the panel. This property is only set if the webview is in -one of the editor view columns.

-
-
- - - -viewType: string -
-

Identifies the type of the webview panel, such as 'markdown.preview'.

-
-
- - - -visible: boolean -
-

Whether the panel is visible.

-
-
- - - -webview: Webview -
-

Webview belonging to the panel.

-
-
- -#### Methods - - - -dispose(): any -
-

Dispose of the webview panel.

-

This closes the panel if it showing and disposes of the resources owned by the webview. -Webview panels are also disposed when the user closes the webview panel. Both cases -fire the onDispose event.

-
-
- - - -
ReturnsDescription
any
-
-
- - - -reveal(viewColumn?: ViewColumn, preserveFocus?: boolean): void -
-

Show the webview panel in a given column.

-

A webview panel may only show in a single column at a time. If it is already showing, this -method moves it to a new column.

-
-
- - - - - - -
ParameterDescription
viewColumn?: ViewColumn

View column to show the panel in. Shows in the current viewColumn if undefined.

-
preserveFocus?: boolean

When true, the webview will not take focus.

-
ReturnsDescription
void
-
-
- -### WebviewPanelOnDidChangeViewStateEvent - - - -

Event fired when a webview panel's view state changes.

-
- -#### Properties - - - -webviewPanel: WebviewPanel -
-

Webview panel whose view state changed.

-
-
- -### WebviewPanelOptions - - - -

Content settings for a webview panel.

-
- -#### Properties - - - -enableFindWidget?: boolean -
-

Controls if the find widget is enabled in the panel.

-

Defaults to false.

-
-
- - - -retainContextWhenHidden?: boolean -
-

Controls if the webview panel's content (iframe) is kept around even when the panel -is no longer visible.

-

Normally the webview panel's html context is created when the panel becomes visible -and destroyed when it is hidden. Extensions that have complex state -or UI can set the retainContextWhenHidden to make VS Code keep the webview -context around, even when the webview moves to a background tab. When a webview using -retainContextWhenHidden becomes hidden, its scripts and other dynamic content keep running. -With retainContextWhenHidden enabled, you can messages to a -hidden webview.

-

retainContextWhenHidden has a high memory overhead and should only be used if -your panel's context cannot be quickly saved and restored.

-
-
- -### WebviewPanelSerializer<T> - - - -

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

-

There are two types of webview persistence:

- -

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

-

Persistence within a session allows a webview to save its state when it becomes hidden -and restore its content from this state when it becomes visible again. It is powered entirely -by the webview content itself. To save off a persisted state, call acquireVsCodeApi().setState() with -any json serializable object. To restore the state again, call getState()

- -
// Within the webview
-const vscode = acquireVsCodeApi();
-
-// Get existing state
-const oldState = vscode.getState() || { value: 0 };
-
-// Update state
-setState({ value: oldState.value + 1 })
-
-

A WebviewPanelSerializer extends this persistence across restarts of VS Code. When the editor is shutdown, -VS Code will save off the state from setState of all webviews that have a serializer. When the -webview first becomes visible after the restart, this state is passed to deserializeWebviewPanel. -The extension can then restore the old WebviewPanel from this state.

-
- -#### Methods - - - -deserializeWebviewPanel(webviewPanel: WebviewPanel, state: T): Thenable<void> -
-

Restore a webview panel from its serialized state.

-

Called when a serialized webview first becomes visible.

-
-
- - - - - - -
ParameterDescription
webviewPanel: WebviewPanel

Webview panel to restore. The serializer should take ownership of this panel. The -serializer must restore the webview's .html and hook up all webview events.

-
state: T

Persisted state from the webview content.

-
ReturnsDescription
Thenable<void>

Thenable indicating that the webview has been fully restored.

-
-
-
- -### WebviewPortMapping - - - -

Defines a port mapping used for localhost inside the webview.

-
- -#### Properties - - - -extensionHostPort: number -
-

Destination port. The webviewPort is resolved to this port.

-
-
- - - -webviewPort: number -
-

Localhost port to remap inside the webview.

-
-
- -### WebviewView - - - -

A webview based view.

-
- -#### Events - - - -onDidChangeVisibility: Event<void> -
-

Event fired when the visibility of the view changes.

-

Actions that trigger a visibility change:

-
    -
  • The view is collapsed or expanded.
    • -
  • The user switches to a different view group in the sidebar or panel.
    • -
-

Note that hiding a view using the context menu instead disposes of the view and fires onDidDispose.

-
-
- - - -onDidDispose: Event<void> -
-

Event fired when the view is disposed.

-

Views are disposed when they are explicitly hidden by a user (this happens when a user -right clicks in a view and unchecks the webview view).

-

Trying to use the view after it has been disposed throws an exception.

-
-
- -#### Properties - - - -description?: string -
-

Human-readable string which is rendered less prominently in the title.

-
-
- - - -title?: string -
-

View title displayed in the UI.

-

The view title is initially taken from the extension package.json contribution.

-
-
- - - -viewType: string -
-

Identifies the type of the webview view, such as 'hexEditor.dataView'.

-
-
- - - -visible: boolean -
-

Tracks if the webview is currently visible.

-

Views are visible when they are on the screen and expanded.

-
-
- - - -webview: Webview -
-

The underlying webview for the view.

-
-
- -#### Methods - - - -show(preserveFocus?: boolean): void -
-

Reveal the view in the UI.

-

If the view is collapsed, this will expand it.

-
-
- - - - - -
ParameterDescription
preserveFocus?: boolean

When true the view will not take focus.

-
ReturnsDescription
void
-
-
- -### WebviewViewProvider - - - -

Provider for creating WebviewView elements.

-
- -#### Methods - - - -resolveWebviewView(webviewView: WebviewView, context: WebviewViewResolveContext, token: CancellationToken): Thenable<void> | void -
-

Revolves a webview view.

-

resolveWebviewView is called when a view first becomes visible. This may happen when the view is -first loaded or when the user hides and then shows a view again.

-
-
- - - - - - - -
ParameterDescription
webviewView: WebviewView

Webview view to restore. The provider should take ownership of this view. The - provider must set the webview's .html and hook up all webview events it is interested in.

-
context: WebviewViewResolveContext

Additional metadata about the view being resolved.

-
token: CancellationToken

Cancellation token indicating that the view being provided is no longer needed.

-
ReturnsDescription
Thenable<void> | void

Optional thenable indicating that the view has been fully resolved.

-
-
-
- -### WebviewViewResolveContext<T> - - - -

Additional information the webview view being resolved.

-
- -#### Properties - - - -state: T | undefined -
-

Persisted state from the webview content.

-

To save resources, VS Code normally deallocates webview documents (the iframe content) that are not visible. -For example, when the user collapse a view or switches to another top level activity in the sidebar, the -WebviewView itself is kept alive but the webview's underlying document is deallocated. It is recreated when -the view becomes visible again.

-

You can prevent this behavior by setting retainContextWhenHidden in the WebviewOptions. However this -increases resource usage and should be avoided wherever possible. Instead, you can use persisted state to -save off a webview's state so that it can be quickly recreated as needed.

-

To save off a persisted state, inside the webview call acquireVsCodeApi().setState() with -any json serializable object. To restore the state again, call getState(). For example:

- -
// Within the webview
-const vscode = acquireVsCodeApi();
-
-// Get existing state
-const oldState = vscode.getState() || { value: 0 };
-
-// Update state
-setState({ value: oldState.value + 1 })
-
-

VS Code ensures that the persisted state is saved correctly when a webview is hidden and across -editor restarts.

-
-
- -### WindowState - - - -

Represents the state of a window.

-
- -#### Properties - - - -focused: boolean -
-

Whether the current window is focused.

-
-
- -### WorkspaceConfiguration - - - -

Represents the configuration. It is a merged view of

- -

The effective value (returned by get) is computed by overriding or merging the values in the following order.

- -
`defaultValue` (if defined in `package.json` otherwise derived from the value's type)
-`globalValue` (if defined)
-`workspaceValue` (if defined)
-`workspaceFolderValue` (if defined)
-`defaultLanguageValue` (if defined)
-`globalLanguageValue` (if defined)
-`workspaceLanguageValue` (if defined)
-`workspaceFolderLanguageValue` (if defined)
-

Note: Only object value types are merged and all other value types are overridden.

-

Example 1: Overriding

- -
defaultValue = 'on';
-globalValue = 'relative'
-workspaceFolderValue = 'off'
-value = 'off'
-
-

Example 2: Language Values

- -
defaultValue = 'on';
-globalValue = 'relative'
-workspaceFolderValue = 'off'
-globalLanguageValue = 'on'
-value = 'on'
-
-

Example 3: Object Values

- -
defaultValue = { "a": 1, "b": 2 };
-globalValue = { "b": 3, "c": 4 };
-value = { "a": 1, "b": 3, "c": 4 };
-
-

Note: Workspace and Workspace Folder configurations contains launch and tasks settings. Their basename will be -part of the section identifier. The following snippets shows how to retrieve all configurations -from launch.json:

- -
// launch.json configuration
-const config = workspace.getConfiguration('launch', vscode.workspace.workspaceFolders[0].uri);
-
-// retrieve values
-const values = config.get('configurations');
-
-

Refer to Settings for more information.

-
- -#### Methods - - - -get<T>(section: string): T | undefined -
-

Return a value from this configuration.

-
-
- - - - - -
ParameterDescription
section: string

Configuration name, supports dotted names.

-
ReturnsDescription
T | undefined

The value section denotes or undefined.

-
-
-
- - - -get<T>(section: string, defaultValue: T): T -
-

Return a value from this configuration.

-
-
- - - - - - -
ParameterDescription
section: string

Configuration name, supports dotted names.

-
defaultValue: T

A value should be returned when no value could be found, is undefined.

-
ReturnsDescription
T

The value section denotes or the default.

-
-
-
- - - -has(section: string): boolean -
-

Check if this configuration has a certain value.

-
-
- - - - - -
ParameterDescription
section: string

Configuration name, supports dotted names.

-
ReturnsDescription
boolean

true if the section doesn't resolve to undefined.

-
-
-
- - - -inspect<T>(section: string): {defaultLanguageValue: T, defaultValue: T, globalLanguageValue: T, globalValue: T, key: string, languageIds: string[], workspaceFolderLanguageValue: T, workspaceFolderValue: T, workspaceLanguageValue: T, workspaceValue: T} | undefined -
-

Retrieve all information about a configuration setting. A configuration value -often consists of a default value, a global or installation-wide value, -a workspace-specific value, folder-specific value -and language-specific values (if WorkspaceConfiguration is scoped to a language).

-

Also provides all language IDs under which the given configuration setting is defined.

-

Note: The configuration name must denote a leaf in the configuration tree -(editor.fontSize vs editor) otherwise no result is returned.

-
-
- - - - - -
ParameterDescription
section: string

Configuration name, supports dotted names.

-
ReturnsDescription
{defaultLanguageValue: T, defaultValue: T, globalLanguageValue: T, globalValue: T, key: string, languageIds: string[], workspaceFolderLanguageValue: T, workspaceFolderValue: T, workspaceLanguageValue: T, workspaceValue: T} | undefined

Information about a configuration setting or undefined.

-
-
-
- - - -update(section: string, value: any, configurationTarget?: ConfigurationTarget | boolean, overrideInLanguage?: boolean): Thenable<void> -
-

Update a configuration value. The updated configuration values are persisted.

-

A value can be changed in

- -

Note: To remove a configuration value use undefined, like so: config.update('somekey', undefined)

-
    -
  • 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.
      • -
    -
    • -
-
-
- - - - - - - - -
ParameterDescription
section: string

Configuration name, supports dotted names.

-
value: any

The new value.

-
configurationTarget?: ConfigurationTarget | boolean

The configuration target or a boolean value.

- -
- If `true` updates [Global settings](#ConfigurationTarget.Global).
-- If `false` updates [Workspace settings](#ConfigurationTarget.Workspace).
-- If `undefined` or `null` updates to [Workspace folder settings](#ConfigurationTarget.WorkspaceFolder) if configuration is resource specific,
-otherwise to [Workspace settings](#ConfigurationTarget.Workspace).
-
overrideInLanguage?: boolean

Whether to update the value in the scope of requested languageId or not.

- -
- If `true` updates the value under the requested languageId.
-- If `undefined` updates the value under the requested languageId only if the configuration is defined for the language.
-
ReturnsDescription
Thenable<void>
-
-
- -### WorkspaceEdit - - - -

A workspace edit is a collection of textual and files changes for -multiple resources and documents.

-

Use the applyEdit-function to apply a workspace edit.

-
- -#### Properties - - - -size: number -
-

The number of affected resources of textual or resource changes.

-
-
- -#### Methods - - - -createFile(uri: Uri, options?: {ignoreIfExists: boolean, overwrite: boolean}, metadata?: WorkspaceEditEntryMetadata): void -
-

Create a regular file.

-
-
- - - - - - - -
ParameterDescription
uri: Uri

Uri of the new file..

-
options?: {ignoreIfExists: boolean, overwrite: boolean}

Defines if an existing file should be overwritten or be -ignored. When overwrite and ignoreIfExists are both set overwrite wins. -When both are unset and when the file already exists then the edit cannot -be applied successfully.

-
metadata?: WorkspaceEditEntryMetadata

Optional metadata for the entry.

-
ReturnsDescription
void
-
-
- - - -delete(uri: Uri, range: Range, metadata?: WorkspaceEditEntryMetadata): void -
-

Delete the text at the given range.

-
-
- - - - - - - -
ParameterDescription
uri: Uri

A resource identifier.

-
range: Range

A range.

-
metadata?: WorkspaceEditEntryMetadata

Optional metadata for the entry.

-
ReturnsDescription
void
-
-
- - - -deleteFile(uri: Uri, options?: {ignoreIfNotExists: boolean, recursive: boolean}, metadata?: WorkspaceEditEntryMetadata): void -
-

Delete a file or folder.

-
-
- - - - - - - -
ParameterDescription
uri: Uri

The uri of the file that is to be deleted.

-
options?: {ignoreIfNotExists: boolean, recursive: boolean}
metadata?: WorkspaceEditEntryMetadata

Optional metadata for the entry.

-
ReturnsDescription
void
-
-
- - - -entries(): [Uri, TextEdit[]][] -
-

Get all text edits grouped by resource.

-
-
- - - -
ReturnsDescription
[Uri, TextEdit[]][]

A shallow copy of [Uri, TextEdit[]]-tuples.

-
-
-
- - - -get(uri: Uri): TextEdit[] -
-

Get the text edits for a resource.

-
-
- - - - - -
ParameterDescription
uri: Uri

A resource identifier.

-
ReturnsDescription
TextEdit[]

An array of text edits.

-
-
-
- - - -has(uri: Uri): boolean -
-

Check if a text edit for a resource exists.

-
-
- - - - - -
ParameterDescription
uri: Uri

A resource identifier.

-
ReturnsDescription
boolean

true if the given resource will be touched by this edit.

-
-
-
- - - -insert(uri: Uri, position: Position, newText: string, metadata?: WorkspaceEditEntryMetadata): void -
-

Insert the given text at the given position.

-
-
- - - - - - - - -
ParameterDescription
uri: Uri

A resource identifier.

-
position: Position

A position.

-
newText: string

A string.

-
metadata?: WorkspaceEditEntryMetadata

Optional metadata for the entry.

-
ReturnsDescription
void
-
-
- - - -renameFile(oldUri: Uri, newUri: Uri, options?: {ignoreIfExists: boolean, overwrite: boolean}, metadata?: WorkspaceEditEntryMetadata): void -
-

Rename a file or folder.

-
-
- - - - - - - - -
ParameterDescription
oldUri: Uri

The existing file.

-
newUri: Uri

The new location.

-
options?: {ignoreIfExists: boolean, overwrite: boolean}

Defines if existing files should be overwritten or be -ignored. When overwrite and ignoreIfExists are both set overwrite wins.

-
metadata?: WorkspaceEditEntryMetadata

Optional metadata for the entry.

-
ReturnsDescription
void
-
-
- - - -replace(uri: Uri, range: Range, newText: string, metadata?: WorkspaceEditEntryMetadata): void -
-

Replace the given range with given text for the given resource.

-
-
- - - - - - - - -
ParameterDescription
uri: Uri

A resource identifier.

-
range: Range

A range.

-
newText: string

A string.

-
metadata?: WorkspaceEditEntryMetadata

Optional metadata for the entry.

-
ReturnsDescription
void
-
-
- - - -set(uri: Uri, edits: TextEdit[]): void -
-

Set (and replace) text edits for a resource.

-
-
- - - - - - -
ParameterDescription
uri: Uri

A resource identifier.

-
edits: TextEdit[]

An array of text edits.

-
ReturnsDescription
void
-
-
- -### WorkspaceEditEntryMetadata - - - -

Additional data for entries of a workspace edit. Supports to label entries and marks entries -as needing confirmation by the user. The editor groups edits with equal labels into tree nodes, -for instance all edits labelled with "Changes in Strings" would be a tree node.

-
- -#### Properties - - - -description?: string -
-

A human-readable string which is rendered less prominent on the same line.

-
-
- - - -iconPath?: Uri | {dark: Uri, light: Uri} | ThemeIcon -
-

The icon path or ThemeIcon for the edit.

-
-
- - - -label: string -
-

A human-readable string which is rendered prominent.

-
-
- - - -needsConfirmation: boolean -
-

A flag which indicates that user confirmation is needed.

-
-
- -### WorkspaceFolder - - - -

A workspace folder is one of potentially many roots opened by the editor. All workspace folders -are equal which means there is no notion of an active or primary workspace folder.

-
- -#### Properties - - - -index: number -
-

The ordinal number of this workspace folder.

-
-
- - - -name: string -
-

The name of this workspace folder. Defaults to -the basename of its uri-path

-
-
- - - -uri: Uri -
-

The associated uri for this workspace folder.

-

Note: The Uri-type was intentionally chosen such that future releases of the editor can support -workspace folders that are not stored on the local disk, e.g. ftp://server/workspaces/foo.

-
-
- -### WorkspaceFolderPickOptions - - - -

Options to configure the behaviour of the workspace folder pick UI.

-
- -#### Properties - - - -ignoreFocusOut?: boolean -
-

Set to true to keep the picker open when focus moves to another part of the editor or to another window.

-
-
- - - -placeHolder?: string -
-

An optional string to show as placeholder in the input box to guide the user what to pick on.

-
-
- -### WorkspaceFoldersChangeEvent - - - -

An event describing a change to the set of workspace folders.

-
- -#### Properties - - - -added: ReadonlyArray<WorkspaceFolder> -
-

Added workspace folders.

-
-
- - - -removed: ReadonlyArray<WorkspaceFolder> -
-

Removed workspace folders.

-
-
- -### WorkspaceSymbolProvider<T> - - - -

The workspace symbol provider interface defines the contract between extensions and -the symbol search-feature.

-
- -#### Methods - - - -provideWorkspaceSymbols(query: string, token: CancellationToken): ProviderResult<T[]> -
-

Project-wide search for a symbol matching the given query string.

-

The query-parameter should be interpreted in a relaxed way as the editor will apply its own highlighting -and scoring on the results. A good rule of thumb is to match case-insensitive and to simply check that the -characters of query appear in their order in a candidate symbol. Don't use prefix, substring, or similar -strict matching.

-

To improve performance implementors can implement resolveWorkspaceSymbol and then provide symbols with partial -location-objects, without a range defined. The editor will then call -resolveWorkspaceSymbol for selected symbols only, e.g. when opening a workspace symbol.

-
-
- - - - - - -
ParameterDescription
query: string

A query string, can be the empty string in which case all symbols should be returned.

-
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<T[]>

An array of document highlights or a thenable that resolves to such. The lack of a result can be -signaled by returning undefined, null, or an empty array.

-
-
-
- - - -resolveWorkspaceSymbol(symbol: T, token: CancellationToken): ProviderResult<T> -
-

Given a symbol fill in its location. This method is called whenever a symbol -is selected in the UI. Providers can implement this method and return incomplete symbols from -provideWorkspaceSymbols which often helps to improve -performance.

-
-
- - - - - - -
ParameterDescription
symbol: T

The symbol that is to be resolved. Guaranteed to be an instance of an object returned from an -earlier call to provideWorkspaceSymbols.

-
token: CancellationToken

A cancellation token.

-
ReturnsDescription
ProviderResult<T>

The resolved symbol or a thenable that resolves to that. When no result is returned, -the given symbol is used.

-
-
-
- - - -## API Patterns - -These are some of the common patterns we use in the VS Code API. - -### Promises - -The VS Code API represents asynchronous operations with [promises](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise). From extensions, __any__ type of promise can be returned, like ES6, WinJS, A+, etc. - -Being independent of a specific promise library is expressed in the API by the `Thenable`-type. `Thenable` represents the common denominator which is the [then](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise/then) method. - -In most cases the use of promises is optional and when VS Code calls into an extension, it can handle the _result type_ as well as a `Thenable` of the _result type_. When the use of a promise is optional, the API indicates this by returning `or`-types. - -```typescript -provideNumber(): number | Thenable -``` - -### Cancellation Tokens - -Often operations are started on volatile state which changes before operations can finish. For instance, computing IntelliSense starts and the user continues to type making the result of that operation obsolete. - -APIs that are exposed to such behavior will get passed a `CancellationToken` on which you can check for cancellation (`isCancellationRequested`) or get notified when cancellation occurs (`onCancellationRequested`). The cancellation token is usually the last parameter of a function call and optional. - -### Disposables - -The VS Code API uses the [dispose pattern](https://en.wikipedia.org/wiki/Dispose_pattern) for resources that are obtained from VS Code. This applies to event listening, commands, interacting with the UI, and various language contributions. - -For instance, the `setStatusBarMessage(value: string)` function returns a `Disposable` which upon calling `dispose` removes the message again. - -### Events - -Events in the VS Code API are exposed as functions which you call with a listener-function to subscribe. Calls to subscribe return a `Disposable` which removes the event listener upon dispose. - -```javascript -var listener = function(event) { - console.log("It happened", event); -}; - -// start listening -var subscription = fsWatcher.onDidDelete(listener); - -// do more stuff - -subscription.dispose(); // stop listening -``` - -Names of events follow the `on[Will|Did]VerbNoun?` pattern. The name signals if the event is going to happen *(onWill)* or already happened *(onDid)*, what happened *(verb)*, and the context *(noun)* unless obvious from the context. - -An example from the VS Code API is `window.onDidChangeActiveTextEditor` which is an event fired when the active text editor *(noun)* has been (*onDid*) changed (*verb*). - -### Strict null - -The VS Code API uses the `undefined` and `null` TypeScript types where appropriate to support [strict null checking](https://github.com/microsoft/TypeScript/pull/7140). \ No newline at end of file