vscode namespace API

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:

  • palette - Use the commands-section in package.json to make a command show in the command palette.
  • keybinding - Use the keybindings-section in package.json to enable keybindings for your extension.

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

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.

debug

Namespace for dealing with debug sessions.

Variables

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 drop down menu of the debug action floating window. If no debug session is active, the value is undefined.

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.

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

startDebugging(folder: WorkspaceFolder | undefined, nameOrConfiguration: string | DebugConfiguration): 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. '${workspaceRoot}') 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.

ReturnsDescription
Thenable<boolean>

A thenable that resolves when debugging could be successfully started.

env

Namespace describing the environment the editor runs in.

Variables

appName: string

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

  • readonly

appRoot: string

The application root folder from which the editor is running.

  • readonly

language: string

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

  • readonly

machineId: string

A unique identifier for the computer.

  • readonly

sessionId: string

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

  • readonly

extensions

Namespace for dealing with installed extensions. Extensions are represented by an extension-interface which allows to reflect 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 extensionDependency-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: Extension<any>[]

All extensions currently known to the system.

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

Functions

createDiagnosticCollection(name?: string): DiagnosticCollection

Create a diagnostics collection.

ParameterDescription
name?: string

The name of the collection.

ReturnsDescription
DiagnosticCollection

A new diagnostic collection.

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. A string will be desugared to become the language-part of a DocumentFilter, so "fooLang" is like { language: "fooLang" }.
  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. When scheme, language, or pattern are defined but one doesn’t match, the result is 0
    3. Matching against * gives a score of 5, matching via equality or via a glob-pattern gives a score of 10
    4. The result is the maximun value of each match

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.

registerCodeActionsProvider(selector: DocumentSelector, provider: CodeActionProvider): 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.

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.

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.

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, like . or :.

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.

registerDocumentSymbolProvider(selector: DocumentSelector, provider: DocumentSymbolProvider): 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.

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

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

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.

scm

Variables

inputBox: SourceControlInputBox

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

Functions

createSourceControl(id: string, label: string): SourceControl

Creates a new source control instance.

ParameterDescription
id: string

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

label: string

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

ReturnsDescription
SourceControl

An instance of source control.

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

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.

  • readonly

visibleTextEditors: TextEditor[]

The currently visible editors or an empty array.

Events

onDidChangeActiveTextEditor: Event<TextEditor>

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.

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.

Functions

createOutputChannel(name: string): OutputChannel

Create 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

createStatusBarItem(alignment?: StatusBarAlignment.Left | StatusBarAlignment.Right, priority?: number): StatusBarItem

Creates a status bar item.

ParameterDescription
alignment?: StatusBarAlignment.Left | StatusBarAlignment.Right

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[]): Terminal

Creates a Terminal. The cwd of the terminal will be the workspace directory if it exists, regardless of whether an explicit customStartPath setting exists.

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[]

