VS Code API
VS Code API is a set of JavaScript APIs that you can invoke in your Visual Studio Code extension. This page lists all VS Code APIs available to extension authors.
API namespaces and classes
This listing is compiled from the vscode.d.ts file from the VS Code repository.
authentication
Events
onDidChangeSessions: Event<AuthenticationSessionsChangeEvent>
An Event which fires when the authentication sessions of an authentication provider have been added, removed, or changed.
Functions
getAccounts(providerId: string): Thenable<readonly AuthenticationSessionAccountInformation[]>
Get all accounts that the user is logged in to for the specified provider. Use this paired with getSession in order to get an authentication session for a specific account.
Currently, there are only two authentication providers that are contributed from built in extensions to the editor that implement GitHub and Microsoft authentication: their providerId's are 'github' and 'microsoft'.
Note: Getting accounts does not imply that your extension has access to that account or its authentication sessions. You can verify access to the account by calling getSession.
Parameter | Description |
---|---|
providerId: string | The id of the provider to use |
Returns | Description |
Thenable<readonly AuthenticationSessionAccountInformation[]> | A thenable that resolves to a readonly array of authentication accounts. |
getSession(providerId: string, scopes: readonly string[], options: AuthenticationGetSessionOptions & {createIfNone: true}): Thenable<AuthenticationSession>
Get an authentication session matching the desired scopes. Rejects if a provider with providerId is not registered, or if the user does not consent to sharing authentication information with the extension. If there are multiple sessions with the same scopes, the user will be shown a quickpick to select which account they would like to use.
Currently, there are only two authentication providers that are contributed from built in extensions to the editor that implement GitHub and Microsoft authentication: their providerId's are 'github' and 'microsoft'.
Parameter | Description |
---|---|
providerId: string | The id of the provider to use |
scopes: readonly string[] | A list of scopes representing the permissions requested. These are dependent on the authentication provider |
options: AuthenticationGetSessionOptions & {createIfNone: true} | The AuthenticationGetSessionOptions to use |
Returns | Description |
Thenable<AuthenticationSession> | A thenable that resolves to an authentication session |
getSession(providerId: string, scopes: readonly string[], options: AuthenticationGetSessionOptions & {forceNewSession: true | AuthenticationForceNewSessionOptions}): Thenable<AuthenticationSession>
Get an authentication session matching the desired scopes. Rejects if a provider with providerId is not registered, or if the user does not consent to sharing authentication information with the extension. If there are multiple sessions with the same scopes, the user will be shown a quickpick to select which account they would like to use.
Currently, there are only two authentication providers that are contributed from built in extensions to the editor that implement GitHub and Microsoft authentication: their providerId's are 'github' and 'microsoft'.
Parameter | Description |
---|---|
providerId: string | The id of the provider to use |
scopes: readonly string[] | A list of scopes representing the permissions requested. These are dependent on the authentication provider |
options: AuthenticationGetSessionOptions & {forceNewSession: true | AuthenticationForceNewSessionOptions} | The AuthenticationGetSessionOptions to use |
Returns | Description |
Thenable<AuthenticationSession> | A thenable that resolves to an authentication session |
getSession(providerId: string, scopes: readonly string[], options?: AuthenticationGetSessionOptions): Thenable<AuthenticationSession | undefined>
Get an authentication session matching the desired scopes. Rejects if a provider with providerId is not registered, or if the user does not consent to sharing authentication information with the extension. If there are multiple sessions with the same scopes, the user will be shown a quickpick to select which account they would like to use.
Currently, there are only two authentication providers that are contributed from built in extensions to the editor that implement GitHub and Microsoft authentication: their providerId's are 'github' and 'microsoft'.
Parameter | Description |
---|---|
providerId: string | The id of the provider to use |
scopes: readonly string[] | A list of scopes representing the permissions requested. These are dependent on the authentication provider |
options?: AuthenticationGetSessionOptions | The AuthenticationGetSessionOptions to use |
Returns | Description |
Thenable<AuthenticationSession | undefined> | A thenable that resolves to an authentication session if available, or undefined if there are no sessions |
registerAuthenticationProvider(id: string, label: string, provider: AuthenticationProvider, options?: AuthenticationProviderOptions): Disposable
Register an authentication provider.
There can only be one provider per id and an error is being thrown when an id has already been used by another provider. Ids are case-sensitive.
Parameter | Description |
---|---|
id: string | The unique identifier of the provider. |
label: string | The human-readable name of the provider. |
provider: AuthenticationProvider | The authentication provider provider. |
options?: AuthenticationProviderOptions | Additional options for the provider. |
Returns | Description |
Disposable | A Disposable that unregisters this provider when being disposed. |
chat
Namespace for chat functionality. Users interact with chat participants by sending messages to them in the chat view. Chat participants can respond with markdown or other types of content via the ChatResponseStream.
Functions
createChatParticipant(id: string, handler: ChatRequestHandler): ChatParticipant
Create a new chat participant instance.
Parameter | Description |
---|---|
id: string | A unique identifier for the participant. |
handler: ChatRequestHandler | A request handler for the participant. |
Returns | Description |
ChatParticipant | A new chat participant |
commands
Namespace for dealing with commands. In short, a command is a function with a unique identifier. The function is sometimes also called command handler.
Commands can be added to the editor using the registerCommand and registerTextEditorCommand functions. Commands can be executed manually or from a UI gesture. Those are:
- palette - Use the
commands
-section inpackage.json
to make a command show in the command palette. - keybinding - Use the
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"
}
]
}
}
Functions
executeCommand<T>(command: string, ...rest: any[]): Thenable<T>
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 as Position, Range, Uri and Location. - 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> | A thenable that resolves to the returned value of the given command. Returns |
getCommands(filterInternal?: boolean): Thenable<string[]>
Retrieve the list of all available commands. Commands starting with an underscore are treated as internal commands.
Parameter | Description |
---|---|
filterInternal?: boolean | Set |
Returns | Description |
Thenable<string[]> | Thenable that resolves to a list of command ids. |
registerCommand(command: string, callback: (args: any[]) => any, thisArg?: any): Disposable
Registers a command that can be invoked via a keyboard shortcut, a menu item, an action, or directly.
Registering a command with an existing command identifier twice will cause an error.
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. Note that the edit-builder is only valid while the callback executes.
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. |
comments
Functions
createCommentController(id: string, label: string): CommentController
Creates a new comment controller instance.
Parameter | Description |
---|---|
id: string | An |
label: string | A human-readable string for the comment controller. |
Returns | Description |
CommentController | An instance of comment controller. |
debug
Namespace for debug functionality.
Variables
activeDebugConsole: DebugConsole
The currently active debug console. If no debug session is active, output sent to the debug console is not shown.
activeDebugSession: DebugSession | undefined
The currently active debug session or undefined
. The active debug session is the one
represented by the debug action floating window or the one currently shown in the drop down menu of the debug action floating window.
If no debug session is active, the value is undefined
.
activeStackItem: DebugThread | DebugStackFrame | undefined
The currently focused thread or stack frame, or undefined
if no
thread or stack is focused. A thread can be focused any time there is
an active debug session, while a stack frame can only be focused when
a session is paused and the call stack has been retrieved.
breakpoints: readonly 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
.
onDidChangeActiveStackItem: Event<DebugThread | DebugStackFrame | undefined>
An event which fires when the debug.activeStackItem has changed.
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: readonly Breakpoint[]): void
Add breakpoints.
Parameter | Description |
---|---|
breakpoints: readonly Breakpoint[] | The breakpoints to add. |
Returns | Description |
void |
asDebugSourceUri(source: DebugProtocolSource, session?: DebugSession): Uri
Converts a "Source" descriptor object received via the Debug Adapter Protocol into a Uri that can be used to load its contents. If the source descriptor is based on a path, a file Uri is returned. If the source descriptor uses a reference number, a specific debug Uri (scheme 'debug') is constructed that requires a corresponding ContentProvider and a running debug session
If the "Source" descriptor has insufficient information for creating the Uri, an error is thrown.
Parameter | Description |
---|---|
source: DebugProtocolSource | An object conforming to the Source type defined in the Debug Adapter Protocol. |
session?: DebugSession | An optional debug session that will be used when the source descriptor uses a reference number to load the contents from an active debug session. |
Returns | Description |
Uri | A uri that can be used to load the contents of the source. |
registerDebugAdapterDescriptorFactory(debugType: string, factory: DebugAdapterDescriptorFactory): Disposable
Register a debug adapter descriptor factory for a specific debug type. An extension is only allowed to register a DebugAdapterDescriptorFactory for the debug type(s) defined by the extension. Otherwise an error is thrown. Registering more than one DebugAdapterDescriptorFactory for a debug type results in an error.
Parameter | Description |
---|---|
debugType: string | The debug type for which the factory is registered. |
factory: DebugAdapterDescriptorFactory | The debug adapter descriptor factory to register. |
Returns | Description |
Disposable | A Disposable that unregisters this factory when being disposed. |
registerDebugAdapterTrackerFactory(debugType: string, factory: DebugAdapterTrackerFactory): Disposable
Register a debug adapter tracker factory for the given debug type.
Parameter | Description |
---|---|
debugType: string | The debug type for which the factory is registered or '*' for matching all debug types. |
factory: DebugAdapterTrackerFactory | The debug adapter tracker factory to register. |
Returns | Description |
Disposable | A Disposable that unregisters this factory when being disposed. |
registerDebugConfigurationProvider(debugType: string, provider: DebugConfigurationProvider, triggerKind?: DebugConfigurationProviderTriggerKind): Disposable
Register a debug configuration provider for a specific debug type.
The optional triggerKind can be used to specify when the provideDebugConfigurations
method of the provider is triggered.
Currently two trigger kinds are possible: with the value Initial
(or if no trigger kind argument is given) the provideDebugConfigurations
method is used to provide the initial debug configurations to be copied into a newly created launch.json.
With the trigger kind Dynamic
the provideDebugConfigurations
method is used to dynamically determine debug configurations to be presented to the user (in addition to the static configurations from the launch.json).
Please note that the triggerKind
argument only applies to the provideDebugConfigurations
method: so the resolveDebugConfiguration
methods are not affected at all.
Registering a single provider with resolve methods for different trigger kinds, results in the same resolve methods called multiple times.
More than one provider can be registered for the same type.
Parameter | Description |
---|---|
debugType: string | The debug type for which the provider is registered. |
provider: DebugConfigurationProvider | The debug configuration provider to register. |
triggerKind?: DebugConfigurationProviderTriggerKind | The trigger for which the 'provideDebugConfiguration' method of the provider is registered. If |
Returns | Description |
Disposable | A Disposable that unregisters this provider when being disposed. |
removeBreakpoints(breakpoints: readonly Breakpoint[]): void
Remove breakpoints.
Parameter | Description |
---|---|
breakpoints: readonly Breakpoint[] | The breakpoints to remove. |
Returns | Description |
void |
startDebugging(folder: WorkspaceFolder, nameOrConfiguration: string | DebugConfiguration, parentSessionOrOptions?: DebugSession | DebugSessionOptions): Thenable<boolean>
Start debugging by using either a named launch or named compound configuration, or by directly passing a DebugConfiguration. The named configurations are looked up in '.vscode/launch.json' found in the given folder. Before debugging starts, all unsaved files are saved and the launch configurations are brought up-to-date. Folder specific variables used in the configuration (e.g. '${workspaceFolder}') are resolved against the given folder.
Parameter | Description |
---|---|
folder: WorkspaceFolder | 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. |
parentSessionOrOptions?: DebugSession | DebugSessionOptions | Debug session options. When passed a parent debug session, assumes options with just this parent session. |
Returns | Description |
Thenable<boolean> | A thenable that resolves when debugging could be successfully started. |
stopDebugging(session?: DebugSession): Thenable<void>
Stop the given debug session or stop all debug sessions if session is omitted.
Parameter | Description |
---|---|
session?: DebugSession | The debug session to stop; if omitted all sessions are stopped. |
Returns | Description |
Thenable<void> | A thenable that resolves when the session(s) have been stopped. |
env
Namespace describing the environment the editor runs in.
Variables
The hosted location of the application On desktop this is 'desktop' In the web this is the specified embedder i.e. 'github.dev', 'codespaces', or 'web' if the embedder does not provide that information
The application name of the editor, like 'VS Code'.
The application root folder from which the editor is running.
Note that the value is the empty string when running in an environment that has no representation of an application root folder.
clipboard: Clipboard
The system clipboard.
Indicates that this is a fresh install of the application.
true
if within the first day of installation otherwise false
.
Indicates whether the users has telemetry enabled. Can be observed to determine if the extension should send telemetry.
Represents the preferred user-language, like de-CH
, fr
, or en-US
.
logLevel: LogLevel
The current log level of the editor.
A unique identifier for the computer.
remoteName: string | undefined
The name of a remote. Defined by extensions, popular samples are wsl
for the Windows
Subsystem for Linux or ssh-remote
for remotes using a secure shell.
Note that the value is undefined
when there is no remote extension host but that the
value is defined in all extension hosts (local and remote) in case a remote extension host
exists. Use Extension.extensionKind to know if
a specific extension runs remote or not.
A unique identifier for the current session. Changes each time the editor is started.
The detected default shell for the extension host, this is overridden by the
terminal.integrated.defaultProfile
setting for the extension host's platform. Note that in
environments that do not support a shell the value is the empty string.
uiKind: UIKind
The UI kind property indicates from which UI extensions are accessed from. For example, extensions could be accessed from a desktop application or a web browser.
The custom uri scheme the editor registers to in the operating system.
Events
onDidChangeLogLevel: Event<LogLevel>
An Event which fires when the log level of the editor changes.
onDidChangeShell: Event<string>
An Event which fires when the default shell changes. This fires with the new shell path.
onDidChangeTelemetryEnabled: Event<boolean>
An Event which fires when the user enabled or disables telemetry.
true
if the user has enabled telemetry or false
if the user has disabled telemetry.
Functions
asExternalUri(target: Uri): Thenable<Uri>
Resolves a uri to a form that is accessible externally.
http:
or https:
scheme
Resolves an external uri, such as a http:
or https:
link, from where the extension is running to a
uri to the same resource on the client machine.
This is a no-op if the extension is running on the client machine.
If the extension is running remotely, this function automatically establishes a port forwarding tunnel
from the local machine to target
on the remote and returns a local uri to the tunnel. The lifetime of
the port forwarding tunnel is managed by the editor and the tunnel can be closed by the user.
Note that uris passed through openExternal
are automatically resolved and you should not call asExternalUri
on them.
vscode.env.uriScheme
Creates a uri that - if opened in a browser (e.g. via openExternal
) - will result in a registered UriHandler
to trigger.
Extensions should not make any assumptions about the resulting uri and should not alter it in any way. Rather, extensions can e.g. use this uri in an authentication flow, by adding the uri as callback query argument to the server to authenticate to.
Note that if the server decides to add additional query parameters to the uri (e.g. a token or secret), it will appear in the uri that is passed to the UriHandler.
Example of an authentication flow:
vscode.window.registerUriHandler({
handleUri(uri: vscode.Uri): vscode.ProviderResult<void> {
if (uri.path === '/did-authenticate') {
console.log(uri.toString());
}
}
});
const callableUri = await vscode.env.asExternalUri(
vscode.Uri.parse(vscode.env.uriScheme + '://my.extension/did-authenticate')
);
await vscode.env.openExternal(callableUri);
Note that extensions should not cache the result of asExternalUri
as the resolved uri may become invalid due to
a system or user action — for example, in remote cases, a user may close a port forwarding tunnel that was opened by
asExternalUri
.
Any other scheme
Any other scheme will be handled as if the provided URI is a workspace URI. In that case, the method will return a URI which, when handled, will make the editor open the workspace.
createTelemetryLogger(sender: TelemetrySender, options?: TelemetryLoggerOptions): TelemetryLogger
Creates a new telemetry logger.
Parameter | Description |
---|---|
sender: TelemetrySender | The telemetry sender that is used by the telemetry logger. |
options?: TelemetryLoggerOptions | Options for the telemetry logger. |
Returns | Description |
TelemetryLogger | A new telemetry logger |
openExternal(target: Uri): Thenable<boolean>
Opens a link externally using the default application. Depending on the used scheme this can be:
- a browser (
http:
,https:
) - a mail client (
mailto:
) - VSCode itself (
vscode:
fromvscode.env.uriScheme
)
Note that showTextDocument is the right way to open a text document inside the editor, not this function.
Parameter | Description |
---|---|
target: Uri | The uri that should be opened. |
Returns | Description |
Thenable<boolean> | A promise indicating if open was successful. |
extensions
Namespace for dealing with installed extensions. Extensions are represented by an Extension-interface which enables reflection on them.
Extension writers can provide APIs to other extensions by returning their API public
surface from the activate
-call.
export function activate(context: vscode.ExtensionContext) {
let api = {
sum(a, b) {
return a + b;
},
mul(a, b) {
return a * b;
}
};
// 'export' public api-surface
return api;
}
When depending on the API of another extension add an extensionDependencies
-entry
to package.json
, and use the getExtension-function
and the exports-property, like below:
let mathExt = extensions.getExtension('genius.math');
let importedApi = mathExt.exports;
console.log(importedApi.mul(42, 1));
Variables
all: readonly Extension<any>[]
All extensions currently known to the system.
Events
onDidChange: Event<void>
An event which fires when extensions.all
changes. This can happen when extensions are
installed, uninstalled, enabled or disabled.
Functions
getExtension<T>(extensionId: string): Extension<T> | undefined
Get an extension by its full identifier in the form of: publisher.name
.
Parameter | Description |
---|---|
extensionId: string | An extension identifier. |
Returns | Description |
Extension<T> | undefined | An extension or |
l10n
Namespace for localization-related functionality in the extension API. To use this properly,
you must have l10n
defined in your extension manifest and have bundle.l10n.
Note: Built-in extensions (for example, Git, TypeScript Language Features, GitHub Authentication)
are excluded from the l10n
property requirement. In other words, they do not need to specify
a l10n
in the extension manifest because their translated strings come from Language Packs.
Variables
The bundle of localized strings that have been loaded for the extension. It's undefined if no bundle has been loaded. The bundle is typically not loaded if there was no bundle found or when we are running with the default language.
uri: Uri | undefined
The URI of the localization bundle that has been loaded for the extension. It's undefined if no bundle has been loaded. The bundle is typically not loaded if there was no bundle found or when we are running with the default language.
Functions
t(message: string, ...args: Array<string | number | boolean>): string
Marks a string for localization. If a localized bundle is available for the language specified by env.language and the bundle has a localized value for this message, then that localized value will be returned (with injected args values for any templated values).
Example
l10n.t('Hello {0}!', 'World');
Parameter | Description |
---|---|
message: string | The message to localize. Supports index templating where strings like |
...args: Array<string | number | boolean> | The arguments to be used in the localized string. The index of the argument is used to match the template placeholder in the localized string. |
Returns | Description |
string | localized string with injected arguments. |
t(message: string, args: Record<string, any>): string
Marks a string for localization. If a localized bundle is available for the language specified by env.language and the bundle has a localized value for this message, then that localized value will be returned (with injected args values for any templated values).
Example
l10n.t('Hello {name}', { name: 'Erich' });
Parameter | Description |
---|---|
message: string | The message to localize. Supports named templating where strings like |
args: Record<string, any> | The arguments to be used in the localized string. The name of the key in the record is used to match the template placeholder in the localized string. |
Returns | Description |
string | localized string with injected arguments. |
t(options: {args: Array<string | number | boolean> | Record<string, any>, comment: string | string[], message: string}): string
Marks a string for localization. If a localized bundle is available for the language specified by env.language and the bundle has a localized value for this message, then that localized value will be returned (with injected args values for any templated values).
Parameter | Description |
---|---|
options: {args: Array<string | number | boolean> | Record<string, any>, comment: string | string[], message: string} | The options to use when localizing the message. |
Returns | Description |
string | localized string with injected arguments. |
languages
Namespace for participating in language-specific editor features, like IntelliSense, code actions, diagnostics etc.
Many programming languages exist and there is huge variety in syntaxes, semantics, and paradigms. Despite that, features like automatic word-completion, code navigation, or code checking have become popular across different tools for different programming languages.
The editor provides an API that makes it simple to provide such common features by having all UI and actions already in place and by allowing you to participate by providing data only. For instance, to contribute a hover all you have to do is provide a function that can be called with a TextDocument and a Position returning hover info. The rest, like tracking the mouse, positioning the hover, keeping the hover stable etc. is taken care of by the editor.
languages.registerHoverProvider('javascript', {
provideHover(document, position, token) {
return new Hover('I am a hover!');
}
});
Registration is done using a document selector which is either a language id, like javascript
or
a more complex filter like { language: 'typescript', scheme: 'file' }
. Matching a document against such
a selector will result in a score that is used to determine if and how a provider shall be used. When
scores are equal the provider that came last wins. For features that allow full arity, like hover,
the score is only checked to be >0
, for other features, like IntelliSense the
score is used for determining the order in which providers are asked to participate.
Events
onDidChangeDiagnostics: Event<DiagnosticChangeEvent>
An Event which fires when the global set of diagnostics changes. This is newly added and removed diagnostics.
Functions
createDiagnosticCollection(name?: string): DiagnosticCollection
Create a diagnostics collection.
Parameter | Description |
---|---|
name?: string | The name of the collection. |
Returns | Description |
DiagnosticCollection | A new diagnostic collection. |
createLanguageStatusItem(id: string, selector: DocumentSelector): LanguageStatusItem
Creates a new language status item.
Parameter | Description |
---|---|
id: string | The identifier of the item. |
selector: DocumentSelector | The document selector that defines for what editors the item shows. |
Returns | Description |
LanguageStatusItem | A new language status item. |
getDiagnostics(resource: Uri): Diagnostic[]
Get all diagnostics for a given resource.
Parameter | Description |
---|---|
resource: Uri | A resource |
Returns | Description |
Diagnostic[] | An array of diagnostics objects or an empty array. |
getDiagnostics(): Array<[Uri, Diagnostic[]]>
Get all diagnostics.
Parameter | Description |
---|---|
Returns | Description |
Array<[Uri, Diagnostic[]]> | An array of uri-diagnostics tuples or an empty array. |
getLanguages(): Thenable<string[]>
Return the identifiers of all known languages.
Parameter | Description |
---|---|
Returns | Description |
Thenable<string[]> | Promise resolving to an array of identifier strings. |
match(selector: DocumentSelector, document: TextDocument): number
Compute the match between a document selector and a document. Values greater than zero mean the selector matches the document.
A match is computed according to these rules:
- When DocumentSelector is an array, compute the match for each contained
DocumentFilter
or language identifier and take the maximum value. - A string will be desugared to become the
language
-part of a DocumentFilter, 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
,pattern
, ornotebook
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 maximum 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
// notebook cell document
doc.uri; // `vscode-notebook-cell:///my/notebook.ipynb#gl65s2pmha`;
doc.languageId; // 'python'
match({ notebookType: 'jupyter-notebook' }, doc); // 10
match({ notebookType: 'fooNotebook', language: 'python' }, doc); // 0
match({ language: 'python' }, doc); // 10
match({ notebookType: '*' }, doc); // 5
Parameter | Description |
---|---|
selector: DocumentSelector | A document selector. |
document: TextDocument | A text document. |
Returns | Description |
number | A number |
registerCallHierarchyProvider(selector: DocumentSelector, provider: CallHierarchyProvider): Disposable
Register a call hierarchy provider.
Parameter | Description |
---|---|
selector: DocumentSelector | A selector that defines the documents this provider is applicable to. |
provider: CallHierarchyProvider | A call hierarchy provider. |
Returns | Description |
Disposable | A Disposable that unregisters this provider when being disposed. |
registerCodeActionsProvider(selector: DocumentSelector, provider: CodeActionProvider<CodeAction>, metadata?: CodeActionProviderMetadata): Disposable
Register a code action provider.
Multiple providers can be registered for a language. In that case providers are asked in parallel and the results are merged. A failing provider (rejected promise or exception) will not cause a failure of the whole operation.
Parameter | Description |
---|---|
selector: DocumentSelector | A selector that defines the documents this provider is applicable to. |
provider: CodeActionProvider<CodeAction> | A code action provider. |
metadata?: CodeActionProviderMetadata | Metadata about the kind of code actions the provider provides. |
Returns | Description |
Disposable | A Disposable that unregisters this provider when being disposed. |
registerCodeLensProvider(selector: DocumentSelector, provider: CodeLensProvider<CodeLens>): 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<CodeLens> | 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<CompletionItem>, ...triggerCharacters: string[]): Disposable
Register a completion provider.
Multiple providers can be registered for a language. In that case providers are sorted by their score and groups of equal score are sequentially asked for completion items. The process stops when one or many providers of a group return a result. A failing provider (rejected promise or exception) will not fail the whole operation.
A completion item provider can be associated with a set of triggerCharacters
. When trigger
characters are being typed, completions are requested but only from providers that registered
the typed character. Because of that trigger characters should be different than word characters,
a common trigger character is .
to trigger member completions.
Parameter | Description |
---|---|
selector: DocumentSelector | A selector that defines the documents this provider is applicable to. |
provider: CompletionItemProvider<CompletionItem> | A completion provider. |
...triggerCharacters: string[] | Trigger completion when the user types one of the characters. |
Returns | Description |
Disposable | A Disposable that unregisters this provider when being disposed. |
registerDeclarationProvider(selector: DocumentSelector, provider: DeclarationProvider): Disposable
Register a declaration provider.
Multiple providers can be registered for a language. In that case providers are asked in parallel and the results are merged. A failing provider (rejected promise or exception) will not cause a failure of the whole operation.
Parameter | Description |
---|---|
selector: DocumentSelector | A selector that defines the documents this provider is applicable to. |
provider: DeclarationProvider | A declaration provider. |
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. |
registerDocumentDropEditProvider(selector: DocumentSelector, provider: DocumentDropEditProvider): Disposable
Registers a new DocumentDropEditProvider.
Parameter | Description |
---|---|
selector: DocumentSelector | A selector that defines the documents this provider applies to. |
provider: DocumentDropEditProvider | A drop provider. |
Returns | Description |
Disposable | A Disposable that unregisters this provider when disposed of. |
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<DocumentLink>): 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<DocumentLink> | 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. |
registerDocumentRangeSemanticTokensProvider(selector: DocumentSelector, provider: DocumentRangeSemanticTokensProvider, legend: SemanticTokensLegend): Disposable
Register a semantic tokens provider for a document range.
Note: If a document has both a DocumentSemanticTokensProvider
and a DocumentRangeSemanticTokensProvider
,
the range provider will be invoked only initially, for the time in which the full document provider takes
to resolve the first request. Once the full document provider resolves the first request, the semantic tokens
provided via the range provider will be discarded and from that point forward, only the document provider
will be used.
Multiple providers can be registered for a language. In that case providers are sorted by their score and the best-matching provider is used. Failure of the selected provider will cause a failure of the whole operation.
Parameter | Description |
---|---|
selector: DocumentSelector | A selector that defines the documents this provider is applicable to. |
provider: DocumentRangeSemanticTokensProvider | A document range semantic tokens provider. |
legend: SemanticTokensLegend | |
Returns | Description |
Disposable | A Disposable that unregisters this provider when being disposed. |
registerDocumentSemanticTokensProvider(selector: DocumentSelector, provider: DocumentSemanticTokensProvider, legend: SemanticTokensLegend): Disposable
Register a semantic tokens provider for a whole document.
Multiple providers can be registered for a language. In that case providers are sorted by their score and the best-matching provider is used. Failure of the selected provider will cause a failure of the whole operation.
Parameter | Description |
---|---|
selector: DocumentSelector | A selector that defines the documents this provider is applicable to. |
provider: DocumentSemanticTokensProvider | A document semantic tokens provider. |
legend: SemanticTokensLegend | |
Returns | Description |
Disposable | A Disposable that unregisters this provider when being disposed. |
registerDocumentSymbolProvider(selector: DocumentSelector, provider: DocumentSymbolProvider, metaData?: DocumentSymbolProviderMetadata): Disposable
Register a document symbol provider.
Multiple providers can be registered for a language. In that case providers are asked in parallel and the results are merged. A failing provider (rejected promise or exception) will not cause a failure of the whole operation.
Parameter | Description |
---|---|
selector: DocumentSelector | A selector that defines the documents this provider is applicable to. |
provider: DocumentSymbolProvider | A document symbol provider. |
metaData?: DocumentSymbolProviderMetadata | metadata about the provider |
Returns | Description |
Disposable | A Disposable that unregisters this provider when being disposed. |
registerEvaluatableExpressionProvider(selector: DocumentSelector, provider: EvaluatableExpressionProvider): Disposable
Register a provider that locates evaluatable expressions in text documents. The editor will evaluate the expression in the active debug session and will show the result in the debug hover.
If multiple providers are registered for a language an arbitrary provider will be used.
Parameter | Description |
---|---|
selector: DocumentSelector | A selector that defines the documents this provider is applicable to. |
provider: EvaluatableExpressionProvider | An evaluatable expression provider. |
Returns | Description |
Disposable | A Disposable that unregisters this provider when being disposed. |
registerFoldingRangeProvider(selector: DocumentSelector, provider: FoldingRangeProvider): Disposable
Register a folding range provider.
Multiple providers can be registered for a language. In that case providers are asked in parallel and the results are merged. If multiple folding ranges start at the same position, only the range of the first registered provider is used. If a folding range overlaps with an other range that has a smaller position, it is also ignored.
A failing provider (rejected promise or exception) will not cause a failure of the whole operation.
Parameter | Description |
---|---|
selector: DocumentSelector | A selector that defines the documents this provider is applicable to. |
provider: FoldingRangeProvider | A folding range 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. |
registerInlayHintsProvider(selector: DocumentSelector, provider: InlayHintsProvider<InlayHint>): Disposable
Register a inlay hints 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: InlayHintsProvider<InlayHint> | An inlay hints provider. |
Returns | Description |
Disposable | A Disposable that unregisters this provider when being disposed. |
registerInlineCompletionItemProvider(selector: DocumentSelector, provider: InlineCompletionItemProvider): Disposable
Registers an inline completion 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: InlineCompletionItemProvider | An inline completion provider. |
Returns | Description |
Disposable | A Disposable that unregisters this provider when being disposed. |
registerInlineValuesProvider(selector: DocumentSelector, provider: InlineValuesProvider): Disposable
Register a provider that returns data for the debugger's 'inline value' feature. Whenever the generic debugger has stopped in a source file, providers registered for the language of the file are called to return textual data that will be shown in the editor at the end of lines.
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: InlineValuesProvider | An inline values provider. |
Returns | Description |
Disposable | A Disposable that unregisters this provider when being disposed. |
registerLinkedEditingRangeProvider(selector: DocumentSelector, provider: LinkedEditingRangeProvider): Disposable
Register a linked editing range provider.
Multiple providers can be registered for a language. In that case providers are sorted by their score and the best-matching provider that has a result 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: LinkedEditingRangeProvider | A linked editing range 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 rename provider.
Multiple providers can be registered for a language. In that case providers are sorted by their score and asked in sequence. The first provider producing a result defines the result of the whole operation.
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. |
registerSelectionRangeProvider(selector: DocumentSelector, provider: SelectionRangeProvider): Disposable
Register a selection range provider.
Multiple providers can be registered for a language. In that case providers are asked in parallel and the results are merged. A failing provider (rejected promise or exception) will not cause a failure of the whole operation.
Parameter | Description |
---|---|
selector: DocumentSelector | A selector that defines the documents this provider is applicable to. |
provider: SelectionRangeProvider | A selection range 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. |
registerSignatureHelpProvider(selector: DocumentSelector, provider: SignatureHelpProvider, metadata: SignatureHelpProviderMetadata): Disposable
Parameter | Description |
---|---|
selector: DocumentSelector | A selector that defines the documents this provider is applicable to. |
provider: SignatureHelpProvider | A signature help provider. |
metadata: SignatureHelpProviderMetadata | Information about the provider. |
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. |
registerTypeHierarchyProvider(selector: DocumentSelector, provider: TypeHierarchyProvider): Disposable
Register a type hierarchy provider.
Parameter | Description |
---|---|
selector: DocumentSelector | A selector that defines the documents this provider is applicable to. |
provider: TypeHierarchyProvider | A type hierarchy provider. |
Returns | Description |
Disposable | A Disposable that unregisters this provider when being disposed. |
registerWorkspaceSymbolProvider(provider: WorkspaceSymbolProvider<SymbolInformation>): 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<SymbolInformation> | 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. |
setTextDocumentLanguage(document: TextDocument, languageId: string): Thenable<TextDocument>
Set (and change) the language that is associated with the given document.
Note that calling this function will trigger the onDidCloseTextDocument event followed by the onDidOpenTextDocument event.
Parameter | Description |
---|---|
document: TextDocument | The document which language is to be changed |
languageId: string | The new language identifier. |
Returns | Description |
Thenable<TextDocument> | A thenable that resolves with the updated document. |
lm
Namespace for language model related functionality.
Events
onDidChangeChatModels: Event<void>
An event that is fired when the set of available chat models changes.
Functions
selectChatModels(selector?: LanguageModelChatSelector): Thenable<LanguageModelChat[]>
Select chat models by a selector. This can yield multiple or no chat models and extensions must handle these cases, esp. when no chat model exists, gracefully.
const models = await vscode.lm.selectChatModels({ family: 'gpt-3.5-turbo' });
if (models.length > 0) {
const [first] = models;
const response = await first.sendRequest(...)
// ...
} else {
// NO chat models available
}
A selector can be written to broadly match all models of a given vendor or family, or it can narrowly select one model by ID. Keep in mind that the available set of models will change over time, but also that prompts may perform differently in different models.
Note that extensions can hold on to the results returned by this function and use them later. However, when the onDidChangeChatModels-event is fired the list of chat models might have changed and extensions should re-query.
Parameter | Description |
---|---|
selector?: LanguageModelChatSelector | A chat model selector. When omitted all chat models are returned. |
Returns | Description |
Thenable<LanguageModelChat[]> | An array of chat models, can be empty! |
notebooks
Namespace for notebooks.
The notebooks functionality is composed of three loosely coupled components:
- NotebookSerializer enable the editor to open, show, and save notebooks
- NotebookController own the execution of notebooks, e.g they create output from code cells.
- NotebookRenderer present notebook output in the editor. They run in a separate context.
Functions
createNotebookController(id: string, notebookType: string, label: string, handler?: (cells: NotebookCell[], notebook: NotebookDocument, controller: NotebookController) => void | Thenable<void>): NotebookController
Creates a new notebook controller.
Parameter | Description |
---|---|
id: string | Identifier of the controller. Must be unique per extension. |
notebookType: string | A notebook type for which this controller is for. |
label: string | The label of the controller. |
handler?: (cells: NotebookCell[], notebook: NotebookDocument, controller: NotebookController) => void | Thenable<void> | The execute-handler of the controller. |
Returns | Description |
NotebookController | A new notebook controller. |
createRendererMessaging(rendererId: string): NotebookRendererMessaging
Creates a new messaging instance used to communicate with a specific renderer.
- Note 1: Extensions can only create renderer that they have defined in their
package.json
-file - Note 2: A renderer only has access to messaging if
requiresMessaging
is set toalways
oroptional
in itsnotebookRenderer
contribution.
Parameter | Description |
---|---|
rendererId: string | The renderer ID to communicate with |
Returns | Description |
NotebookRendererMessaging | A new notebook renderer messaging object. |
registerNotebookCellStatusBarItemProvider(notebookType: string, provider: NotebookCellStatusBarItemProvider): Disposable
Register a cell statusbar item provider for the given notebook type.
Parameter | Description |
---|---|
notebookType: string | The notebook type to register for. |
provider: NotebookCellStatusBarItemProvider | A cell status bar provider. |
Returns | Description |
Disposable | A Disposable that unregisters this provider when being disposed. |
scm
Namespace for source control mangement.
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. E.g.: |
rootUri?: Uri | An optional Uri of the root of the source control. E.g.: |
Returns | Description |
SourceControl | An instance of source control. |
tasks
Namespace for tasks functionality.
Variables
taskExecutions: readonly TaskExecution[]
The currently active task executions or an empty array.
Events
onDidEndTask: Event<TaskEndEvent>
Fires when a task ends.
onDidEndTaskProcess: Event<TaskProcessEndEvent>
Fires when the underlying process has ended. This event will not fire for tasks that don't execute an underlying process.
onDidStartTask: Event<TaskStartEvent>
Fires when a task starts.
onDidStartTaskProcess: Event<TaskProcessStartEvent>
Fires when the underlying process has been started. This event will not fire for tasks that don't execute an underlying process.
Functions
executeTask(task: Task): Thenable<TaskExecution>
Executes a task that is managed by the editor. The returned task execution can be used to terminate the task.
- throws - When running a ShellExecution or a ProcessExecution task in an environment where a new process cannot be started. In such an environment, only CustomExecution tasks can be run.
Parameter | Description |
---|---|
task: Task | the task to execute |
Returns | Description |
Thenable<TaskExecution> | A thenable that resolves to a task execution. |
fetchTasks(filter?: TaskFilter): Thenable<Task[]>
Fetches all tasks available in the systems. This includes tasks
from tasks.json
files as well as tasks from task providers
contributed through extensions.
Parameter | Description |
---|---|
filter?: TaskFilter | Optional filter to select tasks of a certain type or version. |
Returns | Description |
Thenable<Task[]> | A thenable that resolves to an array of tasks. |
registerTaskProvider(type: string, provider: TaskProvider<Task>): Disposable
Register a task provider.
Parameter | Description |
---|---|
type: string | The task kind type this provider is registered for. |
provider: TaskProvider<Task> | A task provider. |
Returns | Description |
Disposable | A Disposable that unregisters this provider when being disposed. |
tests
Namespace for testing functionality. Tests are published by registering TestController instances, then adding TestItems. Controllers may also describe how to run tests by creating one or more TestRunProfile instances.
Functions
createTestController(id: string, label: string): TestController
Creates a new test controller.
Parameter | Description |
---|---|
id: string | Identifier for the controller, must be globally unique. |
label: string | A human-readable label for the controller. |
Returns | Description |
TestController | An instance of the TestController. |
window
Namespace for dealing with the current window of the editor. That is visible and active editors, as well as, UI elements to show messages, selections, and asking for user input.
Variables
activeColorTheme: ColorTheme
The currently active color theme as configured in the settings. The active
theme can be changed via the workbench.colorTheme
setting.
activeNotebookEditor: NotebookEditor | undefined
The currently active notebook 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.
activeTerminal: Terminal | undefined
The currently active terminal or undefined
. The active terminal is the one that
currently has focus or most recently had focus.
activeTextEditor: TextEditor | undefined
The currently active editor or undefined
. The active editor is the one
that currently has focus or, when none has focus, the one that has changed
input most recently.
state: WindowState
Represents the current window's state.
tabGroups: TabGroups
Represents the grid widget within the main editor area
terminals: readonly Terminal[]
The currently opened terminals or an empty array.
visibleNotebookEditors: readonly NotebookEditor[]
The currently visible notebook editors or an empty array.
visibleTextEditors: readonly TextEditor[]
The currently visible editors or an empty array.
Events
onDidChangeActiveColorTheme: Event<ColorTheme>
An Event which fires when the active color theme is changed or has changes.
onDidChangeActiveNotebookEditor: Event<NotebookEditor | undefined>
An Event which fires when the active notebook editor
has changed. Note that the event also fires when the active editor changes
to undefined
.
onDidChangeActiveTerminal: Event<Terminal | undefined>
An Event which fires when the active terminal
has changed. Note that the event also fires when the active terminal changes
to undefined
.
onDidChangeActiveTextEditor: Event<TextEditor | undefined>
An Event which fires when the active editor
has changed. Note that the event also fires when the active editor changes
to undefined
.
onDidChangeNotebookEditorSelection: Event<NotebookEditorSelectionChangeEvent>
An Event which fires when the notebook editor selections have changed.
onDidChangeNotebookEditorVisibleRanges: Event<NotebookEditorVisibleRangesChangeEvent>
An Event which fires when the notebook editor visible ranges have changed.
onDidChangeTerminalShellIntegration: Event<TerminalShellIntegrationChangeEvent>
Fires when shell integration activates or one of its properties changes in a terminal.
onDidChangeTerminalState: Event<Terminal>
An Event which fires when a terminal's state has changed.
onDidChangeTextEditorOptions: Event<TextEditorOptionsChangeEvent>
An Event which fires when the options of an editor have changed.
onDidChangeTextEditorSelection: Event<TextEditorSelectionChangeEvent>
An Event which fires when the selection in an editor has changed.
onDidChangeTextEditorViewColumn: Event<TextEditorViewColumnChangeEvent>
An Event which fires when the view column of an editor has changed.
onDidChangeTextEditorVisibleRanges: Event<TextEditorVisibleRangesChangeEvent>
An Event which fires when the visible ranges of an editor has changed.
onDidChangeVisibleNotebookEditors: Event<readonly NotebookEditor[]>
An Event which fires when the visible notebook editors has changed.
onDidChangeVisibleTextEditors: Event<readonly TextEditor[]>
An Event which fires when the array of visible editors has changed.
onDidChangeWindowState: Event<WindowState>
An Event which fires when the focus or activity 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.
onDidEndTerminalShellExecution: Event<TerminalShellExecutionEndEvent>
This will be fired when a terminal command is ended. This event will fire only when shell integration is activated for the terminal.
onDidOpenTerminal: Event<Terminal>
An Event which fires when a terminal has been created, either through the createTerminal API or commands.
onDidStartTerminalShellExecution: Event<TerminalShellExecutionStartEvent>
This will be fired when a terminal command is started. This event will fire only when shell integration is activated for the terminal.
Functions
createInputBox(): InputBox
Creates a InputBox to let the user enter some text input.
Note that in many cases the more convenient window.showInputBox is easier to use. window.createInputBox should be used when window.showInputBox does not offer the required flexibility.
createOutputChannel(name: string, languageId?: string): OutputChannel
Creates a new output channel with the given name and language id If language id is not provided, then Log is used as default language id.
You can access the visible or active output channel as a text document from visible editors or active editor and use the language id to contribute language features like syntax coloring, code lens etc.,
Parameter | Description |
---|---|
name: string | Human-readable string which will be used to represent the channel in the UI. |
languageId?: string | The identifier of the language associated with the channel. |
Returns | Description |
OutputChannel | A new output channel. |
createOutputChannel(name: string, options: {log: true}): LogOutputChannel
Creates a new log output channel with the given name.
Parameter | Description |
---|---|
name: string | Human-readable string which will be used to represent the channel in the UI. |
options: {log: true} | Options for the log output channel. |
Returns | Description |
LogOutputChannel | A new log output channel. |
createQuickPick<T extends QuickPickItem>(): QuickPick<T>
Creates a QuickPick to let the user pick an item from a list of items of type T.
Note that in many cases the more convenient window.showQuickPick is easier to use. window.createQuickPick should be used when window.showQuickPick does not offer the required flexibility.
createStatusBarItem(id: string, alignment?: StatusBarAlignment, priority?: number): StatusBarItem
Creates a status bar item.
Parameter | Description |
---|---|
id: string | The identifier of the item. Must be unique within the extension. |
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. |
createStatusBarItem(alignment?: StatusBarAlignment, priority?: number): StatusBarItem
Creates a status bar item.
See also createStatusBarItem for creating a status bar item with an identifier.
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 | readonly string[]): Terminal
Creates a Terminal with a backing shell process. The cwd of the terminal will be the workspace directory if it exists.
- throws - When running in an environment where a new process cannot be started.
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 | readonly string[] | Optional args for the custom shell executable. A string can be used on Windows only which allows specifying shell args in command-line format. |
Returns | Description |
Terminal | A new Terminal. |
createTerminal(options: TerminalOptions): Terminal
Creates a Terminal with a backing shell process.
- throws - When running in an environment where a new process cannot be started.
Parameter | Description |
---|---|
options: TerminalOptions | A TerminalOptions object describing the characteristics of the new terminal. |
Returns | Description |
Terminal | A new Terminal. |
createTerminal(options: ExtensionTerminalOptions): Terminal
Creates a Terminal where an extension controls its input and output.
Parameter | Description |
---|---|
options: ExtensionTerminalOptions | An ExtensionTerminalOptions 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: TreeViewOptions<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: TreeViewOptions<T> | Options for creating the TreeView |
Returns | Description |
TreeView<T> | a TreeView. |
createWebviewPanel(viewType: string, title: string, showOptions: ViewColumn | {preserveFocus: boolean, viewColumn: ViewColumn}, options?: WebviewPanelOptions & WebviewOptions): WebviewPanel
Create and show a new webview panel.
Parameter | Description |
---|---|
viewType: string | Identifies the type of the webview panel. |
title: string | Title of the panel. |
showOptions: ViewColumn | {preserveFocus: boolean, viewColumn: ViewColumn} | Where to show the webview in the editor. If preserveFocus is set, the new webview will not take focus. |
options?: WebviewPanelOptions & WebviewOptions | Settings for the new panel. |
Returns | Description |
WebviewPanel | New webview panel. |
registerCustomEditorProvider(viewType: string, provider: CustomTextEditorProvider | CustomReadonlyEditorProvider<CustomDocument> | CustomEditorProvider<CustomDocument>, options?: {supportsMultipleEditorsPerDocument: boolean, webviewOptions: WebviewPanelOptions}): Disposable
Register a provider for custom editors for the viewType
contributed by the customEditors
extension point.
When a custom editor is opened, an onCustomEditor:viewType
activation event is fired. Your extension
must register a CustomTextEditorProvider, CustomReadonlyEditorProvider,
CustomEditorProviderfor viewType
as part of activation.
Parameter | Description |
---|---|
viewType: string | Unique identifier for the custom editor provider. This should match the |
provider: CustomTextEditorProvider | CustomReadonlyEditorProvider<CustomDocument> | CustomEditorProvider<CustomDocument> | Provider that resolves custom editors. |
options?: {supportsMultipleEditorsPerDocument: boolean, webviewOptions: WebviewPanelOptions} | Options for the provider. |
Returns | Description |
Disposable | Disposable that unregisters the provider. |
registerFileDecorationProvider(provider: FileDecorationProvider): Disposable
Register a file decoration provider.
Parameter | Description |
---|---|
provider: FileDecorationProvider | |
Returns | Description |
Disposable | A Disposable that unregisters the provider. |
registerTerminalLinkProvider(provider: TerminalLinkProvider<TerminalLink>): Disposable
Register provider that enables the detection and handling of links within the terminal.
Parameter | Description |
---|---|
provider: TerminalLinkProvider<TerminalLink> | The provider that provides the terminal links. |
Returns | Description |
Disposable | Disposable that unregisters the provider. |
registerTerminalProfileProvider(id: string, provider: TerminalProfileProvider): Disposable
Registers a provider for a contributed terminal profile.
Parameter | Description |
---|---|
id: string | The ID of the contributed terminal profile. |
provider: TerminalProfileProvider | The terminal profile provider. |
Returns | Description |
Disposable | A disposable that unregisters the provider. |
registerTreeDataProvider<T>(viewId: string, treeDataProvider: TreeDataProvider<T>): Disposable
Register a TreeDataProvider for the view contributed using the extension point views
.
This will allow you to contribute data to the TreeView and update if the data changes.
Note: To get access to the TreeView and perform operations on it, use createTreeView.
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 | A disposable that unregisters the TreeDataProvider. |
registerUriHandler(handler: UriHandler): Disposable
Registers a uri handler capable of handling system-wide uris. In case there are multiple windows open, the topmost window will handle the uri. A uri handler is scoped to the extension it is contributed from; it will only be able to handle uris which are directed to the extension itself. A uri must respect the following rules:
- The uri-scheme must be
vscode.env.uriScheme
; - The uri-authority must be the extension id (e.g.
my.extension
); - The uri-path, -query and -fragment parts are arbitrary.
For example, if the my.extension
extension registers a uri handler, it will only
be allowed to handle uris with the prefix product-name://my.extension
.
An extension can only register a single uri handler in its entire activation lifetime.
- Note: There is an activation event
onUri
that fires when a uri directed for the current extension is about to be handled.
Parameter | Description |
---|---|
handler: UriHandler | The uri handler to register for this extension. |
Returns | Description |
Disposable | A disposable that unregisters the handler. |
registerWebviewPanelSerializer(viewType: string, serializer: WebviewPanelSerializer<unknown>): Disposable
Registers a webview panel serializer.
Extensions that support reviving should have an "onWebviewPanel:viewType"
activation event and
make sure that registerWebviewPanelSerializer
is called during activation.
Only a single serializer may be registered at a time for a given viewType
.
Parameter | Description |
---|---|
viewType: string | Type of the webview panel that can be serialized. |
serializer: WebviewPanelSerializer<unknown> | Webview serializer. |
Returns | Description |
Disposable | A disposable that unregisters the serializer. |
registerWebviewViewProvider(viewId: string, provider: WebviewViewProvider, options?: {webviewOptions: {retainContextWhenHidden: boolean}}): Disposable
Register a new provider for webview views.
Parameter | Description |
---|---|
viewId: string | Unique id of the view. This should match the |
provider: WebviewViewProvider | Provider for the webview views. |
options?: {webviewOptions: {retainContextWhenHidden: boolean}} | |
Returns | Description |
Disposable | Disposable that unregisters the provider. |
setStatusBarMessage(text: string, hideAfterTimeout: number): Disposable
Set a message to the status bar. This is a short hand for the more powerful status bar items.
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<T extends string>(message: string, ...items: T[]): Thenable<T | undefined>
Show an error message.
See also showInformationMessage
Parameter | Description |
---|---|
message: string | The message to show. |
...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 |
showErrorMessage<T extends string>(message: string, options: MessageOptions, ...items: T[]): Thenable<T | undefined>
Show an error message.
See also 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 |
showErrorMessage<T extends MessageItem>(message: string, ...items: T[]): Thenable<T | undefined>
Show an error message.
See also showInformationMessage
Parameter | Description |
---|---|
message: string | The message to show. |
...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 |
showErrorMessage<T extends MessageItem>(message: string, options: MessageOptions, ...items: T[]): Thenable<T | undefined>
Show an error message.
See also 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<T extends string>(message: string, ...items: T[]): Thenable<T | 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. |
...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<T extends string>(message: string, options: MessageOptions, ...items: T[]): Thenable<T | 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: 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<T extends MessageItem>(message: string, ...items: T[]): Thenable<T | undefined>
Show an information message.
See also showInformationMessage
Parameter | Description |
---|---|
message: string | The message to show. |
...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<T extends MessageItem>(message: string, options: MessageOptions, ...items: T[]): Thenable<T | undefined>
Show an information message.
See also 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 |
showNotebookDocument(document: NotebookDocument, options?: NotebookDocumentShowOptions): Thenable<NotebookEditor>
Show the given NotebookDocument in a notebook editor.
Parameter | Description |
---|---|
document: NotebookDocument | A text document to be shown. |
options?: NotebookDocumentShowOptions | Editor options to configure the behavior of showing the notebook editor. |
Returns | Description |
Thenable<NotebookEditor> | A promise that resolves to an notebook editor. |
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: readonly string[] | Thenable<readonly string[]>, options: QuickPickOptions & {canPickMany: true}, token?: CancellationToken): Thenable<string[] | undefined>
Shows a selection list allowing multiple selections.
Parameter | Description |
---|---|
items: readonly string[] | Thenable<readonly string[]> | An array of strings, or a promise that resolves to an array of strings. |
options: QuickPickOptions & {canPickMany: true} | Configures the behavior of the selection list. |
token?: CancellationToken | A token that can be used to signal cancellation. |
Returns | Description |
Thenable<string[] | undefined> | A promise that resolves to the selected items or |
showQuickPick(items: readonly string[] | Thenable<readonly string[]>, options?: QuickPickOptions, token?: CancellationToken): Thenable<string | undefined>
Shows a selection list.
Parameter | Description |
---|---|
items: readonly string[] | Thenable<readonly 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: readonly T[] | Thenable<readonly T[]>, options: QuickPickOptions & {canPickMany: true}, token?: CancellationToken): Thenable<T[] | undefined>
Shows a selection list allowing multiple selections.
Parameter | Description |
---|---|
items: readonly T[] | Thenable<readonly T[]> | An array of items, or a promise that resolves to an array of items. |
options: QuickPickOptions & {canPickMany: true} | Configures the behavior of the selection list. |
token?: CancellationToken | A token that can be used to signal cancellation. |
Returns | Description |
Thenable<T[] | undefined> | A promise that resolves to the selected items or |
showQuickPick<T extends QuickPickItem>(items: readonly T[] | Thenable<readonly T[]>, options?: QuickPickOptions, token?: CancellationToken): Thenable<T | undefined>
Shows a selection list.
Parameter | Description |
---|---|
items: readonly T[] | Thenable<readonly 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 | A view column in which the editor should be shown. The default is the active. Columns that do not exist will be created as needed up to the maximum of ViewColumn.Nine. Use ViewColumn.Beside to open the editor to the side of the currently active one. |
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 | Editor options 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 also workspace.openTextDocument
Parameter | Description |
---|---|
uri: Uri | A resource identifier. |
options?: TextDocumentShowOptions | Editor options to configure the behavior of showing the editor. |
Returns | Description |
Thenable<TextEditor> | A promise that resolves to an editor. |
showWarningMessage<T extends string>(message: string, ...items: T[]): Thenable<T | undefined>
Show a warning message.
See also showInformationMessage
Parameter | Description |
---|---|
message: string | The message to show. |
...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 |
showWarningMessage<T extends string>(message: string, options: MessageOptions, ...items: T[]): Thenable<T | undefined>
Show a warning message.
See also 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 |
showWarningMessage<T extends MessageItem>(message: string, ...items: T[]): Thenable<T | undefined>
Show a warning message.
See also showInformationMessage
Parameter | Description |
---|---|
message: string | The message to show. |
...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 |
showWarningMessage<T extends MessageItem>(message: string, options: MessageOptions, ...items: T[]): Thenable<T | undefined>
Show a warning message.
See also 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 | A ProgressOptions-object describing the options to use for showing progress, like its location |
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 CancellationToken.
Note that currently only |
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 collection of one or more folders that are opened in an editor window (instance).
It is also possible to open an editor without a workspace. For example, when you open a new editor window by selecting a file from your platform's File menu, you will not be inside a workspace. In this mode, some of the editor's capabilities are reduced but you can still open text files and edit them.
Refer to https://code.visualstudio.com/docs/editor/workspaces for more information on the concept of workspaces.
The workspace offers support for listening to fs events and for finding files. Both perform well and run outside the editor-process so that they should be always used instead of nodejs-equivalents.
Variables
fs: FileSystem
A file system instance that allows to interact with local and remote
files, e.g. vscode.workspace.fs.readDirectory(someUri)
allows to retrieve all entries
of a directory or vscode.workspace.fs.stat(anotherUri)
returns the meta data for a
file.
When true, the user has explicitly trusted the contents of the workspace.
The name of the workspace. undefined
when no workspace
has been opened.
Refer to https://code.visualstudio.com/docs/editor/workspaces for more information on the concept of workspaces.
notebookDocuments: readonly NotebookDocument[]
All notebook documents currently known to the editor.
The uri of the first entry of workspaceFolders
as string
. undefined
if there is no first entry.
Refer to https://code.visualstudio.com/docs/editor/workspaces for more information on workspaces.
- deprecated - Use workspaceFolders instead.
textDocuments: readonly TextDocument[]
All text documents currently known to the editor.
workspaceFile: Uri | undefined
The location of the workspace file, for example:
file:///Users/name/Development/myProject.code-workspace
or
untitled:1555503116870
for a workspace that is untitled and not yet saved.
Depending on the workspace that is opened, the value will be:
undefined
when no workspace is opened- the path of the workspace file as
Uri
otherwise. if the workspace is untitled, the returned URI will use theuntitled:
scheme
The location can e.g. be used with the vscode.openFolder
command to
open the workspace again after it has been closed.
Example:
vscode.commands.executeCommand('vscode.openFolder', uriOfWorkspace);
Refer to https://code.visualstudio.com/docs/editor/workspaces for more information on the concept of workspaces.
Note: it is not advised to use workspace.workspaceFile
to write
configuration data into the file. You can use workspace.getConfiguration().update()
for that purpose which will work both when a single folder is opened as
well as an untitled or saved workspace.
workspaceFolders: readonly WorkspaceFolder[] | undefined
List of workspace folders (0-N) that are open in the editor. undefined
when no workspace
has been opened.
Refer to https://code.visualstudio.com/docs/editor/workspaces for more information on workspaces.
Events
onDidChangeConfiguration: Event<ConfigurationChangeEvent>
An event that is emitted when the configuration changed.
onDidChangeNotebookDocument: Event<NotebookDocumentChangeEvent>
An event that is emitted when a notebook has 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.
Note: this event will not fire if the first workspace folder is added, removed or changed,
because in that case the currently executing extensions (including the one that listens to this
event) will be terminated and restarted so that the (deprecated) rootPath
property is updated
to point to the first workspace folder.
onDidCloseNotebookDocument: Event<NotebookDocument>
An event that is emitted when a notebook is disposed.
Note 1: There is no guarantee that this event fires when an editor tab is closed.
Note 2: A notebook can be open but not shown in an editor which means this event can fire for a notebook that has not been shown in an editor.
onDidCloseTextDocument: Event<TextDocument>
An event that is emitted when a text document is disposed or when the language id of a text document has been changed.
Note 1: There is no guarantee that this event fires when an editor tab is closed, use the onDidChangeVisibleTextEditors-event to know when editors change.
Note 2: A document can be open but not shown in an editor which means this event can fire for a document that has not been shown in an editor.
onDidCreateFiles: Event<FileCreateEvent>
An event that is emitted when files have been created.
Note: This event is triggered by user gestures, like creating a file from the explorer, or from the workspace.applyEdit-api, but this event is not fired when files change on disk, e.g triggered by another application, or when using the workspace.fs-api.
onDidDeleteFiles: Event<FileDeleteEvent>
An event that is emitted when files have been deleted.
Note 1: This event is triggered by user gestures, like deleting a file from the explorer, or from the workspace.applyEdit-api, but this event is not fired when files change on disk, e.g triggered by another application, or when using the workspace.fs-api.
Note 2: When deleting a folder with children only one event is fired.
onDidGrantWorkspaceTrust: Event<void>
Event that fires when the current workspace has been trusted.
onDidOpenNotebookDocument: Event<NotebookDocument>
An event that is emitted when a notebook is opened.
onDidOpenTextDocument: Event<TextDocument>
An event that is emitted when a text document is opened or when the language id of a text document has been changed.
To add an event listener when a visible text document is opened, use the TextEditor events in the window namespace. Note that:
- The event is emitted before the document is updated in the active text editor
- When a text document is already open (e.g.: open in another visible text editor) this event is not emitted
onDidRenameFiles: Event<FileRenameEvent>
An event that is emitted when files have been renamed.
Note 1: This event is triggered by user gestures, like renaming a file from the explorer, and from the workspace.applyEdit-api, but this event is not fired when files change on disk, e.g triggered by another application, or when using the workspace.fs-api.
Note 2: When renaming a folder with children only one event is fired.
onDidSaveNotebookDocument: Event<NotebookDocument>
An event that is emitted when a notebook is saved.
onDidSaveTextDocument: Event<TextDocument>
An event that is emitted when a text document is saved to disk.
onWillCreateFiles: Event<FileWillCreateEvent>
An event that is emitted when files are being created.
Note 1: This event is triggered by user gestures, like creating a file from the explorer, or from the workspace.applyEdit-api. This event is not fired when files change on disk, e.g triggered by another application, or when using the workspace.fs-api.
Note 2: When this event is fired, edits to files that are are being created cannot be applied.
onWillDeleteFiles: Event<FileWillDeleteEvent>
An event that is emitted when files are being deleted.
Note 1: This event is triggered by user gestures, like deleting a file from the explorer, or from the workspace.applyEdit-api, but this event is not fired when files change on disk, e.g triggered by another application, or when using the workspace.fs-api.
Note 2: When deleting a folder with children only one event is fired.
onWillRenameFiles: Event<FileWillRenameEvent>
An event that is emitted when files are being renamed.
Note 1: This event is triggered by user gestures, like renaming a file from the explorer, and from the workspace.applyEdit-api, but this event is not fired when files change on disk, e.g triggered by another application, or when using the workspace.fs-api.
Note 2: When renaming a folder with children only one event is fired.
onWillSaveNotebookDocument: Event<NotebookDocumentWillSaveEvent>
An event that is emitted when a notebook 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.
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, metadata?: WorkspaceEditMetadata): Thenable<boolean>
Make changes to one or many resources or create, delete, and rename resources as defined by the given workspace edit.
All changes of a workspace edit are applied in the same order in which they have been added. If multiple textual inserts are made at the same position, these strings appear in the resulting text in the order the 'inserts' were made, unless that are interleaved with resource edits. Invalid sequences like 'delete file a' -> 'insert text in file a' cause failure of the operation.
When applying a workspace edit that consists only of text edits an 'all-or-nothing'-strategy is used. A workspace edit with resource creations or deletions aborts the operation, e.g. consecutive edits will not be attempted, when a single edit fails.
Parameter | Description |
---|---|
edit: WorkspaceEdit | A workspace edit. |
metadata?: WorkspaceEditMetadata | Optional metadata for the 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 that is notified on file events (create, change, delete) depending on the parameters provided.
By default, all opened workspace folders will be watched for file changes recursively.
Additional paths can be added for file watching by providing a RelativePattern with
a base
path to watch. If the path is a folder and the pattern
is complex (e.g. contains
**
or path segments), it will be watched recursively and otherwise will be watched
non-recursively (i.e. only changes to the first level of the path will be reported).
Note that paths must exist in the file system to be watched. File watching may stop when the watched path is renamed or deleted.
If possible, keep the use of recursive watchers to a minimum because recursive file watching is quite resource intense.
Providing a string
as globPattern
acts as convenience method for watching file events in
all opened workspace folders. It cannot be used to add more folders for file watching, nor will
it report any file events from folders that are not part of the opened workspace folders.
Optionally, flags to ignore certain kinds of events can be provided.
To stop listening to events the watcher must be disposed.
Note that file events from recursive file watchers may be excluded based on user configuration.
The setting files.watcherExclude
helps to reduce the overhead of file events from folders
that are known to produce many file changes at once (such as node_modules
folders). As such,
it is highly recommended to watch with simple patterns that do not require recursive watchers
where the exclude settings are ignored and you have full control over the events.
Note that symbolic links are not automatically followed for file watching unless the path to watch itself is a symbolic link.
Note that file changes for the path to be watched may not be delivered when the path itself
changes. For example, when watching a path /Users/somename/Desktop
and the path itself is
being deleted, the watcher may not report an event and may not work anymore from that moment on.
The underlying behaviour depends on the path that is provided for watching:
- if the path is within any of the workspace folders, deletions are tracked and reported unless
excluded via
files.watcherExclude
setting - if the path is equal to any of the workspace folders, deletions are not tracked
- if the path is outside of any of the workspace folders, deletions are not tracked
If you are interested in being notified when the watched path itself is being deleted, you have
to watch it's parent folder. Make sure to use a simple pattern
(such as putting the name of the
folder) to not accidentally watch all sibling folders recursively.
Note that the file paths that are reported for having changed may have a different path casing compared to the actual casing on disk on case-insensitive platforms (typically macOS and Windows but not Linux). We allow a user to open a workspace folder with any desired path casing and try to preserve that. This means:
- if the path is within any of the workspace folders, the path will match the casing of the workspace folder up to that portion of the path and match the casing on disk for children
- if the path is outside of any of the workspace folders, the casing will match the case of the path that was provided for watching In the same way, symbolic links are preserved, i.e. the file event will report the path of the symbolic link as it was provided for watching and not the target.
Examples
The basic anatomy of a file watcher is as follows:
const watcher = vscode.workspace.createFileSystemWatcher(new vscode.RelativePattern(<folder>, <pattern>));
watcher.onDidChange(uri => { ... }); // listen to files being changed
watcher.onDidCreate(uri => { ... }); // listen to files/folders being created
watcher.onDidDelete(uri => { ... }); // listen to files/folders getting deleted
watcher.dispose(); // dispose after usage
Workspace file watching
If you only care about file events in a specific workspace folder:
vscode.workspace.createFileSystemWatcher(
new vscode.RelativePattern(vscode.workspace.workspaceFolders[0], '**/*.js')
);
If you want to monitor file events across all opened workspace folders:
vscode.workspace.createFileSystemWatcher('**/*.js');
Note: the array of workspace folders can be empty if no workspace is opened (empty window).
Out of workspace file watching
To watch a folder for changes to *.js files outside the workspace (non recursively), pass in a Uri
to such
a folder:
vscode.workspace.createFileSystemWatcher(new vscode.RelativePattern(vscode.Uri.file(<path to folder outside workspace>), '*.js'));
And use a complex glob pattern to watch recursively:
vscode.workspace.createFileSystemWatcher(new vscode.RelativePattern(vscode.Uri.file(<path to folder outside workspace>), '**/*.js'));
Here is an example for watching the active editor for file changes:
vscode.workspace.createFileSystemWatcher(
new vscode.RelativePattern(vscode.window.activeTextEditor.document.uri, '*')
);
Parameter | Description |
---|---|
globPattern: GlobPattern | A glob pattern that controls which file events the watcher should report. |
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. Must be disposed when no longer needed. |
findFiles(include: GlobPattern, exclude?: GlobPattern, maxResults?: number, token?: CancellationToken): Thenable<Uri[]>
Find files across all workspace folders in the workspace.
Example
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 | 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, scope?: ConfigurationScope): WorkspaceConfiguration
Get a workspace configuration object.
When a section-identifier is provided only that part of the configuration
is returned. Dots in the section-identifier are interpreted as child-access,
like { myExt: { setting: { doIt: true }}}
and getConfiguration('myExt.setting').get('doIt') === true
.
When a scope is provided configuration confined to that scope is returned. Scope can be a resource or a language identifier or both.
Parameter | Description |
---|---|
section?: string | A dot-separated identifier. |
scope?: ConfigurationScope | A scope 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 |
openNotebookDocument(uri: Uri): Thenable<NotebookDocument>
Open a notebook. Will return early if this notebook is already loaded. Otherwise the notebook is loaded and the onDidOpenNotebookDocument-event fires.
Note that the lifecycle of the returned notebook is owned by the editor and not by the extension. That means an onDidCloseNotebookDocument-event can occur at any time after.
Note that opening a notebook does not show a notebook editor. This function only returns a notebook document which can be shown in a notebook editor but it can also be used for other things.
Parameter | Description |
---|---|
uri: Uri | The resource to open. |
Returns | Description |
Thenable<NotebookDocument> | A promise that resolves to a notebook |
openNotebookDocument(notebookType: string, content?: NotebookData): Thenable<NotebookDocument>
Open an untitled notebook. The editor will prompt the user for a file path when the document is to be saved.
See also workspace.openNotebookDocument
Parameter | Description |
---|---|
notebookType: string | The notebook type that should be used. |
content?: NotebookData | The initial contents of the notebook. |
Returns | Description |
Thenable<NotebookDocument> | A promise that resolves to a notebook. |
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 (openTextDocument(Uri.file(path))
). Will be rejected if the file does not exist or cannot be loaded.untitled
-scheme: Open a blank untitled file with associated path (openTextDocument(Uri.file(path).with({ scheme: 'untitled' }))
). The language will be derived from the file name.- For all other schemes contributed text document content providers and file system providers are consulted.
Note that the lifecycle of the returned document is owned by the editor and not by the extension. That means an onDidClose-event can occur at any time after opening it.
Parameter | Description |
---|---|
uri: Uri | Identifies the resource to open. |
Returns | Description |
Thenable<TextDocument> | A promise that resolves to a document. |
openTextDocument(path: string): Thenable<TextDocument>
A short-hand for openTextDocument(Uri.file(path))
.
See also workspace.openTextDocument
Parameter | Description |
---|---|
path: string | A path 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. |
registerFileSystemProvider(scheme: string, provider: FileSystemProvider, options?: {isCaseSensitive: boolean, isReadonly: boolean | MarkdownString}): Disposable
Register a filesystem provider for a given scheme, e.g. ftp
.
There can only be one provider per scheme and an error is being thrown when a scheme has been claimed by another provider or when it is reserved.
Parameter | Description |
---|---|
scheme: string | The uri-scheme the provider registers for. |
provider: FileSystemProvider | The filesystem provider. |
options?: {isCaseSensitive: boolean, isReadonly: boolean | MarkdownString} | Immutable metadata about the provider. |
Returns | Description |
Disposable | A Disposable that unregisters this provider when being disposed. |
registerNotebookSerializer(notebookType: string, serializer: NotebookSerializer, options?: NotebookDocumentContentOptions): Disposable
Register a notebook serializer.
A notebook serializer must be contributed through the notebooks
extension point. When opening a notebook file, the editor will send
the onNotebook:<notebookType>
activation event, and extensions must register their serializer in return.
Parameter | Description |
---|---|
notebookType: string | A notebook. |
serializer: NotebookSerializer | A notebook serializer. |
options?: NotebookDocumentContentOptions | Optional context options that define what parts of a notebook should be persisted |
Returns | Description |
Disposable | A Disposable that unregisters this serializer when being disposed. |
registerTaskProvider(type: string, provider: TaskProvider<Task>): Disposable
Register a task provider.
- deprecated - Use the corresponding function on the
tasks
namespace instead
Parameter | Description |
---|---|
type: string | The task kind type this provider is registered for. |
provider: TaskProvider<Task> | 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. |
save(uri: Uri): Thenable<Uri | undefined>
Saves the editor identified by the given resource and returns the resulting resource or undefined
if save was not successful or no editor with the given resource was found.
Note that an editor with the provided resource must be opened in order to be saved.
saveAll(includeUntitled?: boolean): Thenable<boolean>
Save all dirty files.
Parameter | Description |
---|---|
includeUntitled?: boolean | Also save files that have been created during this session. |
Returns | Description |
Thenable<boolean> | A thenable that resolves when the files have been saved. Will return |
saveAs(uri: Uri): Thenable<Uri | undefined>
Saves the editor identified by the given resource to a new file name as provided by the user and
returns the resulting resource or undefined
if save was not successful or cancelled or no editor
with the given resource was found.
Note that an editor with the provided resource must be opened in order to be saved as.
updateWorkspaceFolders(start: number, deleteCount: number, ...workspaceFoldersToAdd: Array<{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.
Note: in some cases calling this method may result in the currently executing extensions (including the
one that called this method) to be terminated and restarted. For example when the first workspace folder is
added, removed or changed the (deprecated) rootPath
property is updated to point to the first workspace
folder. Another case is when transitioning from an empty or single-folder workspace into a multi-folder
workspace (see also: https://code.visualstudio.com/docs/editor/workspaces).
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 | the optional number of workspace folders to remove. |
...workspaceFoldersToAdd: Array<{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). |
AccessibilityInformation
Accessibility information which controls screen reader behavior.
Properties
Label to be read out by a screen reader once the item has focus.
Role of the widget which defines how a screen reader interacts with it. The role should be set in special cases when for example a tree-like element behaves like a checkbox. If role is not specified the editor will pick the appropriate role automatically. More about aria roles can be found here https://w3c.github.io/aria/#widget_roles
AuthenticationForceNewSessionOptions
Optional options to be used when calling authentication.getSession with the flag forceNewSession
.
Properties
An optional message that will be displayed to the user when we ask to re-authenticate. Providing additional context as to why you are asking a user to re-authenticate can help increase the odds that they will accept.
AuthenticationGetSessionOptions
Options to be used when getting an AuthenticationSession from an AuthenticationProvider.
Properties
account?: AuthenticationSessionAccountInformation
The account that you would like to get a session for. This is passed down to the Authentication Provider to be used for creating the correct session.
clearSessionPreference?: boolean
Whether the existing session preference should be cleared.
For authentication providers that support being signed into multiple accounts at once, the user will be prompted to select an account to use when getSession is called. This preference is remembered until getSession is called with this flag.
Note: The preference is extension specific. So if one extension calls getSession, it will not affect the session preference for another extension calling getSession. Additionally, the preference is set for the current workspace and also globally. This means that new workspaces will use the "global" value at first and then when this flag is provided, a new value can be set for that workspace. This also means that pre-existing workspaces will not lose their preference if a new workspace sets this flag.
Defaults to false.
Whether login should be performed if there is no matching session.
If true, a modal dialog will be shown asking the user to sign in. If false, a numbered badge will be shown on the accounts activity bar icon. An entry for the extension will be added under the menu to sign in. This allows quietly prompting the user to sign in.
If there is a matching session but the extension has not been granted access to it, setting this to true will also result in an immediate modal dialog, and false will add a numbered badge to the accounts icon.
Defaults to false.
Note: you cannot use this option with silent.
forceNewSession?: boolean | AuthenticationForceNewSessionOptions
Whether we should attempt to reauthenticate even if there is already a session available.
If true, a modal dialog will be shown asking the user to sign in again. This is mostly used for scenarios where the token needs to be re minted because it has lost some authorization.
If there are no existing sessions and forceNewSession is true, it will behave identically to createIfNone.
This defaults to false.
Whether we should show the indication to sign in in the Accounts menu.
If false, the user will be shown a badge on the Accounts menu with an option to sign in for the extension. If true, no indication will be shown.
Defaults to false.
Note: you cannot use this option with any other options that prompt the user like createIfNone.
AuthenticationProvider
A provider for performing authentication to a service.
Events
onDidChangeSessions: Event<AuthenticationProviderAuthenticationSessionsChangeEvent>
An Event which fires when the array of sessions has changed, or data within a session has changed.
Methods
createSession(scopes: readonly string[], options: AuthenticationProviderSessionOptions): Thenable<AuthenticationSession>
Prompts a user to login.
If login is successful, the onDidChangeSessions event should be fired.
If login fails, a rejected promise should be returned.
If the provider has specified that it does not support multiple accounts, then this should never be called if there is already an existing session matching these scopes.
Parameter | Description |
---|---|
scopes: readonly string[] | A list of scopes, permissions, that the new session should be created with. |
options: AuthenticationProviderSessionOptions | Additional options for creating a session. |
Returns | Description |
Thenable<AuthenticationSession> | A promise that resolves to an authentication session. |
getSessions(scopes: readonly string[], options: AuthenticationProviderSessionOptions): Thenable<AuthenticationSession[]>
Get a list of sessions.
Parameter | Description |
---|---|
scopes: readonly string[] | An optional list of scopes. If provided, the sessions returned should match these permissions, otherwise all sessions should be returned. |
options: AuthenticationProviderSessionOptions | Additional options for getting sessions. |
Returns | Description |
Thenable<AuthenticationSession[]> | A promise that resolves to an array of authentication sessions. |
removeSession(sessionId: string): Thenable<void>
Removes the session corresponding to session id.
If the removal is successful, the onDidChangeSessions event should be fired.
If a session cannot be removed, the provider should reject with an error message.
Parameter | Description |
---|---|
sessionId: string | The id of the session to remove. |
Returns | Description |
Thenable<void> |
AuthenticationProviderAuthenticationSessionsChangeEvent
An Event which fires when an AuthenticationSession is added, removed, or changed.
Properties
added: readonly AuthenticationSession[]
The AuthenticationSessions of the AuthenticationProvider that have been added.
changed: readonly AuthenticationSession[]
The AuthenticationSessions of the AuthenticationProvider that have been changed. A session changes when its data excluding the id are updated. An example of this is a session refresh that results in a new access token being set for the session.
removed: readonly AuthenticationSession[]
The AuthenticationSessions of the AuthenticationProvider that have been removed.
AuthenticationProviderInformation
Basic information about an AuthenticationProvider
Properties
The unique identifier of the authentication provider.
The human-readable name of the authentication provider.
AuthenticationProviderOptions
Options for creating an AuthenticationProvider.
Properties
supportsMultipleAccounts?: boolean
Whether it is possible to be signed into multiple accounts at once with this provider. If not specified, will default to false.
AuthenticationProviderSessionOptions
The options passed in to the AuthenticationProvider.getSessions and AuthenticationProvider.createSession call.
Properties
account?: AuthenticationSessionAccountInformation
The account that is being asked about. If this is passed in, the provider should attempt to return the sessions that are only related to this account.
AuthenticationSession
Represents a session of a currently logged in user.
Properties
The access token.
account: AuthenticationSessionAccountInformation
The account associated with the session.
The identifier of the authentication session.
The permissions granted by the session's access token. Available scopes are defined by the AuthenticationProvider.
AuthenticationSessionAccountInformation
The information of an account associated with an AuthenticationSession.
Properties
The unique identifier of the account.
The human-readable name of the account.
AuthenticationSessionsChangeEvent
An Event which fires when an AuthenticationSession is added, removed, or changed.
Properties
provider: AuthenticationProviderInformation
The AuthenticationProvider that has had its sessions change.
AutoClosingPair
Describes pairs of strings where the close string will be automatically inserted when typing the opening string.
Properties
The closing string that will be automatically inserted when typing the opening string.
notIn?: SyntaxTokenType[]
A set of tokens where the pair should not be auto closed.
The string that will trigger the automatic insertion of the closing string.
BranchCoverage
Contains coverage information for a branch of a StatementCoverage.
Constructors
new BranchCoverage(executed: number | boolean, location?: Range | Position, label?: string): BranchCoverage
Parameter | Description |
---|---|
executed: number | boolean | The number of times this branch was executed, or a boolean indicating whether it was executed if the exact count is unknown. If zero or false, the branch will be marked as un-covered. |
location?: Range | Position | The branch position. |
label?: string | |
Returns | Description |
BranchCoverage |
Properties
The number of times this branch was executed, or a boolean indicating whether it was executed if the exact count is unknown. If zero or false, the branch will be marked as un-covered.
Label for the branch, used in the context of "the ${label} branch was not taken," for example.
Branch location.
Breakpoint
The base class of all breakpoint types.
Constructors
new Breakpoint(enabled?: boolean, condition?: string, hitCondition?: string, logMessage?: string): Breakpoint
Creates a new breakpoint
Parameter | Description |
---|---|
enabled?: boolean | Is breakpoint enabled. |
condition?: string | Expression for conditional breakpoints |
hitCondition?: string | Expression that controls how many hits of the breakpoint are ignored |
logMessage?: string | Log message to display when breakpoint is hit |
Returns | Description |
Breakpoint |
Properties
An optional expression for conditional breakpoints.
Is breakpoint enabled.
An optional expression that controls how many hits of the breakpoint are ignored.
The unique ID of the breakpoint.
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: readonly Breakpoint[]
Added breakpoints.
changed: readonly Breakpoint[]
Changed breakpoints.
removed: readonly Breakpoint[]
Removed breakpoints.
CallHierarchyIncomingCall
Represents an incoming call, e.g. a caller of a method or constructor.
Constructors
new CallHierarchyIncomingCall(item: CallHierarchyItem, fromRanges: Range[]): CallHierarchyIncomingCall
Create a new call object.
Parameter | Description |
---|---|
item: CallHierarchyItem | The item making the call. |
fromRanges: Range[] | The ranges at which the calls appear. |
Returns | Description |
CallHierarchyIncomingCall |
Properties
from: CallHierarchyItem
The item that makes the call.
fromRanges: Range[]
The range at which at which the calls appears. This is relative to the caller denoted by this.from.
CallHierarchyItem
Represents programming constructs like functions or constructors in the context of call hierarchy.
Constructors
new CallHierarchyItem(kind: SymbolKind, name: string, detail: string, uri: Uri, range: Range, selectionRange: Range): CallHierarchyItem
Creates a new call hierarchy item.
Parameter | Description |
---|---|
kind: SymbolKind | |
name: string | |
detail: string | |
uri: Uri | |
range: Range | |
selectionRange: Range | |
Returns | Description |
CallHierarchyItem |
Properties
More detail for this item, e.g. the signature of a function.
kind: SymbolKind
The kind of this item.
The name of this item.
range: Range
The range enclosing this symbol not including leading/trailing whitespace but everything else, e.g. comments and code.
selectionRange: Range
The range that should be selected and revealed when this symbol is being picked, e.g. the name of a function. Must be contained by the range.
tags?: readonly Deprecated[]
Tags for this item.
uri: Uri
The resource identifier of this item.
CallHierarchyOutgoingCall
Represents an outgoing call, e.g. calling a getter from a method or a method from a constructor etc.
Constructors
new CallHierarchyOutgoingCall(item: CallHierarchyItem, fromRanges: Range[]): CallHierarchyOutgoingCall
Create a new call object.
Parameter | Description |
---|---|
item: CallHierarchyItem | The item being called |
fromRanges: Range[] | The ranges at which the calls appear. |
Returns | Description |
CallHierarchyOutgoingCall |
Properties
fromRanges: Range[]
The range at which this item is called. This is the range relative to the caller, e.g the item passed to provideCallHierarchyOutgoingCalls and not this.to.
The item that is called.
CallHierarchyProvider
The call hierarchy provider interface describes the contract between extensions and the call hierarchy feature which allows to browse calls and caller of function, methods, constructor etc.
Methods
prepareCallHierarchy(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<CallHierarchyItem | CallHierarchyItem[]>
Bootstraps call hierarchy by returning the item that is denoted by the given document
and position. This item will be used as entry into the call graph. Providers should
return undefined
or null
when there is no item at the given location.
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<CallHierarchyItem | CallHierarchyItem[]> | One or multiple call hierarchy items or a thenable that resolves to such. The lack of a result can be
signaled by returning |
provideCallHierarchyIncomingCalls(item: CallHierarchyItem, token: CancellationToken): ProviderResult<CallHierarchyIncomingCall[]>
Provide all incoming calls for an item, e.g all callers for a method. In graph terms this describes directed and annotated edges inside the call graph, e.g the given item is the starting node and the result is the nodes that can be reached.
Parameter | Description |
---|---|
item: CallHierarchyItem | The hierarchy item for which incoming calls should be computed. |
token: CancellationToken | A cancellation token. |
Returns | Description |
ProviderResult<CallHierarchyIncomingCall[]> | A set of incoming calls or a thenable that resolves to such. The lack of a result can be
signaled by returning |
provideCallHierarchyOutgoingCalls(item: CallHierarchyItem, token: CancellationToken): ProviderResult<CallHierarchyOutgoingCall[]>
Provide all outgoing calls for an item, e.g call calls to functions, methods, or constructors from the given item. In graph terms this describes directed and annotated edges inside the call graph, e.g the given item is the starting node and the result is the nodes that can be reached.
Parameter | Description |
---|---|
item: CallHierarchyItem | The hierarchy item for which outgoing calls should be computed. |
token: CancellationToken | A cancellation token. |
Returns | Description |
ProviderResult<CallHierarchyOutgoingCall[]> | A set of outgoing calls or a thenable that resolves to such. The lack of a result can be
signaled by returning |
CancellationError
An error type that should be used to signal cancellation of an operation.
This type can be used in response to a cancellation token being cancelled or when an operation is being cancelled by the executor of that operation.
Constructors
new CancellationError(): CancellationError
Creates a new cancellation error.
Parameter | Description |
---|---|
Returns | Description |
CancellationError |
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.
Constructors
new CancellationTokenSource(): CancellationTokenSource
Parameter | Description |
---|---|
Returns | Description |
CancellationTokenSource |
Properties
token: CancellationToken
The cancellation token of this source.
Methods
Signal cancellation on the token.
Parameter | Description |
---|---|
Returns | Description |
void |
Dispose object and free resources.
Parameter | Description |
---|---|
Returns | Description |
void |
CharacterPair
A tuple of two characters, like a pair of opening and closing brackets.
CharacterPair: [string, string]
ChatContext
Extra context passed to a participant.
Properties
history: ReadonlyArray<ChatRequestTurn | ChatResponseTurn>
All of the chat messages so far in the current chat session. Currently, only chat messages for the current participant are included.
ChatErrorDetails
Represents an error result from a chat request.
Properties
An error message that is shown to the user.
If set to true, the response will be partly blurred out.
ChatFollowup
A followup question suggested by the participant.
Properties
By default, the followup goes to the same participant/command. But this property can be set to invoke a different command.
A title to show the user. The prompt will be shown by default, when this is unspecified.
By default, the followup goes to the same participant/command. But this property can be set to invoke a different participant by ID. Followups can only invoke a participant that was contributed by the same extension.
The message to send to the chat.
ChatFollowupProvider
Will be invoked once after each request to get suggested followup questions to show the user. The user can click the followup to send it to the chat.
Methods
provideFollowups(result: ChatResult, context: ChatContext, token: CancellationToken): ProviderResult<ChatFollowup[]>
Provide followups for the given result.
Parameter | Description |
---|---|
result: ChatResult | This object has the same properties as the result returned from the participant callback, including |
context: ChatContext | |
token: CancellationToken | A cancellation token. |
Returns | Description |
ProviderResult<ChatFollowup[]> |
ChatParticipant
A chat participant can be invoked by the user in a chat session, using the prefix. When it is invoked, it handles the chat request and is solely
responsible for providing a response to the user. A ChatParticipant is created using chat.createChatParticipant.
Events
onDidReceiveFeedback: Event<ChatResultFeedback>
An event that fires whenever feedback for a result is received, e.g. when a user up- or down-votes a result.
The passed result is guaranteed to have the same properties as the result that was previously returned from this chat participant's handler.
Properties
followupProvider?: ChatFollowupProvider
This provider will be called once after each request to retrieve suggested followup questions.
iconPath?: Uri | ThemeIcon | {dark: Uri, light: Uri}
An icon for the participant shown in UI.
A unique ID for this participant.
requestHandler: ChatRequestHandler
The handler for requests to this participant.
Methods
Dispose this participant and free resources.
Parameter | Description |
---|---|
Returns | Description |
void |
ChatPromptReference
A reference to a value that the user added to their chat request.
Properties
A unique identifier for this kind of reference.
A description of this value that could be used in an LLM prompt.
range?: [start: number, end: number]
The start and end index of the reference in the prompt. When undefined, the reference was not part of the prompt text.
Note that the indices take the leading #
-character into account which means they can
used to modify the prompt as-is.
The value of this reference. The string | Uri | Location
types are used today, but this could expand in the future.
ChatRequest
A request to a chat participant.
Properties
The name of the [ChatCommand command](#ChatCommand command) that was selected for this request.
The prompt as entered by the user.
Information about references used in this request is stored in ChatRequest.references.
Note that the [ChatParticipant.name name](#ChatParticipant.name name) of the participant and the [ChatCommand.name command](#ChatCommand.name command) are not part of the prompt.
references: readonly ChatPromptReference[]
The list of references and their values that are referenced in the prompt.
Note that the prompt contains references as authored and that it is up to the participant to further modify the prompt, for instance by inlining reference values or creating links to headings which contain the resolved values. References are sorted in reverse by their range in the prompt. That means the last reference in the prompt is the first in this list. This simplifies string-manipulation of the prompt.
ChatRequestHandler
ChatRequestHandler: (request: ChatRequest, context: ChatContext, response: ChatResponseStream, token: CancellationToken) => ProviderResult<ChatResult | void>
ChatRequestTurn
Represents a user request in chat history.
Properties
The name of the [ChatCommand command](#ChatCommand command) that was selected for this request.
The id of the chat participant to which this request was directed.
The prompt as entered by the user.
Information about references used in this request is stored in ChatRequestTurn.references.
Note that the [ChatParticipant.name name](#ChatParticipant.name name) of the participant and the [ChatCommand.name command](#ChatCommand.name command) are not part of the prompt.
references: ChatPromptReference[]
The references that were used in this message.
ChatResponseAnchorPart
Represents a part of a chat response that is an anchor, that is rendered as a link to a target.
Constructors
new ChatResponseAnchorPart(value: Uri | Location, title?: string): ChatResponseAnchorPart
Create a new ChatResponseAnchorPart.
Parameter | Description |
---|---|
value: Uri | Location | A uri or location. |
title?: string | An optional title that is rendered with value. |
Returns | Description |
ChatResponseAnchorPart |
Properties
An optional title that is rendered with value.
The target of this anchor.
ChatResponseCommandButtonPart
Represents a part of a chat response that is a button that executes a command.
Constructors
new ChatResponseCommandButtonPart(value: Command): ChatResponseCommandButtonPart
Create a new ChatResponseCommandButtonPart.
Parameter | Description |
---|---|
value: Command | A Command that will be executed when the button is clicked. |
Returns | Description |
ChatResponseCommandButtonPart |
Properties
value: Command
The command that will be executed when the button is clicked.
ChatResponseFileTree
Represents a file tree structure in a chat response.
Properties
children?: ChatResponseFileTree[]
An array of child file trees, if the current file tree is a directory.
The name of the file or directory.
ChatResponseFileTreePart
Represents a part of a chat response that is a file tree.
Constructors
new ChatResponseFileTreePart(value: ChatResponseFileTree[], baseUri: Uri): ChatResponseFileTreePart
Create a new ChatResponseFileTreePart.
Parameter | Description |
---|---|
value: ChatResponseFileTree[] | File tree data. |
baseUri: Uri | The base uri to which this file tree is relative. |
Returns | Description |
ChatResponseFileTreePart |
Properties
baseUri: Uri
The base uri to which this file tree is relative
value: ChatResponseFileTree[]
File tree data.
ChatResponseMarkdownPart
Represents a part of a chat response that is formatted as Markdown.
Constructors
new ChatResponseMarkdownPart(value: string | MarkdownString): ChatResponseMarkdownPart
Create a new ChatResponseMarkdownPart.
Parameter | Description |
---|---|
value: string | MarkdownString | A markdown string or a string that should be interpreted as markdown. The boolean form of MarkdownString.isTrusted is NOT supported. |
Returns | Description |
ChatResponseMarkdownPart |
Properties
value: MarkdownString
A markdown string or a string that should be interpreted as markdown.
ChatResponsePart
Represents the different chat response types.
ChatResponsePart: ChatResponseMarkdownPart | ChatResponseFileTreePart | ChatResponseAnchorPart | ChatResponseProgressPart | ChatResponseReferencePart | ChatResponseCommandButtonPart
ChatResponseProgressPart
Represents a part of a chat response that is a progress message.
Constructors
new ChatResponseProgressPart(value: string): ChatResponseProgressPart
Create a new ChatResponseProgressPart.
Parameter | Description |
---|---|
value: string | A progress message |
Returns | Description |
ChatResponseProgressPart |
Properties
The progress message
ChatResponseReferencePart
Represents a part of a chat response that is a reference, rendered separately from the content.
Constructors
new ChatResponseReferencePart(value: Uri | Location, iconPath?: Uri | ThemeIcon | {dark: Uri, light: Uri}): ChatResponseReferencePart
Create a new ChatResponseReferencePart.
Properties
iconPath?: Uri | ThemeIcon | {dark: Uri, light: Uri}
The icon for the reference.
The reference target.
ChatResponseStream
The ChatResponseStream is how a participant is able to return content to the chat view. It provides several methods for streaming different types of content which will be rendered in an appropriate way in the chat view. A participant can use the helper method for the type of content it wants to return, or it can instantiate a ChatResponsePart and use the generic ChatResponseStream.push method to return it.
Methods
anchor(value: Uri | Location, title?: string): void
Push an anchor part to this stream. Short-hand for
push(new ChatResponseAnchorPart(value, title))
.
An anchor is an inline reference to some type of resource.
button(command: Command): void
Push a command button part to this stream. Short-hand for
push(new ChatResponseCommandButtonPart(value, title))
.
Parameter | Description |
---|---|
command: Command | A Command that will be executed when the button is clicked. |
Returns | Description |
void |
filetree(value: ChatResponseFileTree[], baseUri: Uri): void
Push a filetree part to this stream. Short-hand for
push(new ChatResponseFileTreePart(value))
.
Parameter | Description |
---|---|
value: ChatResponseFileTree[] | File tree data. |
baseUri: Uri | The base uri to which this file tree is relative. |
Returns | Description |
void |
markdown(value: string | MarkdownString): void
Push a markdown part to this stream. Short-hand for
push(new ChatResponseMarkdownPart(value))
.
See also ChatResponseStream.push
Parameter | Description |
---|---|
value: string | MarkdownString | A markdown string or a string that should be interpreted as markdown. The boolean form of MarkdownString.isTrusted is NOT supported. |
Returns | Description |
void |
Push a progress part to this stream. Short-hand for
push(new ChatResponseProgressPart(value))
.
Parameter | Description |
---|---|
value: string | A progress message |
Returns | Description |
void |
push(part: ChatResponsePart): void
Pushes a part to this stream.
Parameter | Description |
---|---|
part: ChatResponsePart | A response part, rendered or metadata |
Returns | Description |
void |
reference(value: Uri | Location, iconPath?: Uri | ThemeIcon | {dark: Uri, light: Uri}): void
Push a reference to this stream. Short-hand for
push(new ChatResponseReferencePart(value))
.
Note that the reference is not rendered inline with the response.
ChatResponseTurn
Represents a chat participant's response in chat history.
Properties
The name of the command that this response came from.
The id of the chat participant that this response came from.
response: ReadonlyArray<ChatResponseMarkdownPart | ChatResponseFileTreePart | ChatResponseAnchorPart | ChatResponseCommandButtonPart>
The content that was received from the chat participant. Only the stream parts that represent actual content (not metadata) are represented.
result: ChatResult
The result that was received from the chat participant.
ChatResult
The result of a chat request.
Properties
errorDetails?: ChatErrorDetails
If the request resulted in an error, this property defines the error details.
Arbitrary metadata for this result. Can be anything, but must be JSON-stringifyable.
ChatResultFeedback
Represents user feedback for a result.
Properties
kind: ChatResultFeedbackKind
The kind of feedback that was received.
result: ChatResult
The ChatResult for which the user is providing feedback.
This object has the same properties as the result returned from the participant callback, including metadata
, but is not the same instance.
ChatResultFeedbackKind
Represents the type of user feedback received.
Enumeration Members
The user marked the result as unhelpful.
The user marked the result as helpful.
Clipboard
The clipboard provides read and write access to the system's clipboard.
Methods
Read the current clipboard contents as text.
Parameter | Description |
---|---|
Returns | Description |
Thenable<string> | A thenable that resolves to a string. |
writeText(value: string): Thenable<void>
Writes text into the clipboard.
Parameter | Description |
---|---|
value: string | |
Returns | Description |
Thenable<void> | A thenable that resolves when writing happened. |
CodeAction
A code action represents a change that can be performed in code, e.g. to fix a problem or to refactor code.
A CodeAction must set either edit and/or a command. If both are supplied, the edit
is applied first, then the command is executed.
Constructors
new CodeAction(title: string, kind?: CodeActionKind): CodeAction
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.
If this command throws an exception, the editor displays the exception message to users in the editor at the current cursor position.
diagnostics?: Diagnostic[]
Diagnostics that this code action resolves.
Marks that the code action cannot currently be applied.
Disabled code actions are not shown in automatic lightbulb code action menu.
Disabled actions are shown as faded out in the code action menu when the user request a more specific type of code action, such as refactorings.
If the user has a keybinding that auto applies a code action and only a disabled code actions are returned, the editor will show the user an error message with
reason
in the editor.
Parameter | Description |
---|---|
reason: string | Human readable description of why the code action is currently disabled. This is displayed in the code actions UI. |
edit?: WorkspaceEdit
A workspace edit this code action performs.
Marks this as a preferred action. Preferred actions are used by the auto fix
command and can be targeted
by keybindings.
A quick fix should be marked preferred if it properly addresses the underlying error. A refactoring should be marked preferred if it is the most reasonable choice of actions to take.
kind?: CodeActionKind
Kind of the code action.
Used to filter code actions.
A short, human-readable, title for this code action.
CodeActionContext
Contains additional diagnostic information about the context in which a code action is run.
Properties
diagnostics: readonly Diagnostic[]
An array of diagnostics.
only: CodeActionKind
Requested kind of actions to return.
Actions not of this kind are filtered out before being shown by the lightbulb.
triggerKind: CodeActionTriggerKind
The reason why code actions were requested.
CodeActionKind
Kind of a code action.
Kinds are a hierarchical list of identifiers separated by .
, e.g. "refactor.extract.function"
.
Code action kinds are used by the editor for UI elements such as the refactoring context menu. Users
can also trigger code actions with a specific kind with the editor.action.codeAction
command.
Static
Empty: CodeActionKind
Empty kind.
Notebook: CodeActionKind
Base kind for all code actions applying to the enitre notebook's scope. CodeActionKinds using
this should always begin with notebook.
This requires that new CodeActions be created for it and contributed via extensions.
Pre-existing kinds can not just have the new notebook.
prefix added to them, as the functionality
is unique to the full-notebook scope.
Notebook CodeActionKinds can be initialized as either of the following (both resulting in notebook.source.xyz
):
const newKind = CodeActionKind.Notebook.append(CodeActionKind.Source.append('xyz').value)
const newKind = CodeActionKind.Notebook.append('source.xyz')
Example Kinds/Actions:
notebook.source.organizeImports
(might move all imports to a new top cell)notebook.source.normalizeVariableNames
(might rename all variables to a standardized casing format)
QuickFix: CodeActionKind
Base kind for quickfix actions: quickfix
.
Quick fix actions address a problem in the code and are shown in the normal code action context menu.
Refactor: CodeActionKind
Base kind for refactoring actions: refactor
Refactoring actions are shown in the refactoring context menu.
RefactorExtract: CodeActionKind
Base kind for refactoring extraction actions: refactor.extract
Example extract actions:
- Extract method
- Extract function
- Extract variable
- Extract interface from class
- ...
RefactorInline: CodeActionKind
Base kind for refactoring inline actions: refactor.inline
Example inline actions:
- Inline function
- Inline variable
- Inline constant
- ...
RefactorMove: CodeActionKind
Base kind for refactoring move actions: refactor.move
Example move actions:
- Move a function to a new file
- Move a property between classes
- Move method to base class
- ...
RefactorRewrite: CodeActionKind
Base kind for refactoring rewrite actions: refactor.rewrite
Example rewrite actions:
- Convert JavaScript function to class
- Add or remove parameter
- Encapsulate field
- Make method static
- ...
Source: CodeActionKind
Base kind for source actions: source
Source code actions apply to the entire file. They must be explicitly requested and will not show in the
normal lightbulb menu. Source actions
can be run on save using editor.codeActionsOnSave
and are also shown in the source
context menu.
SourceFixAll: CodeActionKind
Base kind for auto-fix source actions: source.fixAll
.
Fix all actions automatically fix errors that have a clear fix that do not require user input. They should not suppress errors or perform unsafe fixes such as generating new types or classes.
SourceOrganizeImports: CodeActionKind
Base kind for an organize imports source action: source.organizeImports
.
Constructors
new CodeActionKind(value: string): CodeActionKind
Private constructor, use statix CodeActionKind.XYZ
to derive from an existing code action kind.
Parameter | Description |
---|---|
value: string | The value of the kind, such as |
Returns | Description |
CodeActionKind |
Properties
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
Checks if other
is a sub-kind of this CodeActionKind
.
The kind "refactor.extract"
for example contains "refactor.extract"
and ``"refactor.extract.function", but not
"unicorn.refactor.extract", or
"refactor.extractAll"or
refactor`.
Parameter | Description |
---|---|
other: CodeActionKind | Kind to check. |
Returns | Description |
boolean |
intersects(other: CodeActionKind): boolean
Checks if this code action kind intersects other
.
The kind "refactor.extract"
for example intersects refactor
, "refactor.extract"
and "refactor.extract.function"
,
but not "unicorn.refactor.extract"
, or "refactor.extractAll"
.
Parameter | Description |
---|---|
other: CodeActionKind | Kind to check. |
Returns | Description |
boolean |
CodeActionProvider<T>
Provides contextual actions for code. Code actions typically either fix problems or beautify/refactor code.
Code actions are surfaced to users in a few different ways:
- The lightbulb feature, which shows a list of code actions at the current cursor position. The lightbulb's list of actions includes both quick fixes and refactorings.
- As commands that users can run, such as
Refactor
. Users can run these from the command palette or with keybindings. - As source actions, such
Organize Imports
. - Quick fixes are shown in the problems view.
- Change applied on save by the
editor.codeActionsOnSave
setting.
Methods
provideCodeActions(document: TextDocument, range: Range | Selection, context: CodeActionContext, token: CancellationToken): ProviderResult<Array<Command | T>>
Get code actions for a given range in a document.
Only return code actions that are relevant to user for the requested range. Also keep in mind how the
returned code actions will appear in the UI. The lightbulb widget and Refactor
commands for instance show
returned code actions as a list, so do not return a large number of code actions that will overwhelm the user.
Parameter | Description |
---|---|
document: TextDocument | The document in which the command was invoked. |
range: Range | Selection | The selector or range for which the command was invoked. This will always be a selection if the actions are being requested in the currently active editor. |
context: CodeActionContext | Provides additional information about what code actions are being requested. You can use this to see what specific type of code actions are being requested by the editor in order to return more relevant actions and avoid returning irrelevant code actions that the editor will discard. |
token: CancellationToken | A cancellation token. |
Returns | Description |
ProviderResult<Array<Command | T>> | An array of code actions, such as quick fixes or refactorings. The lack of a result can be signaled
by returning We also support returning |
resolveCodeAction(codeAction: T, token: CancellationToken): ProviderResult<T>
Given a code action fill in its edit-property. Changes to all other properties, like title, are ignored. A code action that has an edit will not be resolved.
Note that a code action provider that returns commands, not code actions, cannot successfully implement this function. Returning commands is deprecated and instead code actions should be returned.
Parameter | Description |
---|---|
codeAction: T | A code action. |
token: CancellationToken | A cancellation token. |
Returns | Description |
ProviderResult<T> | The resolved code action or a thenable that resolves to such. It is OK to return the given
|
CodeActionProviderMetadata
Metadata about the type of code actions that a CodeActionProvider provides.
Properties
documentation?: ReadonlyArray<{command: Command, kind: CodeActionKind}>
Static documentation for a class of code actions.
Documentation from the provider is shown in the code actions menu if either:
Code actions of
kind
are requested by the editor. In this case, the editor will show the documentation that most closely matches the requested code action kind. For example, if a provider has documentation for bothRefactor
andRefactorExtract
, when the user requests code actions forRefactorExtract
, the editor will use the documentation forRefactorExtract
instead of the documentation forRefactor
.Any code actions of
kind
are returned by the provider.
At most one documentation entry will be shown per provider.
providedCodeActionKinds?: readonly CodeActionKind[]
List of CodeActionKinds that a CodeActionProvider may return.
This list is used to determine if a given CodeActionProvider
should be invoked or not.
To avoid unnecessary computation, every CodeActionProvider
should list use providedCodeActionKinds
. The
list of kinds may either be generic, such as [CodeActionKind.Refactor]
, or list out every kind provided,
such as [CodeActionKind.Refactor.Extract.append('function'), CodeActionKind.Refactor.Extract.append('constant'), ...]
.
CodeActionTriggerKind
The reason why code actions were requested.
Enumeration Members
Code actions were explicitly requested by the user or by an extension.
Code actions were requested automatically.
This typically happens when current selection in a file changes, but can also be triggered when file content changes.
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.
See also
Constructors
new CodeLens(range: Range, command?: Command): CodeLens
Creates a new code lens object.
Properties
command?: Command
The command this code lens represents.
true
when there is a command associated.
range: Range
The range in which this code lens is valid. Should only span a single line.
CodeLensProvider<T>
A code lens provider adds commands to source text. The commands will be shown as dedicated horizontal lines in between the source text.
Events
onDidChangeCodeLenses?: Event<void>
An optional event to signal that the code lenses from this provider have changed.
Methods
provideCodeLenses(document: TextDocument, token: CancellationToken): ProviderResult<T[]>
Compute a list of lenses. This call should return as fast as possible and if computing the commands is expensive implementors should only return code lens objects with the range set and implement resolve.
Parameter | Description |
---|---|
document: TextDocument | The document in which the command was invoked. |
token: CancellationToken | A cancellation token. |
Returns | Description |
ProviderResult<T[]> | An array of code lenses or a thenable that resolves to such. The lack of a result can be
signaled by returning |
resolveCodeLens(codeLens: T, token: CancellationToken): ProviderResult<T>
This function will be called for each visible code lens, usually when scrolling and after calls to compute-lenses.
Parameter | Description |
---|---|
codeLens: T | Code lens that must be resolved. |
token: CancellationToken | A cancellation token. |
Returns | Description |
ProviderResult<T> | The given, resolved code lens or thenable that resolves to such. |
Color
Represents a color in RGBA space.
Constructors
new Color(red: number, green: number, blue: number, alpha: number): Color
Creates a new color instance.
Parameter | Description |
---|---|
red: number | The red component. |
green: number | The green component. |
blue: number | The blue component. |
alpha: number | The alpha component. |
Returns | Description |
Color |
Properties
The alpha component of this color in the range [0-1]
.
The blue component of this color in the range [0-1]
.
The green component of this color in the range [0-1]
.
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 appears.
ColorPresentation
A color presentation object describes how a Color should be represented as text and what edits are required to refer to it from source code.
For some languages one color can have multiple presentations, e.g. css can represent the color red with
the constant Red
, the hex-value #ff0000
, or in rgba and hsla forms. In csharp other representations
apply, e.g. System.Drawing.Color.Red
.
Constructors
new ColorPresentation(label: string): ColorPresentation
Creates a new color presentation.
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.
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
ColorTheme
Represents a color theme.
Properties
kind: ColorThemeKind
The kind of this color theme: light, dark, high contrast dark and high contrast light.
ColorThemeKind
Represents a color theme kind.
Enumeration Members
A light color theme.
A dark color theme.
A dark high contrast color theme.
A light high contrast color theme.
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 that the command handler should be invoked with.
The identifier of the actual command handler.
See also commands.registerCommand
Title of the command, like save
.
A tooltip for the command, when represented in the UI.
Comment
A comment is displayed within the editor or the Comments Panel, depending on how it is provided.
Properties
author: CommentAuthorInformation
The author information of the comment
body: string | MarkdownString
The human-readable comment body
Context value of the comment. This can be used to contribute comment specific actions.
For example, a comment is given a context value as editable
. When contributing actions to comments/comment/title
using menus
extension point, you can specify context value for key comment
in when
expression like comment == editable
.
"contributes": {
"menus": {
"comments/comment/title": [
{
"command": "extension.deleteComment",
"when": "comment == editable"
}
]
}
}
This will show action extension.deleteComment
only for comments with contextValue
is editable
.
Optional label describing the Comment Label will be rendered next to authorName if exists.
mode: CommentMode
Comment mode of the comment
reactions?: CommentReaction[]
Optional reactions of the Comment
Optional timestamp that will be displayed in comments. The date will be formatted according to the user's locale and settings.
CommentAuthorInformation
Author information of a Comment
Properties
iconPath?: Uri
The optional icon path for the author
The display name of the author of the comment
CommentController
A comment controller is able to provide comments support to the editor and provide users various ways to interact with comments.
Properties
commentingRangeProvider?: CommentingRangeProvider
Optional commenting range provider. Provide a list ranges which support commenting to any given resource uri.
If not provided, users cannot leave any comments.
The id of this comment controller.
The human-readable label of this comment controller.
options?: CommentOptions
Comment controller options
reactionHandler?: (comment: Comment, reaction: CommentReaction) => Thenable<void>
Optional reaction handler for creating and deleting reactions on a Comment.
Parameter | Description |
---|---|
comment: Comment | |
reaction: CommentReaction | |
Returns | Description |
Thenable<void> |
Methods
createCommentThread(uri: Uri, range: Range, comments: readonly Comment[]): CommentThread
Create a comment thread. The comment thread will be displayed in visible text editors (if the resource matches) and Comments Panel once created.
Parameter | Description |
---|---|
uri: Uri | The uri of the document the thread has been created on. |
range: Range | The range the comment thread is located within the document. |
comments: readonly Comment[] | The ordered comments of the thread. |
Returns | Description |
CommentThread |
Dispose this comment controller.
Once disposed, all comment threads created by this comment controller will also be removed from the editor and Comments Panel.
Parameter | Description |
---|---|
Returns | Description |
void |
CommentingRangeProvider
Commenting range provider for a comment controller.
Methods
provideCommentingRanges(document: TextDocument, token: CancellationToken): ProviderResult<Range[]>
Provide a list of ranges which allow new comment threads creation or null for a given document
Parameter | Description |
---|---|
document: TextDocument | |
token: CancellationToken | |
Returns | Description |
ProviderResult<Range[]> |
CommentMode
Comment mode of a Comment
Enumeration Members
Displays the comment editor
Displays the preview of the comment
CommentOptions
Represents a comment controller's options.
Properties
An optional string to show as placeholder in the comment input box when it's focused.
An optional string to show on the comment input box when it's collapsed.
CommentReaction
Reactions of a Comment
Properties
Whether the author of the comment has reacted to this reaction
The number of users who have reacted to this reaction
iconPath: string | Uri
Icon for the reaction shown in UI.
The human-readable label for the reaction
CommentReply
Command argument for actions registered in comments/commentThread/context
.
Properties
The value in the comment editor
thread: CommentThread
The active comment thread
CommentRule
Describes how comments for a language work.
Properties
blockComment?: CharacterPair
The block comment character pair, like /* block comment */
The line comment token, like // this is a comment
CommentThread
A collection of comments representing a conversation at a particular range in a document.
Properties
Whether the thread supports reply. Defaults to true.
collapsibleState: CommentThreadCollapsibleState
Whether the thread should be collapsed or expanded when opening the document. Defaults to Collapsed.
comments: readonly Comment[]
The ordered comments of the thread.
Context value of the comment thread. This can be used to contribute thread specific actions.
For example, a comment thread is given a context value as editable
. When contributing actions to comments/commentThread/title
using menus
extension point, you can specify context value for key commentThread
in when
expression like commentThread == editable
.
"contributes": {
"menus": {
"comments/commentThread/title": [
{
"command": "extension.deleteCommentThread",
"when": "commentThread == editable"
}
]
}
}
This will show action extension.deleteCommentThread
only for comment threads with contextValue
is editable
.
The optional human-readable label describing the Comment Thread
range: Range
The range the comment thread is located within the document. The thread icon will be shown at the last line of the range.
state?: CommentThreadState
The optional state of a comment thread, which may affect how the comment is displayed.
uri: Uri
The uri of the document the thread has been created on.
Methods
Dispose this comment thread.
Once disposed, this comment thread will be removed from visible editors and Comment Panel when appropriate.
Parameter | Description |
---|---|
Returns | Description |
void |
CommentThreadCollapsibleState
Collapsible state of a comment thread
Enumeration Members
Determines an item is collapsed
Determines an item is expanded
CommentThreadState
The state of a comment thread.
Enumeration Members
Unresolved thread state
Resolved thread state
CompletionContext
Contains additional information about the context in which completion provider is triggered.
Properties
Character that triggered the completion item provider.
undefined
if the provider was not triggered by a character.
The trigger character is already in the document when the completion provider is triggered.
triggerKind: CompletionTriggerKind
How the completion was triggered.
CompletionItem
A completion item represents a text snippet that is proposed to complete text that is being typed.
It is sufficient to create a completion item from just a label. In that case the completion item will replace the word until the cursor with the given label or insertText. Otherwise the given edit is used.
When selecting a completion item in the editor its defined or synthesized text edit will be applied to all cursors/selections whereas additionalTextEdits will be applied as provided.
See also
Constructors
new CompletionItem(label: string | CompletionItemLabel, 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 | CompletionItemLabel | 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.
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.
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.
insertText?: string | SnippetString
A string or snippet that should be inserted in a document when selecting
this completion. When falsy
the label
is used.
Keep whitespace of the insertText as is. By default, the editor adjusts leading
whitespace of new lines so that they match the indentation of the line for which the item is accepted - setting
this to true
will prevent that.
kind?: CompletionItemKind
The kind of this completion item. Based on the kind an icon is chosen by the editor.
label: string | CompletionItemLabel
The label of this completion item. By default this is also the text that is inserted when selecting this completion.
Select this item when showing. Note that only one completion item can be selected and that the editor decides which item that is. The rule is that the first item of those that match best is selected.
range?: Range | {inserting: Range, replacing: Range}
A range or a insert and replace range selecting the text that should be replaced by this completion item.
When omitted, the range of the current word is used as replace-range and as insert-range the start of the current word to the current position is used.
Note 1: A range must be a single line and it must contain the position at which completion has been requested. Note 2: A insert range must be a prefix of a replace range, that means it must be contained and starting at the same position.
A string that should be used when comparing this item
with other items. When falsy
the label
is used.
Note that sortText
is only used for the initial ordering of completion
items. When having a leading word (prefix) ordering is based on how
well completions match that prefix and the initial ordering is only used
when completions match equally well. The prefix is defined by the
range-property and can therefore be different
for each completion.
tags?: readonly Deprecated[]
Tags for this completion item.
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
The Text
completion item kind.
The Method
completion item kind.
The Function
completion item kind.
The Constructor
completion item kind.
The Field
completion item kind.
The Variable
completion item kind.
The Class
completion item kind.
The Interface
completion item kind.
The Module
completion item kind.
The Property
completion item kind.
The Unit
completion item kind.
The Value
completion item kind.
The Enum
completion item kind.
The Keyword
completion item kind.
The Snippet
completion item kind.
The Color
completion item kind.
The File
completion item kind.
The Reference
completion item kind.
The Folder
completion item kind.
The EnumMember
completion item kind.
The Constant
completion item kind.
The Struct
completion item kind.
The Event
completion item kind.
The Operator
completion item kind.
The TypeParameter
completion item kind.
The User
completion item kind.
The Issue
completion item kind.
CompletionItemLabel
A structured label for a completion item.
Properties
An optional string which is rendered less prominently after CompletionItemLabel.detail. Should be used for fully qualified names or file path.
An optional string which is rendered less prominently directly after label, without any spacing. Should be used for function signatures or type annotations.
The label of this completion item.
By default this is also the text that is inserted when this completion is selected.
CompletionItemProvider<T>
The completion item provider interface defines the contract between extensions and IntelliSense.
Providers can delay the computation of the detail
and documentation properties by implementing the
resolveCompletionItem-function. However, properties that
are needed for the initial sorting and filtering, like sortText
, filterText
, insertText
, and range
, must
not be changed during resolve.
Providers are asked for completions either explicitly by a user gesture or -depending on the configuration- implicitly when typing words or trigger characters.
Methods
provideCompletionItems(document: TextDocument, position: Position, token: CancellationToken, context: CompletionContext): ProviderResult<CompletionList<T> | T[]>
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<CompletionList<T> | T[]> | An array of completions, a completion list, or a thenable that resolves to either.
The lack of a result can be signaled by returning |
resolveCompletionItem(item: T, token: CancellationToken): ProviderResult<T>
Given a completion item fill in more data, like doc-comment or details.
The editor will only resolve a completion item once.
Note that this function is called when completion items are already showing in the UI or when an item has been selected for insertion. Because of that, no property that changes the presentation (label, sorting, filtering etc) or the (primary) insert behaviour (insertText) can be changed.
This function may fill in additionalTextEdits. However, that means an item might be inserted before resolving is done and in that case the editor will do a best effort to still apply those additional text edits.
Parameter | Description |
---|---|
item: T | A completion item currently active in the UI. |
token: CancellationToken | A cancellation token. |
Returns | Description |
ProviderResult<T> | The resolved completion item or a thenable that resolves to of such. It is OK to return the given
|
CompletionItemTag
Completion item tags are extra annotations that tweak the rendering of a completion item.
Enumeration Members
Render a completion as obsolete, usually using a strike-out.
CompletionList<T>
Represents a collection of completion items to be presented in the editor.
Constructors
new CompletionList<T extends CompletionItem>(items?: T[], isIncomplete?: boolean): CompletionList<T>
Creates a new completion list.
Parameter | Description |
---|---|
items?: T[] | The completion items. |
isIncomplete?: boolean | The list is not complete. |
Returns | Description |
CompletionList<T> |
Properties
This list is not complete. Further typing should result in recomputing this list.
The completion items.
CompletionTriggerKind
How a completion provider was triggered
Enumeration Members
Completion was triggered normally.
Completion was triggered by a trigger character.
TriggerForIncompleteCompletions: 2
Completion was re-triggered as current completion list is incomplete
ConfigurationChangeEvent
An event describing the change in Configuration
Methods
affectsConfiguration(section: string, scope?: ConfigurationScope): boolean
Checks if the given section has changed. If scope is provided, checks if the section has changed for resources under the given scope.
Parameter | Description |
---|---|
section: string | Configuration name, supports dotted names. |
scope?: ConfigurationScope | A scope in which to check. |
Returns | Description |
boolean |
|
ConfigurationScope
The configuration scope which can be a a 'resource' or a languageId or both or a 'TextDocument' or a 'WorkspaceFolder'
ConfigurationScope: Uri | TextDocument | WorkspaceFolder | {languageId: string, uri: Uri}
ConfigurationTarget
The configuration target
Enumeration Members
Global configuration
Workspace configuration
Workspace folder configuration
CustomDocument
Represents a custom document used by a CustomEditorProvider.
Custom documents are only used within a given CustomEditorProvider
. The lifecycle of a CustomDocument
is
managed by the editor. When no more references remain to a CustomDocument
, it is disposed of.
Properties
uri: Uri
The associated uri for this document.
Methods
Dispose of the custom document.
This is invoked by the editor when there are no more references to a given CustomDocument
(for example when
all editors associated with the document have been closed.)
Parameter | Description |
---|---|
Returns | Description |
void |
CustomDocumentBackup
A backup for an CustomDocument.
Properties
Unique identifier for the backup.
This id is passed back to your extension in openCustomDocument
when opening a custom editor from a backup.
Methods
Delete the current backup.
This is called by the editor when it is clear the current backup is no longer needed, such as when a new backup is made or when the file is saved.
Parameter | Description |
---|---|
Returns | Description |
void |
CustomDocumentBackupContext
Additional information used to implement CustomDocumentBackup.
Properties
destination: Uri
Suggested file location to write the new backup.
Note that your extension is free to ignore this and use its own strategy for backup.
If the editor is for a resource from the current workspace, destination
will point to a file inside
ExtensionContext.storagePath
. The parent folder of destination
may not exist, so make sure to created it
before writing the backup to this location.
CustomDocumentContentChangeEvent<T>
Event triggered by extensions to signal to the editor that the content of a CustomDocument has changed.
Properties
The document that the change is for.
CustomDocumentEditEvent<T>
Event triggered by extensions to signal to the editor that an edit has occurred on an CustomDocument.
Properties
The document that the edit is for.
Display name describing the edit.
This will be shown to users in the UI for undo/redo operations.
Methods
Redo the edit operation.
This is invoked by the editor when the user redoes this edit. To implement redo
, your
extension should restore the document and editor to the state they were in just after this
edit was added to the editor's internal edit stack by onDidChangeCustomDocument
.
Parameter | Description |
---|---|
Returns | Description |
void | Thenable<void> |
Undo the edit operation.
This is invoked by the editor when the user undoes this edit. To implement undo
, your
extension should restore the document and editor to the state they were in just before this
edit was added to the editor's internal edit stack by onDidChangeCustomDocument
.
Parameter | Description |
---|---|
Returns | Description |
void | Thenable<void> |
CustomDocumentOpenContext
Additional information about the opening custom document.
Properties
The id of the backup to restore the document from or undefined
if there is no backup.
If this is provided, your extension should restore the editor from the backup instead of reading the file from the user's workspace.
untitledDocumentData: Uint8Array
If the URI is an untitled file, this will be populated with the byte data of that file
If this is provided, your extension should utilize this byte data rather than executing fs APIs on the URI passed in
CustomEditorProvider<T>
Provider for editable custom editors that use a custom document model.
Custom editors use CustomDocument as their document model instead of a TextDocument. This gives extensions full control over actions such as edit, save, and backup.
You should use this type of custom editor when dealing with binary files or more complex scenarios. For simple text based documents, use CustomTextEditorProvider instead.
Events
onDidChangeCustomDocument: Event<CustomDocumentEditEvent<T>> | Event<CustomDocumentContentChangeEvent<T>>
Signal that an edit has occurred inside a custom editor.
This event must be fired by your extension whenever an edit happens in a custom editor. An edit can be anything from changing some text, to cropping an image, to reordering a list. Your extension is free to define what an edit is and what data is stored on each edit.
Firing onDidChange
causes the editors to be marked as being dirty. This is cleared when the user either
saves or reverts the file.
Editors that support undo/redo must fire a CustomDocumentEditEvent
whenever an edit happens. This allows
users to undo and redo the edit using the editor's standard keyboard shortcuts. The editor will also mark
the editor as no longer being dirty if the user undoes all edits to the last saved state.
Editors that support editing but cannot use the editor's standard undo/redo mechanism must fire a CustomDocumentContentChangeEvent
.
The only way for a user to clear the dirty state of an editor that does not support undo/redo is to either
save
or revert
the file.
An editor should only ever fire CustomDocumentEditEvent
events, or only ever fire CustomDocumentContentChangeEvent
events.
Methods
backupCustomDocument(document: T, context: CustomDocumentBackupContext, cancellation: CancellationToken): Thenable<CustomDocumentBackup>
Back up a dirty custom document.
Backups are used for hot exit and to prevent data loss. Your backup
method should persist the resource in
its current state, i.e. with the edits applied. Most commonly this means saving the resource to disk in
the ExtensionContext.storagePath
. When the editor reloads and your custom editor is opened for a resource,
your extension should first check to see if any backups exist for the resource. If there is a backup, your
extension should load the file contents from there instead of from the resource in the workspace.
backup
is triggered approximately one second after the user stops editing the document. If the user
rapidly edits the document, backup
will not be invoked until the editing stops.
backup
is not invoked when auto save
is enabled (since auto save already persists the resource).
Parameter | Description |
---|---|
document: T | Document to backup. |
context: CustomDocumentBackupContext | Information that can be used to backup the document. |
cancellation: CancellationToken | Token that signals the current backup since a new backup is coming in. It is up to your extension to decided how to respond to cancellation. If for example your extension is backing up a large file in an operation that takes time to complete, your extension may decide to finish the ongoing backup rather than cancelling it to ensure that the editor has some valid backup. |
Returns | Description |
Thenable<CustomDocumentBackup> |
openCustomDocument(uri: Uri, openContext: CustomDocumentOpenContext, token: CancellationToken): T | Thenable<T>
Create a new document for a given resource.
openCustomDocument
is called when the first time an editor for a given resource is opened. The opened
document is then passed to resolveCustomEditor
so that the editor can be shown to the user.
Already opened CustomDocument
are re-used if the user opened additional editors. When all editors for a
given resource are closed, the CustomDocument
is disposed of. Opening an editor at this point will
trigger another call to openCustomDocument
.
Parameter | Description |
---|---|
uri: Uri | Uri of the document to open. |
openContext: CustomDocumentOpenContext | Additional information about the opening custom document. |
token: CancellationToken | A cancellation token that indicates the result is no longer needed. |
Returns | Description |
T | Thenable<T> | The custom document. |
resolveCustomEditor(document: T, webviewPanel: WebviewPanel, token: CancellationToken): void | Thenable<void>
Resolve a custom editor for a given resource.
This is called whenever the user opens a new editor for this CustomEditorProvider
.
Parameter | Description |
---|---|
document: T | Document for the resource being resolved. |
webviewPanel: WebviewPanel | The webview panel used to display the editor UI for this resource. During resolve, the provider must fill in the initial html for the content webview panel and hook up all
the event listeners on it that it is interested in. The provider can also hold onto the |
token: CancellationToken | A cancellation token that indicates the result is no longer needed. |
Returns | Description |
void | Thenable<void> | Optional thenable indicating that the custom editor has been resolved. |
revertCustomDocument(document: T, cancellation: CancellationToken): Thenable<void>
Revert a custom document to its last saved state.
This method is invoked by the editor when the user triggers File: Revert File
in a custom editor. (Note that
this is only used using the editor's File: Revert File
command and not on a git revert
of the file).
To implement revert
, the implementer must make sure all editor instances (webviews) for document
are displaying the document in the same state is saved in. This usually means reloading the file from the
workspace.
Parameter | Description |
---|---|
document: T | Document to revert. |
cancellation: CancellationToken | Token that signals the revert is no longer required. |
Returns | Description |
Thenable<void> | Thenable signaling that the change has completed. |
saveCustomDocument(document: T, cancellation: CancellationToken): Thenable<void>
Save a custom document.
This method is invoked by the editor when the user saves a custom editor. This can happen when the user
triggers save while the custom editor is active, by commands such as save all
, or by auto save if enabled.
To implement save
, the implementer must persist the custom editor. This usually means writing the
file data for the custom document to disk. After save
completes, any associated editor instances will
no longer be marked as dirty.
Parameter | Description |
---|---|
document: T | Document to save. |
cancellation: CancellationToken | Token that signals the save is no longer required (for example, if another save was triggered). |
Returns | Description |
Thenable<void> | Thenable signaling that saving has completed. |
saveCustomDocumentAs(document: T, destination: Uri, cancellation: CancellationToken): Thenable<void>
Save a custom document to a different location.
This method is invoked by the editor when the user triggers 'save as' on a custom editor. The implementer must
persist the custom editor to destination
.
When the user accepts save as, the current editor is be replaced by an non-dirty editor for the newly saved file.
Parameter | Description |
---|---|
document: T | Document to save. |
destination: Uri | Location to save to. |
cancellation: CancellationToken | Token that signals the save is no longer required. |
Returns | Description |
Thenable<void> | Thenable signaling that saving has completed. |
CustomExecution
Class used to execute an extension callback as a task.
Constructors
new CustomExecution(callback: (resolvedDefinition: TaskDefinition) => Thenable<Pseudoterminal>): CustomExecution
Constructs a CustomExecution task object. The callback will be executed when the task is run, at which point the extension should return the Pseudoterminal it will "run in". The task should wait to do further execution until Pseudoterminal.open is called. Task cancellation should be handled using Pseudoterminal.close. When the task is complete fire Pseudoterminal.onDidClose.
Parameter | Description |
---|---|
callback: (resolvedDefinition: TaskDefinition) => Thenable<Pseudoterminal> | The callback that will be called when the task is started by a user. Any ${} style variables that
were in the task definition will be resolved and passed into the callback as |
Returns | Description |
CustomExecution |
CustomReadonlyEditorProvider<T>
Provider for readonly custom editors that use a custom document model.
Custom editors use CustomDocument as their document model instead of a TextDocument.
You should use this type of custom editor when dealing with binary files or more complex scenarios. For simple text based documents, use CustomTextEditorProvider instead.
Methods
openCustomDocument(uri: Uri, openContext: CustomDocumentOpenContext, token: CancellationToken): T | Thenable<T>
Create a new document for a given resource.
openCustomDocument
is called when the first time an editor for a given resource is opened. The opened
document is then passed to resolveCustomEditor
so that the editor can be shown to the user.
Already opened CustomDocument
are re-used if the user opened additional editors. When all editors for a
given resource are closed, the CustomDocument
is disposed of. Opening an editor at this point will
trigger another call to openCustomDocument
.
Parameter | Description |
---|---|
uri: Uri | Uri of the document to open. |
openContext: CustomDocumentOpenContext | Additional information about the opening custom document. |
token: CancellationToken | A cancellation token that indicates the result is no longer needed. |
Returns | Description |
T | Thenable<T> | The custom document. |
resolveCustomEditor(document: T, webviewPanel: WebviewPanel, token: CancellationToken): void | Thenable<void>
Resolve a custom editor for a given resource.
This is called whenever the user opens a new editor for this CustomEditorProvider
.
Parameter | Description |
---|---|
document: T | Document for the resource being resolved. |
webviewPanel: WebviewPanel | The webview panel used to display the editor UI for this resource. During resolve, the provider must fill in the initial html for the content webview panel and hook up all
the event listeners on it that it is interested in. The provider can also hold onto the |
token: CancellationToken | A cancellation token that indicates the result is no longer needed. |
Returns | Description |
void | Thenable<void> | Optional thenable indicating that the custom editor has been resolved. |
CustomTextEditorProvider
Provider for text based custom editors.
Text based custom editors use a TextDocument as their data model. This considerably simplifies
implementing a custom editor as it allows the editor to handle many common operations such as
undo and backup. The provider is responsible for synchronizing text changes between the webview and the TextDocument
.
Methods
resolveCustomTextEditor(document: TextDocument, webviewPanel: WebviewPanel, token: CancellationToken): void | Thenable<void>
Resolve a custom editor for a given text resource.
This is called when a user first opens a resource for a CustomTextEditorProvider
, or if they reopen an
existing editor using this CustomTextEditorProvider
.
Parameter | Description |
---|---|
document: TextDocument | Document for the resource to resolve. |
webviewPanel: WebviewPanel | The webview panel used to display the editor UI for this resource. During resolve, the provider must fill in the initial html for the content webview panel and hook up all
the event listeners on it that it is interested in. The provider can also hold onto the |
token: CancellationToken | A cancellation token that indicates the result is no longer needed. |
Returns | Description |
void | Thenable<void> | Thenable indicating that the custom editor has been resolved. |
DataTransfer
A map containing a mapping of the mime type of the corresponding transferred data.
Drag and drop controllers that implement handleDrag
can add additional mime types to the
data transfer. These additional mime types will only be included in the handleDrop
when the the drag was initiated from
an element in the same drag and drop controller.
Constructors
new DataTransfer(): DataTransfer
Parameter | Description |
---|---|
Returns | Description |
DataTransfer |
Methods
[iterator](): IterableIterator<[mimeType: string, item: DataTransferItem]>
Get a new iterator with the [mime, item]
pairs for each element in this data transfer.
Parameter | Description |
---|---|
Returns | Description |
IterableIterator<[mimeType: string, item: DataTransferItem]> |
forEach(callbackfn: (item: DataTransferItem, mimeType: string, dataTransfer: DataTransfer) => void, thisArg?: any): void
Allows iteration through the data transfer items.
Parameter | Description |
---|---|
callbackfn: (item: DataTransferItem, mimeType: string, dataTransfer: DataTransfer) => void | Callback for iteration through the data transfer items. |
thisArg?: any | The |
Returns | Description |
void |
get(mimeType: string): DataTransferItem
Retrieves the data transfer item for a given mime type.
Parameter | Description |
---|---|
mimeType: string | The mime type to get the data transfer item for, such as Special mime types:
|
Returns | Description |
DataTransferItem |
set(mimeType: string, value: DataTransferItem): void
Sets a mime type to data transfer item mapping.
Parameter | Description |
---|---|
mimeType: string | The mime type to set the data for. Mimes types stored in lower case, with case-insensitive looks up. |
value: DataTransferItem | The data transfer item for the given mime type. |
Returns | Description |
void |
DataTransferFile
A file associated with a DataTransferItem.
Instances of this type can only be created by the editor and not by extensions.
Properties
The name of the file.
uri?: Uri
The full file path of the file.
May be undefined
on web.
Methods
The full file contents of the file.
Parameter | Description |
---|---|
Returns | Description |
Thenable<Uint8Array> |
DataTransferItem
Encapsulates data transferred during drag and drop operations.
Constructors
new DataTransferItem(value: any): DataTransferItem
Parameter | Description |
---|---|
value: any | Custom data stored on this item. Can be retrieved using DataTransferItem.value. |
Returns | Description |
DataTransferItem |
Properties
Custom data stored on this item.
You can use value
to share data across operations. The original object can be retrieved so long as the extension that
created the DataTransferItem
runs in the same extension host.
Methods
asFile(): DataTransferFile
Try getting the file associated with this data transfer item.
Note that the file object is only valid for the scope of the drag and drop operation.
Parameter | Description |
---|---|
Returns | Description |
DataTransferFile | The file for the data transfer or |
Get a string representation of this item.
If DataTransferItem.value is an object, this returns the result of json stringifying DataTransferItem.value value.
Parameter | Description |
---|---|
Returns | Description |
Thenable<string> |
DebugAdapter
A debug adapter that implements the Debug Adapter Protocol can be registered with the editor if it implements the DebugAdapter interface.
Events
onDidSendMessage: Event<DebugProtocolMessage>
An event which fires after the debug adapter has sent a Debug Adapter Protocol message to the editor. Messages can be requests, responses, or events.
Methods
Dispose this object.
Parameter | Description |
---|---|
Returns | Description |
any |
handleMessage(message: DebugProtocolMessage): void
Handle a Debug Adapter Protocol message. Messages can be requests, responses, or events. Results or errors are returned via onSendMessage events.
Parameter | Description |
---|---|
message: DebugProtocolMessage | A Debug Adapter Protocol message |
Returns | Description |
void |
DebugAdapterDescriptor
Represents the different types of debug adapters
DebugAdapterDescriptor: DebugAdapterExecutable | DebugAdapterServer | DebugAdapterNamedPipeServer | DebugAdapterInlineImplementation
DebugAdapterDescriptorFactory
A debug adaper factory that creates debug adapter descriptors.
Methods
createDebugAdapterDescriptor(session: DebugSession, executable: DebugAdapterExecutable): ProviderResult<DebugAdapterDescriptor>
'createDebugAdapterDescriptor' is called at the start of a debug session to provide details about the debug adapter to use. These details must be returned as objects of type DebugAdapterDescriptor. Currently two types of debug adapters are supported:
- a debug adapter executable is specified as a command path and arguments (see DebugAdapterExecutable),
- a debug adapter server reachable via a communication port (see DebugAdapterServer). If the method is not implemented the default behavior is this: createDebugAdapter(session: DebugSession, executable: DebugAdapterExecutable) { if (typeof session.configuration.debugServer === 'number') { return new DebugAdapterServer(session.configuration.debugServer); } return executable; }
Parameter | Description |
---|---|
session: DebugSession | The debug session for which the debug adapter will be used. |
executable: DebugAdapterExecutable | The debug adapter's executable information as specified in the package.json (or undefined if no such information exists). |
Returns | Description |
ProviderResult<DebugAdapterDescriptor> | a debug adapter descriptor or undefined. |
DebugAdapterExecutable
Represents a debug adapter executable and optional arguments and runtime options passed to it.
Constructors
new DebugAdapterExecutable(command: string, args?: string[], options?: DebugAdapterExecutableOptions): DebugAdapterExecutable
Creates a description for a debug adapter based on an executable program.
Parameter | Description |
---|---|
command: string | The command or executable path that implements the debug adapter. |
args?: string[] | Optional arguments to be passed to the command or executable. |
options?: DebugAdapterExecutableOptions | Optional options to be used when starting the command or executable. |
Returns | Description |
DebugAdapterExecutable |
Properties
The arguments passed to the debug adapter executable. Defaults to an empty array.
The command or path of the debug adapter executable. A command must be either an absolute path of an executable or the name of an command to be looked up via the PATH environment variable. The special value 'node' will be mapped to the editor's built-in Node.js runtime.
options?: DebugAdapterExecutableOptions
Optional options to be used when the debug adapter is started. Defaults to undefined.
DebugAdapterExecutableOptions
Options for a debug adapter executable.
Properties
The current working directory for the executed debug adapter.
The additional environment of the executed program or shell. If omitted the parent process' environment is used. If provided it is merged with the parent process' environment.
DebugAdapterInlineImplementation
A debug adapter descriptor for an inline implementation.
Constructors
new DebugAdapterInlineImplementation(implementation: DebugAdapter): DebugAdapterInlineImplementation
Create a descriptor for an inline implementation of a debug adapter.
Parameter | Description |
---|---|
implementation: DebugAdapter | |
Returns | Description |
DebugAdapterInlineImplementation |
DebugAdapterNamedPipeServer
Represents a debug adapter running as a Named Pipe (on Windows)/UNIX Domain Socket (on non-Windows) based server.
Constructors
new DebugAdapterNamedPipeServer(path: string): DebugAdapterNamedPipeServer
Create a description for a debug adapter running as a Named Pipe (on Windows)/UNIX Domain Socket (on non-Windows) based server.
Parameter | Description |
---|---|
path: string | |
Returns | Description |
DebugAdapterNamedPipeServer |
Properties
The path to the NamedPipe/UNIX Domain Socket.
DebugAdapterServer
Represents a debug adapter running as a socket based server.
Constructors
new DebugAdapterServer(port: number, host?: string): DebugAdapterServer
Create a description for a debug adapter running as a socket based server.
Parameter | Description |
---|---|
port: number | |
host?: string | |
Returns | Description |
DebugAdapterServer |
Properties
The host.
The port.
DebugAdapterTracker
A Debug Adapter Tracker is a means to track the communication between the editor and a Debug Adapter.
Events
onDidSendMessage(message: any): void
The debug adapter has sent a Debug Adapter Protocol message to the editor.
Parameter | Description |
---|---|
message: any | |
Returns | Description |
void |
onWillReceiveMessage(message: any): void
The debug adapter is about to receive a Debug Adapter Protocol message from the editor.
Parameter | Description |
---|---|
message: any | |
Returns | Description |
void |
A session with the debug adapter is about to be started.
Parameter | Description |
---|---|
Returns | Description |
void |
The debug adapter session is about to be stopped.
Parameter | Description |
---|---|
Returns | Description |
void |
Methods
An error with the debug adapter has occurred.
Parameter | Description |
---|---|
error: Error | |
Returns | Description |
void |
onExit(code: number, signal: string): void
The debug adapter has exited with the given exit code or signal.
Parameter | Description |
---|---|
code: number | |
signal: string | |
Returns | Description |
void |
DebugAdapterTrackerFactory
A debug adaper factory that creates debug adapter trackers.
Methods
createDebugAdapterTracker(session: DebugSession): ProviderResult<DebugAdapterTracker>
The method 'createDebugAdapterTracker' is called at the start of a debug session in order to return a "tracker" object that provides read-access to the communication between the editor and a debug adapter.
Parameter | Description |
---|---|
session: DebugSession | The debug session for which the debug adapter tracker will be used. |
Returns | Description |
ProviderResult<DebugAdapterTracker> | A debug adapter tracker or undefined. |
DebugConfiguration
Configuration for a debug session.
Properties
The name of the debug session.
The request type of the debug session.
The type of the debug session.
DebugConfigurationProvider
A debug configuration provider allows to add debug configurations to the debug service and to resolve launch configurations before they are used to start a debug session. A debug configuration provider is registered via debug.registerDebugConfigurationProvider.
Methods
provideDebugConfigurations(folder: WorkspaceFolder, token?: CancellationToken): ProviderResult<DebugConfiguration[]>
Provides debug configuration to the debug service. If more than one debug configuration provider is registered for the same type, debug configurations are concatenated in arbitrary order.
Parameter | Description |
---|---|
folder: WorkspaceFolder | The workspace folder for which the configurations are used or |
token?: CancellationToken | A cancellation token. |
Returns | Description |
ProviderResult<DebugConfiguration[]> | An array of debug configurations. |
resolveDebugConfiguration(folder: WorkspaceFolder, debugConfiguration: DebugConfiguration, token?: CancellationToken): ProviderResult<DebugConfiguration>
Resolves a debug configuration by filling in missing values or by adding/changing/removing attributes. If more than one debug configuration provider is registered for the same type, the resolveDebugConfiguration calls are chained in arbitrary order and the initial debug configuration is piped through the chain. Returning the value 'undefined' prevents the debug session from starting. Returning the value 'null' prevents the debug session from starting and opens the underlying debug configuration instead.
Parameter | Description |
---|---|
folder: WorkspaceFolder | The workspace folder from which the configuration originates from or |
debugConfiguration: DebugConfiguration | The debug configuration to resolve. |
token?: CancellationToken | A cancellation token. |
Returns | Description |
ProviderResult<DebugConfiguration> | The resolved debug configuration or undefined or null. |
resolveDebugConfigurationWithSubstitutedVariables(folder: WorkspaceFolder, debugConfiguration: DebugConfiguration, token?: CancellationToken): ProviderResult<DebugConfiguration>
This hook is directly called after 'resolveDebugConfiguration' but with all variables substituted. It can be used to resolve or verify a debug configuration by filling in missing values or by adding/changing/removing attributes. If more than one debug configuration provider is registered for the same type, the 'resolveDebugConfigurationWithSubstitutedVariables' calls are chained in arbitrary order and the initial debug configuration is piped through the chain. Returning the value 'undefined' prevents the debug session from starting. Returning the value 'null' prevents the debug session from starting and opens the underlying debug configuration instead.
Parameter | Description |
---|---|
folder: WorkspaceFolder | The workspace folder from which the configuration originates from or |
debugConfiguration: DebugConfiguration | The debug configuration to resolve. |
token?: CancellationToken | A cancellation token. |
Returns | Description |
ProviderResult<DebugConfiguration> | The resolved debug configuration or undefined or null. |
DebugConfigurationProviderTriggerKind
A DebugConfigurationProviderTriggerKind specifies when the provideDebugConfigurations
method of a DebugConfigurationProvider
is triggered.
Currently there are two situations: to provide the initial debug configurations for a newly created launch.json or
to provide dynamically generated debug configurations when the user asks for them through the UI (e.g. via the "Select and Start Debugging" command).
A trigger kind is used when registering a DebugConfigurationProvider
with debug.registerDebugConfigurationProvider.
Enumeration Members
DebugConfigurationProvider.provideDebugConfigurations
is called to provide the initial debug configurations for a newly created launch.json.
DebugConfigurationProvider.provideDebugConfigurations
is called to provide dynamically generated debug configurations when the user asks for them through the UI (e.g. via the "Select and Start Debugging" command).
DebugConsole
Represents the debug console.
Methods
Append the given value to the debug console.
Parameter | Description |
---|---|
value: string | A string, falsy values will not be printed. |
Returns | Description |
void |
appendLine(value: string): void
Append the given value and a line feed character to the debug console.
Parameter | Description |
---|---|
value: string | A string, falsy values will be printed. |
Returns | Description |
void |
DebugConsoleMode
Debug console mode used by debug session, see options.
Enumeration Members
Debug session should have a separate debug console.
Debug session should share debug console with its parent session. This value has no effect for sessions which do not have a parent session.
DebugProtocolBreakpoint
A DebugProtocolBreakpoint is an opaque stand-in type for the Breakpoint type defined in the Debug Adapter Protocol.
DebugProtocolMessage
A DebugProtocolMessage is an opaque stand-in type for the ProtocolMessage type defined in the Debug Adapter Protocol.
DebugProtocolSource
A DebugProtocolSource is an opaque stand-in type for the Source type defined in the Debug Adapter Protocol.
DebugSession
A debug session.
Properties
configuration: DebugConfiguration
The "resolved" debug configuration of this session. "Resolved" means that
- all variables have been substituted and
- platform specific attribute sections have been "flattened" for the matching platform and removed for non-matching platforms.
The unique ID of this debug session.
The debug session's name is initially taken from the debug configuration. Any changes will be properly reflected in the UI.
parentSession?: DebugSession
The parent session of this debug session, if it was created as a child.
See also DebugSessionOptions.parentSession
The debug session's type from the debug configuration.
workspaceFolder: WorkspaceFolder
The workspace folder of this session or undefined
for a folderless setup.
Methods
customRequest(command: string, args?: any): Thenable<any>
Send a custom request to the debug adapter.
Parameter | Description |
---|---|
command: string | |
args?: any | |
Returns | Description |
Thenable<any> |
getDebugProtocolBreakpoint(breakpoint: Breakpoint): Thenable<DebugProtocolBreakpoint>
Maps a breakpoint in the editor to the corresponding Debug Adapter Protocol (DAP) breakpoint that is managed by the debug adapter of the debug session.
If no DAP breakpoint exists (either because the editor breakpoint was not yet registered or because the debug adapter is not interested in the breakpoint), the value undefined
is returned.
Parameter | Description |
---|---|
breakpoint: Breakpoint | A Breakpoint in the editor. |
Returns | Description |
Thenable<DebugProtocolBreakpoint> | A promise that resolves to the Debug Adapter Protocol breakpoint or |
DebugSessionCustomEvent
A custom Debug Adapter Protocol event received from a debug session.
Properties
Event specific information.
Type of event.
session: DebugSession
The debug session for which the custom event was received.
DebugSessionOptions
Options for starting a debug session.
Properties
Controls if the debug session's parent session is shown in the CALL STACK view even if it has only a single child. By default, the debug session will never hide its parent. If compact is true, debug sessions with a single child are hidden in the CALL STACK view to make the tree more compact.
consoleMode?: DebugConsoleMode
Controls whether this session should have a separate debug console or share it with the parent session. Has no effect for sessions which do not have a parent session. Defaults to Separate.
lifecycleManagedByParent?: boolean
Controls whether lifecycle requests like 'restart' are sent to the newly created session or its parent session. By default (if the property is false or missing), lifecycle requests are sent to the new session. This property is ignored if the session has no parent session.
Controls whether this session should run without debugging, thus ignoring breakpoints. When this property is not specified, the value from the parent session (if there is one) is used.
parentSession?: DebugSession
When specified the newly created debug session is registered as a "child" session of this "parent" debug session.
suppressDebugStatusbar?: boolean
When true, the window statusbar color will not be changed for this session.
suppressDebugToolbar?: boolean
When true, the debug toolbar will not be shown for this session.
When true, the debug viewlet will not be automatically revealed for this session.
suppressSaveBeforeStart?: boolean
When true, a save will not be triggered for open editors when starting a debug session, regardless of the value of the debug.saveBeforeStart
setting.
testRun?: TestRun
Signals to the editor that the debug session was started from a test run request. This is used to link the lifecycle of the debug session and test run in UI actions.
DebugStackFrame
Represents a stack frame in a debug session.
Properties
ID of the stack frame in the debug protocol.
session: DebugSession
Debug session for thread.
ID of the associated thread in the debug protocol.
DebugThread
Represents a thread in a debug session.
Properties
session: DebugSession
Debug session for thread.
ID of the associated thread in the debug protocol.
Declaration
The declaration of a symbol representation as one or many locations or location links.
Declaration: Location | Location[] | LocationLink[]
DeclarationCoverage
Contains coverage information for a declaration. Depending on the reporter and language, this may be types such as functions, methods, or namespaces.
Constructors
new DeclarationCoverage(name: string, executed: number | boolean, location: Range | Position): DeclarationCoverage
Parameter | Description |
---|---|
name: string | |
executed: number | boolean | The number of times this declaration was executed, or a boolean indicating whether it was executed if the exact count is unknown. If zero or false, the declaration will be marked as un-covered. |
location: Range | Position | The declaration position. |
Returns | Description |
DeclarationCoverage |
Properties
The number of times this declaration was executed, or a boolean indicating whether it was executed if the exact count is unknown. If zero or false, the declaration will be marked as un-covered.
Declaration location.
Name of the declaration.
DeclarationProvider
The declaration provider interface defines the contract between extensions and the go to declaration feature.
Methods
provideDeclaration(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<Declaration>
Provide the declaration of the symbol at the given position and document.
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<Declaration> | A declaration or a thenable that resolves to such. The lack of a result can be
signaled by returning |
DecorationInstanceRenderOptions
Represents render options for decoration instances. See DecorationOptions.renderOptions.
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?: MarkdownString | MarkedString | Array<MarkdownString | MarkedString>
A message that should be rendered when hovering over the decoration.
range: Range
Range to which this decoration is applied. The range must not be empty.
renderOptions?: DecorationInstanceRenderOptions
Render options applied to the current decoration. For performance reasons, keep the number of decoration specific options small, and use decoration types wherever possible.
DecorationRangeBehavior
Describes the behavior of decorations when typing/editing at their edges.
Enumeration Members
The decoration's range will widen when edits occur at the start or end.
The decoration's range will not widen when edits occur at the start or end.
The decoration's range will widen when edits occur at the start, but not at the end.
The decoration's range will widen when edits occur at the end, but not at the start.
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.
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.
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.
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.
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.
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.
CSS styling property that will be applied to text enclosed by a decoration.
dark?: ThemableDecorationRenderOptions
Overwrite options for dark themes.
CSS styling property that will be applied to text enclosed by a decoration.
CSS styling property that will be applied to text enclosed by a decoration.
gutterIconPath?: string | Uri
An absolute path or an URI to an image to be rendered in the gutter.
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
Should the decoration be rendered also on the whitespace after the line text.
Defaults to false
.
CSS styling property that will be applied to text enclosed by a decoration.
light?: ThemableDecorationRenderOptions
Overwrite options for light themes.
CSS styling property that will be applied to text enclosed by a decoration.
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.
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.
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
.
CSS styling property that will be applied to text enclosed by a decoration.
Definition
The definition of a symbol represented as one or many locations. For most programming languages there is only one location at which a symbol is defined.
Definition: Location | Location[]
DefinitionLink
Information about where a symbol is defined.
Provides additional metadata over normal Location definitions, including the range of the defining symbol
DefinitionLink: LocationLink
DefinitionProvider
The definition provider interface defines the contract between extensions and the go to definition and peek definition features.
Methods
provideDefinition(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<Definition | LocationLink[]>
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 | LocationLink[]> | 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
code?: string | number | {target: Uri, value: string | number}
A code or identifier for this diagnostic. Should be used for later processing, e.g. when providing code actions.
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.
A human-readable string describing the source of this diagnostic, e.g. 'typescript' or 'super lint'.
tags?: DiagnosticTag[]
Additional metadata about the diagnostic.
DiagnosticChangeEvent
The event that is fired when diagnostics change.
Properties
uris: readonly Uri[]
An array of resources for which diagnostics have changed.
DiagnosticCollection
A diagnostics collection is a container that manages a set of diagnostics. Diagnostics are always scopes to a diagnostics collection and a resource.
To get an instance of a DiagnosticCollection
use
createDiagnosticCollection.
Properties
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
Remove all diagnostics from this collection. The same
as calling #set(undefined)
;
Parameter | Description |
---|---|
Returns | Description |
void |
delete(uri: Uri): void
Remove all diagnostics from this collection that belong
to the provided uri
. The same as #set(uri, undefined)
.
Parameter | Description |
---|---|
uri: Uri | A resource identifier. |
Returns | Description |
void |
Dispose and free associated resources. Calls clear.
Parameter | Description |
---|---|
Returns | Description |
void |
forEach(callback: (uri: Uri, diagnostics: readonly Diagnostic[], collection: DiagnosticCollection) => any, thisArg?: any): void
Iterate over each entry in this collection.
Parameter | Description |
---|---|
callback: (uri: Uri, diagnostics: readonly Diagnostic[], collection: DiagnosticCollection) => any | Function to execute for each entry. |
thisArg?: any | The |
Returns | Description |
void |
get(uri: Uri): readonly Diagnostic[]
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 |
readonly Diagnostic[] | An immutable array of diagnostics or |
has(uri: Uri): boolean
Check if this collection contains diagnostics for a given resource.
Parameter | Description |
---|---|
uri: Uri | A resource identifier. |
Returns | Description |
boolean |
|
set(uri: Uri, diagnostics: readonly Diagnostic[]): void
Assign diagnostics for given resource. Will replace existing diagnostics for that resource.
Parameter | Description |
---|---|
uri: Uri | A resource identifier. |
diagnostics: readonly Diagnostic[] | Array of diagnostics or |
Returns | Description |
void |
set(entries: ReadonlyArray<[Uri, readonly Diagnostic[]]>): void
Replace diagnostics for multiple resources in this collection.
Note that 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: ReadonlyArray<[Uri, readonly Diagnostic[]]> | 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.
The message of this related diagnostic information.
DiagnosticSeverity
Represents the severity of diagnostics.
Enumeration Members
Something not allowed by the rules of a language or other means.
Something suspicious but allowed.
Something to inform about but not a problem.
Something to hint to a better way of doing it, like proposing a refactoring.
DiagnosticTag
Additional metadata about the type of a diagnostic.
Enumeration Members
Unused or unnecessary code.
Diagnostics with this tag are rendered faded out. The amount of fading
is controlled by the "editorUnnecessaryCode.opacity"
theme color. For
example, "editorUnnecessaryCode.opacity": "#000000c0"
will render the
code with 75% opacity. For high contrast themes, use the
"editorUnnecessaryCode.border"
theme color to underline unnecessary code
instead of fading it out.
Deprecated or obsolete code.
Diagnostics with this tag are rendered with a strike through.
Disposable
Represents a type which can release resources, such as event listening or a timer.
Static
from(...disposableLikes: Array<{dispose: () => any}>): Disposable
Combine many disposable-likes into one. You can use this method when having objects with
a dispose function which aren't instances of Disposable
.
Parameter | Description |
---|---|
...disposableLikes: Array<{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: () => any): Disposable
Creates a new disposable that calls the provided function on dispose.
Note that an asynchronous function is not awaited.
Parameter | Description |
---|---|
callOnDispose: () => any | Function that disposes something. |
Returns | Description |
Disposable |
Methods
Dispose this object.
Parameter | Description |
---|---|
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 information or a thenable that resolves to such. The lack of a result
can be signaled by returning |
DocumentDropEdit
An edit operation applied on drop.
Constructors
new DocumentDropEdit(insertText: string | SnippetString): DocumentDropEdit
Parameter | Description |
---|---|
insertText: string | SnippetString | The text or snippet to insert at the drop location. |
Returns | Description |
DocumentDropEdit |
Properties
additionalEdit?: WorkspaceEdit
An optional additional edit to apply on drop.
insertText: string | SnippetString
The text or snippet to insert at the drop location.
DocumentDropEditProvider
Provider which handles dropping of resources into a text editor.
This allows users to drag and drop resources (including resources from external apps) into the editor. While dragging
and dropping files, users can hold down shift
to drop the file into the editor instead of opening it.
Requires editor.dropIntoEditor.enabled
to be on.
Methods
provideDocumentDropEdits(document: TextDocument, position: Position, dataTransfer: DataTransfer, token: CancellationToken): ProviderResult<DocumentDropEdit>
Provide edits which inserts the content being dragged and dropped into the document.
Parameter | Description |
---|---|
document: TextDocument | The document in which the drop occurred. |
position: Position | The position in the document where the drop occurred. |
dataTransfer: DataTransfer | A DataTransfer object that holds data about what is being dragged and dropped. |
token: CancellationToken | A cancellation token. |
Returns | Description |
ProviderResult<DocumentDropEdit> | A DocumentDropEdit 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.
Example A language filter that applies to typescript files on disk
{ language: 'typescript', scheme: 'file' }
Example A language filter that applies to all package.json paths
{ language: 'json', pattern: '**/package.json' }
Properties
A language id, like typescript
.
The type of a notebook, like jupyter-notebook
. This allows
to narrow down on the type of a notebook that a cell document belongs to.
Note that setting the notebookType
-property changes how scheme
and pattern
are interpreted. When set
they are evaluated against the notebook uri, not the document uri.
Example
Match python document inside jupyter notebook that aren't stored yet (untitled
)
{ language: 'python', notebookType: 'jupyter-notebook', scheme: 'untitled' }
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.
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
A textual occurrence.
Read-access of a symbol, like reading a variable.
Write-access of a symbol, like writing to a variable.
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.
The tooltip text when you hover over this link.
If a tooltip is provided, is will be displayed in a string that includes instructions on how to
trigger the link, such as {0} (ctrl + click)
. The specific instructions vary depending on OS,
user settings, and localization.
DocumentLinkProvider<T>
The document link provider defines the contract between extensions and feature of showing links in the editor.
Methods
provideDocumentLinks(document: TextDocument, token: CancellationToken): ProviderResult<T[]>
Provide links for the given document. Note that the editor ships with a default provider that detects
http(s)
and file
links.
Parameter | Description |
---|---|
document: TextDocument | The document in which the command was invoked. |
token: CancellationToken | A cancellation token. |
Returns | Description |
ProviderResult<T[]> | An array of document links or a thenable that resolves to such. The lack of a result
can be signaled by returning |
resolveDocumentLink(link: T, token: CancellationToken): ProviderResult<T>
Given a link fill in its target. This method is called when an incomplete link is selected in the UI. Providers can implement this method and return incomplete links (without target) from the provideDocumentLinks method which often helps to improve performance.
Parameter | Description |
---|---|
link: T | The link that is to be resolved. |
token: CancellationToken | A cancellation token. |
Returns | Description |
ProviderResult<T> |
DocumentRangeFormattingEditProvider
The document formatting provider interface defines the contract between extensions and the formatting-feature.
Methods
provideDocumentRangeFormattingEdits(document: TextDocument, range: Range, options: FormattingOptions, token: CancellationToken): ProviderResult<TextEdit[]>
Provide formatting edits for a range in a document.
The given range is a hint and providers can decide to format a smaller or larger range. Often this is done by adjusting the start and end of the range to full syntax nodes.
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 |
provideDocumentRangesFormattingEdits(document: TextDocument, ranges: Range[], options: FormattingOptions, token: CancellationToken): ProviderResult<TextEdit[]>
Provide formatting edits for multiple ranges in a document.
This function is optional but allows a formatter to perform faster when formatting only modified ranges or when formatting a large number of selections.
The given ranges are hints 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. |
ranges: Range[] | The ranges 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 |
DocumentRangeSemanticTokensProvider
The document range semantic tokens provider interface defines the contract between extensions and semantic tokens.
Methods
provideDocumentRangeSemanticTokens(document: TextDocument, range: Range, token: CancellationToken): ProviderResult<SemanticTokens>
See also provideDocumentSemanticTokens.
Parameter | Description |
---|---|
document: TextDocument | |
range: Range | |
token: CancellationToken | |
Returns | Description |
ProviderResult<SemanticTokens> |
DocumentSelector
A language selector is the combination of one or many language identifiers and language filters.
Note that a document selector that is just a language identifier selects all documents, even those that are not saved on disk. Only use such selectors when a feature works without further context, e.g. without the need to resolve related 'files'.
Example
let sel: DocumentSelector = { scheme: 'file', language: 'typescript' };
DocumentSelector: DocumentFilter | string | ReadonlyArray<DocumentFilter | string>
DocumentSemanticTokensProvider
The document semantic tokens provider interface defines the contract between extensions and semantic tokens.
Events
onDidChangeSemanticTokens?: Event<void>
An optional event to signal that the semantic tokens from this provider have changed.
Methods
provideDocumentSemanticTokens(document: TextDocument, token: CancellationToken): ProviderResult<SemanticTokens>
Tokens in a file are represented as an array of integers. The position of each token is expressed relative to the token before it, because most tokens remain stable relative to each other when edits are made in a file.
In short, each token takes 5 integers to represent, so a specific token i
in the file consists of the following array indices:
- at index
5*i
-deltaLine
: token line number, relative to the previous token - at index
5*i+1
-deltaStart
: token start character, relative to the previous token (relative to 0 or the previous token's start if they are on the same line) - at index
5*i+2
-length
: the length of the token. A token cannot be multiline. - at index
5*i+3
-tokenType
: will be looked up inSemanticTokensLegend.tokenTypes
. We currently ask thattokenType
< 65536. - at index
5*i+4
-tokenModifiers
: each set bit will be looked up inSemanticTokensLegend.tokenModifiers
How to encode tokens
Here is an example for encoding a file with 3 tokens in a uint32 array:
{ line: 2, startChar: 5, length: 3, tokenType: "property", tokenModifiers: ["private", "static"] },
{ line: 2, startChar: 10, length: 4, tokenType: "type", tokenModifiers: [] },
{ line: 5, startChar: 2, length: 7, tokenType: "class", tokenModifiers: [] }
- First of all, a legend must be devised. This legend must be provided up-front and capture all possible token types. For this example, we will choose the following legend which must be passed in when registering the provider:
tokenTypes: ['property', 'type', 'class'],
tokenModifiers: ['private', 'static']
- The first transformation step is to encode
tokenType
andtokenModifiers
as integers using the legend. Token types are looked up by index, so atokenType
value of1
meanstokenTypes[1]
. Multiple token modifiers can be set by using bit flags, so atokenModifier
value of3
is first viewed as binary0b00000011
, which means[tokenModifiers[0], tokenModifiers[1]]
because bits 0 and 1 are set. Using this legend, the tokens now are:
{ line: 2, startChar: 5, length: 3, tokenType: 0, tokenModifiers: 3 },
{ line: 2, startChar: 10, length: 4, tokenType: 1, tokenModifiers: 0 },
{ line: 5, startChar: 2, length: 7, tokenType: 2, tokenModifiers: 0 }
- The next step is to represent each token relative to the previous token in the file. In this case, the second token
is on the same line as the first token, so the
startChar
of the second token is made relative to thestartChar
of the first token, so it will be10 - 5
. The third token is on a different line than the second token, so thestartChar
of the third token will not be altered:
{ deltaLine: 2, deltaStartChar: 5, length: 3, tokenType: 0, tokenModifiers: 3 },
{ deltaLine: 0, deltaStartChar: 5, length: 4, tokenType: 1, tokenModifiers: 0 },
{ deltaLine: 3, deltaStartChar: 2, length: 7, tokenType: 2, tokenModifiers: 0 }
- Finally, the last step is to inline each of the 5 fields for a token in a single array, which is a memory friendly representation:
// 1st token, 2nd token, 3rd token
[ 2,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0 ]
See also SemanticTokensBuilder for a helper to encode tokens as integers. NOTE: When doing edits, it is possible that multiple edits occur until the editor decides to invoke the semantic tokens provider. NOTE: If the provider cannot temporarily compute semantic tokens, it can indicate this by throwing an error with the message 'Busy'.
Parameter | Description |
---|---|
document: TextDocument | |
token: CancellationToken | |
Returns | Description |
ProviderResult<SemanticTokens> |
provideDocumentSemanticTokensEdits(document: TextDocument, previousResultId: string, token: CancellationToken): ProviderResult<SemanticTokens | SemanticTokensEdits>
Instead of always returning all the tokens in a file, it is possible for a DocumentSemanticTokensProvider
to implement
this method (provideDocumentSemanticTokensEdits
) and then return incremental updates to the previously provided semantic tokens.
How tokens change when the document changes
Suppose that provideDocumentSemanticTokens
has previously returned the following semantic tokens:
// 1st token, 2nd token, 3rd token
[ 2,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0 ]
Also suppose that after some edits, the new semantic tokens in a file are:
// 1st token, 2nd token, 3rd token
[ 3,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0 ]
It is possible to express these new tokens in terms of an edit applied to the previous tokens:
[ 2,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0 ] // old tokens
[ 3,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0 ] // new tokens
edit: { start: 0, deleteCount: 1, data: [3] } // replace integer at offset 0 with 3
NOTE: If the provider cannot compute SemanticTokensEdits
, it can "give up" and return all the tokens in the document again.
NOTE: All edits in SemanticTokensEdits
contain indices in the old integers array, so they all refer to the previous result state.
Parameter | Description |
---|---|
document: TextDocument | |
previousResultId: string | |
token: CancellationToken | |
Returns | Description |
ProviderResult<SemanticTokens | SemanticTokensEdits> |
DocumentSymbol
Represents programming constructs like variables, classes, interfaces etc. that appear in a document. Document symbols can be hierarchical and they have two ranges: one that encloses its definition and one that points to its most interesting range, e.g. the range of an identifier.
Constructors
new DocumentSymbol(name: string, detail: string, kind: SymbolKind, range: Range, selectionRange: Range): DocumentSymbol
Creates a new document symbol.
Parameter | Description |
---|---|
name: string | The name of the symbol. |
detail: string | Details for the symbol. |
kind: SymbolKind | The kind of the symbol. |
range: Range | The full range of the symbol. |
selectionRange: Range | The range that should be reveal. |
Returns | Description |
DocumentSymbol |
Properties
children: DocumentSymbol[]
Children of this symbol, e.g. properties of a class.
More detail for this symbol, e.g. the signature of a function.
kind: SymbolKind
The kind of this symbol.
The name of this symbol.
range: Range
The range enclosing this symbol not including leading/trailing whitespace but everything else, e.g. comments and code.
selectionRange: Range
The range that should be selected and reveal when this symbol is being picked, e.g. the name of a function. Must be contained by the range.
tags?: readonly Deprecated[]
Tags for this symbol.
DocumentSymbolProvider
The document symbol provider interface defines the contract between extensions and the go to symbol-feature.
Methods
provideDocumentSymbols(document: TextDocument, token: CancellationToken): ProviderResult<DocumentSymbol[] | 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<DocumentSymbol[] | SymbolInformation[]> | An array of document highlights or a thenable that resolves to such. The lack of a result can be
signaled by returning |
DocumentSymbolProviderMetadata
Metadata about a document symbol provider.
Properties
A human-readable string that is shown when multiple outlines trees show for one document.
EndOfLine
Represents an end of line character sequence in a document.
Enumeration Members
The line feed \n
character.
The carriage return line feed \r\n
sequence.
EnterAction
Describes what to do when pressing Enter.
Properties
Describes text to be appended after the new line and after the indentation.
indentAction: IndentAction
Describe what to do with the indentation.
Describes the number of characters to remove from the new line's indentation.
EnvironmentVariableCollection
A collection of mutations that an extension can apply to a process environment.
Properties
description: string | MarkdownString
A description for the environment variable collection, this will be used to describe the changes in the UI.
Whether the collection should be cached for the workspace and applied to the terminal across window reloads. When true the collection will be active immediately such when the window reloads. Additionally, this API will return the cached version if it exists. The collection will be invalidated when the extension is uninstalled or when the collection is cleared. Defaults to true.
Methods
append(variable: string, value: string, options?: EnvironmentVariableMutatorOptions): void
Append a value to an environment variable.
Note that an extension can only make a single change to any one variable, so this will overwrite any previous calls to replace, append or prepend.
Parameter | Description |
---|---|
variable: string | The variable to append to. |
value: string | The value to append to the variable. |
options?: EnvironmentVariableMutatorOptions | Options applied to the mutator, when no options are provided this will
default to |
Returns | Description |
void |
Clears all mutators from this collection.
Parameter | Description |
---|---|
Returns | Description |
void |
delete(variable: string): void
Deletes this collection's mutator for a variable.
Parameter | Description |
---|---|
variable: string | The variable to delete the mutator for. |
Returns | Description |
void |
forEach(callback: (variable: string, mutator: EnvironmentVariableMutator, collection: EnvironmentVariableCollection) => any, thisArg?: any): void
Iterate over each mutator in this collection.
Parameter | Description |
---|---|
callback: (variable: string, mutator: EnvironmentVariableMutator, collection: EnvironmentVariableCollection) => any | Function to execute for each entry. |
thisArg?: any | The |
Returns | Description |
void |
get(variable: string): EnvironmentVariableMutator
Gets the mutator that this collection applies to a variable, if any.
Parameter | Description |
---|---|
variable: string | The variable to get the mutator for. |
Returns | Description |
EnvironmentVariableMutator |
prepend(variable: string, value: string, options?: EnvironmentVariableMutatorOptions): void
Prepend a value to an environment variable.
Note that an extension can only make a single change to any one variable, so this will overwrite any previous calls to replace, append or prepend.
Parameter | Description |
---|---|
variable: string | The variable to prepend. |
value: string | The value to prepend to the variable. |
options?: EnvironmentVariableMutatorOptions | Options applied to the mutator, when no options are provided this will
default to |
Returns | Description |
void |
replace(variable: string, value: string, options?: EnvironmentVariableMutatorOptions): void
Replace an environment variable with a value.
Note that an extension can only make a single change to any one variable, so this will overwrite any previous calls to replace, append or prepend.
Parameter | Description |
---|---|
variable: string | The variable to replace. |
value: string | The value to replace the variable with. |
options?: EnvironmentVariableMutatorOptions | Options applied to the mutator, when no options are provided this will
default to |
Returns | Description |
void |
EnvironmentVariableMutator
A type of mutation and its value to be applied to an environment variable.
Properties
options: EnvironmentVariableMutatorOptions
Options applied to the mutator.
type: EnvironmentVariableMutatorType
The type of mutation that will occur to the variable.
The value to use for the variable.
EnvironmentVariableMutatorOptions
Options applied to the mutator.
Properties
applyAtProcessCreation?: boolean
Apply to the environment just before the process is created. Defaults to false.
applyAtShellIntegration?: boolean
Apply to the environment in the shell integration script. Note that this will not apply the mutator if shell integration is disabled or not working for some reason. Defaults to false.
EnvironmentVariableMutatorType
A type of mutation that can be applied to an environment variable.
Enumeration Members
Replace the variable's existing value.
Append to the end of the variable's existing value.
Prepend to the start of the variable's existing value.
EnvironmentVariableScope
The scope object to which the environment variable collection applies.
Properties
workspaceFolder?: WorkspaceFolder
Any specific workspace folder to get collection for.
EvaluatableExpression
An EvaluatableExpression represents an expression in a document that can be evaluated by an active debugger or runtime. The result of this evaluation is shown in a tooltip-like widget. If only a range is specified, the expression will be extracted from the underlying document. An optional expression can be used to override the extracted expression. In this case the range is still used to highlight the range in the document.
Constructors
new EvaluatableExpression(range: Range, expression?: string): EvaluatableExpression
Creates a new evaluatable expression object.
Parameter | Description |
---|---|
range: Range | The range in the underlying document from which the evaluatable expression is extracted. |
expression?: string | If specified overrides the extracted expression. |
Returns | Description |
EvaluatableExpression |
Properties
range: Range
EvaluatableExpressionProvider
The evaluatable expression provider interface defines the contract between extensions and the debug hover. In this contract the provider returns an evaluatable expression for a given position in a document and the editor evaluates this expression in the active debug session and shows the result in a debug hover.
Methods
provideEvaluatableExpression(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<EvaluatableExpression>
Provide an evaluatable expression for the given document and position. The editor will evaluate this expression in the active debug session and will show the result in the debug hover. The expression can be implicitly specified by the range in the underlying document or by explicitly returning an expression.
Parameter | Description |
---|---|
document: TextDocument | The document for which the debug hover is about to appear. |
position: Position | The line and character position in the document where the debug hover is about to appear. |
token: CancellationToken | A cancellation token. |
Returns | Description |
ProviderResult<EvaluatableExpression> | An EvaluatableExpression or a thenable that resolves to such. The lack of a result can be
signaled by returning |
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.
Example
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.
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.
Constructors
new EventEmitter<T>(): EventEmitter<T>
Parameter | Description |
---|---|
Returns | Description |
EventEmitter<T> |
Properties
event: Event<T>
The event listeners can subscribe to.
Methods
Dispose this object and free resources.
Parameter | Description |
---|---|
Returns | Description |
void |
Notify all subscribers of the event. Failure of one or more listener will not fail this function call.
Parameter | Description |
---|---|
data: T | The event object. |
Returns | Description |
void |
Extension<T>
Represents an extension.
To get an instance of an Extension
use getExtension.
Properties
The public API exported by this extension (return value of activate
).
It is an invalid action to access this field before this extension has been activated.
extensionKind: ExtensionKind
The extension kind describes if an extension runs where the UI runs
or if an extension runs where the remote extension host runs. The extension kind
is defined in the package.json
-file of extensions but can also be refined
via the remote.extensionKind
-setting. When no remote extension host exists,
the value is ExtensionKind.UI.
The absolute file path of the directory containing this extension. Shorthand notation for Extension.extensionUri.fsPath (independent of the uri scheme).
extensionUri: Uri
The uri of the directory containing the extension.
The canonical extension identifier in the form of: publisher.name
.
true
if the extension has been activated.
The parsed contents of the extension's package.json.
Methods
Activates this extension and returns its public API.
Parameter | Description |
---|---|
Returns | Description |
Thenable<T> | A promise that will resolve when this extension has been activated. |
ExtensionContext
An extension context is a collection of utilities private to an extension.
An instance of an ExtensionContext
is provided as the first
parameter to the activate
-call of an extension.
Properties
environmentVariableCollection: GlobalEnvironmentVariableCollection
Gets the extension's global environment variable collection for this workspace, enabling changes to be applied to terminal environment variables.
extension: Extension<any>
The current Extension
instance.
extensionMode: ExtensionMode
The mode the extension is running in. See ExtensionMode for possible values and scenarios.
The absolute file path of the directory containing the extension. Shorthand notation for ExtensionContext.extensionUri.fsPath (independent of the uri scheme).
extensionUri: Uri
The uri of the directory containing the extension.
globalState: Memento & {setKeysForSync}
A memento object that stores state independent of the current opened workspace.
An absolute file path in which the extension can store global state. The directory might not exist on disk and creation is up to the extension. However, the parent directory is guaranteed to be existent.
Use globalState to store key value data.
- deprecated - Use globalStorageUri instead.
globalStorageUri: Uri
The uri of a directory in which the extension can store global state. The directory might not exist on disk and creation is up to the extension. However, the parent directory is guaranteed to be existent.
Use globalState to store key value data.
See also workspace.fs for how to read and write files and folders from an uri.
languageModelAccessInformation: LanguageModelAccessInformation
An object that keeps information about how this extension can use language models.
See also LanguageModelChat.sendRequest
An absolute file path of a directory in which the extension can create log files. The directory might not exist on disk and creation is up to the extension. However, the parent directory is guaranteed to be existent.
- deprecated - Use logUri instead.
logUri: Uri
The uri of a directory in which the extension can create log files. The directory might not exist on disk and creation is up to the extension. However, the parent directory is guaranteed to be existent.
See also workspace.fs for how to read and write files and folders from an uri.
secrets: SecretStorage
A storage utility for secrets. Secrets are persisted across reloads and are independent of the current opened workspace.
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.
- deprecated - Use storageUri instead.
storageUri: Uri
The uri of a workspace specific directory in which the extension
can store private state. The directory might not exist and creation is
up to the extension. However, the parent directory is guaranteed to be existent.
The value is undefined
when no workspace nor folder has been opened.
Use workspaceState or globalState to store key value data.
See also workspace.fs for how to read and write files and folders from an uri.
subscriptions: Array<{dispose}>
An array to which disposables can be added. When this extension is deactivated the disposables will be disposed.
Note that asynchronous dispose-functions aren't awaited.
workspaceState: Memento
A memento object that stores state in the context of the currently opened workspace.
Methods
asAbsolutePath(relativePath: string): string
Get the absolute path of a resource contained in the extension.
Note that an absolute uri can be constructed via Uri.joinPath and
extensionUri, e.g. vscode.Uri.joinPath(context.extensionUri, relativePath);
Parameter | Description |
---|---|
relativePath: string | A relative path to a resource contained in the extension. |
Returns | Description |
string | The absolute path of the resource. |
ExtensionKind
In a remote window the extension kind describes if an extension runs where the UI (window) runs or if an extension runs remotely.
Enumeration Members
Extension runs where the UI runs.
Extension runs where the remote extension host runs.
ExtensionMode
The ExtensionMode is provided on the ExtensionContext
and indicates the
mode the specific extension is running in.
Enumeration Members
The extension is installed normally (for example, from the marketplace or VSIX) in the editor.
The extension is running from an --extensionDevelopmentPath
provided
when launching the editor.
The extension is running from an --extensionTestsPath
and
the extension host is running unit tests.
ExtensionTerminalOptions
Value-object describing what options a virtual process terminal should use.
Properties
color?: ThemeColor
The icon ThemeColor for the terminal.
The standard terminal.ansi*
theme keys are
recommended for the best contrast and consistency across themes.
iconPath?: Uri | ThemeIcon | {dark: Uri, light: Uri}
The icon path or ThemeIcon for the terminal.
Opt-out of the default terminal persistence on restart and reload.
This will only take effect when terminal.integrated.enablePersistentSessions
is enabled.
location?: TerminalEditorLocationOptions | TerminalSplitLocationOptions | TerminalLocation
The TerminalLocation or TerminalEditorLocationOptions or TerminalSplitLocationOptions for the terminal.
A human-readable string which will be used to represent the terminal in the UI.
pty: Pseudoterminal
An implementation of Pseudoterminal that allows an extension to control a terminal.
FileChangeEvent
The event filesystem providers must use to signal a file change.
Properties
type: FileChangeType
The type of change.
uri: Uri
The uri of the file that has changed.
FileChangeType
Enumeration of file change types.
Enumeration Members
The contents or metadata of a file have changed.
A file has been created.
A file has been deleted.
FileCoverage
Contains coverage metadata for a file.
Static
fromDetails(uri: Uri, details: readonly FileCoverageDetail[]): FileCoverage
Creates a FileCoverage instance with counts filled in from the coverage details.
Parameter | Description |
---|---|
uri: Uri | Covered file URI |
details: readonly FileCoverageDetail[] | |
Returns | Description |
FileCoverage |
Constructors
new FileCoverage(uri: Uri, statementCoverage: TestCoverageCount, branchCoverage?: TestCoverageCount, declarationCoverage?: TestCoverageCount): FileCoverage
Parameter | Description |
---|---|
uri: Uri | Covered file URI |
statementCoverage: TestCoverageCount | Statement coverage information. If the reporter does not provide statement coverage information, this can instead be used to represent line coverage. |
branchCoverage?: TestCoverageCount | Branch coverage information |
declarationCoverage?: TestCoverageCount | Declaration coverage information |
Returns | Description |
FileCoverage |
Properties
branchCoverage?: TestCoverageCount
Branch coverage information.
declarationCoverage?: TestCoverageCount
Declaration coverage information. Depending on the reporter and language, this may be types such as functions, methods, or namespaces.
statementCoverage: TestCoverageCount
Statement coverage information. If the reporter does not provide statement coverage information, this can instead be used to represent line coverage.
uri: Uri
File URI.
FileCoverageDetail
Coverage details returned from TestRunProfile.loadDetailedCoverage.
FileCoverageDetail: StatementCoverage | DeclarationCoverage
FileCreateEvent
An event that is fired after files are created.
Properties
files: readonly Uri[]
The files that got created.
FileDecoration
A file decoration represents metadata that can be rendered with a file.
Constructors
new FileDecoration(badge?: string, tooltip?: string, color?: ThemeColor): FileDecoration
Creates a new decoration.
Parameter | Description |
---|---|
badge?: string | A letter that represents the decoration. |
tooltip?: string | The tooltip of the decoration. |
color?: ThemeColor | The color of the decoration. |
Returns | Description |
FileDecoration |
Properties
A very short string that represents this decoration.
color?: ThemeColor
The color of this decoration.
A flag expressing that this decoration should be propagated to its parents.
A human-readable tooltip for this decoration.
FileDecorationProvider
The decoration provider interfaces defines the contract between extensions and file decorations.
Events
onDidChangeFileDecorations?: Event<Uri | Uri[]>
An optional event to signal that decorations for one or many files have changed.
Note that this event should be used to propagate information about children.
See also EventEmitter
Methods
provideFileDecoration(uri: Uri, token: CancellationToken): ProviderResult<FileDecoration>
Provide decorations for a given uri.
Note that this function is only called when a file gets rendered in the UI. This means a decoration from a descendent that propagates upwards must be signaled to the editor via the onDidChangeFileDecorations-event.
Parameter | Description |
---|---|
uri: Uri | The uri of the file to provide a decoration for. |
token: CancellationToken | A cancellation token. |
Returns | Description |
ProviderResult<FileDecoration> | A decoration or a thenable that resolves to such. |
FileDeleteEvent
An event that is fired after files are deleted.
Properties
files: readonly Uri[]
The files that got deleted.
FilePermission
Permissions of a file.
Enumeration Members
The file is readonly.
Note: All FileStat
from a FileSystemProvider
that is registered with
the option isReadonly: true
will be implicitly handled as if FilePermission.Readonly
is set. As a consequence, it is not possible to have a readonly file system provider
registered where some FileStat
are not readonly.
FileRenameEvent
An event that is fired after files are renamed.
Properties
files: ReadonlyArray<{newUri: Uri, oldUri: Uri}>
The files that got renamed.
FileStat
The FileStat
-type represents metadata about a file
Properties
The creation timestamp in milliseconds elapsed since January 1, 1970 00:00:00 UTC.
The modification timestamp in milliseconds elapsed since January 1, 1970 00:00:00 UTC.
Note: If the file changed, it is important to provide an updated mtime
that advanced
from the previous value. Otherwise there may be optimizations in place that will not show
the updated file contents in an editor for example.
permissions?: Readonly
The permissions of the file, e.g. whether the file is readonly.
Note: This value might be a bitmask, e.g. FilePermission.Readonly | FilePermission.Other
.
The size in bytes.
Note: If the file changed, it is important to provide an updated size
. Otherwise there
may be optimizations in place that will not show the updated file contents in an editor for
example.
type: FileType
The type of the file, e.g. is a regular file, a directory, or symbolic link to a file.
Note: This value might be a bitmask, e.g. FileType.File | FileType.SymbolicLink
.
FileSystem
The file system interface exposes the editor's built-in and contributed file system providers. It allows extensions to work with files from the local disk as well as files from remote places, like the remote extension host or ftp-servers.
Note that an instance of this interface is available as workspace.fs.
Methods
copy(source: Uri, target: Uri, options?: {overwrite: boolean}): Thenable<void>
Copy files or folders.
createDirectory(uri: Uri): Thenable<void>
Create a new directory (Note, that new files are created via write
-calls).
Note that missing directories are created automatically, e.g this call has
mkdirp
semantics.
Parameter | Description |
---|---|
uri: Uri | The uri of the new folder. |
Returns | Description |
Thenable<void> |
delete(uri: Uri, options?: {recursive: boolean, useTrash: boolean}): Thenable<void>
Delete a file.
Parameter | Description |
---|---|
uri: Uri | The resource that is to be deleted. |
options?: {recursive: boolean, useTrash: boolean} | Defines if trash can should be used and if deletion of folders is recursive |
Returns | Description |
Thenable<void> |
isWritableFileSystem(scheme: string): boolean
Check if a given file system supports writing files.
Keep in mind that just because a file system supports writing, that does not mean that writes will always succeed. There may be permissions issues or other errors that prevent writing a file.
Parameter | Description |
---|---|
scheme: string | The scheme of the filesystem, for example |
Returns | Description |
boolean |
|
readDirectory(uri: Uri): Thenable<Array<[string, FileType]>>
Retrieve all entries of a directory.
readFile(uri: Uri): Thenable<Uint8Array>
Read the entire contents of a file.
Parameter | Description |
---|---|
uri: Uri | The uri of the file. |
Returns | Description |
Thenable<Uint8Array> | An array of bytes or a thenable that resolves to such. |
rename(source: Uri, target: Uri, options?: {overwrite: boolean}): Thenable<void>
Rename a file or folder.
stat(uri: Uri): Thenable<FileStat>
Retrieve metadata about a file.
writeFile(uri: Uri, content: Uint8Array): Thenable<void>
Write data to a file, replacing its entire contents.
Parameter | Description |
---|---|
uri: Uri | The uri of the file. |
content: Uint8Array | The new content of the file. |
Returns | Description |
Thenable<void> |
FileSystemError
A type that filesystem providers should use to signal errors.
This class has factory methods for common error-cases, like FileNotFound
when
a file or folder doesn't exist, use them like so: throw vscode.FileSystemError.FileNotFound(someUri);
Static
FileExists(messageOrUri?: string | Uri): FileSystemError
Create an error to signal that a file or folder already exists, e.g. when creating but not overwriting a file.
Parameter | Description |
---|---|
messageOrUri?: string | Uri | Message or uri. |
Returns | Description |
FileSystemError |
FileIsADirectory(messageOrUri?: string | Uri): FileSystemError
Create an error to signal that a file is a folder.
Parameter | Description |
---|---|
messageOrUri?: string | Uri | Message or uri. |
Returns | Description |
FileSystemError |
FileNotADirectory(messageOrUri?: string | Uri): FileSystemError
Create an error to signal that a file is not a folder.
Parameter | Description |
---|---|
messageOrUri?: string | Uri | Message or uri. |
Returns | Description |
FileSystemError |
FileNotFound(messageOrUri?: string | Uri): FileSystemError
Create an error to signal that a file or folder wasn't found.
Parameter | Description |
---|---|
messageOrUri?: string | Uri | Message or uri. |
Returns | Description |
FileSystemError |
NoPermissions(messageOrUri?: string | Uri): FileSystemError
Create an error to signal that an operation lacks required permissions.
Parameter | Description |
---|---|
messageOrUri?: string | Uri | Message or uri. |
Returns | Description |
FileSystemError |
Unavailable(messageOrUri?: string | Uri): FileSystemError
Create an error to signal that the file system is unavailable or too busy to complete a request.
Parameter | Description |
---|---|
messageOrUri?: string | Uri | Message or uri. |
Returns | Description |
FileSystemError |
Constructors
new FileSystemError(messageOrUri?: string | Uri): FileSystemError
Creates a new filesystem error.
Parameter | Description |
---|---|
messageOrUri?: string | Uri | Message or uri. |
Returns | Description |
FileSystemError |
Properties
A code that identifies this error.
Possible values are names of errors, like FileNotFound,
or Unknown
for unspecified errors.
FileSystemProvider
The filesystem provider defines what the editor needs to read, write, discover, and to manage files and folders. It allows extensions to serve files from remote places, like ftp-servers, and to seamlessly integrate those into the editor.
- Note 1: The filesystem provider API works with uris and assumes hierarchical
paths, e.g.
foo:/my/path
is a child offoo:/my/
and a parent offoo:/my/path/deeper
. - Note 2: There is an activation event
onFileSystem:<scheme>
that fires when a file or folder is being accessed. - Note 3: The word 'file' is often used to denote all kinds of files, e.g. folders, symbolic links, and regular files.
Events
onDidChangeFile: Event<FileChangeEvent[]>
An event to signal that a resource has been created, changed, or deleted. This event should fire for resources that are being watched by clients of this provider.
Note: It is important that the metadata of the file that changed provides an
updated mtime
that advanced from the previous value in the stat and a
correct size
value. Otherwise there may be optimizations in place that will not show
the change in an editor for example.
Methods
copy(source: Uri, destination: Uri, options: {overwrite: boolean}): void | Thenable<void>
Copy files or folders. Implementing this function is optional but it will speedup the copy operation.
- throws - FileNotFound when
source
doesn't exist.
- throws - FileNotFound when parent of
destination
doesn't exist, e.g. no mkdirp-logic required.
- throws - FileExists when
destination
exists and when theoverwrite
option is nottrue
.
- throws - NoPermissions when permissions aren't sufficient.
createDirectory(uri: Uri): void | Thenable<void>
Create a new directory (Note, that new files are created via write
-calls).
- throws - FileNotFound when the parent of
uri
doesn't exist, e.g. no mkdirp-logic required.
- throws - FileExists when
uri
already exists.
- throws - NoPermissions when permissions aren't sufficient.
Parameter | Description |
---|---|
uri: Uri | The uri of the new folder. |
Returns | Description |
void | Thenable<void> |
delete(uri: Uri, options: {recursive: boolean}): void | Thenable<void>
Delete a file.
- throws - FileNotFound when
uri
doesn't exist.
- throws - NoPermissions when permissions aren't sufficient.
Parameter | Description |
---|---|
uri: Uri | The resource that is to be deleted. |
options: {recursive: boolean} | Defines if deletion of folders is recursive. |
Returns | Description |
void | Thenable<void> |
readDirectory(uri: Uri): Array<[string, FileType]> | Thenable<Array<[string, FileType]>>
Retrieve all entries of a directory.
- throws - FileNotFound when
uri
doesn't exist.
readFile(uri: Uri): Uint8Array | Thenable<Uint8Array>
Read the entire contents of a file.
- throws - FileNotFound when
uri
doesn't exist.
Parameter | Description |
---|---|
uri: Uri | The uri of the file. |
Returns | Description |
Uint8Array | Thenable<Uint8Array> | An array of bytes or a thenable that resolves to such. |
rename(oldUri: Uri, newUri: Uri, options: {overwrite: boolean}): void | Thenable<void>
Rename a file or folder.
- throws - FileNotFound when
oldUri
doesn't exist.
- throws - FileNotFound when parent of
newUri
doesn't exist, e.g. no mkdirp-logic required.
- throws - FileExists when
newUri
exists and when theoverwrite
option is nottrue
.
- throws - NoPermissions when permissions aren't sufficient.
stat(uri: Uri): FileStat | Thenable<FileStat>
Retrieve metadata about a file.
Note that the metadata for symbolic links should be the metadata of the file they refer to.
Still, the SymbolicLink-type must be used in addition to the actual type, e.g.
FileType.SymbolicLink | FileType.Directory
.
- throws - FileNotFound when
uri
doesn't exist.
watch(uri: Uri, options: {excludes: readonly string[], recursive: boolean}): Disposable
Subscribes to file change events in the file or folder denoted by uri
. For folders,
the option recursive
indicates whether subfolders, sub-subfolders, etc. should
be watched for file changes as well. With recursive: false
, only changes to the
files that are direct children of the folder should trigger an event.
The excludes
array is used to indicate paths that should be excluded from file
watching. It is typically derived from the files.watcherExclude
setting that
is configurable by the user. Each entry can be be:
- the absolute path to exclude
- a relative path to exclude (for example
build/output
) - a simple glob pattern (for example
**/build
,output/**
)
It is the file system provider's job to call onDidChangeFile for every change given these rules. No event should be emitted for files that match any of the provided excludes.
Parameter | Description |
---|---|
uri: Uri | The uri of the file or folder to be watched. |
options: {excludes: readonly string[], recursive: boolean} | Configures the watch. |
Returns | Description |
Disposable | A disposable that tells the provider to stop watching the |
writeFile(uri: Uri, content: Uint8Array, options: {create: boolean, overwrite: boolean}): void | Thenable<void>
Write data to a file, replacing its entire contents.
- throws - FileNotFound when
uri
doesn't exist andcreate
is not set.
- throws - FileNotFound when the parent of
uri
doesn't exist andcreate
is set, e.g. no mkdirp-logic required.
- throws - FileExists when
uri
already exists,create
is set butoverwrite
is not set.
- throws - NoPermissions when permissions aren't sufficient.
Parameter | Description |
---|---|
uri: Uri | The uri of the file. |
content: Uint8Array | The new content of the file. |
options: {create: boolean, overwrite: boolean} | Defines if missing files should or must be created. |
Returns | Description |
void | Thenable<void> |
FileSystemWatcher
A file system watcher notifies about changes to files and folders on disk or from other FileSystemProviders.
To get an instance of a FileSystemWatcher
use
createFileSystemWatcher.
Events
An event which fires on file/folder change.
An event which fires on file/folder creation.
An event which fires on file/folder deletion.
Properties
true if this file system watcher has been created such that it ignores change file system events.
true if this file system watcher has been created such that it ignores creation file system events.
true if this file system watcher has been created such that it ignores delete file system events.
Methods
Dispose this object.
Parameter | Description |
---|---|
Returns | Description |
any |
FileType
Enumeration of file types. The types File
and Directory
can also be
a symbolic links, in that case use FileType.File | FileType.SymbolicLink
and
FileType.Directory | FileType.SymbolicLink
.
Enumeration Members
The file type is unknown.
A regular file.
A directory.
A symbolic link to a file.
FileWillCreateEvent
An event that is fired when files are going to be created.
To make modifications to the workspace before the files are created, call the waitUntil-function with a thenable that resolves to a workspace edit.
Properties
files: readonly Uri[]
The files that are going to be created.
token: CancellationToken
A cancellation token.
Methods
waitUntil(thenable: Thenable<WorkspaceEdit>): void
Allows to pause the event and to apply a workspace edit.
Note: This function can only be called during event dispatch and not in an asynchronous manner:
workspace.onWillCreateFiles(event => {
// async, will *throw* an error
setTimeout(() => event.waitUntil(promise));
// sync, OK
event.waitUntil(promise);
});
Parameter | Description |
---|---|
thenable: Thenable<WorkspaceEdit> | A thenable that delays saving. |
Returns | Description |
void |
waitUntil(thenable: Thenable<any>): void
Allows to pause the event until the provided thenable resolves.
Note: This function can only be called during event dispatch.
Parameter | Description |
---|---|
thenable: Thenable<any> | A thenable that delays saving. |
Returns | Description |
void |
FileWillDeleteEvent
An event that is fired when files are going to be deleted.
To make modifications to the workspace before the files are deleted,
call the waitUntil
-function with a
thenable that resolves to a workspace edit.
Properties
files: readonly Uri[]
The files that are going to be deleted.
token: CancellationToken
A cancellation token.
Methods
waitUntil(thenable: Thenable<WorkspaceEdit>): void
Allows to pause the event and to apply a workspace edit.
Note: This function can only be called during event dispatch and not in an asynchronous manner:
workspace.onWillCreateFiles(event => {
// async, will *throw* an error
setTimeout(() => event.waitUntil(promise));
// sync, OK
event.waitUntil(promise);
});
Parameter | Description |
---|---|
thenable: Thenable<WorkspaceEdit> | A thenable that delays saving. |
Returns | Description |
void |
waitUntil(thenable: Thenable<any>): void
Allows to pause the event until the provided thenable resolves.
Note: This function can only be called during event dispatch.
Parameter | Description |
---|---|
thenable: Thenable<any> | A thenable that delays saving. |
Returns | Description |
void |
FileWillRenameEvent
An event that is fired when files are going to be renamed.
To make modifications to the workspace before the files are renamed,
call the waitUntil
-function with a
thenable that resolves to a workspace edit.
Properties
files: ReadonlyArray<{newUri: Uri, oldUri: Uri}>
The files that are going to be renamed.
token: CancellationToken
A cancellation token.
Methods
waitUntil(thenable: Thenable<WorkspaceEdit>): void
Allows to pause the event and to apply a workspace edit.
Note: This function can only be called during event dispatch and not in an asynchronous manner:
workspace.onWillCreateFiles(event => {
// async, will *throw* an error
setTimeout(() => event.waitUntil(promise));
// sync, OK
event.waitUntil(promise);
});
Parameter | Description |
---|---|
thenable: Thenable<WorkspaceEdit> | A thenable that delays saving. |
Returns | Description |
void |
waitUntil(thenable: Thenable<any>): void
Allows to pause the event until the provided thenable resolves.
Note: This function can only be called during event dispatch.
Parameter | Description |
---|---|
thenable: Thenable<any> | A thenable that delays saving. |
Returns | Description |
void |
FoldingContext
Folding context (for future use)
FoldingRange
A line based folding range. To be valid, start and end line must be bigger than zero and smaller than the number of lines in the document. Invalid ranges will be ignored.
Constructors
new FoldingRange(start: number, end: number, kind?: FoldingRangeKind): FoldingRange
Creates a new folding range.
Parameter | Description |
---|---|
start: number | The start line of the folded range. |
end: number | The end line of the folded range. |
kind?: FoldingRangeKind | The kind of the folding range. |
Returns | Description |
FoldingRange |
Properties
The zero-based end line of the range to fold. The folded area ends with the line's last character. To be valid, the end must be zero or larger and smaller than the number of lines in the document.
kind?: FoldingRangeKind
Describes the Kind of the folding range such as Comment or Region. The kind is used to categorize folding ranges and used by commands like 'Fold all comments'. See FoldingRangeKind for an enumeration of all kinds. If not set, the range is originated from a syntax element.
The zero-based start line of the range to fold. The folded area starts after the line's last character. To be valid, the end must be zero or larger and smaller than the number of lines in the document.
FoldingRangeKind
An enumeration of specific folding range kinds. The kind is an optional field of a FoldingRange
and is used to distinguish specific folding ranges such as ranges originated from comments. The kind is used by commands like
Fold all comments
or Fold all regions
.
If the kind is not set on the range, the range originated from a syntax element other than comments, imports or region markers.
Enumeration Members
Kind for folding range representing a comment.
Kind for folding range representing a import.
Kind for folding range representing regions originating from folding markers like #region
and #endregion
.
FoldingRangeProvider
The folding range provider interface defines the contract between extensions and Folding in the editor.
Events
onDidChangeFoldingRanges?: Event<void>
An optional event to signal that the folding ranges from this provider have changed.
Methods
provideFoldingRanges(document: TextDocument, context: FoldingContext, token: CancellationToken): ProviderResult<FoldingRange[]>
Returns a list of folding ranges or null and undefined if the provider does not want to participate or was cancelled.
Parameter | Description |
---|---|
document: TextDocument | The document in which the command was invoked. |
context: FoldingContext | Additional context information (for future use) |
token: CancellationToken | A cancellation token. |
Returns | Description |
ProviderResult<FoldingRange[]> |
FormattingOptions
Value-object describing what options formatting should use.
Properties
Prefer spaces over tabs.
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.
Parameter | Description |
---|---|
functionName: string | |
enabled?: boolean | |
condition?: string | |
hitCondition?: string | |
logMessage?: string | |
Returns | Description |
FunctionBreakpoint |
Properties
An optional expression for conditional breakpoints.
Is breakpoint enabled.
The name of the function to which this breakpoint is attached.
An optional expression that controls how many hits of the breakpoint are ignored.
The unique ID of the breakpoint.
An optional message that gets logged when this breakpoint is hit. Embedded expressions within {} are interpolated by the debug adapter.
GlobalEnvironmentVariableCollection
A collection of mutations that an extension can apply to a process environment. Applies to all scopes.
Properties
description: string | MarkdownString
A description for the environment variable collection, this will be used to describe the changes in the UI.
Whether the collection should be cached for the workspace and applied to the terminal across window reloads. When true the collection will be active immediately such when the window reloads. Additionally, this API will return the cached version if it exists. The collection will be invalidated when the extension is uninstalled or when the collection is cleared. Defaults to true.
Methods
append(variable: string, value: string, options?: EnvironmentVariableMutatorOptions): void
Append a value to an environment variable.
Note that an extension can only make a single change to any one variable, so this will overwrite any previous calls to replace, append or prepend.
Parameter | Description |
---|---|
variable: string | The variable to append to. |
value: string | The value to append to the variable. |
options?: EnvironmentVariableMutatorOptions | Options applied to the mutator, when no options are provided this will
default to |
Returns | Description |
void |
Clears all mutators from this collection.
Parameter | Description |
---|---|
Returns | Description |
void |
delete(variable: string): void
Deletes this collection's mutator for a variable.
Parameter | Description |
---|---|
variable: string | The variable to delete the mutator for. |
Returns | Description |
void |
forEach(callback: (variable: string, mutator: EnvironmentVariableMutator, collection: EnvironmentVariableCollection) => any, thisArg?: any): void
Iterate over each mutator in this collection.
Parameter | Description |
---|---|
callback: (variable: string, mutator: EnvironmentVariableMutator, collection: EnvironmentVariableCollection) => any | Function to execute for each entry. |
thisArg?: any | The |
Returns | Description |
void |
get(variable: string): EnvironmentVariableMutator
Gets the mutator that this collection applies to a variable, if any.
Parameter | Description |
---|---|
variable: string | The variable to get the mutator for. |
Returns | Description |
EnvironmentVariableMutator |
getScoped(scope: EnvironmentVariableScope): EnvironmentVariableCollection
Gets scope-specific environment variable collection for the extension. This enables alterations to terminal environment variables solely within the designated scope, and is applied in addition to (and after) the global collection.
Each object obtained through this method is isolated and does not impact objects for other scopes, including the global collection.
Namespace for authentication.