vscode namespace API
commands
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
, andnull
, as well asPosition
,Range
,Uri
andLocation
. - Note 2: There are no restrictions when executing commands that have been contributed by extensions.
Parameter | Description |
---|---|
command: string | Identifier of the command to execute. |
...rest: any[] | Parameters passed to the command function. |
Returns | Description |
Thenable<T | undefined> | A thenable that resolves to the returned value of the given command. |
getCommands(filterInternal?: boolean): Thenable<string[]>
Retrieve the list of all available commands. Commands starting an underscore are treated as internal commands.
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.
Parameter | Description |
---|---|
command: string | A unique identifier for the command. |
callback: (args: any[]) => any | A command handler function. |
thisArg?: any | The |
Returns | Description |
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.
Parameter | Description |
---|---|
command: string | A unique identifier for the command. |
callback: (textEditor: TextEditor, edit: TextEditorEdit, args: any[]) => void | |
thisArg?: any | The |
Returns | Description |
Disposable | Disposable which unregisters this command on disposal. |
debug
Namespace for debug functionality.
Variables
activeDebugConsole: DebugConsole
The currently active debug console.
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
.
breakpoints: Breakpoint[]
List of breakpoints.
Events
onDidChangeActiveDebugSession: Event<DebugSession | undefined>
An event which fires when the active debug session
has changed. Note that the event also fires when the active debug session changes
to undefined
.
onDidChangeBreakpoints: Event<BreakpointsChangeEvent>
An event that is emitted when the set of breakpoints is added, removed, or changed.
onDidReceiveDebugSessionCustomEvent: Event<DebugSessionCustomEvent>
An event which fires when a custom DAP event is received from the debug session.
onDidStartDebugSession: Event<DebugSession>
An event which fires when a new debug session has been started.
onDidTerminateDebugSession: Event<DebugSession>
An event which fires when a debug session has terminated.
Functions
addBreakpoints(breakpoints: Breakpoint[]): void
Add breakpoints.
Parameter | Description |
---|---|
breakpoints: Breakpoint[] | The breakpoints to add. |
Returns | Description |
void |
registerDebugConfigurationProvider(debugType: string, provider: DebugConfigurationProvider): Disposable
Register a debug configuration provider for a specifc debug type. More than one provider can be registered for the same type.
Parameter | Description |
---|---|
debugType: string | |
provider: DebugConfigurationProvider | The debug configuration provider to register. |
Returns | Description |
Disposable | A disposable that unregisters this provider when being disposed. |
removeBreakpoints(breakpoints: Breakpoint[]): void
Remove breakpoints.
Parameter | Description |
---|---|
breakpoints: Breakpoint[] | The breakpoints to remove. |
Returns | Description |
void |
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. '${workspaceFolder}') are resolved against the given folder.
Parameter | Description |
---|---|
folder: WorkspaceFolder | undefined | The workspace folder for looking up named configurations and resolving variables or |
nameOrConfiguration: string | DebugConfiguration | Either the name of a debug or compound configuration or a DebugConfiguration object. |
Returns | Description |
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 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
.
getExtension<T>(extensionId: string): Extension<T> | undefined
Get an extension its full identifier in the form of: publisher.name
.
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.
Parameter | Description |
---|---|
name?: string | The name of the collection. |
Returns | Description |
DiagnosticCollection | A new diagnostic collection. |
getLanguages(): Thenable<string[]>
Return the identifiers of all known languages.
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:
- When
DocumentSelector
is an array, compute the match for each containedDocumentFilter
or language identifier and take the maximum value. - A string will be desugared to become the
language
-part of aDocumentFilter
, so"fooLang"
is like{ language: "fooLang" }
. - A
DocumentFilter
will be matched against the document by comparing its parts with the document. The following rules apply:- When the
DocumentFilter
is empty ({}
) the result is0
- When
scheme
,language
, orpattern
are defined but one doesn’t match, the result is0
- Matching against
*
gives a score of5
, matching via equality or via a glob-pattern gives a score of10
- The result is the maximun value of each match
- When the
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
Parameter | Description |
---|---|
selector: DocumentSelector | A document selector. |
document: TextDocument | A text document. |
Returns | Description |
number | A number |
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.
Parameter | Description |
---|---|
selector: DocumentSelector | A selector that defines the documents this provider is applicable to. |
provider: CodeActionProvider | A code action provider. |
Returns | Description |
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.
Parameter | Description |
---|---|
selector: DocumentSelector | A selector that defines the documents this provider is applicable to. |
provider: CodeLensProvider | A code lens provider. |
Returns | Description |
Disposable | A disposable that unregisters this provider when being disposed. |
registerColorProvider(selector: DocumentSelector, provider: DocumentColorProvider): Disposable
Register a color provider.
Multiple providers can be registered for a language. In that case providers are asked in parallel and the results are merged. A failing provider (rejected promise or exception) will not cause a failure of the whole operation.
Parameter | Description |
---|---|
selector: DocumentSelector | A selector that defines the documents this provider is applicable to. |
provider: DocumentColorProvider | A color provider. |
Returns | Description |
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.
Parameter | Description |
---|---|
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 |
Returns | Description |
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.
Parameter | Description |
---|---|
selector: DocumentSelector | A selector that defines the documents this provider is applicable to. |
provider: DefinitionProvider | A definition provider. |
Returns | Description |
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.
Parameter | Description |
---|---|
selector: DocumentSelector | A selector that defines the documents this provider is applicable to. |
provider: DocumentFormattingEditProvider | A document formatting edit provider. |
Returns | Description |
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.
Parameter | Description |
---|---|
selector: DocumentSelector | A selector that defines the documents this provider is applicable to. |
provider: DocumentHighlightProvider | A document highlight provider. |
Returns | Description |
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.
Parameter | Description |
---|---|
selector: DocumentSelector | A selector that defines the documents this provider is applicable to. |
provider: DocumentLinkProvider | A document link provider. |
Returns | Description |
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.
Parameter | Description |
---|---|
selector: DocumentSelector | A selector that defines the documents this provider is applicable to. |
provider: DocumentRangeFormattingEditProvider | A document range formatting edit provider. |
Returns | Description |
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.
Parameter | Description |
---|---|
selector: DocumentSelector | A selector that defines the documents this provider is applicable to. |
provider: DocumentSymbolProvider | A document symbol provider. |
Returns | Description |
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.
Parameter | Description |
---|---|
selector: DocumentSelector | A selector that defines the documents this provider is applicable to. |
provider: HoverProvider | A hover provider. |
Returns | Description |
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.
Parameter | Description |
---|---|
selector: DocumentSelector | A selector that defines the documents this provider is applicable to. |
provider: ImplementationProvider | An implementation provider. |
Returns | Description |
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.
Parameter | Description |
---|---|
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. |
Returns | Description |
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.
Parameter | Description |
---|---|
selector: DocumentSelector | A selector that defines the documents this provider is applicable to. |
provider: ReferenceProvider | A reference provider. |
Returns | Description |
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.
Parameter | Description |
---|---|
selector: DocumentSelector | A selector that defines the documents this provider is applicable to. |
provider: RenameProvider | A rename provider. |
Returns | Description |
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.
Parameter | Description |
---|---|
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 |
Returns | Description |
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.
Parameter | Description |
---|---|
selector: DocumentSelector | A selector that defines the documents this provider is applicable to. |
provider: TypeDefinitionProvider | A type definition provider. |
Returns | Description |
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.
Parameter | Description |
---|---|
provider: WorkspaceSymbolProvider | A workspace symbol provider. |
Returns | Description |
Disposable | A disposable that unregisters this provider when being disposed. |
setLanguageConfiguration(language: string, configuration: LanguageConfiguration): Disposable
Set a language configuration for a language.
Parameter | Description |
---|---|
language: string | A language identifier like |
configuration: LanguageConfiguration | Language configuration. |
Returns | Description |
Disposable | A disposable that unsets this configuration. |
scm
Variables
inputBox: SourceControlInputBox
The input box for the last source control
created by the extension.
- deprecated - Use SourceControl.inputBox instead
Functions
createSourceControl(id: string, label: string, rootUri?: Uri): SourceControl
Creates a new source control instance.
Parameter | Description |
---|---|
id: string | An |
label: string | A human-readable string for the source control. Eg: |
rootUri?: Uri | An optional Uri of the root of the source control. Eg: |
Returns | Description |
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 | undefined>
An event which fires when the active editor
has changed. Note that the event also fires when the active editor changes
to undefined
.
onDidChangeTextEditorOptions: Event<TextEditorOptionsChangeEvent>
An event which fires when the options of an editor have changed.
onDidChangeTextEditorSelection: Event<TextEditorSelectionChangeEvent>
An event which fires when the selection in an editor has changed.
onDidChangeTextEditorViewColumn: Event<TextEditorViewColumnChangeEvent>
An event which fires when the view column of an editor has changed.
onDidChangeTextEditorVisibleRanges: Event<TextEditorVisibleRangesChangeEvent>
An event which fires when the selection in 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.
Parameter | Description |
---|---|
name: string | Human-readable string which will be used to represent the channel in the UI. |
Returns | Description |
OutputChannel |
createStatusBarItem(alignment?: StatusBarAlignment, priority?: number): StatusBarItem
Creates a status bar item.
Parameter | Description |
---|---|
alignment?: StatusBarAlignment | The alignment of the item. |
priority?: number | The priority of the item. Higher values mean the item should be shown more to the left. |
Returns | Description |
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.
Parameter | Description |
---|---|
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) |
Returns | Description |
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.
Parameter | Description |
---|---|
options: TerminalOptions | A TerminalOptions object describing the characteristics of the new terminal. |
Returns | Description |
Terminal | A new Terminal. |
createTextEditorDecorationType(options: DecorationRenderOptions): TextEditorDecorationType
Create a TextEditorDecorationType that can be used to add decorations to text editors.
Parameter | Description |
---|---|
options: DecorationRenderOptions | Rendering options for the decoration type. |
Returns | Description |
TextEditorDecorationType | A new decoration type instance. |
createTreeView<T>(viewId: string, options: {treeDataProvider: TreeDataProvider<T>}): TreeView<T>
Create a TreeView for the view contributed using the extension point views
.
Parameter | Description |
---|---|
viewId: string | Id of the view contributed using the extension point |
options: {treeDataProvider: TreeDataProvider<T>} | Options object to provide TreeDataProvider for the view. |
Returns | Description |
TreeView<T> | a TreeView. |
registerTreeDataProvider<T>(viewId: string, treeDataProvider: TreeDataProvider<T>): Disposable
Register a TreeDataProvider for the view contributed using the extension point views
.
This will allow you to contribute data to the TreeView and update if the data changes.
Note: To get access to the TreeView and perform operations on it, use createTreeView.
Parameter | Description |
---|---|
viewId: string | Id of the view contributed using the extension point |
treeDataProvider: TreeDataProvider<T> | A TreeDataProvider that provides tree data for the view |
Returns | Description |
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.
Parameter | Description |
---|---|
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. |
Returns | Description |
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.
Parameter | Description |
---|---|
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. |
Returns | Description |
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.
Parameter | Description |
---|---|
text: string | The message to show, supports icon substitution as in status bar items. |
Returns | Description |
Disposable | A disposable which hides the status bar message. |
showErrorMessage(message: string, ...items: string[]): Thenable<string | undefined>
Show an error message.
- see - showInformationMessage
showErrorMessage(message: string, options: MessageOptions, ...items: string[]): Thenable<string | undefined>
Show an error message.
- see - showInformationMessage
Parameter | Description |
---|---|
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. |
Returns | Description |
Thenable<string | undefined> | A thenable that resolves to the selected item or |
showErrorMessage<T extends MessageItem>(message: string, ...items: T[]): Thenable<T | undefined>
Show an error message.
- see - showInformationMessage
showErrorMessage<T extends MessageItem>(message: string, options: MessageOptions, ...items: T[]): Thenable<T | undefined>
Show an error message.
- see - showInformationMessage
Parameter | Description |
---|---|
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. |
Returns | Description |
Thenable<T | undefined> | A thenable that resolves to the selected item or |
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.
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.
Parameter | Description |
---|---|
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. |
Returns | Description |
Thenable<string | undefined> | A thenable that resolves to the selected item or |
showInformationMessage<T extends MessageItem>(message: string, ...items: T[]): Thenable<T | undefined>
Show an information message.
- see - showInformationMessage
showInformationMessage<T extends MessageItem>(message: string, options: MessageOptions, ...items: T[]): Thenable<T | undefined>
Show an information message.
- see - showInformationMessage
Parameter | Description |
---|---|
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. |
Returns | Description |
Thenable<T | undefined> | A thenable that resolves to the selected item or |
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.
Parameter | Description |
---|---|
options?: InputBoxOptions | Configures the behavior of the input box. |
token?: CancellationToken | A token that can be used to signal cancellation. |
Returns | Description |
Thenable<string | undefined> | A promise that resolves to a string the user provided or to |
showOpenDialog(options: OpenDialogOptions): Thenable<Uri[] | undefined>
Shows a file open dialog to the user which allows to select a file for opening-purposes.
Parameter | Description |
---|---|
options: OpenDialogOptions | Options that control the dialog. |
Returns | Description |
Thenable<Uri[] | undefined> | A promise that resolves to the selected resources or |
showQuickPick(items: string[] | Thenable<string[]>, options: !!!MISSING TYPE intersection, token?: CancellationToken): Thenable<string[] | undefined>
Shows a selection list allowing multiple selections.
Parameter | Description |
---|---|
items: string[] | Thenable<string[]> | An array of strings, or a promise that resolves to an array of strings. |
options: !!!MISSING TYPE intersection | Configures the behavior of the selection list. |
token?: CancellationToken | A token that can be used to signal cancellation. |
Returns | Description |
Thenable<string[] | undefined> | A promise that resolves to the selected items or |
showQuickPick(items: string[] | Thenable<string[]>, options?: QuickPickOptions, token?: CancellationToken): Thenable<string | undefined>
Shows a selection list.
Parameter | Description |
---|---|
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. |
Returns | Description |
Thenable<string | undefined> | A promise that resolves to the selection or |
showQuickPick<T extends QuickPickItem>(items: T[] | Thenable<T[]>, options: !!!MISSING TYPE intersection, token?: CancellationToken): Thenable<T[] | undefined>
Shows a selection list allowing multiple selections.
Parameter | Description |
---|---|
items: T[] | Thenable<T[]> | An array of items, or a promise that resolves to an array of items. |
options: !!!MISSING TYPE intersection | Configures the behavior of the selection list. |
token?: CancellationToken | A token that can be used to signal cancellation. |
Returns | Description |
Thenable<T[] | undefined> | A promise that resolves to the selected items or |
showQuickPick<T extends QuickPickItem>(items: T[] | Thenable<T[]>, options?: QuickPickOptions, token?: CancellationToken): Thenable<T | undefined>
Shows a selection list.
Parameter | Description |
---|---|
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. |
Returns | Description |
Thenable<T | undefined> | A promise that resolves to the selected item or |
showSaveDialog(options: SaveDialogOptions): Thenable<Uri | undefined>
Shows a file save dialog to the user which allows to select a file for saving-purposes.
Parameter | Description |
---|---|
options: SaveDialogOptions | Options that control the dialog. |
Returns | Description |
Thenable<Uri | undefined> | A promise that resolves to the selected resource or |
showTextDocument(document: TextDocument, column?: ViewColumn, preserveFocus?: boolean): Thenable<TextEditor>
Show the given document in a text editor. A column can be provided to control where the editor is being shown. Might change the active editor.
Parameter | Description |
---|---|
document: TextDocument | A text document to be shown. |
column?: ViewColumn | |
preserveFocus?: boolean | When |
Returns | Description |
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.
Parameter | Description |
---|---|
document: TextDocument | A text document to be shown. |
options?: TextDocumentShowOptions | (#_TextDocumentShowOptions) to configure the behavior of showing the editor. |
Returns | Description |
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))
.
- see - openTextDocument
Parameter | Description |
---|---|
uri: Uri | A resource identifier. |
options?: TextDocumentShowOptions | (#_TextDocumentShowOptions) to configure the behavior of showing the editor. |
Returns | Description |
Thenable<TextEditor> | A promise that resolves to an editor. |
showWarningMessage(message: string, ...items: string[]): Thenable<string | undefined>
Show a warning message.
- see - showInformationMessage
showWarningMessage(message: string, options: MessageOptions, ...items: string[]): Thenable<string | undefined>
Show a warning message.
- see - showInformationMessage
Parameter | Description |
---|---|
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. |
Returns | Description |
Thenable<string | undefined> | A thenable that resolves to the selected item or |
showWarningMessage<T extends MessageItem>(message: string, ...items: T[]): Thenable<T | undefined>
Show a warning message.
- see - showInformationMessage
showWarningMessage<T extends MessageItem>(message: string, options: MessageOptions, ...items: T[]): Thenable<T | undefined>
Show a warning message.
- see - showInformationMessage
Parameter | Description |
---|---|
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. |
Returns | Description |
Thenable<T | undefined> | A thenable that resolves to the selected item or |
showWorkspaceFolderPick(options?: WorkspaceFolderPickOptions): Thenable<WorkspaceFolder | undefined>
Shows a selection list of workspace folders to pick from.
Returns undefined
if no folder is open.
Parameter | Description |
---|---|
options?: WorkspaceFolderPickOptions | Configures the behavior of the workspace folder list. |
Returns | Description |
Thenable<WorkspaceFolder | undefined> | A promise that resolves to the workspace folder or |
withProgress<R>(options: ProgressOptions, task: (progress: Progress<{increment: number, message: string}>, token: CancellationToken) => Thenable<R>): Thenable<R>
Show progress in the editor. Progress is shown while running the given callback
and while the promise it returned isn't resolved nor rejected. The location at which
progress should show (and other details) is defined via the passed ProgressOptions
.
Parameter | Description |
---|---|
options: ProgressOptions | |
task: (progress: Progress<{increment: number, message: string}>, token: CancellationToken) => Thenable<R> | A callback returning a promise. Progress state can be reported with the provided progress-object. To report discrete progress, use To monitor if the operation has been cancelled by the user, use the provided |
Returns | Description |
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.
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
The name of the workspace. undefined
when no folder
has been opened.
- readonly
The folder that is open in the editor. undefined
when no folder
has been opened.
- deprecated - Use
workspaceFolders
instead.
- 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<ConfigurationChangeEvent>
An event that is emitted when the configuration changed.
onDidChangeTextDocument: Event<TextDocumentChangeEvent>
An event that is emitted when a text document is changed. This usually happens when the contents changes but also when other things like the dirty-state changes.
onDidChangeWorkspaceFolders: Event<WorkspaceFoldersChangeEvent>
An event that is emitted when a workspace folder is added or removed.
onDidCloseTextDocument: Event<TextDocument>
An event that is emitted when a text document is disposed.
To add an event listener when a visible text document is closed, use the TextEditor events in the window namespace. Note that this event is not emitted when a TextEditor is closed but the document remains open in another visible text editor.
onDidOpenTextDocument: Event<TextDocument>
An event that is emitted when a text document is opened.
To add an event listener when a visible text document is opened, use the TextEditor events in the window namespace. Note that:
- The event is emitted before the document is updated in the active text editor
- When a text document is already open (e.g.: open in another visible text editor) this event is not emitted
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.
Parameter | Description |
---|---|
edit: WorkspaceEdit | A workspace edit. |
Returns | Description |
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.
Parameter | Description |
---|---|
pathOrUri: string | Uri | A path or uri. When a uri is given its fsPath is used. |
includeWorkspaceFolder?: boolean | When |
Returns | Description |
string | A path relative to the root or the input. |
createFileSystemWatcher(globPattern: GlobPattern, ignoreCreateEvents?: boolean, ignoreChangeEvents?: boolean, ignoreDeleteEvents?: boolean): FileSystemWatcher
Creates a file system watcher.
A glob pattern that filters the file events on their absolute path must be provided. Optionally, flags to ignore certain kinds of events can be provided. To stop listening to events the watcher must be disposed.
Note that only files within the current workspace folders can be watched.
Parameter | Description |
---|---|
globPattern: GlobPattern | A glob pattern that is applied to the absolute paths of created, changed, and deleted files. Use a relative pattern to limit events to a certain workspace folder. |
ignoreCreateEvents?: boolean | Ignore when files have been created. |
ignoreChangeEvents?: boolean | Ignore when files have been changed. |
ignoreDeleteEvents?: boolean | Ignore when files have been deleted. |
Returns | Description |
FileSystemWatcher | A new file system watcher instance. |
findFiles(include: GlobPattern, exclude?: GlobPattern | null, maxResults?: number, token?: CancellationToken): Thenable<Uri[]>
Find files across all workspace folders in the workspace.
- sample -
findFiles('**/*.js', '**/node_modules/**', 10)
Parameter | Description |
---|---|
include: GlobPattern | A glob pattern that defines the files to search for. The glob pattern will be matched against the file paths of resulting matches relative to their workspace. Use a relative pattern to restrict the search results to a workspace folder. |
exclude?: GlobPattern | null | A glob pattern that defines files and folders to exclude. The glob pattern
will be matched against the file paths of resulting matches relative to their workspace. When |
maxResults?: number | An upper-bound for the result. |
token?: CancellationToken | A token that can be used to signal cancellation to the underlying search engine. |
Returns | Description |
Thenable<Uri[]> | A thenable that resolves to an array of resource identifiers. Will return no results if no workspace folders are opened. |
getConfiguration(section?: string, resource?: Uri | null): WorkspaceConfiguration
Get a workspace configuration object.
When a section-identifier is provided only that part of the configuration
is returned. Dots in the section-identifier are interpreted as child-access,
like { myExt: { setting: { doIt: true }}}
and getConfiguration('myExt.setting').get('doIt') === true
.
When a resource is provided, configuration scoped to that resource is returned.
Parameter | Description |
---|---|
section?: string | A dot-separated identifier. |
resource?: Uri | null | A resource for which the configuration is asked for |
Returns | Description |
WorkspaceConfiguration | The full configuration or a subset. |
getWorkspaceFolder(uri: Uri): WorkspaceFolder | undefined
Returns the workspace folder that contains a given uri.
- returns
undefined
when the given uri doesn't match any workspace folder - returns the input when the given uri is a workspace folder itself
Parameter | Description |
---|---|
uri: Uri | An uri. |
Returns | Description |
WorkspaceFolder | undefined | A workspace folder or |
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.
Parameter | Description |
---|---|
uri: Uri | Identifies the resource to open. |
Returns | Description |
Thenable<TextDocument> | A promise that resolves to a document. |
openTextDocument(fileName: string): Thenable<TextDocument>
A short-hand for openTextDocument(Uri.file(fileName))
.
- see - openTextDocument
Parameter | Description |
---|---|
fileName: string | A name of a file on disk. |
Returns | Description |
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.
Parameter | Description |
---|---|
options?: {content: string, language: string} | Options to control how the document will be created. |
Returns | Description |
Thenable<TextDocument> | A promise that resolves to a document. |
registerTaskProvider(type: string, provider: TaskProvider): Disposable
Register a task provider.
Parameter | Description |
---|---|
type: string | The task kind type this provider is registered for. |
provider: TaskProvider | A task provider. |
Returns | Description |
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.
Parameter | Description |
---|---|
scheme: string | The uri-scheme to register for. |
provider: TextDocumentContentProvider | A content provider. |
Returns | Description |
Disposable | A disposable that unregisters this provider when being disposed. |
saveAll(includeUntitled?: boolean): Thenable<boolean>
Save all dirty files.
updateWorkspaceFolders(start: number, deleteCount: number | undefined | null, ...workspaceFoldersToAdd: {name: string, uri: Uri}[]): boolean
This method replaces deleteCount
workspace folders starting at index start
by an optional set of workspaceFoldersToAdd
on the vscode.workspace.workspaceFolders
array. This "splice"
behavior can be used to add, remove and change workspace folders in a single operation.
If the first workspace folder is added, removed or changed, the currently executing extensions (including the
one that called this method) will be terminated and restarted so that the (deprecated) rootPath
property is
updated to point to the first workspace folder.
Use the onDidChangeWorkspaceFolders()
event to get notified when the
workspace folders have been updated.
Example: adding a new workspace folder at the end of workspace folders
workspace.updateWorkspaceFolders(workspace.workspaceFolders ? workspace.workspaceFolders.length : 0, null, { uri: ...});
Example: removing the first workspace folder
workspace.updateWorkspaceFolders(0, 1);
Example: replacing an existing workspace folder with a new one
workspace.updateWorkspaceFolders(0, 1, { uri: ...});
It is valid to remove an existing workspace folder and add it again with a different name to rename that folder.
Note: it is not valid to call updateWorkspaceFolders() multiple times
without waiting for the onDidChangeWorkspaceFolders()
to fire.
Parameter | Description |
---|---|
start: number | the zero-based location in the list of currently opened workspace folders from which to start deleting workspace folders. |
deleteCount: number | undefined | null | the optional number of workspace folders to remove. |
...workspaceFoldersToAdd: {name: string, uri: Uri}[] | the optional variable set of workspace folders to add in place of the deleted ones. Each workspace is identified with a mandatory URI and an optional name. |
Returns | Description |
boolean | true if the operation was successfully started and false otherwise if arguments were used that would result in invalid workspace folder state (e.g. 2 folders with the same URI). |
Breakpoint
The base class of all breakpoint types.
Constructors
new Breakpoint(enabled?: boolean, condition?: string, hitCondition?: string, logMessage?: string): Breakpoint
Parameter | Description |
---|---|
enabled?: boolean | |
condition?: string | |
hitCondition?: string | |
logMessage?: string | |
Returns | Description |
Breakpoint |
Properties
condition?: string
An optional expression for conditional breakpoints.
enabled: boolean
Is breakpoint enabled.
hitCondition?: string
An optional expression that controls how many hits of the breakpoint are ignored.
logMessage?: string
An optional message that gets logged when this breakpoint is hit. Embedded expressions within {} are interpolated by the debug adapter.
BreakpointsChangeEvent
An event describing the changes to the set of breakpoints.
Properties
added: Breakpoint[]
Added breakpoints.
changed: Breakpoint[]
Changed breakpoints.
removed: Breakpoint[]
Removed breakpoints.
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.
Returns | Description |
---|---|
void |
dispose(): void
Dispose object and free resources.
Returns | Description |
---|---|
void |
CharacterPair
A tuple of two characters, like a pair of opening and closing brackets.
CharacterPair: [string, string]
CodeAction
A code action represents a change that can be performed in code, e.g. to fix a problem or to refactor code.
A CodeAction must set either edit
and/or a command
. If both are supplied, the edit
is applied first, then the command is executed.
Constructors
new CodeAction(title: string, kind?: CodeActionKind): CodeAction
Parameter | Description |
---|---|
title: string | The title of the code action. |
kind?: CodeActionKind | The kind of the code action. |
Returns | Description |
CodeAction |
Properties
command?: Command
A command this code action executes.
diagnostics?: Diagnostic[]
Diagnostics that this code action resolves.
edit?: WorkspaceEdit
A workspace edit this code action performs.
kind?: CodeActionKind
Kind of the code action.
Used to filter code actions.
title: string
A short, human-readable, title for this code action.
CodeActionContext
Contains additional diagnostic information about the context in which a code action is run.
Events
only?: CodeActionKind
Requested kind of actions to return.
Actions not of this kind are filtered out before being shown by the lightbulb.
Properties
diagnostics: Diagnostic[]
An array of diagnostics.
CodeActionKind
Kind of a code action.
Kinds are a hierarchical list of identifiers separated by .
, e.g. "refactor.extract.function"
.
Static
Empty: CodeActionKind
Empty kind.
QuickFix: CodeActionKind
Base kind for quickfix actions.
Refactor: CodeActionKind
Base kind for refactoring actions.
RefactorExtract: CodeActionKind
Base kind for refactoring extraction actions.
Example extract actions:
- Extract method
- Extract function
- Extract variable
- Extract interface from class
- ...
RefactorInline: CodeActionKind
Base kind for refactoring inline actions.
Example inline actions:
- Inline function
- Inline variable
- Inline constant
- ...
RefactorRewrite: CodeActionKind
Base kind for refactoring rewrite actions.
Example rewrite actions:
- Convert JavaScript function to class
- Add or remove parameter
- Encapsulate field
- Make method static
- Move method to base class
- ...
Constructors
new CodeActionKind(value: string): CodeActionKind
Parameter | Description |
---|---|
value: string | |
Returns | Description |
CodeActionKind |
Properties
value?: string
String value of the kind, e.g. "refactor.extract.function"
.
Methods
append(parts: string): CodeActionKind
Create a new kind by appending a more specific selector to the current kind.
Does not modify the current kind.
Parameter | Description |
---|---|
parts: string | |
Returns | Description |
CodeActionKind |
contains(other: CodeActionKind): boolean
Does this kind contain other
?
The kind "refactor"
for example contains "refactor.extract"
and `"refactor.extract.function"
, but not "unicorn.refactor.extract"
or "refactory.extract"
Parameter | Description |
---|---|
other: CodeActionKind | Kind to check. |
Returns | Description |
boolean |
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 | CodeAction[]>
Provide commands for the given document and range.
Parameter | Description |
---|---|
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. |
Returns | Description |
ProviderResult<Command | CodeAction[]> | An array of commands, quick fixes, or refactorings or a thenable of such. The lack of a result can be
signaled by returning |
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.
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.
Parameter | Description |
---|---|
document: TextDocument | The document in which the command was invoked. |
token: CancellationToken | A cancellation token. |
Returns | Description |
ProviderResult<CodeLens[]> | An array of code lenses or a thenable that resolves to such. The lack of a result can be
signaled by returning |
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.
Parameter | Description |
---|---|
codeLens: CodeLens | code lens that must be resolved. |
token: CancellationToken | A cancellation token. |
Returns | Description |
ProviderResult<CodeLens> | The given, resolved code lens or thenable that resolves to such. |
Color
Represents a color in RGBA space.
Constructors
new Color(red: number, green: number, blue: number, alpha: number): Color
Creates a new color instance.
Properties
alpha: number
The alpha component of this color in the range [0-1].
blue: number
The blue component of this color in the range [0-1].
green: number
The green component of this color in the range [0-1].
red: number
The red component of this color in the range [0-1].
ColorInformation
Represents a color range from a document.
Constructors
new ColorInformation(range: Range, color: Color): ColorInformation
Creates a new color range.
Parameter | Description |
---|---|
range: Range | The range the color appears in. Must not be empty. |
color: Color | The value of the color. |
Returns | Description |
ColorInformation |
Properties
color: Color
The actual color value for this color range.
range: Range
The range in the document where this color appers.
ColorPresentation
A color presentation object describes how a color
should be represented as text and what
edits are required to refer to it from source code.
For some languages one color can have multiple presentations, e.g. css can represent the color red with
the constant Red
, the hex-value #ff0000
, or in rgba and hsla forms. In csharp other representations
apply, e.g System.Drawing.Color.Red
.
Constructors
new ColorPresentation(label: string): ColorPresentation
Creates a new color presentation.
Parameter | Description |
---|---|
label: string | The label of this color presentation. |
Returns | Description |
ColorPresentation |
Properties
additionalTextEdits?: TextEdit[]
An optional array of additional text edits that are applied when selecting this color presentation. Edits must not overlap with the main edit nor with themselves.
label: string
The label of this color presentation. It will be shown on the color picker header. By default this is also the text that is inserted when selecting this color presentation.
textEdit?: TextEdit
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.
- see - commands.registerCommand.
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 */
lineComment?: string
The line comment token, like // this is a comment
CompletionContext
Contains additional information about the context in which completion provider is triggered.
Properties
triggerCharacter?: string
Character that triggered the completion item provider.
undefined
if provider was not triggered by a character.
The trigger character is already in the document when the completion provider is triggered.
triggerKind: CompletionTriggerKind
How the completion was triggered.
CompletionItem
A completion item represents a text snippet that is proposed to complete text that is being typed.
It is 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): CompletionItem
Creates a new completion item.
Completion items must have at least a label which then will be used as insert text as well as for sorting and filtering.
Parameter | Description |
---|---|
label: string | The label of the completion. |
kind?: CompletionItemKind | The kind of the completion. |
Returns | Description |
CompletionItem |
Properties
additionalTextEdits?: TextEdit[]
An optional array of additional text edits that are applied when selecting this completion. Edits must not overlap with the main edit nor with themselves.
command?: Command
An optional command that is executed after inserting this completion. Note that additional modifications to the current document should be described with the additionalTextEdits-property.
commitCharacters?: string[]
An optional set of characters that when pressed while this completion is active will accept it first and
then type that character. Note that all commit characters should have length=1
and that superfluous
characters will be ignored.
detail?: string
A human-readable string with additional information about this item, like type or symbol information.
documentation?: string | MarkdownString
A human-readable string that represents a doc-comment.
filterText?: string
A string that should be used when filtering a set of
completion items. When falsy
the label
is used.
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
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
andCompletionItem.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
CompletionItemProvider
The completion item provider interface defines the contract between extensions and IntelliSense.
Providers can delay the computation of the detail
and documentation
properties by implementing the
resolveCompletionItem
-function. However, properties that
are needed for the inital sorting and filtering, like sortText
, filterText
, insertText
, and range
, must
not be changed during resolve.
Providers are asked for completions either explicitly by a user gesture or -depending on the configuration- implicitly when typing words or trigger characters.
Methods
provideCompletionItems(document: TextDocument, position: Position, token: CancellationToken, context: CompletionContext): ProviderResult<CompletionItem[] | CompletionList>
Provide completion items for the given position and document.
Parameter | Description |
---|---|
document: TextDocument | The document in which the command was invoked. |
position: Position | The position at which the command was invoked. |
token: CancellationToken | A cancellation token. |
context: CompletionContext | How the completion was triggered. |
Returns | Description |
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 |
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.
Parameter | Description |
---|---|
item: CompletionItem | A completion item currently active in the UI. |
token: CancellationToken | A cancellation token. |
Returns | Description |
ProviderResult<CompletionItem> | The resolved completion item or a thenable that resolves to of such. It is OK to return the given
|
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.
Parameter | Description |
---|---|
items?: CompletionItem[] | The completion items. |
isIncomplete?: boolean | The list is not complete. |
Returns | Description |
CompletionList |
Properties
isIncomplete?: boolean
This list is not complete. Further typing should result in recomputing this list.
items: CompletionItem[]
The completion items.
CompletionTriggerKind
How a completion provider was triggered
Enumeration members
TriggerForIncompleteCompletions
ConfigurationChangeEvent
An event describing the change in Configuration
Methods
affectsConfiguration(section: string, resource?: Uri): boolean
Returns true
if the given section for the given resource (if provided) is affected.
ConfigurationTarget
The configuration target
Enumeration members
DebugConfiguration
Configuration for a debug session.
Properties
name: string
The name of the debug session.
request: string
The request type of the debug session.
type: string
The type of the debug session.
DebugConfigurationProvider
A debug configuration provider allows to add the initial debug configurations to a newly created launch.json and to resolve a launch configuration before it is used to start a new debug session. A debug configuration provider is registered via #debug.registerDebugConfigurationProvider.
Methods
provideDebugConfigurations(folder: WorkspaceFolder | undefined, token?: CancellationToken): ProviderResult<DebugConfiguration[]>
Provides initial debug configuration. If more than one debug configuration provider is registered for the same type, debug configurations are concatenated in arbitrary order.
Parameter | Description |
---|---|
folder: WorkspaceFolder | undefined | The workspace folder for which the configurations are used or undefined for a folderless setup. |
token?: CancellationToken | A cancellation token. |
Returns | Description |
ProviderResult<DebugConfiguration[]> | An array of debug configurations. |
resolveDebugConfiguration(folder: WorkspaceFolder | undefined, debugConfiguration: DebugConfiguration, token?: CancellationToken): ProviderResult<DebugConfiguration>
Resolves a debug configuration by filling in missing values or by adding/changing/removing attributes. If more than one debug configuration provider is registered for the same type, the resolveDebugConfiguration calls are chained in arbitrary order and the initial debug configuration is piped through the chain. Returning the value 'undefined' prevents the debug session from starting.
Parameter | Description |
---|---|
folder: WorkspaceFolder | undefined | The workspace folder from which the configuration originates from or undefined for a folderless setup. |
debugConfiguration: DebugConfiguration | The debug configuration to resolve. |
token?: CancellationToken | A cancellation token. |
Returns | Description |
ProviderResult<DebugConfiguration> | The resolved debug configuration or undefined. |
DebugConsole
Represents the debug console.
Methods
Append the given value to the debug console.
appendLine(value: string): void
Append the given value and a line feed character to the debug console.
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.
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
DecorationRenderOptions
Represents rendering styles for a text editor decoration.
Properties
after?: ThemableDecorationAttachmentRenderOptions
Defines the rendering options of the attachment that is inserted after the decorated text
backgroundColor?: string | ThemeColor
Background color of the decoration. Use rgba() and define transparent background colors to play well with other decorations. Alternatively a color from the color registry can be referenced.
before?: ThemableDecorationAttachmentRenderOptions
Defines the rendering options of the attachment that is inserted before the decorated text
border?: string
CSS styling property that will be applied to text enclosed by a decoration.
borderColor?: string | ThemeColor
CSS styling property that will be applied to text enclosed by a decoration. Better use 'border' for setting one or more of the individual border properties.
borderRadius?: string
CSS styling property that will be applied to text enclosed by a decoration. Better use 'border' for setting one or more of the individual border properties.
borderSpacing?: string
CSS styling property that will be applied to text enclosed by a decoration. Better use 'border' for setting one or more of the individual border properties.
borderStyle?: string
CSS styling property that will be applied to text enclosed by a decoration. Better use 'border' for setting one or more of the individual border properties.
borderWidth?: string
CSS styling property that will be applied to text enclosed by a decoration. Better use 'border' for setting one or more of the individual border properties.
color?: string | ThemeColor
CSS styling property that will be applied to text enclosed by a decoration.
cursor?: string
CSS styling property that will be applied to text enclosed by a decoration.
dark?: ThemableDecorationRenderOptions
Overwrite options for dark themes.
fontStyle?: string
CSS styling property that will be applied to text enclosed by a decoration.
fontWeight?: string
CSS styling property that will be applied to text enclosed by a decoration.
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
The position in the overview ruler where the decoration should be rendered.
rangeBehavior?: DecorationRangeBehavior
Customize the growing behavior of the decoration when edits occur at the edges of the decoration's range.
Defaults to DecorationRangeBehavior.OpenOpen
.
textDecoration?: string
CSS styling property that will be applied to text enclosed by a decoration.
Definition
The definition of a symbol represented as one or many locations. For most programming languages there is only one location at which a symbol is defined.
Definition: Location | Location[]
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.
Parameter | Description |
---|---|
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. |
Returns | Description |
ProviderResult<Definition> | A definition or a thenable that resolves to such. The lack of a result can be
signaled by returning |
Diagnostic
Represents a diagnostic, such as a compiler error or warning. Diagnostic objects are only valid in the scope of a file.
Constructors
new Diagnostic(range: Range, message: string, severity?: DiagnosticSeverity): Diagnostic
Creates a new diagnostic object.
Parameter | Description |
---|---|
range: Range | The range to which this diagnostic applies. |
message: string | The human-readable message. |
severity?: DiagnosticSeverity | The severity, default is error. |
Returns | Description |
Diagnostic |
Properties
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.
relatedInformation?: DiagnosticRelatedInformation[]
An array of related diagnostic information, e.g. when symbol-names within a scope collide all definitions can be marked via this property.
severity: DiagnosticSeverity
The severity, default is error.
source?: string
A human-readable string describing the source of this diagnostic, e.g. 'typescript' or 'super lint'.
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)
;
Returns | Description |
---|---|
void |
Remove all diagnostics from this collection that belong
to the provided uri
. The same as #set(uri, undefined)
.
dispose(): void
forEach(callback: (uri: Uri, diagnostics: Diagnostic[], collection: DiagnosticCollection) => any, thisArg?: any): void
Iterate over each entry in this collection.
Parameter | Description |
---|---|
callback: (uri: Uri, diagnostics: Diagnostic[], collection: DiagnosticCollection) => any | Function to execute for each entry. |
thisArg?: any | The |
Returns | Description |
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.
Parameter | Description |
---|---|
uri: Uri | A resource identifier. |
Returns | Description |
Diagnostic[] | undefined | An immutable array of diagnostics or |
Check if this collection contains diagnostics for a given resource.
set(uri: Uri, diagnostics: Diagnostic[] | undefined): void
Assign diagnostics for given resource. Will replace existing diagnostics for that resource.
Parameter | Description |
---|---|
uri: Uri | A resource identifier. |
diagnostics: Diagnostic[] | undefined | Array of diagnostics or |
Returns | Description |
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.
Parameter | Description |
---|---|
entries: [Uri, Diagnostic[] | undefined][] | An array of tuples, like |
Returns | Description |
void |
DiagnosticRelatedInformation
Represents a related message and source code location for a diagnostic. This should be used to point to code locations that cause or related to a diagnostics, e.g when duplicating a symbol in a scope.
Constructors
new DiagnosticRelatedInformation(location: Location, message: string): DiagnosticRelatedInformation
Creates a new related diagnostic information object.
Parameter | Description |
---|---|
location: Location | The location. |
message: string | The message. |
Returns | Description |
DiagnosticRelatedInformation |
Properties
location: Location
The location of this related diagnostic information.
message: string
The message of this related diagnostic information.
DiagnosticSeverity
Represents the severity of diagnostics.
Enumeration members
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.
Parameter | Description |
---|---|
...disposableLikes: {dispose: () => any}[] | Objects that have at least a |
Returns | Description |
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.
Parameter | Description |
---|---|
callOnDispose: Function | Function that disposes something. |
Returns | Description |
Disposable |
Methods
dispose(): any
Dispose this object.
Returns | Description |
---|---|
any |
DocumentColorProvider
The document color provider defines the contract between extensions and feature of picking and modifying colors in the editor.
Methods
provideColorPresentations(color: Color, context: {document: TextDocument, range: Range}, token: CancellationToken): ProviderResult<ColorPresentation[]>
Provide representations for a color.
Parameter | Description |
---|---|
color: Color | The color to show and insert. |
context: {document: TextDocument, range: Range} | A context object with additional information |
token: CancellationToken | A cancellation token. |
Returns | Description |
ProviderResult<ColorPresentation[]> | An array of color presentations or a thenable that resolves to such. The lack of a result
can be signaled by returning |
provideDocumentColors(document: TextDocument, token: CancellationToken): ProviderResult<ColorInformation[]>
Provide colors for the given document.
Parameter | Description |
---|---|
document: TextDocument | The document in which the command was invoked. |
token: CancellationToken | A cancellation token. |
Returns | Description |
ProviderResult<ColorInformation[]> | An array of color informations or a thenable that resolves to such. The lack of a result
can be signaled by returning |
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?: GlobPattern
A glob pattern that is matched on the absolute path of the document. Use a relative pattern to filter documents to a workspace folder.
scheme?: string
A Uri scheme, like file
or untitled
.
DocumentFormattingEditProvider
The document formatting provider interface defines the contract between extensions and the formatting-feature.
Methods
provideDocumentFormattingEdits(document: TextDocument, options: FormattingOptions, token: CancellationToken): ProviderResult<TextEdit[]>
Provide formatting edits for a whole document.
Parameter | Description |
---|---|
document: TextDocument | The document in which the command was invoked. |
options: FormattingOptions | Options controlling formatting. |
token: CancellationToken | A cancellation token. |
Returns | Description |
ProviderResult<TextEdit[]> | A set of text edits or a thenable that resolves to such. The lack of a result can be
signaled by returning |
DocumentHighlight
A document highlight is a range inside a text document which deserves special attention. Usually a document highlight is visualized by changing the background color of its range.
Constructors
new DocumentHighlight(range: Range, kind?: DocumentHighlightKind): DocumentHighlight
Creates a new document highlight object.
Parameter | Description |
---|---|
range: Range | The range the highlight applies to. |
kind?: DocumentHighlightKind | The highlight kind, default is text. |
Returns | Description |
DocumentHighlight |
Properties
kind?: DocumentHighlightKind
The highlight kind, default is text.
range: Range
The range this highlight applies to.
DocumentHighlightKind
A document highlight kind.
Enumeration members
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.
Parameter | Description |
---|---|
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. |
Returns | Description |
ProviderResult<DocumentHighlight[]> | An array of document highlights or a thenable that resolves to such. The lack of a result can be
signaled by returning |
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.
Parameter | Description |
---|---|
range: Range | The range the document link applies to. Must not be empty. |
target?: Uri | The uri the document link points to. |
Returns | Description |
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.
Parameter | Description |
---|---|
document: TextDocument | The document in which the command was invoked. |
token: CancellationToken | A cancellation token. |
Returns | Description |
ProviderResult<DocumentLink[]> | An array of document links or a thenable that resolves to such. The lack of a result
can be signaled by returning |
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.
Parameter | Description |
---|---|
link: DocumentLink | The link that is to be resolved. |
token: CancellationToken | A cancellation token. |
Returns | Description |
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.
Parameter | Description |
---|---|
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. |
Returns | Description |
ProviderResult<TextEdit[]> | A set of text edits or a thenable that resolves to such. The lack of a result can be
signaled by returning |
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.
Parameter | Description |
---|---|
document: TextDocument | The document in which the command was invoked. |
token: CancellationToken | A cancellation token. |
Returns | Description |
ProviderResult<SymbolInformation[]> | An array of document highlights or a thenable that resolves to such. The lack of a result can be
signaled by returning |
EndOfLine
Represents an end of line character sequence in a document.
Enumeration members
EnterAction
Describes what to do when pressing Enter.
Properties
appendText?: string
Describes text to be appended after the new line and after the indentation.
indentAction: IndentAction
Describe what to do with the indentation.
removeText?: number
Describes the number of characters to remove from the new line's indentation.
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.
Parameter | Description |
---|---|
listener: (e: T) => any | The listener function will be called when the event happens. |
thisArgs?: any | The |
disposables?: Disposable[] | An array to which a disposable will be added. |
Returns | Description |
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
The event listeners can subscribe to.
Methods
dispose(): void
Dispose this object and free resources.
Returns | Description |
---|---|
void |
Notify all subscribers of the event. Failure of one or more listener will not fail this function call.
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
Activates this extension and returns its public API.
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.
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.
FileSystemWatcher
A file system watcher notifies about changes to files and folders on disk.
To get an instance of a FileSystemWatcher
use
createFileSystemWatcher.
Events
An event which fires on file/folder change.
An event which fires on file/folder creation.
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.
Parameter | Description |
---|---|
...disposableLikes: {dispose: () => any}[] | Objects that have at least a |
Returns | Description |
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.
Parameter | Description |
---|---|
callOnDispose: Function | Function that disposes something. |
Returns | Description |
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.
Returns | Description |
---|---|
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.
FunctionBreakpoint
A breakpoint specified by a function name.
Constructors
new FunctionBreakpoint(functionName: string, enabled?: boolean, condition?: string, hitCondition?: string, logMessage?: string): FunctionBreakpoint
Create a new function breakpoint.
Properties
condition?: string
An optional expression for conditional breakpoints.
enabled: boolean
Is breakpoint enabled.
functionName: string
The name of the function to which this breakpoint is attached.
hitCondition?: string
An optional expression that controls how many hits of the breakpoint are ignored.
logMessage?: string
An optional message that gets logged when this breakpoint is hit. Embedded expressions within {} are interpolated by the debug adapter.
GlobPattern
A file glob pattern to match file paths against. This can either be a glob pattern string
(like **/*.{ts,js}
or *.{ts,js}
) or a relative pattern.
Glob patterns can have the following syntax:
*
to match one or more characters in a path segment?
to match on one character in a path segment**
to match any number of path segments, including none{}
to group conditions (e.g.**/*.{ts,js}
matches all TypeScript and JavaScript files)[]
to declare a range of characters to match in a path segment (e.g.,example.[0-9]
to match onexample.0
,example.1
, …)[!...]
to negate a range of characters to match in a path segment (e.g.,example.[!0-9]
to match onexample.a
,example.b
, but notexample.0
)
GlobPattern: string | RelativePattern
Hover
A hover represents additional information for a symbol or word. Hovers are rendered in a tooltip-like widget.
Constructors
new Hover(contents: MarkedString | MarkedString[], range?: Range): Hover
Creates a new hover object.
Parameter | Description |
---|---|
contents: MarkedString | MarkedString[] | The contents of the hover. |
range?: Range | The range to which the hover applies. |
Returns | Description |
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.
Parameter | Description |
---|---|
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. |
Returns | Description |
ProviderResult<Hover> | A hover or a thenable that resolves to such. The lack of a result can be
signaled by returning |
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.
Parameter | Description |
---|---|
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. |
Returns | Description |
ProviderResult<Definition> | A definition or a thenable that resolves to such. The lack of a result can be
signaled by returning |
IndentAction
Describes what to do with the indentation when pressing Enter.
Enumeration members
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 | Thenable<string | undefined | null>
An optional function that will be called to validate input and to give a hint to the user.
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.
Properties
range: Range
The document range of this location.
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.
Parameter | Description |
---|---|
value?: string | Optional, initial value. |
Returns | Description |
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
appendCodeblock(value: string, language?: string): MarkdownString
Appends the given string as codeblock using the provided language.
Parameter | Description |
---|---|
value: string | A code snippet. |
language?: string | An optional language identifier. |
Returns | Description |
MarkdownString |
appendMarkdown(value: string): MarkdownString
Appends the given string 'as is' to this markdown string.
Parameter | Description |
---|---|
value: string | Markdown string. |
Returns | Description |
MarkdownString |
appendText(value: string): MarkdownString
Appends and escapes the given string to this markdown string.
Parameter | Description |
---|---|
value: string | Plain text. |
Returns | Description |
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.
get<T>(key: string, defaultValue: T): T
Return a value.
update(key: string, value: any): Thenable<void>
Store a value. The value must be JSON-stringifyable.
MessageItem
Represents an action that is shown with an information, warning, or error message.
- see - showInformationMessage
- see - showWarningMessage
- see - showErrorMessage
Properties
isCloseAffordance?: boolean
A hint for modal dialogs that the item should be triggered when the user cancels the dialog (e.g. by pressing the ESC key).
Note: this option is ignored for non-modal messages.
title: string
A short title like 'Retry', 'Open Log' etc.
MessageOptions
Options to configure the behavior of the message.
- see - showInformationMessage
- see - showWarningMessage
- see - showErrorMessage
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.
Parameter | Description |
---|---|
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. |
Returns | Description |
ProviderResult<TextEdit[]> | A set of text edits or a thenable that resolves to such. The lack of a result can be
signaled by returning |
OpenDialogOptions
Options to configure the behaviour of a file open dialog.
- Note 1: A dialog can select files, folders, or both. This is not true for Windows which enforces to open either files or folder, but not both.
- Note 2: Explictly setting
canSelectFiles
andcanSelectFolders
tofalse
is futile and the editor then silently adjusts the options to select files.
Properties
canSelectFiles?: boolean
Allow to select files, defaults to true
.
canSelectFolders?: boolean
Allow to select folders, defaults to false
.
canSelectMany?: boolean
Allow to select many files or folders.
defaultUri?: Uri
The resource the dialog shows when opened.
A set of file filters that are used by the dialog. Each entry is a human readable label, like "TypeScript", and an array of extensions, e.g.
{
'Images': ['png', 'jpg']
'TypeScript': ['ts', 'tsx']
}
openLabel?: string
A human-readable string for the open button.
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 the given value to the channel.
appendLine(value: string): void
Append the given value and a line feed character to the channel.
clear(): void
Removes all output from the channel.
Returns | Description |
---|---|
void |
dispose(): void
Dispose and free associated resources.
Returns | Description |
---|---|
void |
hide(): void
Hide this channel from the UI.
Returns | Description |
---|---|
void |
show(preserveFocus?: boolean): void
Reveal this channel in the UI.
show(column?: ViewColumn, preserveFocus?: boolean): void
Reveal this channel in the UI.
- deprecated - Use the overload with just one parameter (
show(preserveFocus?: boolean): void
).
Parameter | Description |
---|---|
column?: ViewColumn | This argument is deprecated and will be ignored. |
preserveFocus?: boolean | When |
Returns | Description |
void |
OverviewRulerLane
Represents different positions for rendering a decoration in an overview ruler. The overview ruler supports three lanes.
Enumeration members
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 | MarkdownString): ParameterInformation
Creates a new parameter information object.
Parameter | Description |
---|---|
label: string | A label string. |
documentation?: string | MarkdownString | A doc string. |
Returns | Description |
ParameterInformation |
Properties
documentation?: string | MarkdownString
The human-readable doc-comment of this signature. Will be shown in the UI but can be omitted.
label: string
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
Properties
character: number
The zero-based character value.
line: number
The zero-based line value.
Methods
compareTo(other: Position): number
Compare this to other
.
isAfter(other: Position): boolean
Check if this position is after other
.
isAfterOrEqual(other: Position): boolean
Check if this position is after or equal to other
.
isBefore(other: Position): boolean
Check if this position is before other
.
isBeforeOrEqual(other: Position): boolean
Check if this position is before or equal to other
.
isEqual(other: Position): boolean
Check if this position is equal to other
.
translate(lineDelta?: number, characterDelta?: number): Position
Create a new position relative to this position.
translate(change: {characterDelta: number, lineDelta: number}): Position
Derived a new position relative to this position.
with(line?: number, character?: number): Position
Create a new position derived from this position.
Parameter | Description |
---|---|
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 |
Returns | Description |
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.
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.
Parameter | Description |
---|---|
process: string | The process to start. |
options?: ProcessExecutionOptions | Optional options for the started process. |
Returns | Description |
ProcessExecution |
new ProcessExecution(process: string, args: string[], options?: ProcessExecutionOptions): ProcessExecution
Creates a process execution.
Parameter | Description |
---|---|
process: string | The process to start. |
args: string[] | Arguments to be passed to the process. |
options?: ProcessExecutionOptions | Optional options for the started process. |
Returns | Description |
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.
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 a progress update.
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
ProgressOptions
Value-object describing where and how progress should show.
Properties
cancellable?: boolean
Controls if a cancel button should show to allow the user to
cancel the long running operation. Note that currently only
ProgressLocation.Notification
is supporting to show a cancel
button.
location: ProgressLocation
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.
Parameter | Description |
---|---|
uri: Uri | The uri of the resource open in a text editor. |
token: CancellationToken | A cancellation token. |
Returns | Description |
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.
picked?: boolean
Optional flag indicating if this item is picked initially. (Only honored when the picker allows multiple selections.)
QuickPickOptions
Options to configure the behavior of the quick pick UI.
Events
onDidSelectItem(item: QuickPickItem | string): any
An optional function that is invoked whenever an item is selected.
Parameter | Description |
---|---|
item: QuickPickItem | string | |
Returns | Description |
any |
Properties
canPickMany?: boolean
An optional flag to make the picker accept multiple selections, if true the result is an array of picks.
ignoreFocusOut?: boolean
Set to true
to keep the picker open when focus moves to another part of the editor or to another window.
matchOnDescription?: boolean
An optional flag to include the description when filtering the picks.
matchOnDetail?: boolean
An optional flag to include the detail when filtering the picks.
placeHolder?: string
An optional string to show as 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.
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))
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.
intersection(range: Range): Range | undefined
Intersect range
with this range and returns a new range or undefined
if the ranges have no overlap.
isEqual(other: Range): boolean
Check if other
equals this range.
Compute the union of other
with this range.
with(start?: Position, end?: Position): Range
Derived a new range from this range.
Parameter | Description |
---|---|
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. |
Returns | Description |
Range | A range derived from this range with the given start and end position.
If start and end are not different |
with(change: {end: Position, start: Position}): Range
Derived a new range from this range.
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.
Parameter | Description |
---|---|
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. |
Returns | Description |
ProviderResult<Location[]> | An array of locations or a thenable that resolves to such. The lack of a result can be
signaled by returning |
RelativePattern
A relative pattern is a helper to construct glob patterns that are matched relatively to a base path. The base path can either be an absolute file path or a workspace folder.
Constructors
new RelativePattern(base: WorkspaceFolder | string, pattern: string): RelativePattern
Creates a new relative pattern object with a base path and pattern to match. This pattern will be matched on file paths relative to the base path.
Parameter | Description |
---|---|
base: WorkspaceFolder | string | A base file path to which this pattern will be matched against relatively. |
pattern: string | A file glob pattern like |
Returns | Description |
RelativePattern |
Properties
base: string
A base file path to which this pattern will be matched against relatively.
pattern: string
A file glob pattern like *.{ts,js}
that will be matched on file paths
relative to the base path.
Example: Given a base of /home/work/folder
and a file path of /home/work/folder/index.js
,
the file glob pattern will match on index.js
.
RenameProvider
The rename provider interface defines the contract between extensions and the rename-feature.
Methods
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.
Parameter | Description |
---|---|
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. |
Returns | Description |
ProviderResult<WorkspaceEdit> | A workspace edit or a thenable that resolves to such. The lack of a result can be
signaled by returning |
SaveDialogOptions
Options to configure the behaviour of a file save dialog.
Properties
defaultUri?: Uri
The resource the dialog shows when opened.
A set of file filters that are used by the dialog. Each entry is a human readable label, like "TypeScript", and an array of extensions, e.g.
{
'Images': ['png', 'jpg']
'TypeScript': ['ts', 'tsx']
}
saveLabel?: string
A human-readable string for the save button.
Selection
Represents a text selection in an editor.
Constructors
new Selection(anchor: Position, active: Position): Selection
Create a selection from two postions.
new Selection(anchorLine: number, anchorCharacter: number, activeLine: number, activeCharacter: number): Selection
Create a selection from four coordinates.
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
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.
intersection(range: Range): Range | undefined
Intersect range
with this range and returns a new range or undefined
if the ranges have no overlap.
isEqual(other: Range): boolean
Check if other
equals this range.
Compute the union of other
with this range.
with(start?: Position, end?: Position): Range
Derived a new range from this range.
Parameter | Description |
---|---|
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. |
Returns | Description |
Range | A range derived from this range with the given start and end position.
If start and end are not different |
with(change: {end: Position, start: Position}): Range
Derived a new range from this range.
ShellExecution
Constructors
new ShellExecution(commandLine: string, options?: ShellExecutionOptions): ShellExecution
Creates a shell execution with a full command line.
Parameter | Description |
---|---|
commandLine: string | The command line to execute. |
options?: ShellExecutionOptions | Optional options for the started the shell. |
Returns | Description |
ShellExecution |
new ShellExecution(command: string | ShellQuotedString, args: string | ShellQuotedString[], options?: ShellExecutionOptions): ShellExecution
Creates a shell execution with a command and arguments. For the real execution VS Code will
construct a command line from the command and the arguments. This is subject to interpretation
especially when it comes to quoting. If full control over the command line is needed please
use the constructor that creates a ShellExecution
with the full command line.
Parameter | Description |
---|---|
command: string | ShellQuotedString | The command to execute. |
args: string | ShellQuotedString[] | The command arguments. |
options?: ShellExecutionOptions | Optional options for the started the shell. |
Returns | Description |
ShellExecution |
Properties
args: string | ShellQuotedString[]
The shell args. Is undefined
if created with a full command line.
command: string | ShellQuotedString
The shell command. Is undefined
if created with a full command line.
commandLine: string
The shell command line. Is undefined
if created with a command and arguments.
options?: ShellExecutionOptions
The shell options used when the command line is executed in a shell. Defaults to undefined.
ShellExecutionOptions
Options for a shell execution
Properties
cwd?: string
The current working directory of the executed shell. If omitted the tools current workspace root is used.
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.
shellQuoting?: ShellQuotingOptions
The shell quotes supported by this shell.
ShellQuotedString
A string that will be quoted depending on the used shell.
Properties
quoting: ShellQuoting
The quoting style to use.
value: string
The actual string value.
ShellQuoting
Defines how an argument should be quoted if it contains spaces or unsuppoerted characters.
Enumeration members
ShellQuotingOptions
The shell quoting options.
Properties
escape?: string | {charsToEscape: string, escapeChar: string}
The character used to do character escaping. If a string is provided only spaces
are escaped. If a { escapeChar, charsToEscape }
literal is provide all characters
in charsToEscape
are escaped using the escapeChar
.
strong?: string
The character used for strong quoting. The string's length must be 1.
weak?: string
The character used for weak quoting. The string's length must be 1.
SignatureHelp
Signature help represents the signature of something callable. There can be multiple signatures but only one active and only one active parameter.
Properties
activeParameter: number
The active parameter of the active signature.
activeSignature: number
The active signature.
signatures: SignatureInformation[]
One or more signatures.
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.
Parameter | Description |
---|---|
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. |
Returns | Description |
ProviderResult<SignatureHelp> | Signature help or a thenable that resolves to such. The lack of a result can be
signaled by returning |
SignatureInformation
Represents the signature of something callable. A signature can have a label, like a function-name, a doc-comment, and a set of parameters.
Constructors
new SignatureInformation(label: string, documentation?: string | MarkdownString): SignatureInformation
Creates a new signature information object.
Parameter | Description |
---|---|
label: string | A label string. |
documentation?: string | MarkdownString | A doc string. |
Returns | Description |
SignatureInformation |
Properties
documentation?: string | MarkdownString
The human-readable doc-comment of this signature. Will be shown in the UI but can be omitted.
label: string
The label of this signature. Will be shown in the UI.
parameters: ParameterInformation[]
The parameters of this signature.
SnippetString
A snippet string is a template which allows to insert text and to control the editor cursor when insertion happens.
A snippet can define tab stops and placeholders with $1
, $2
and ${3:foo}
. $0
defines the final tab stop, it defaults to
the end of the snippet. Variables are defined with $name
and
${name:default value}
. The full snippet syntax is documented
here.
Constructors
new SnippetString(value?: string): SnippetString
Parameter | Description |
---|---|
value?: string | |
Returns | Description |
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.
Parameter | Description |
---|---|
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. |
Returns | Description |
SnippetString | This snippet string. |
appendTabstop(number?: number): SnippetString
Builder-function that appends a tabstop ($1
, $2
etc) to
the value
of this snippet string.
Parameter | Description |
---|---|
number?: number | The number of this tabstop, defaults to an auto-incremet value starting at 1. |
Returns | Description |
SnippetString | This snippet string. |
appendText(string: string): SnippetString
Builder-function that appends the given string to
the value
of this snippet string.
Parameter | Description |
---|---|
string: string | A value to append 'as given'. The string will be escaped. |
Returns | Description |
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.
Parameter | Description |
---|---|
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. |
Returns | Description |
SnippetString | This snippet string. |
SourceBreakpoint
A breakpoint specified by a source location.
Constructors
new SourceBreakpoint(location: Location, enabled?: boolean, condition?: string, hitCondition?: string, logMessage?: string): SourceBreakpoint
Create a new breakpoint for a source location.
Properties
condition?: string
An optional expression for conditional breakpoints.
enabled: boolean
Is breakpoint enabled.
hitCondition?: string
An optional expression that controls how many hits of the breakpoint are ignored.
location: Location
The source and line position of this breakpoint.
logMessage?: string
An optional message that gets logged when this breakpoint is hit. Embedded expressions within {} are interpolated by the debug adapter.
SourceControl
An source control is able to provide resource states to the editor and interact with the editor in several source control related ways.
Properties
acceptInputCommand?: Command
Optional accept input command.
This command will be invoked when the user accepts the value in the Source Control input.
commitTemplate?: string
Optional commit template string.
The Source Control viewlet will populate the Source Control input with this value when appropriate.
count?: number
The UI-visible count of resource states of this source control.
Equals to the total number of resource state of this source control, if undefined.
id: string
The id of this source control.
inputBox: SourceControlInputBox
The input box for this source control.
label: string
The human-readable label of this source control.
quickDiffProvider?: QuickDiffProvider
An optional quick diff provider.
The (optional) Uri of the root of this source control.
statusBarCommands?: Command[]
Optional status bar commands.
These commands will be displayed in the editor's status bar.
Methods
createResourceGroup(id: string, label: string): SourceControlResourceGroup
Create a new resource group.
Parameter | Description |
---|---|
id: string | |
label: string | |
Returns | Description |
SourceControlResourceGroup |
dispose(): void
Dispose this source control.
Returns | Description |
---|---|
void |
SourceControlInputBox
Represents the input box in the Source Control viewlet.
Properties
placeholder: string
A string to show as place holder in the input box to guide the user.
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.
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.
Returns | Description |
---|---|
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
The icon path for a specific source control resource state.
StatusBarAlignment
Represents the alignment of status bar items.
Enumeration members
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
The alignment of this item.
color: string | ThemeColor | undefined
The foreground color for this entry.
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.
The tooltip text when you hover over this entry.
Methods
dispose(): void
hide(): void
Hide the entry in the status bar.
Returns | Description |
---|---|
void |
show(): void
Shows the entry in the status bar.
Returns | Description |
---|---|
void |
SymbolInformation
Represents information about programming constructs like variables, classes, interfaces etc.
Constructors
new SymbolInformation(name: string, kind: SymbolKind, containerName: string, location: Location): SymbolInformation
Creates a new symbol information object.
Parameter | Description |
---|---|
name: string | The name of the symbol. |
kind: SymbolKind | The kind of the symbol. |
containerName: string | The name of the symbol containing the symbol. |
location: Location | The the location of the symbol. |
Returns | Description |
SymbolInformation |
new SymbolInformation(name: string, kind: SymbolKind, range: Range, uri?: Uri, containerName?: string): SymbolInformation
Creates a new symbol information object.
- deprecated - Please use the constructor taking a location object.
Parameter | Description |
---|---|
name: string | The name of the symbol. |
kind: SymbolKind | The kind of the symbol. |
range: Range | The range of the location of the symbol. |
uri?: Uri | The resource of the location of symbol, defaults to the current document. |
containerName?: string | The name of the symbol containing the symbol. |
Returns | Description |
SymbolInformation |
Properties
containerName: string
The name of the symbol containing this symbol.
kind: SymbolKind
The kind of this symbol.
location: Location
The location of this symbol.
name: string
The name of this symbol.
SymbolKind
A symbol kind.
Enumeration members
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.
- deprecated - Use the new constructors that allow specifying a target for the task.
Parameter | Description |
---|---|
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 |
Returns | Description |
Task |
new Task(taskDefinition: TaskDefinition, target: WorkspaceFolder | Global | Workspace, name: string, source: string, execution?: ProcessExecution | ShellExecution, problemMatchers?: string | string[]): Task
Creates a new task.
Parameter | Description |
---|---|
taskDefinition: TaskDefinition | |
target: WorkspaceFolder | Global | Workspace | Specifies the task's target. It is either a global or a workspace task or a task for a specific workspace folder. |
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 |
Returns | Description |
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.
scope?: Global | Workspace | WorkspaceFolder
The task's scope.
source: string
A human-readable string describing the source of this shell task, e.g. 'gulp' or 'npm'.
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
TaskPanelKind
Controls how the task channel is used between tasks
Enumeration members
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
Controls if the task panel is used for this task only (dedicated),
shared between tasks (shared) or if a new panel is created on
every task execution (new). Defaults to TaskInstanceKind.Shared
reveal?: TaskRevealKind
Controls whether the task output is reveal in the user interface.
Defaults to RevealKind.Always
.
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.
Parameter | Description |
---|---|
token?: CancellationToken | A cancellation token. |
Returns | Description |
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 tasks.json
-file. Such tasks miss
the information on how to execute them and a task provider must fill in
the missing information in the resolveTask
-method. This method will not be
called for tasks returned from the above provideTasks
method since those
tasks are always fully resolved. A valid default implementation for the
resolveTask
method is to return undefined
.
Parameter | Description |
---|---|
task: Task | The task to resolve. |
token?: CancellationToken | A cancellation token. |
Returns | Description |
ProviderResult<Task> | The resolved task |
TaskRevealKind
Controls the behaviour of the terminal's visibility.
Enumeration members
TaskScope
The scope of a task.
Enumeration members
Terminal
An individual terminal instance within the integrated terminal.
Properties
name: string
The name of the terminal.
The process ID of the shell process.
Methods
dispose(): void
Dispose and free associated resources.
Returns | Description |
---|---|
void |
hide(): void
Hide the terminal panel if this terminal is currently showing.
Returns | Description |
---|---|
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.
show(preserveFocus?: boolean): void
Show the terminal panel and reveal this terminal in the UI.
TerminalOptions
Value-object describing what options a terminal should use.
Properties
cwd?: string
A path for the current working directory to be used for the terminal.
Object with environment variables that will be added to the VS Code process.
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
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.
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.
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.
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.
- see - TextDocument.lineAt
offsetAt(position: Position): number
Converts the position to a zero-based offset.
The position will be adjusted.
positionAt(offset: number): Position
Converts a zero-based offset to a position.
Save the underlying file.
validatePosition(position: Position): Position
Ensure a position is contained in the range of this document.
validateRange(range: Range): Range
Ensure a range is completely contained in this document.
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
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.
Parameter | Description |
---|---|
uri: Uri | An uri which scheme matches the scheme this provider was registered for. |
token: CancellationToken | A cancellation token. |
Returns | Description |
ProviderResult<string> | A string or a thenable that resolves to such. |
TextDocumentSaveReason
Represents reasons why a text document is saved.
Enumeration members
TextDocumentShowOptions
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
TextDocumentWillSaveEvent
An event that is fired when a document will be saved.
To make modifications to the document before it is being saved, call the
waitUntil
-function with a thenable
that resolves to an array of text edits.
Properties
document: TextDocument
The document that will be saved.
reason: TextDocumentSaveReason
The reason why save was triggered.
Methods
waitUntil(thenable: Thenable<TextEdit[]>): void
Allows to pause the event loop and to apply pre-save-edits. Edits of subsequent calls to this function will be applied in order. The edits will be ignored if concurrent modifications of the document happened.
Note: This function can only be called during event dispatch and not in an asynchronous manner:
workspace.onWillSaveTextDocument(event => {
// async, will *throw* an error
setTimeout(() => event.waitUntil(promise));
// sync, OK
event.waitUntil(promise);
})
Parameter | Description |
---|---|
thenable: Thenable<TextEdit[]> | A thenable that resolves to pre-save-edits. |
Returns | Description |
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.
TextEdit
A text edit represents edits that should be applied to a document.
Static
delete(range: Range): TextEdit
Utility to create a delete edit.
insert(position: Position, newText: string): TextEdit
Utility to create an insert edit.
replace(range: Range, newText: string): TextEdit
Utility to create a replace edit.
setEndOfLine(eol: EndOfLine): TextEdit
Utility to create an eol-edit.
Constructors
new TextEdit(range: Range, newText: string): TextEdit
Create a new TextEdit.
Properties
newEol: EndOfLine
The eol-sequence used in the document.
Note that the eol-sequence will be applied to the whole document.
newText: string
The string this edit will insert.
range: Range
The range this edit applies to.
TextEditor
Represents an editor that is attached to a document.
Properties
document: TextDocument
The document associated with this text editor. The document will be the same for the entire lifetime of this text editor.
options: TextEditorOptions
Text editor options.
selection: Selection
The primary selection on this text editor. Shorthand for TextEditor.selections[0]
.
selections: Selection[]
The selections in this text editor. The primary selection is always at index 0.
viewColumn?: ViewColumn
The column in which this editor shows. Will be undefined
in case this
isn't one of the three main editors, e.g an embedded editor.
visibleRanges: Range[]
The current visible ranges in the editor (vertically). This accounts only for vertical scrolling, and not for horizontal scrolling.
Methods
edit(callback: (editBuilder: TextEditorEdit) => void, options?: {undoStopAfter: boolean, undoStopBefore: boolean}): Thenable<boolean>
Perform an edit on the document associated with this text editor.
The given callback-function is invoked with an edit-builder which must be used to make edits. Note that the edit-builder is only valid while the callback executes.
Parameter | Description |
---|---|
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. |
Returns | Description |
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.
Returns | Description |
---|---|
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.
Parameter | Description |
---|---|
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. |
Returns | Description |
Thenable<boolean> | A promise that resolves with a value indicating if the snippet could be inserted. Note that the promise does not signal that the snippet is completely filled-in or accepted. |
revealRange(range: Range, revealType?: TextEditorRevealType): void
Scroll as indicated by revealType
in order to reveal the given range.
Parameter | Description |
---|---|
range: Range | A range. |
revealType?: TextEditorRevealType | The scrolling strategy for revealing |
Returns | Description |
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.
Parameter | Description |
---|---|
decorationType: TextEditorDecorationType | A decoration type. |
rangesOrOptions: Range[] | DecorationOptions[] | |
Returns | Description |
void |
show(column?: ViewColumn): void
Show the text editor.
- deprecated - Use window.showTextDocument
Parameter | Description |
---|---|
column?: ViewColumn | The column in which to show this editor. instead. This method shows unexpected behavior and will be removed in the next major update. |
Returns | Description |
void |
TextEditorCursorStyle
Rendering style of the cursor.
Enumeration members
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.
Returns | Description |
---|---|
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.
insert(location: Position, value: string): 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.
setEndOfLine(endOfLine: EndOfLine): void
Set the end of line sequence.
TextEditorLineNumbersStyle
Rendering style of the line numbers.
Enumeration members
TextEditorOptions
Represents a text editor's options.
Properties
cursorStyle?: TextEditorCursorStyle
The rendering style of the cursor in this editor. When getting a text editor's options, this property will always be present. When setting a text editor's options, this property is optional.
insertSpaces?: boolean | string
When pressing Tab insert n spaces.
When getting a text editor's options, this property will always be a boolean (resolved).
When setting a text editor's options, this property is optional and it can be a boolean or "auto"
.
lineNumbers?: TextEditorLineNumbersStyle
Render relative line numbers w.r.t. the current line number. When getting a text editor's options, this property will always be present. When setting a text editor's options, this property is optional.
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
TextEditorSelectionChangeEvent
Represents an event describing the change in a text editor's selections.
Properties
kind?: TextEditorSelectionChangeKind
The change kind which has triggered this
event. Can be undefined
.
selections: 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
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
The new value for the text editor's view column.
TextEditorVisibleRangesChangeEvent
Represents an event describing the change in a text editor's visible ranges.
Properties
textEditor: TextEditor
The text editor for which the visible ranges have changed.
visibleRanges: Range[]
The new value for the text editor's visible ranges.
TextLine
Represents a line of text, such as a line of source code.
TextLine objects are immutable. When a document changes, previously retrieved lines will not represent the latest state.
Properties
firstNonWhitespaceCharacterIndex: number
The offset of the first character which is not a whitespace character as defined
by /\s/
. Note that if a line is all 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.
fontStyle?: string
CSS styling property that will be applied to the decoration attachment.
fontWeight?: string
CSS styling property that will be applied to the decoration attachment.
height?: string
CSS styling property that will be applied to the decoration attachment.
margin?: string
CSS styling property that will be applied to the decoration attachment.
textDecoration?: string
CSS styling property that will be applied to the decoration attachment.
width?: string
CSS styling property that will be applied to the decoration attachment.
ThemableDecorationInstanceRenderOptions
Properties
after?: ThemableDecorationAttachmentRenderOptions
Defines the rendering options of the attachment that is inserted after the decorated text
before?: ThemableDecorationAttachmentRenderOptions
Defines the rendering options of the attachment that is inserted before the decorated text
ThemableDecorationRenderOptions
Represents theme specific rendering styles for a text editor decoration.
Properties
after?: ThemableDecorationAttachmentRenderOptions
Defines the rendering options of the attachment that is inserted after the decorated text
backgroundColor?: string | ThemeColor
Background color of the decoration. Use rgba() and define transparent background colors to play well with other decorations. Alternatively a color from the color registry can be referenced.
before?: ThemableDecorationAttachmentRenderOptions
Defines the rendering options of the attachment that is inserted before the decorated text
border?: string
CSS styling property that will be applied to text enclosed by a decoration.
borderColor?: string | ThemeColor
CSS styling property that will be applied to text enclosed by a decoration. Better use 'border' for setting one or more of the individual border properties.
borderRadius?: string
CSS styling property that will be applied to text enclosed by a decoration. Better use 'border' for setting one or more of the individual border properties.
borderSpacing?: string
CSS styling property that will be applied to text enclosed by a decoration. Better use 'border' for setting one or more of the individual border properties.
borderStyle?: string
CSS styling property that will be applied to text enclosed by a decoration. Better use 'border' for setting one or more of the individual border properties.
borderWidth?: string
CSS styling property that will be applied to text enclosed by a decoration. Better use 'border' for setting one or more of the individual border properties.
color?: string | ThemeColor
CSS styling property that will be applied to text enclosed by a decoration.
cursor?: string
CSS styling property that will be applied to text enclosed by a decoration.
fontStyle?: string
CSS styling property that will be applied to text enclosed by a decoration.
fontWeight?: string
CSS styling property that will be applied to text enclosed by a decoration.
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.
Parameter | Description |
---|---|
id: string | of the color. The available colors are listed in https://code.visualstudio.com/docs/getstarted/theme-color-reference. |
Returns | Description |
ThemeColor |
ThemeIcon
A reference to a named icon. Currently only File and Folder are supported. Using a theme icon is preferred over a custom icon as it gives theme authors the possibility to change the icons.
Static
File: ThemeIcon
Reference to a icon representing a file. The icon is taken from the current file icon theme or a placeholder icon.
Folder: ThemeIcon
Reference to a icon representing a folder. The icon is taken from the current file icon theme or a placeholder icon.
Constructors
new ThemeIcon(id: string): ThemeIcon
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.
This will trigger the view to update the changed element/root and its children recursively (if shown).
To signal that root has changed, do not pass any argument or pass undefined
or null
.
Methods
getChildren(element?: T): ProviderResult<T[]>
Get the children of element
or root if no element is passed.
Parameter | Description |
---|---|
element?: T | The element from which the provider gets children. Can be |
Returns | Description |
ProviderResult<T[]> | Children of |
getParent(element: T): ProviderResult<T>
Optional method to return the parent of element
.
Return null
or undefined
if element
is a child of root.
NOTE: This method should be implemented in order to access reveal API.
Parameter | Description |
---|---|
element: T | The element for which the parent has to be returned. |
Returns | Description |
ProviderResult<T> | Parent of |
getTreeItem(element: T): TreeItem | Thenable<TreeItem>
Get TreeItem representation of the element
TreeItem
Constructors
new TreeItem(label: string, collapsibleState?: TreeItemCollapsibleState): TreeItem
Parameter | Description |
---|---|
label: string | A human-readable string describing this item |
collapsibleState?: TreeItemCollapsibleState | (#_TreeItemCollapsibleState) of the tree item. Default is TreeItemCollapsibleState.None |
Returns | Description |
TreeItem |
new TreeItem(resourceUri: Uri, collapsibleState?: TreeItemCollapsibleState): TreeItem
Parameter | Description |
---|---|
resourceUri: Uri | The uri of the resource representing this item. |
collapsibleState?: TreeItemCollapsibleState | (#_TreeItemCollapsibleState) of the tree item. Default is TreeItemCollapsibleState.None |
Returns | Description |
TreeItem |
Properties
collapsibleState?: TreeItemCollapsibleState
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} | ThemeIcon
The icon path or ThemeIcon for the tree item.
When falsy
, Folder Theme Icon is assigned, if item is collapsible otherwise File Theme Icon.
When a ThemeIcon is specified, icon is derived from the current file icon theme for the specified theme icon using resourceUri (if provided).
id?: string
Optional id for the tree item that has to be unique across tree. The id is used to preserve the selection and expansion state of the tree item.
If not provided, an id is generated using the tree item's label. Note that when labels change, ids will change and that selection and expansion state cannot be kept stable anymore.
label?: string
A human-readable string describing this item. When falsy
, it is derived from resourceUri.
resourceUri?: Uri
The tooltip text when you hover over this item.
TreeItemCollapsibleState
Collapsible state of the tree item
Enumeration members
TreeView<T>
Represents a Tree view
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.
Parameter | Description |
---|---|
...disposableLikes: {dispose: () => any}[] | Objects that have at least a |
Returns | Description |
Disposable | Returns a new disposable which, upon dispose, will dispose all provided disposables. |
Constructors
new TreeView(callOnDispose: Function): TreeView
Creates a new Disposable calling the provided function on dispose.
Methods
dispose(): any
Dispose this object.
Returns | Description |
---|---|
any |
reveal(element: T, options?: {select: boolean}): Thenable<void>
Reveal an element. By default revealed element is selected.
In order to not to select, set the option select
to false
.
NOTE: TreeDataProvider is required to implement getParent method to access this API.
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.
Parameter | Description |
---|---|
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. |
Returns | Description |
ProviderResult<Definition> | A definition or a thenable that resolves to such. The lack of a result can be
signaled by returning |
Uri
A universal resource identifier representing either a file on disk or another resource, like untitled resources.
Static
Create an URI from a file system path. The scheme
will be file
.
Create an URI from a string. Will throw if the given value is not valid.
Constructors
new Uri(scheme: string, authority: string, path: string, query: string, fragment: string): Uri
Use the file
and parse
factory functions to create new Uri
objects.
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.
Returns | Description |
---|---|
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.
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');
Parameter | Description |
---|---|
change: {authority: string, fragment: string, path: string, query: string, scheme: string} | An object that describes a change to this Uri. To unset components use |
Returns | Description |
Uri | A new Uri that reflects the given change. Will return |
ViewColumn
Denotes a column in the editor window. Columns are used to show editors side by side.
Enumeration members
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.
get<T>(section: string, defaultValue: T): T
Return a value from this configuration.
Check if this configuration has a certain value.
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.
update(section: string, value: any, configurationTarget?: ConfigurationTarget | boolean): Thenable<void>
Update a configuration value. The updated configuration values are persisted.
A value can be changed in
- Global configuration: Changes the value for all instances of the editor.
- Workspace configuration: Changes the value for current workspace, if available.
- Workspace folder configuration: Changes the value for the Workspace folder to which the current configuration is scoped to.
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
Parameter | Description |
---|---|
section: string | Configuration name, supports dotted names. |
value: any | The new value. |
configurationTarget?: ConfigurationTarget | boolean | The configuration target or a boolean value.
|
Returns | Description |
Thenable<void> |
WorkspaceEdit
A workspace edit represents textual and files changes for multiple resources and documents.
Properties
size: number
The number of affected resources.
Methods
delete(uri: Uri, range: Range): void
Delete the text at the given range.
entries(): [Uri, TextEdit[]][]
Get all text edits grouped by resource.
Get the text edits for a resource.
Check if this edit affects the given resource.
insert(uri: Uri, position: Position, newText: string): void
Insert the given text at the given position.
replace(uri: Uri, range: Range, newText: string): void
Replace the given range with given text for the given resource.
set(uri: Uri, edits: TextEdit[]): void
Set (and replace) text edits for a resource.
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 of its uri-path
uri: Uri
The associated uri for this workspace folder.
Note: The Uri-type was intentionally chosen such that future releases of the editor can support
workspace folders that are not stored on the local disk, e.g. ftp://server/workspaces/foo
.
WorkspaceFolderPickOptions
Options to configure the behaviour of the workspace folder pick UI.
Properties
ignoreFocusOut?: boolean
Set to true
to keep the picker open when focus moves to another part of the editor or to another window.
placeHolder?: string
An optional string to show as place holder in the input box to guide the user what to pick on.
WorkspaceFoldersChangeEvent
An event describing a change to the set of workspace folders.
Properties
added: 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.
The query
-parameter should be interpreted in a relaxed way as the editor will apply its own highlighting
and scoring on the results. A good rule of thumb is to match case-insensitive and to simply check that the
characters of query appear in their order in a candidate symbol. Don't use prefix, substring, or similar
strict matching.
Parameter | Description |
---|---|
query: string | A non-empty query string. |
token: CancellationToken | A cancellation token. |
Returns | Description |
ProviderResult<SymbolInformation[]> | An array of document highlights or a thenable that resolves to such. The lack of a result can be
signaled by returning |
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.
Parameter | Description |
---|---|
symbol: SymbolInformation | The symbol that is to be resolved. Guaranteed to be an instance of an object returned from an
earlier call to |
token: CancellationToken | A cancellation token. |
Returns | Description |
ProviderResult<SymbolInformation> | The resolved symbol or a thenable that resolves to that. When no result is returned,
the given |
Namespace for dealing with commands. In short, a command is a function with a unique identifier. The function is sometimes also called command handler.
Commands can be added to the editor using the registerCommand and registerTextEditorCommand functions. Commands can be executed manually or from a UI gesture. Those are:
commands
-section inpackage.json
to make a command show in the command palette.keybindings
-section inpackage.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" }] } }