Optional args for the custom shell executable, this does not work on Windows (see #8429)

ReturnsDescription
Terminal

A new Terminal.

createTerminal(options: TerminalOptions): Terminal

Creates a Terminal. The cwd of the terminal will be the workspace directory if it exists, regardless of whether an explicit customStartPath setting exists.

ParameterDescription
options: TerminalOptions

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

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

Register a TreeDataProvider for the view contributed using the extension point views.

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

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.

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

showTextDocument(document: TextDocument, column?: ViewColumn.One | ViewColumn.Two | ViewColumn.Three, 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.One | ViewColumn.Two | ViewColumn.Three

A view column in which the editor should be shown. The default is the one, other values are adjusted to be Min(column, columnCount + 1).

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

(#_ShowTextDocumentOptions) 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

(#_ShowTextDocumentOptions) 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.

withProgress<R>(options: ProgressOptions, task: (progress: Progress<{message: string}>) => 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<{message: string}>) => Thenable<R>

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

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

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

rootPath: string | undefined

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

  • readonly

textDocuments: TextDocument[]

All text documents currently known to the system.

  • readonly

workspaceFolders: WorkspaceFolder[] | undefined

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

  • readonly

Events

onDidChangeConfiguration: Event<void>

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.

onDidOpenTextDocument: Event<TextDocument>

An event that is emitted when a text document is opened.

onDidSaveTextDocument: Event<TextDocument>

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

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 as defined by the given workspace edit.

When applying a workspace edit, the editor implements an 'all-or-nothing'-strategy, that means failure to load one document or make changes to one document will cause the edit to be rejected.

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: string, ignoreCreateEvents?: boolean, ignoreChangeEvents?: boolean, ignoreDeleteEvents?: boolean): FileSystemWatcher

Creates a file system watcher.

A glob pattern that filters the file events 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: string

A glob pattern that is applied to the names of created, changed, and deleted files.

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: string, exclude?: string, maxResults?: number, token?: CancellationToken): Thenable<Uri[]>

Find files in the workspace.

  • sample - findFiles('**∕*.js', '**∕node_modules∕**', 10)
ParameterDescription
include: string

A glob pattern that defines the files to search for.

exclude?: string

A glob pattern that defines files and folders to exclude.

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.

getConfiguration(section?: string, resource?: Uri): 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 resource is provided, configuration scoped to that resource is returned.

ParameterDescription
section?: string

A dot-separated identifier.

resource?: Uri

A resource for which the configuration is asked for

ReturnsDescription
WorkspaceConfiguration

The full configuration or a subset.

getWorkspaceFolder(uri: Uri): WorkspaceFolder | undefined

Returns a workspace folder for the provided resource. When the resource is a workspace folder itself, its parent workspace folder or undefined is returned.

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 the registered text document content 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.

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.

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.

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. Will call cancel.

ReturnsDescription
void

CharacterPair

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

CharacterPair: [string, string]

CodeActionContext

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

Properties

diagnostics: Diagnostic[]

An array of diagnostics.

CodeActionProvider

The code action interface defines the contract between extensions and the light bulb feature.

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

Methods

provideCodeActions(document: TextDocument, range: Range, context: CodeActionContext, token: CancellationToken): ProviderResult<Command[]>

Provide commands for the given document and range.

ParameterDescription
document: TextDocument

The document in which the command was invoked.

range: Range

The range for which the command was invoked.

context: CodeActionContext

Context carrying additional information.

token: CancellationToken

A cancellation token.

ReturnsDescription
ProviderResult<Command[]>

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

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

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<CodeLens[]>

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<CodeLens[]>

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: CodeLens, token: CancellationToken): ProviderResult<CodeLens>

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

ParameterDescription
codeLens: CodeLens

code lens that must be resolved.

token: CancellationToken

A cancellation token.

ReturnsDescription
ProviderResult<CodeLens>

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

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 for command, when represented in the UI.

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

CompletionItem

A completion item represents a text snippet that is proposed to complete text that is being typed.

It is suffient 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 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.Text | CompletionItemKind.Method | CompletionItemKind.Function | CompletionItemKind.Constructor | CompletionItemKind.Field | CompletionItemKind.Variable | CompletionItemKind.Class | CompletionItemKind.Interface | CompletionItemKind.Module | CompletionItemKind.Property | CompletionItemKind.Unit | CompletionItemKind.Value | CompletionItemKind.Enum | CompletionItemKind.Keyword | CompletionItemKind.Snippet | CompletionItemKind.Color | CompletionItemKind.Reference | CompletionItemKind.File | CompletionItemKind.Folder | CompletionItemKind.EnumMember | CompletionItemKind.Constant | CompletionItemKind.Struct | CompletionItemKind.Event | CompletionItemKind.Operator | CompletionItemKind.TypeParameter): 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

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.

insertText?: string | SnippetString

A string or snippet that should be inserted in a document when selecting this completion. When falsy the label is used.

