From 8c8d343a5a3a6cefada9dca523c277af72652100 Mon Sep 17 00:00:00 2001 From: Pine Wu Date: Fri, 22 Mar 2019 15:51:44 -0700 Subject: [PATCH] VS Code 1.24 Extension API --- types/vscode/index.d.ts | 293 +++++++++++++++++++++++++++++++++------- 1 file changed, 246 insertions(+), 47 deletions(-) diff --git a/types/vscode/index.d.ts b/types/vscode/index.d.ts index 6d38bd81bb..a27285eff8 100644 --- a/types/vscode/index.d.ts +++ b/types/vscode/index.d.ts @@ -1,4 +1,4 @@ -// Type definitions for Visual Studio Code 1.23 +// Type definitions for Visual Studio Code 1.24 // Project: https://github.com/microsoft/vscode // Definitions by: Visual Studio Code Team, Microsoft // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped @@ -10,15 +10,10 @@ *--------------------------------------------------------------------------------------------*/ /** - * Type Definition for Visual Studio Code 1.23 Extension API + * Type Definition for Visual Studio Code 1.24 Extension API * See https://code.visualstudio.com/api for more information */ -/*--------------------------------------------------------------------------------------------- - * Copyright (c) Microsoft Corporation. All rights reserved. - * Licensed under the MIT License. See License.txt in the project root for license information. - *--------------------------------------------------------------------------------------------*/ - declare module 'vscode' { /** @@ -221,7 +216,7 @@ declare module 'vscode' { /** * Get a word-range at the given position. By default words are defined by - * common separators, like space, -, _, etc. In addition, per languge custom + * common separators, like space, -, _, etc. In addition, per language custom * [word definitions](#LanguageConfiguration.wordPattern) can be defined. It * is also possible to provide a custom regular expression. * @@ -499,7 +494,7 @@ declare module 'vscode' { active: Position; /** - * Create a selection from two postions. + * Create a selection from two positions. * * @param anchor A position. * @param active A position. @@ -1054,7 +1049,7 @@ declare module 'vscode' { /** * Render options applied to the current decoration. For performance reasons, keep the - * number of decoration specific options small, and use decoration types whereever possible. + * number of decoration specific options small, and use decoration types wherever possible. */ renderOptions?: DecorationInstanceRenderOptions; } @@ -1135,7 +1130,7 @@ declare module 'vscode' { /** * Insert a [snippet](#SnippetString) and put the editor into snippet mode. "Snippet mode" - * means the editor adds placeholders and additionals cursors so that the user can complete + * means the editor adds placeholders and additional cursors so that the user can complete * or accept the snippet. * * @param snippet The snippet to insert in this edit. @@ -1326,7 +1321,7 @@ declare module 'vscode' { * [Uri.parse](#Uri.parse). * * @param skipEncoding Do not percentage-encode the result, defaults to `false`. Note that - * the `#` and `?` characters occuring in the path will always be encoded. + * the `#` and `?` characters occurring in the path will always be encoded. * @returns A string representation of this Uri. */ toString(skipEncoding?: boolean): string; @@ -1621,7 +1616,7 @@ declare module 'vscode' { * * * Note 1: A dialog can select files, folders, or both. This is not true for Windows * which enforces to open either files or folder, but *not both*. - * * Note 2: Explictly setting `canSelectFiles` and `canSelectFolders` to `false` is futile + * * Note 2: Explicitly setting `canSelectFiles` and `canSelectFolders` to `false` is futile * and the editor then silently adjusts the options to select files. */ export interface OpenDialogOptions { @@ -1871,7 +1866,7 @@ declare module 'vscode' { * to that type `T`. In addition, `null` and `undefined` can be returned - either directly or from a * thenable. * - * The snippets below are all valid implementions of the [`HoverProvider`](#HoverProvider): + * The snippets below are all valid implementations of the [`HoverProvider`](#HoverProvider): * * ```ts * let a: HoverProvider = { @@ -1901,6 +1896,9 @@ declare module 'vscode' { * Kind of a code action. * * Kinds are a hierarchical list of identifiers separated by `.`, e.g. `"refactor.extract.function"`. + * + * Code action kinds are used by VS Code for UI elements such as the refactoring context menu. Users + * can also trigger code actions with a specific kind with the `editor.action.codeAction` command. */ export class CodeActionKind { /** @@ -1909,12 +1907,16 @@ declare module 'vscode' { static readonly Empty: CodeActionKind; /** - * Base kind for quickfix actions: `quickfix` + * 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. */ static readonly QuickFix: CodeActionKind; /** * Base kind for refactoring actions: `refactor` + * + * Refactoring actions are shown in the refactoring context menu. */ static readonly Refactor: CodeActionKind; @@ -1960,12 +1962,13 @@ declare module 'vscode' { /** * Base kind for source actions: `source` * - * Source code actions apply to the entire file. + * Source code actions apply to the entire file and can be run on save + * using `editor.codeActionsOnSave`. They also are shown in `source` context menu. */ static readonly Source: CodeActionKind; /** - * Base kind for an organize imports source action: `source.organizeImports` + * Base kind for an organize imports source action: `source.organizeImports`. */ static readonly SourceOrganizeImports: CodeActionKind; @@ -2049,8 +2052,8 @@ declare module 'vscode' { /** * Creates a new code action. * - * A code action must have at least a [title](#CodeAction.title) and either [edits](#CodeAction.edit) - * or a [command](#CodeAction.command). + * A code action must have at least a [title](#CodeAction.title) and [edits](#CodeAction.edit) + * and/or a [command](#CodeAction.command). * * @param title The title of the code action. * @param kind The kind of the code action. @@ -2069,13 +2072,14 @@ declare module 'vscode' { * Provide commands for the given document and range. * * @param document The document in which the command was invoked. - * @param range The range for which the command was invoked. + * @param range The selector or range for which the command was invoked. This will always be a selection if + * there is a currently active editor. * @param context Context carrying additional information. * @param token A cancellation token. * @return An array of commands, quick fixes, or refactorings or a thenable of such. The lack of a result can be * signaled by returning `undefined`, `null`, or an empty array. */ - provideCodeActions(document: TextDocument, range: Range, context: CodeActionContext, token: CancellationToken): ProviderResult<(Command | CodeAction)[]>; + provideCodeActions(document: TextDocument, range: Range | Selection, context: CodeActionContext, token: CancellationToken): ProviderResult<(Command | CodeAction)[]>; } /** @@ -2188,7 +2192,7 @@ declare module 'vscode' { } /** - * The implemenetation provider interface defines the contract between extensions and + * The implementation provider interface defines the contract between extensions and * the go to implementation feature. */ export interface ImplementationProvider { @@ -2725,7 +2729,7 @@ declare module 'vscode' { * Builder-function that appends a tabstop (`$1`, `$2` etc) to * the [`value`](#SnippetString.value) of this snippet string. * - * @param number The number of this tabstop, defaults to an auto-incremet + * @param number The number of this tabstop, defaults to an auto-increment * value starting at 1. * @return This snippet string. */ @@ -2737,7 +2741,7 @@ declare module 'vscode' { * * @param value The value of this placeholder - either a string or a function * with which a nested snippet can be created. - * @param number The number of this tabstop, defaults to an auto-incremet + * @param number The number of this tabstop, defaults to an auto-increment * value starting at 1. * @return This snippet string. */ @@ -3008,7 +3012,7 @@ declare module 'vscode' { /** * A completion item represents a text snippet that is proposed to complete text that is being typed. * - * It is suffient to create a completion item from just a [label](#CompletionItem.label). In that + * It is sufficient to create a completion item from just a [label](#CompletionItem.label). In that * case the completion item will replace the [word](#TextDocument.getWordRangeAtPosition) * until the cursor with the given label or [insertText](#CompletionItem.insertText). Otherwise the * the given [edit](#CompletionItem.textEdit) is used. @@ -3194,7 +3198,7 @@ declare module 'vscode' { * Providers can delay the computation of the [`detail`](#CompletionItem.detail) * and [`documentation`](#CompletionItem.documentation) properties by implementing the * [`resolveCompletionItem`](#CompletionItemProvider.resolveCompletionItem)-function. However, properties that - * are needed for the inital sorting and filtering, like `sortText`, `filterText`, `insertText`, and `range`, must + * 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- @@ -3274,7 +3278,7 @@ declare module 'vscode' { /** * Given a link fill in its [target](#DocumentLink.target). This method is called when an incomplete - * link is selected in the UI. Providers can implement this method and return incomple links + * link is selected in the UI. Providers can implement this method and return incomplete links * (without target) from the [`provideDocumentLinks`](#DocumentLinkProvider.provideDocumentLinks) method which * often helps to improve performance. * @@ -3314,7 +3318,7 @@ declare module 'vscode' { * * @param red The red component. * @param green The green component. - * @param blue The bluew component. + * @param blue The blue component. * @param alpha The alpha component. */ constructor(red: number, green: number, blue: number, alpha: number); @@ -3326,7 +3330,7 @@ declare module 'vscode' { export class ColorInformation { /** - * The range in the document where this color appers. + * The range in the document where this color appears. */ range: Range; @@ -3394,7 +3398,7 @@ declare module 'vscode' { * * @param document The document in which the command was invoked. * @param token A cancellation token. - * @return An array of [color informations](#ColorInformation) or a thenable that resolves to such. The lack of a result + * @return An array of [color information](#ColorInformation) or a thenable that resolves to such. The lack of a result * can be signaled by returning `undefined`, `null`, or an empty array. */ provideDocumentColors(document: TextDocument, token: CancellationToken): ProviderResult; @@ -3411,15 +3415,21 @@ declare module 'vscode' { provideColorPresentations(color: Color, context: { document: TextDocument, range: Range }, token: CancellationToken): ProviderResult; } + /** + * A line based folding range. To be valid, start and end line must a zero or larger and smaller than the number of lines in the document. + * Invalid ranges will be ignored. + */ export class FoldingRange { /** * 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. */ start: number; /** * The zero-based end line of the range to fold. The folded area ends with the line's last character. + * To be valid, the end must be zero or larger and smaller than the number of lines in the document. */ end: number; @@ -3441,6 +3451,9 @@ declare module 'vscode' { constructor(start: number, end: number, kind?: FoldingRangeKind); } + /** + * An enumeration of all folding range kinds. The kind is used to categorize folding ranges. + */ export enum FoldingRangeKind { /** * Kind for folding range representing a comment. @@ -3462,6 +3475,10 @@ declare module 'vscode' { export interface FoldingContext { } + /** + * The folding range provider interface defines the contract between extensions and + * [Folding](https://code.visualstudio.com/docs/editor/codebasics#_folding) in the editor. + */ export interface FoldingRangeProvider { /** * Returns a list of folding ranges or null and undefined if the provider @@ -3500,7 +3517,7 @@ declare module 'vscode' { */ export interface IndentationRule { /** - * If a line matches this pattern, then all the lines after it should be unindendented once (until another rule matches). + * If a line matches this pattern, then all the lines after it should be unindented once (until another rule matches). */ decreaseIndentPattern: RegExp; /** @@ -3731,7 +3748,7 @@ declare module 'vscode' { * The *effective* value (returned by [`get`](#WorkspaceConfiguration.get)) * is computed like this: `defaultValue` overwritten by `globalValue`, * `globalValue` overwritten by `workspaceValue`. `workspaceValue` overwritten by `workspaceFolderValue`. - * Refer to [Settings Inheritence](https://code.visualstudio.com/docs/getstarted/settings) + * Refer to [Settings Inheritance](https://code.visualstudio.com/docs/getstarted/settings) * for more information. * * *Note:* The configuration name must denote a leaf in the configuration tree @@ -3756,7 +3773,7 @@ declare module 'vscode' { * has no observable effect in that workspace, but in others. Setting a workspace value * in the presence of a more specific folder value has no observable effect for the resources * under respective [folder](#workspace.workspaceFolders), but in others. Refer to - * [Settings Inheritence](https://code.visualstudio.com/docs/getstarted/settings) for more information. + * [Settings Inheritance](https://code.visualstudio.com/docs/getstarted/settings) for more information. * * *Note 2:* To remove a configuration value use `undefined`, like so: `config.update('somekey', undefined)` * @@ -4608,7 +4625,7 @@ declare module 'vscode' { /** * Defines how an argument should be quoted if it contains - * spaces or unsuppoerted characters. + * spaces or unsupported characters. */ export enum ShellQuoting { @@ -4797,7 +4814,7 @@ declare module 'vscode' { /** * A task provider allows to add tasks to the task service. - * A task provider is registered via #workspace.registerTaskProvider. + * A task provider is registered via #tasks.registerTaskProvider. */ export interface TaskProvider { /** @@ -4823,6 +4840,158 @@ declare module 'vscode' { resolveTask(task: Task, token?: CancellationToken): ProviderResult; } + /** + * An object representing an executed Task. It can be used + * to terminate a task. + * + * This interface is not intended to be implemented. + */ + export interface TaskExecution { + /** + * The task that got started. + */ + task: Task; + + /** + * Terminates the task execution. + */ + terminate(): void; + } + + /** + * An event signaling the start of a task execution. + * + * This interface is not intended to be implemented. + */ + interface TaskStartEvent { + /** + * The task item representing the task that got started. + */ + execution: TaskExecution; + } + + /** + * An event signaling the end of an executed task. + * + * This interface is not intended to be implemented. + */ + interface TaskEndEvent { + /** + * The task item representing the task that finished. + */ + execution: TaskExecution; + } + + /** + * An event signaling the start of a process execution + * triggered through a task + */ + export interface TaskProcessStartEvent { + + /** + * The task execution for which the process got started. + */ + execution: TaskExecution; + + /** + * The underlying process id. + */ + processId: number; + } + + /** + * An event signaling the end of a process execution + * triggered through a task + */ + export interface TaskProcessEndEvent { + + /** + * The task execution for which the process got started. + */ + execution: TaskExecution; + + /** + * The process's exit code. + */ + exitCode: number; + } + + export interface TaskFilter { + /** + * The task version as used in the tasks.json file. + * The string support the package.json semver notation. + */ + version?: string; + + /** + * The task type to return; + */ + type?: string; + } + + /** + * Namespace for tasks functionality. + */ + export namespace tasks { + + /** + * Register a task provider. + * + * @param type The task kind type this provider is registered for. + * @param provider A task provider. + * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + */ + export function registerTaskProvider(type: string, provider: TaskProvider): Disposable; + + /** + * Fetches all tasks available in the systems. This includes tasks + * from `tasks.json` files as well as tasks from task providers + * contributed through extensions. + * + * @param filter a filter to filter the return tasks. + */ + export function fetchTasks(filter?: TaskFilter): Thenable; + + /** + * Executes a task that is managed by VS Code. The returned + * task execution can be used to terminate the task. + * + * @param task the task to execute + */ + export function executeTask(task: Task): Thenable; + + /** + * The currently active task executions or an empty array. + * + * @readonly + */ + export let taskExecutions: ReadonlyArray; + + /** + * Fires when a task starts. + */ + export const onDidStartTask: Event; + + /** + * Fires when a task ends. + */ + export const onDidEndTask: Event; + + /** + * Fires when the underlying process has been started. + * This event will not fire for tasks that don't + * execute an underlying process. + */ + export const onDidStartTaskProcess: Event; + + /** + * Fires when the underlying process has ended. + * This event will not fire for tasks that don't + * execute an underlying process. + */ + export const onDidEndTaskProcess: Event; + } + /** * Enumeration of file types. The types `File` and `Directory` can also be * a symbolic links, in that use `FileType.File | FileType.SymbolicLink` and @@ -5064,7 +5233,7 @@ declare module 'vscode' { * * @param oldUri The existing file. * @param newUri The new location. - * @param options Defines if existing files should be overwriten. + * @param options Defines if existing files should be overwritten. * @throws [`FileNotFound`](#FileSystemError.FileNotFound) when `oldUri` doesn't exist. * @throws [`FileNotFound`](#FileSystemError.FileNotFound) when parent of `newUri` doesn't exist, e.g. no mkdirp-logic required. * @throws [`FileExists`](#FileSystemError.FileExists) when `newUri` exists and when the `overwrite` option is not `true`. @@ -5139,7 +5308,7 @@ declare module 'vscode' { /** * Post a message to the webview content. * - * Messages are only develivered if the webview is visible. + * Messages are only delivered if the webview is visible. * * @param message Body of the message. */ @@ -5235,8 +5404,9 @@ declare module 'vscode' { * method moves it to a new column. * * @param viewColumn View column to show the panel in. Shows in the current `viewColumn` if undefined. + * @param preserveFocus When `true`, the webview will not take focus. */ - reveal(viewColumn?: ViewColumn): void; + reveal(viewColumn?: ViewColumn, preserveFocus?: boolean): void; /** * Dispose of the webview panel. @@ -5745,12 +5915,12 @@ declare module 'vscode' { * * @param viewType Identifies the type of the webview panel. * @param title Title of the panel. - * @param position Editor column to show the new panel in. + * @param showOptions Where to show the webview in the editor. If preserveFocus is set, the new webview will not take focus. * @param options Settings for the new panel. * * @return New webview panel. */ - export function createWebviewPanel(viewType: string, title: string, position: ViewColumn, options?: WebviewPanelOptions & WebviewOptions): WebviewPanel; + export function createWebviewPanel(viewType: string, title: string, showOptions: ViewColumn | { viewColumn: ViewColumn, preserveFocus?: boolean }, options?: WebviewPanelOptions & WebviewOptions): WebviewPanel; /** * Set a message to the status bar. This is a short hand for the more powerful @@ -5792,7 +5962,7 @@ declare module 'vscode' { * * @param task A callback returning a promise. Progress increments can be reported with * the provided [progress](#Progress)-object. - * @return The thenable the task did rseturn. + * @return The thenable the task did return. */ export function withScmProgress(task: (progress: Progress) => Thenable): Thenable; @@ -5866,11 +6036,38 @@ declare module 'vscode' { export function createTreeView(viewId: string, options: { treeDataProvider: TreeDataProvider }): TreeView; } + /** + * The event that is fired when an element in the [TreeView](#TreeView) is expanded or collapsed + */ + export interface TreeViewExpansionEvent { + + /** + * Element that is expanded or collapsed. + */ + element: T; + + } + /** * Represents a Tree view */ export interface TreeView extends Disposable { + /** + * Event that is fired when an element is expanded + */ + readonly onDidExpandElement: Event>; + + /** + * Event that is fired when an element is collapsed + */ + readonly onDidCollapseElement: Event>; + + /** + * Currently selected elements. + */ + readonly selection: ReadonlyArray; + /** * Reveal an element. By default revealed element is selected. * @@ -6063,7 +6260,7 @@ declare module 'vscode' { Window = 10, /** - * Show progress as notifiation with an optional cancel button. Supports to show infinite and discrete progress. + * Show progress as notification with an optional cancel button. Supports to show infinite and discrete progress. */ Notification = 15 } @@ -6540,6 +6737,8 @@ declare module 'vscode' { * @param type The task kind type this provider is registered for. * @param provider A task provider. * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * + * @deprecated Use the corresponding function on the `tasks` namespace instead */ export function registerTaskProvider(type: string, provider: TaskProvider): Disposable; @@ -6619,7 +6818,7 @@ declare module 'vscode' { * 1. When the `DocumentFilter` is empty (`{}`) the result is `0` * 2. When `scheme`, `language`, or `pattern` are defined but one doesn’t match, the result is `0` * 3. Matching against `*` gives a score of `5`, matching via equality or via a glob-pattern gives a score of `10` - * 4. The result is the maximun value of each match + * 4. The result is the maximum value of each match * * Samples: * ```js @@ -6658,7 +6857,7 @@ declare module 'vscode' { * all extensions but *not yet* from the task framework. * * @param resource A resource - * @returns An arrary of [diagnostics](#Diagnostic) objects or an empty array. + * @returns An array of [diagnostics](#Diagnostic) objects or an empty array. */ export function getDiagnostics(resource: Uri): Diagnostic[]; @@ -7425,7 +7624,7 @@ declare module 'vscode' { /** - * Register a [debug configuration provider](#DebugConfigurationProvider) for a specifc debug type. + * Register a [debug configuration provider](#DebugConfigurationProvider) for a specific debug type. * More than one provider can be registered for the same type. * * @param type The debug type for which the provider is registered. @@ -7518,7 +7717,7 @@ declare module 'vscode' { /** * Thenable is a common denominator between ES6 promises, Q, jquery.Deferred, WinJS.Promise, - * and others. This API makes no assumption about what promise libary is being used which + * and others. This API makes no assumption about what promise library is being used which * enables reusing existing code without migrating to a specific promise implementation. Still, * we recommend the use of native promises which are available in this editor. */ @@ -7531,4 +7730,4 @@ interface Thenable { */ then(onfulfilled?: (value: T) => TResult | Thenable, onrejected?: (reason: any) => TResult | Thenable): Thenable; then(onfulfilled?: (value: T) => TResult | Thenable, onrejected?: (reason: any) => void): Thenable; -} \ No newline at end of file +}