kind?: CompletionItemKind.Text | CompletionItemKind.Method | CompletionItemKind.Function | CompletionItemKind.Constructor | CompletionItemKind.Field | CompletionItemKind.Variable | CompletionItemKind.Class | CompletionItemKind.Interface | CompletionItemKind.Module | CompletionItemKind.Property | CompletionItemKind.Unit | CompletionItemKind.Value | CompletionItemKind.Enum | CompletionItemKind.Keyword | CompletionItemKind.Snippet | CompletionItemKind.Color | CompletionItemKind.Reference | CompletionItemKind.File | CompletionItemKind.Folder | CompletionItemKind.EnumMember | CompletionItemKind.Constant | CompletionItemKind.Struct | CompletionItemKind.Event | CompletionItemKind.Operator | CompletionItemKind.TypeParameter

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.

range?: Range

A range of text that should be replaced by this completion item.

Defaults to a range from the start of the current word to the current position.

Note: The range must be a single line and it must contain the position at which completion has been requested.

sortText?: string

A string that should be used when comparing this item with other items. When falsy the label is used.

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

Keyword

13

Method

1

Module

8

Operator

23

Property

9

Reference

17

Snippet

14

Struct

21

Text

0

TypeParameter

24

Unit

10

Value

11

Variable

5

CompletionItemProvider

The completion item provider interface defines the contract between extensions and IntelliSense.

When computing complete completion items is expensive, providers can optionally implement the resolveCompletionItem-function. In that case it is enough to return completion items with a label from the provideCompletionItems-function. Subsequently, when a completion item is shown in the UI and gains focus this provider is asked to resolve the item, like adding doc-comment or details.

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): ProviderResult<CompletionItem[] | CompletionList>

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.

ReturnsDescription
ProviderResult<CompletionItem[] | CompletionList>

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: CompletionItem, token: CancellationToken): ProviderResult<CompletionItem>

Given a completion item fill in more data, like doc-comment or details.

The editor will only resolve a completion item once.

ParameterDescription
item: CompletionItem

A completion item currently active in the UI.

token: CancellationToken

A cancellation token.

ReturnsDescription
ProviderResult<CompletionItem>

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.

CompletionList

Represents a collection of completion items to be presented in the editor.

Constructors

new CompletionList(items?: CompletionItem[], isIncomplete?: boolean): CompletionList

Creates a new completion list.

ParameterDescription
items?: CompletionItem[]

The completion items.

isIncomplete?: boolean

The list is not complete.

ReturnsDescription
CompletionList

Properties

isIncomplete?: boolean

This list it not complete. Further typing should result in recomputing this list.

items: CompletionItem[]

The completion items.

ConfigurationTarget

The configuration target

Enumeration members

Global

1

Workspace

2

WorkspaceFolder

3

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.

DebugSession

A debug session.

Properties

id: string

The unique ID of this debug session.

name: string

The debug session's name from the debug configuration.

type: string

The debug session's type from the debug configuration.

Methods

customRequest(command: string, args?: any): Thenable<any>

Send a custom request to the debug adapter.

ParameterDescription
command: string
args?: any
ReturnsDescription
Thenable<any>

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.

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 whereever 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. Alternativly a color from the color registry an 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.

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.

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.Left | OverviewRulerLane.Center | OverviewRulerLane.Right | OverviewRulerLane.Full

The position in the overview ruler where the decoration should be rendered.

rangeBehavior?: DecorationRangeBehavior.OpenOpen | DecorationRangeBehavior.ClosedClosed | DecorationRangeBehavior.OpenClosed | DecorationRangeBehavior.ClosedOpen

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[]

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>

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>

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.Error | DiagnosticSeverity.Warning | DiagnosticSeverity.Information | DiagnosticSeverity.Hint): Diagnostic

Creates a new diagnostic object.

ParameterDescription
range: Range

The range to which this diagnostic applies.

message: string

The human-readable message.

severity?: DiagnosticSeverity.Error | DiagnosticSeverity.Warning | DiagnosticSeverity.Information | DiagnosticSeverity.Hint

The severity, default is error.

ReturnsDescription
Diagnostic

Properties

code: string | number

A code or identifier for this diagnostics. Will not be surfaced to the user, but 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.

severity: DiagnosticSeverity.Error | DiagnosticSeverity.Warning | DiagnosticSeverity.Information | DiagnosticSeverity.Hint

The severity, default is error.

source: string

A human-readable string describing the source of this diagnostic, e.g. 'typescript' or 'super lint'.

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: Diagnostic[], collection: DiagnosticCollection) => any, thisArg?: any): void

Iterate over each entry in this collection.

ParameterDescription
callback: (uri: Uri, diagnostics: 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): 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
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: Diagnostic[] | undefined): void

Assign diagnostics for given resource. Will replace existing diagnostics for that resource.

ParameterDescription
uri: Uri

A resource identifier.

diagnostics: Diagnostic[] | undefined

Array of diagnostics or undefined

ReturnsDescription
void

set(entries: [Uri, 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: [Uri, Diagnostic[] | undefined][]

An array of tuples, like [[file1, [d1, d2]], [file2, [d3, d4, d5]]], or undefined.

ReturnsDescription
void

DiagnosticSeverity

Represents the severity of diagnostics.

Enumeration members

Error

0

Hint

3

Information

2

Warning

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

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.

  • sample - A language filter that applies to typescript files on disk: { language: 'typescript', scheme: 'file' }
  • sample - A language filter that applies to all package.json paths: { language: 'json', pattern: '**∕package.json' }

Properties

language?: string

A language id, like typescript.

pattern?: string

A glob pattern, like *.{ts,js}.

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.Text | DocumentHighlightKind.Read | DocumentHighlightKind.Write): DocumentHighlight

Creates a new document highlight object.

ParameterDescription
range: Range

The range the highlight applies to.

kind?: DocumentHighlightKind.Text | DocumentHighlightKind.Read | DocumentHighlightKind.Write

The highlight kind, default is text.

ReturnsDescription
DocumentHighlight

Properties

kind?: DocumentHighlightKind.Text | DocumentHighlightKind.Read | DocumentHighlightKind.Write

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.

DocumentLinkProvider

The document link provider defines the contract between extensions and feature of showing links in the editor.

Methods

provideDocumentLinks(document: TextDocument, token: CancellationToken): ProviderResult<DocumentLink[]>

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<DocumentLink[]>

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: DocumentLink, token: CancellationToken): ProviderResult<DocumentLink>

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 incomple links (without target) from the provideDocumentLinks method which often helps to improve performance.

ParameterDescription
link: DocumentLink

The link that is to be resolved.

token: CancellationToken

A cancellation token.

ReturnsDescription
ProviderResult<DocumentLink>

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.

DocumentSelector

A language selector is the combination of one or many language identifiers and language filters.

  • sample - let sel:DocumentSelector = 'typescript';
  • sample - let sel:DocumentSelector = ['typescript', { language: 'json', pattern: '**∕tsconfig.json' }];

DocumentSelector: string | DocumentFilter | string | DocumentFilter[]

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[]>

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[]>

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.

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.None | IndentAction.Indent | IndentAction.IndentOutdent | IndentAction.Outdent

Describe what to do with the indentation.

removeText?: number

Describes the number of characters to remove from the new line's indentation.

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.

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

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

extensionPath: string

The absolute file path of the directory containing this 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

extensionPath: string

The absolute file path of the directory containing the extension.

globalState: Memento

A memento object that stores state independent of the current opened workspace.

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.

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.

ParameterDescription
relativePath: string

A relative path to a resource contained in the extension.

ReturnsDescription
string

The absolute path of the resource.

FileSystemWatcher

A file system watcher notifies about changes to files and folders on disk.

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

FormattingOptions

Value-object describing what options formatting should use.

Properties

insertSpaces: boolean

Prefer spaces over tabs.

tabSize: number

Size of a tab in spaces.

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 implemenetation provider interface defines the contract between extensions and the go to implementation feature.

Methods

provideImplementation(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<Definition>

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>

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

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

Set to true to show a password prompt that will not show the typed value.

placeHolder?: string

An optional string to show as place holder 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

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

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

uri: Uri

The resource identifier of this location.

MarkdownString

The MarkdownString represents human readable text that supports formatting via the markdown syntax. Standard markdown is supported, also tables, but no embedded html.

Constructors

new MarkdownString(value?: string): MarkdownString

Creates a new markdown string with the given value.

ParameterDescription
value?: string

Optional, initial value.

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

value: string

The markdown string.

Methods

appendMarkdown(value: string): MarkdownString

Appends the given string 'as is' to this markdown string.

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.

  • deprecated - This type is deprecated, please use MarkdownString instead.

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

Indicates that this item replaces the default 'Close' action.

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.

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.One | ViewColumn.Two | ViewColumn.Three, preserveFocus?: boolean): void

Reveal this channel in the UI.

  • deprecated - Use the overload with just one parameter (show(preserveFocus?: boolean): void).
ParameterDescription
column?: ViewColumn.One | ViewColumn.Two | ViewColumn.Three

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, documentation?: string): ParameterInformation

Creates a new parameter information object.

ParameterDescription
label: string

A label string.

documentation?: string

A doc string.

ReturnsDescription
ParameterInformation

Properties

documentation?: string

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.

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 other is after this position.

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 other is after or equal to this position.

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 other is before this position.

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 other is before or equal to this position.

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 other equals this position.

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 or an updated percentage value

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

SourceControl

1

Window

10

ProgressOptions

Value-object describing where and how progress should show.

Properties

location: ProgressLocation.SourceControl | ProgressLocation.Window

The location at which progress should show.

title?: string

A human-readable string which will be used to describe the operation.

ProviderResult

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

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.

QuickPickItem

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

Properties

description: string

A human readable string which is rendered less prominent.

detail?: string

A human readable string which is rendered less prominent.

label: string

A human readable string which is rendered prominent.

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

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

RenameProvider

The rename provider interface defines the contract between extensions and the rename-feature.

Methods

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.

Selection

Represents a text selection in an editor.

Constructors

new Selection(anchor: Position, active: Position): Selection

Create a selection from two postions.

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.

ShellExecution

Constructors

new ShellExecution(commandLine: string, options?: ShellExecutionOptions): ShellExecution

Creates a process execution.

ParameterDescription
commandLine: string

The command line to execute.

options?: ShellExecutionOptions

Optional options for the started the shell.

ReturnsDescription
ShellExecution

Properties

commandLine: string

The shell command line

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.

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.

SignatureHelpProvider

The signature help provider interface defines the contract between extensions and the parameter hints-feature.

Methods

provideSignatureHelp(document: TextDocument, position: Position, token: CancellationToken): 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.

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.

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

Creates a new signature information object.

ParameterDescription
label: string

A label string.

documentation?: string

A doc string.

ReturnsDescription
SignatureInformation

Properties

documentation?: string

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

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

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.

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

value: string

Setter and getter for the contents of the input box.

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.

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

alignment: StatusBarAlignment.Left | StatusBarAlignment.Right

The alignment of this item.

color: string | ThemeColor | undefined

The foreground color for this entry.

command: string | undefined

The identifier of a command to run on click. The command must be known.

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 octicon 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.File | SymbolKind.Module | SymbolKind.Namespace | SymbolKind.Package | SymbolKind.Class | SymbolKind.Method | SymbolKind.Property | SymbolKind.Field | SymbolKind.Constructor | SymbolKind.Enum | SymbolKind.Interface | SymbolKind.Function | SymbolKind.Variable | SymbolKind.Constant | SymbolKind.String | SymbolKind.Number | SymbolKind.Boolean | SymbolKind.Array | SymbolKind.Object | SymbolKind.Key | SymbolKind.Null | SymbolKind.EnumMember | SymbolKind.Struct | SymbolKind.Event | SymbolKind.Operator | SymbolKind.TypeParameter, containerName: string, location: Location): SymbolInformation

new SymbolInformation(name: string, kind: SymbolKind.File | SymbolKind.Module | SymbolKind.Namespace | SymbolKind.Package | SymbolKind.Class | SymbolKind.Method | SymbolKind.Property | SymbolKind.Field | SymbolKind.Constructor | SymbolKind.Enum | SymbolKind.Interface | SymbolKind.Function | SymbolKind.Variable | SymbolKind.Constant | SymbolKind.String | SymbolKind.Number | SymbolKind.Boolean | SymbolKind.Array | SymbolKind.Object | SymbolKind.Key | SymbolKind.Null | SymbolKind.EnumMember | SymbolKind.Struct | SymbolKind.Event | SymbolKind.Operator | SymbolKind.TypeParameter, 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.File | SymbolKind.Module | SymbolKind.Namespace | SymbolKind.Package | SymbolKind.Class | SymbolKind.Method | SymbolKind.Property | SymbolKind.Field | SymbolKind.Constructor | SymbolKind.Enum | SymbolKind.Interface | SymbolKind.Function | SymbolKind.Variable | SymbolKind.Constant | SymbolKind.String | SymbolKind.Number | SymbolKind.Boolean | SymbolKind.Array | SymbolKind.Object | SymbolKind.Key | SymbolKind.Null | SymbolKind.EnumMember | SymbolKind.Struct | SymbolKind.Event | SymbolKind.Operator | SymbolKind.TypeParameter

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.File | SymbolKind.Module | SymbolKind.Namespace | SymbolKind.Package | SymbolKind.Class | SymbolKind.Method | SymbolKind.Property | SymbolKind.Field | SymbolKind.Constructor | SymbolKind.Enum | SymbolKind.Interface | SymbolKind.Function | SymbolKind.Variable | SymbolKind.Constant | SymbolKind.String | SymbolKind.Number | SymbolKind.Boolean | SymbolKind.Array | SymbolKind.Object | SymbolKind.Key | SymbolKind.Null | SymbolKind.EnumMember | SymbolKind.Struct | SymbolKind.Event | SymbolKind.Operator | SymbolKind.TypeParameter

The kind of this symbol.

location: Location

The location of this symbol.

name: string

The name of 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

Task

A task to execute

Constructors

new Task(taskDefinition: TaskDefinition, name: string, source: string, execution?: ProcessExecution | ShellExecution, problemMatchers?: string | string[]): Task

Creates a new 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.

execution: ProcessExecution | ShellExecution

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.

source: string

A human-readable string describing the source of this shell task, e.g. 'gulp' or 'npm'.

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;
}

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

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.Shared | TaskPanelKind.Dedicated | TaskPanelKind.New

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.Always | TaskRevealKind.Silent | TaskRevealKind.Never

Controls whether the task output is reveal in the user interface. Defaults to RevealKind.Always.

TaskProvider

A task provider allows to add tasks to the task service. A task provider is registered via #workspace.registerTaskProvider.

Methods

provideTasks(token?: CancellationToken): ProviderResult<Task[]>

Provides tasks.

ParameterDescription
token?: CancellationToken

A cancellation token.

ReturnsDescription
ProviderResult<Task[]>

an array of tasks

resolveTask(task: Task, token?: CancellationToken): ProviderResult<Task>

Resolves a task that has no execution set. Tasks are often created from information found in the task.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.

ParameterDescription
task: Task

The task to resolve.

token?: CancellationToken

A cancellation token.

ReturnsDescription
ProviderResult<Task>

The resolved task

TaskRevealKind

Controls the behaviour of the terminal's visibility.

Enumeration members

Always

1

Never

3

Silent

2

Terminal

An individual terminal instance within the integrated terminal.

Properties

name: string

The name of the terminal.

processId: Thenable<number>

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

TerminalOptions

Value-object describing what options a terminal should use.

Properties

name?: string

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

shellArgs?: string[]

Args for the custom shell executable, this does not work on Windows (see #8429)

shellPath?: string

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

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.LF | EndOfLine.CRLF

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

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. Most documents have the file-scheme, indicating that they represent files on disk. However, some documents may have other schemes indicating that they are not available 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 languge 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: 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.

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.

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.One | ViewColumn.Two | ViewColumn.Three

An optional view column in which the editor should be shown. The default is the one, other values are adjusted to be Min(column, columnCount + 1).

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.Manual | TextDocumentSaveReason.AfterDelay | TextDocumentSaveReason.FocusOut

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.LF | EndOfLine.CRLF): TextEdit

Utility to create an eol-edit.

ParameterDescription
eol: EndOfLine.LF | EndOfLine.CRLF

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.LF | EndOfLine.CRLF

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.One | ViewColumn.Two | ViewColumn.Three

The column in which this editor shows. Will be undefined in case this isn't one of the three main editors, e.g an embedded editor.

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 | Position[] | 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 additionals cursors so that the user can complete or accept the snippet.

ParameterDescription
snippet: SnippetString

The snippet to insert in this edit.

location?: Position | Range | Position[] | 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.Default | TextEditorRevealType.InCenter | TextEditorRevealType.InCenterIfOutsideViewport | TextEditorRevealType.AtTop): void

Scroll as indicated by revealType in order to reveal the given range.

ParameterDescription
range: Range

A range.

revealType?: TextEditorRevealType.Default | TextEditorRevealType.InCenter | TextEditorRevealType.InCenterIfOutsideViewport | TextEditorRevealType.AtTop

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.One | ViewColumn.Two | ViewColumn.Three): void

Show the text editor.

ParameterDescription
column?: ViewColumn.One | ViewColumn.Two | ViewColumn.Three

The column in which to show this editor. instead. 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.LF | EndOfLine.CRLF): void

Set the end of line sequence.

ParameterDescription
endOfLine: EndOfLine.LF | EndOfLine.CRLF

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.Line | TextEditorCursorStyle.Block | TextEditorCursorStyle.Underline | TextEditorCursorStyle.LineThin | TextEditorCursorStyle.BlockOutline | TextEditorCursorStyle.UnderlineThin

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.Off | TextEditorLineNumbersStyle.On | TextEditorLineNumbersStyle.Relative

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.Keyboard | TextEditorSelectionChangeKind.Mouse | TextEditorSelectionChangeKind.Command

The change kind which has triggered this event. Can be undefined.

selections: 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 options have changed.

viewColumn: ViewColumn.One | ViewColumn.Two | ViewColumn.Three

The new value for the text editor's view column.

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

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. Alternativly a color from the color registry an 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.

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.

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

TreeDataProvider<T>

A data provider that provides tree data

Events

onDidChangeTreeData?: Event<T | undefined | null>

An optional event to signal that an element or root has changed. 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.

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.None | TreeItemCollapsibleState.Collapsed | TreeItemCollapsibleState.Expanded): TreeItem

ParameterDescription
label: string

A human-readable string describing this item

collapsibleState?: TreeItemCollapsibleState.None | TreeItemCollapsibleState.Collapsed | TreeItemCollapsibleState.Expanded

(#_TreeItemCollapsibleState) of the tree item. Default is TreeItemCollapsibleState.None

ReturnsDescription
TreeItem

Properties

collapsibleState?: TreeItemCollapsibleState.None | TreeItemCollapsibleState.Collapsed | TreeItemCollapsibleState.Expanded

TreeItemCollapsibleState of the tree item.

command?: Command

The command which should be run 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.

iconPath?: string | Uri | {dark: string | Uri, light: string | Uri}

The icon path for the tree item

label: string

A human-readable string describing this item

TreeItemCollapsibleState

Collapsible state of the tree item

Enumeration members

Collapsed

1

Expanded

2

None

0

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>

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>

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

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.

ParameterDescription
path: string

A file system or UNC path.

ReturnsDescription
Uri

A new Uri instance.

parse(value: string): Uri

Create an URI from a string. Will throw if the given value is not valid.

ParameterDescription
value: string

The string value of an Uri.

ReturnsDescription
Uri

A new Uri instance.

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.

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.

ParameterDescription
skipEncoding?: boolean

Do not percentage-encode the result, defaults to false. Note that the # and ? characters occuring 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.

ViewColumn

Denotes a column in the editor window. Columns are used to show editors side by side.

Enumeration members

One

1

Three

3

Two

2

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

  • Default configuration
  • Global configuration
  • Workspace configuration (if available)
  • Workspace folder configuration of the requested resource (if available)

Global configuration comes from User Settings and shadows Defaults.

Workspace configuration comes from Workspace Settings and shadows Global configuration.

Workspace Folder configuration comes from .vscode folder under one of the workspace folders.

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.window.activeTextEditor.document.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): {defaultValue: T, globalValue: T, key: string, workspaceFolderValue: 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 and a folder-specific value.

The effective value (returned by get) is computed like this: defaultValue overwritten by globalValue, globalValue overwritten by workspaceValue. workspaceValue overwritten by workspaceFolderValue. Refer to Settings Inheritence for more information.

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
{defaultValue: T, globalValue: T, key: string, workspaceFolderValue: T, workspaceValue: T} | undefined

Information about a configuration setting or undefined.

update(section: string, value: any, configurationTarget?: ConfigurationTarget.Global | ConfigurationTarget.Workspace | ConfigurationTarget.WorkspaceFolder | boolean): Thenable<void>

Update a configuration value. The updated configuration values are persisted.

A value can be changed in

Note 1: Setting a global value in the presence of a more specific workspace value has no observable effect in that workspace, but in others. Setting a workspace value in the presence of a more specific folder value has no observable effect for the resources under respective folder, but in others. Refer to Settings Inheritence for more information.

Note 2: To remove a configuration value use undefined, like so: config.update('somekey', undefined)

Will throw error when

  • Writing a configuration which is not registered.
  • Writing a configuration to workspace or folder target when no workspace is opened
  • Writing a configuration to folder target when there is no folder settings
  • Writing to folder target without passing a resource when getting the configuration (workspace.getConfiguration(section, resource))
  • Writing a window configuration to folder target
ParameterDescription
section: string

Configuration name, supports dotted names.

value: any

The new value.

configurationTarget?: ConfigurationTarget.Global | ConfigurationTarget.Workspace | ConfigurationTarget.WorkspaceFolder | boolean

The configuration target or a boolean value.

- If `true` configuration target is `ConfigurationTarget.Global`.
- If `false` configuration target is `ConfigurationTarget.Workspace`.
- If `undefined` or `null` configuration target is
`ConfigurationTarget.WorkspaceFolder` when configuration is resource specific
`ConfigurationTarget.Workspace` otherwise.
ReturnsDescription
Thenable<void>

WorkspaceEdit

A workspace edit represents textual changes for many documents.

Properties

size: number

The number of affected resources.

Methods

delete(uri: Uri, range: Range): void

Delete the text at the given range.

ParameterDescription
uri: Uri

A resource identifier.

range: Range

A range.

ReturnsDescription
void

entries(): [Uri, TextEdit[]][]

Get all text edits grouped by resource.

ReturnsDescription
[Uri, TextEdit[]][]

An array 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 this edit affects the given resource.

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

Insert the given text at the given position.

ParameterDescription
uri: Uri

A resource identifier.

position: Position

A position.

newText: string

A string.

ReturnsDescription
void

replace(uri: Uri, range: Range, newText: string): 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.

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

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 master workspace folder.

Properties

index: number

The ordinal number of this workspace folder.

name: string

The name of this workspace folder. Defaults to the basename its uri-path

uri: Uri

The associated URI for this workspace folder.

WorkspaceFoldersChangeEvent

An event describing a change to the set of workspace folders.

Properties

added: WorkspaceFolder[]

Added workspace folders.

removed: WorkspaceFolder[]

Removed workspace folders.

WorkspaceSymbolProvider

The workspace symbol provider interface defines the contract between extensions and the symbol search-feature.

Methods

provideWorkspaceSymbols(query: string, token: CancellationToken): ProviderResult<SymbolInformation[]>

Project-wide search for a symbol matching the given query string. It is up to the provider how to search given the query string, like substring, indexOf etc. To improve performance implementors can skip the location of symbols and implement resolveWorkspaceSymbol to do that later.

ParameterDescription
query: string

A non-empty query string.

token: CancellationToken

A cancellation token.

ReturnsDescription
ProviderResult<SymbolInformation[]>

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: SymbolInformation, token: CancellationToken): ProviderResult<SymbolInformation>

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

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

The resolved symbol or a thenable that resolves to that. When no result is returned, the given symbol is used.