From 4f3ee38e452377fb35fb35237776d52ffd89667d Mon Sep 17 00:00:00 2001 From: Pine Wu Date: Fri, 22 Mar 2019 16:28:52 -0700 Subject: [PATCH] VS Code 1.25 Extension API --- types/vscode/index.d.ts | 298 +++++++++++++++++++++++++++++++++++----- 1 file changed, 260 insertions(+), 38 deletions(-) diff --git a/types/vscode/index.d.ts b/types/vscode/index.d.ts index a27285eff8..89a9b6d1a8 100644 --- a/types/vscode/index.d.ts +++ b/types/vscode/index.d.ts @@ -1,4 +1,4 @@ -// Type definitions for Visual Studio Code 1.24 +// Type definitions for Visual Studio Code 1.25 // Project: https://github.com/microsoft/vscode // Definitions by: Visual Studio Code Team, Microsoft // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped @@ -10,7 +10,7 @@ *--------------------------------------------------------------------------------------------*/ /** - * Type Definition for Visual Studio Code 1.24 Extension API + * Type Definition for Visual Studio Code 1.25 Extension API * See https://code.visualstudio.com/api for more information */ @@ -587,7 +587,7 @@ declare module 'vscode' { */ export interface TextEditorViewColumnChangeEvent { /** - * The [text editor](#TextEditor) for which the options have changed. + * The [text editor](#TextEditor) for which the view column has changed. */ textEditor: TextEditor; /** @@ -763,9 +763,10 @@ declare module 'vscode' { export interface TextDocumentShowOptions { /** * An optional view column in which the [editor](#TextEditor) should be shown. - * The default is the [one](#ViewColumn.One), other values are adjusted to + * The default is the [active](#ViewColumn.Active), other values are adjusted to * be `Min(column, columnCount + 1)`, the [active](#ViewColumn.Active)-column is - * not adjusted. + * not adjusted. Use [`ViewColumn.Beside`](#ViewColumn.Beside) to open the + * editor to the side of the currently active one. */ viewColumn?: ViewColumn; @@ -1111,7 +1112,8 @@ declare module 'vscode' { /** * The column in which this editor shows. Will be `undefined` in case this - * isn't one of the three main editors, e.g an embedded editor. + * isn't one of the main editors, e.g an embedded editor, or when the editor + * column is larger than three. */ viewColumn?: ViewColumn; @@ -1163,10 +1165,10 @@ declare module 'vscode' { /** * ~~Show the text editor.~~ * - * @deprecated Use [window.showTextDocument](#window.showTextDocument) + * @deprecated Use [window.showTextDocument](#window.showTextDocument) instead. * * @param column The [column](#ViewColumn) in which to show this editor. - * instead. This method shows unexpected behavior and will be removed in the next major update. + * This method shows unexpected behavior and will be removed in the next major update. */ show(column?: ViewColumn): void; @@ -2475,6 +2477,56 @@ declare module 'vscode' { constructor(name: string, kind: SymbolKind, range: Range, uri?: Uri, containerName?: string); } + /** + * 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. + */ + export class DocumentSymbol { + + /** + * The name of this symbol. + */ + name: string; + + /** + * More detail for this symbol, e.g the signature of a function. + */ + detail: string; + + /** + * The kind of this symbol. + */ + kind: SymbolKind; + + /** + * The range enclosing this symbol not including leading/trailing whitespace but everything else, e.g comments and code. + */ + range: 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`](#DocumentSymbol.range). + */ + selectionRange: Range; + + /** + * Children of this symbol, e.g. properties of a class. + */ + children: DocumentSymbol[]; + + /** + * Creates a new document symbol. + * + * @param name The name of the symbol. + * @param detail Details for the symbol. + * @param kind The kind of the symbol. + * @param range The full range of the symbol. + * @param selectionRange The range that should be reveal. + */ + constructor(name: string, detail: string, kind: SymbolKind, range: Range, selectionRange: Range); + } + /** * The document symbol provider interface defines the contract between extensions and * the [go to symbol](https://code.visualstudio.com/docs/editor/editingevolved#_go-to-symbol)-feature. @@ -2489,7 +2541,7 @@ declare module 'vscode' { * @return An array of document highlights or a thenable that resolves to such. The lack of a result can be * signaled by returning `undefined`, `null`, or an empty array. */ - provideDocumentSymbols(document: TextDocument, token: CancellationToken): ProviderResult; + provideDocumentSymbols(document: TextDocument, token: CancellationToken): ProviderResult; } /** @@ -2499,16 +2551,17 @@ declare module 'vscode' { export interface WorkspaceSymbolProvider { /** - * Project-wide search for a symbol matching the given query string. It is up to the provider - * how to search given the query string, like substring, indexOf etc. To improve performance implementors can - * skip the [location](#SymbolInformation.location) of symbols and implement `resolveWorkspaceSymbol` to do that - * later. + * Project-wide search for a symbol matching the given query string. * * The `query`-parameter should be interpreted in a *relaxed way* as the editor will apply its own highlighting * and scoring on the results. A good rule of thumb is to match case-insensitive and to simply check that the * characters of *query* appear in their order in a candidate symbol. Don't use prefix, substring, or similar * strict matching. * + * To improve performance implementors can implement `resolveWorkspaceSymbol` and then provide symbols with partial + * [location](#SymbolInformation.location)-objects, without a `range` defined. The editor will then call + * `resolveWorkspaceSymbol` for selected symbols only, e.g. when opening a workspace symbol. + * * @param query A non-empty query string. * @param token A cancellation token. * @return An array of document highlights or a thenable that resolves to such. The lack of a result can be @@ -3064,6 +3117,13 @@ declare module 'vscode' { */ filterText?: string; + /** + * 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. + */ + preselect?: boolean; + /** * A string or snippet that should be inserted in a document when selecting * this completion. When `falsy` the [label](#CompletionItem.label) @@ -3890,6 +3950,23 @@ declare module 'vscode' { constructor(location: Location, message: string); } + /** + * Additional metadata about the type of a diagnostic. + */ + export enum DiagnosticTag { + /** + * 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"` the color to underline unnecessary code + * instead of fading it out. + */ + Unnecessary = 1, + } + /** * Represents a diagnostic, such as a compiler error or warning. Diagnostic objects * are only valid in the scope of a file. @@ -3930,6 +4007,11 @@ declare module 'vscode' { */ relatedInformation?: DiagnosticRelatedInformation[]; + /** + * Additional metadata about the diagnostic. + */ + tags?: DiagnosticTag[]; + /** * Creates a new diagnostic object. * @@ -4026,29 +4108,59 @@ declare module 'vscode' { } /** - * Denotes a column in the editor window. Columns are - * used to show editors side by side. + * Denotes a location of an editor in the window. Editors can be arranged in a grid + * and each column represents one editor location in that grid by counting the editors + * in order of their appearance. */ export enum ViewColumn { /** - * A *symbolic* editor column representing the currently - * active column. This value can be used when opening editors, but the - * *resolved* [viewColumn](#TextEditor.viewColumn)-value of editors will always - * be `One`, `Two`, `Three`, or `undefined` but never `Active`. + * A *symbolic* editor column representing the currently active column. This value + * can be used when opening editors, but the *resolved* [viewColumn](#TextEditor.viewColumn)-value + * of editors will always be `One`, `Two`, `Three`,... or `undefined` but never `Active`. */ Active = -1, /** - * The left most editor column. + * A *symbolic* editor column representing the column to the side of the active one. This value + * can be used when opening editors, but the *resolved* [viewColumn](#TextEditor.viewColumn)-value + * of editors will always be `One`, `Two`, `Three`,... or `undefined` but never `Beside`. + */ + Beside = -2, + /** + * The first editor column. */ One = 1, /** - * The center editor column. + * The second editor column. */ Two = 2, /** - * The right most editor column. + * The third editor column. */ - Three = 3 + Three = 3, + /** + * The fourth editor column. + */ + Four = 4, + /** + * The fifth editor column. + */ + Five = 5, + /** + * The sixth editor column. + */ + Six = 6, + /** + * The seventh editor column. + */ + Seven = 7, + /** + * The eighth editor column. + */ + Eight = 8, + /** + * The ninth editor column. + */ + Nine = 9 } /** @@ -4440,6 +4552,11 @@ declare module 'vscode' { * every task execution (new). Defaults to `TaskInstanceKind.Shared` */ panel?: TaskPanelKind; + + /** + * Controls whether to show the "Terminal will be reused by tasks, press any key to close it" message. + */ + showReuseMessage?: boolean; } /** @@ -5291,7 +5408,7 @@ declare module 'vscode' { /** * Content settings for the webview. */ - readonly options: WebviewOptions; + options: WebviewOptions; /** * Contents of the webview. @@ -5371,14 +5488,19 @@ declare module 'vscode' { /** * Editor position of the panel. This property is only set if the webview is in - * one of the three editor view columns. + * one of the editor view columns. * * @deprecated */ readonly viewColumn?: ViewColumn; /** - * Is the panel currently visible? + * Whether the panel is active (focused by the user). + */ + readonly active: boolean; + + /** + * Whether the panel is visible. */ readonly visible: boolean; @@ -5428,6 +5550,52 @@ declare module 'vscode' { readonly webviewPanel: WebviewPanel; } + /** + * Restore webview panels that have been persisted when vscode shuts down. + * + * There are two types of webview persistence: + * + * - Persistence within a session. + * - Persistence across sessions (across restarts of VS Code). + * + * A `WebviewPanelSerializer` is only required for the second case: persisting a webview across sessions. + * + * Persistence within a session allows a webview to save its state when it becomes hidden + * and restore its content from this state when it becomes visible again. It is powered entirely + * by the webview content itself. To save off a persisted state, call `acquireVsCodeApi().setState()` with + * any json serializable object. To restore the state again, call `getState()` + * + * ```js + * // Within the webview + * const vscode = acquireVsCodeApi(); + * + * // Get existing state + * const oldState = vscode.getState() || { value: 0 }; + * + * // Update state + * setState({ value: oldState.value + 1 }) + * ``` + * + * A `WebviewPanelSerializer` extends this persistence across restarts of VS Code. When the editor is shutdown, + * VS Code will save off the state from `setState` of all webviews that have a serializer. When the + * webview first becomes visible after the restart, this state is passed to `deserializeWebviewPanel`. + * The extension can then restore the old `WebviewPanel` from this state. + */ + interface WebviewPanelSerializer { + /** + * Restore a webview panel from its seriailzed `state`. + * + * Called when a serialized webview first becomes visible. + * + * @param webviewPanel Webview panel to restore. The serializer should take ownership of this panel. The + * serializer must restore the webview's `.html` and hook up all webview events. + * @param state Persisted state from the webview content. + * + * @return Thanble indicating that the webview has been fully restored. + */ + deserializeWebviewPanel(webviewPanel: WebviewPanel, state: any): Thenable; + } + /** * Namespace describing the environment the editor runs in. */ @@ -5613,7 +5781,7 @@ declare module 'vscode' { export const onDidChangeTextEditorSelection: Event; /** - * An [event](#Event) which fires when the selection in an editor has changed. + * An [event](#Event) which fires when the visible ranges of an editor has changed. */ export const onDidChangeTextEditorVisibleRanges: Event; @@ -5650,9 +5818,9 @@ declare module 'vscode' { * to control where the editor is being shown. Might change the [active editor](#window.activeTextEditor). * * @param document A text document to be shown. - * @param column A view column in which the [editor](#TextEditor) should be shown. The default is the [one](#ViewColumn.One), other values - * are adjusted to be `Min(column, columnCount + 1)`, the [active](#ViewColumn.Active)-column is - * not adjusted. + * @param column A view column in which the [editor](#TextEditor) should be shown. The default is the [active](#ViewColumn.Active), other values + * are adjusted to be `Min(column, columnCount + 1)`, the [active](#ViewColumn.Active)-column is not adjusted. Use [`ViewColumn.Beside`](#ViewColumn.Beside) + * to open the editor to the side of the currently active one. * @param preserveFocus When `true` the editor will not take focus. * @return A promise that resolves to an [editor](#TextEditor). */ @@ -6034,6 +6202,19 @@ declare module 'vscode' { * @returns a [TreeView](#TreeView). */ export function createTreeView(viewId: string, options: { treeDataProvider: TreeDataProvider }): TreeView; + + /** + * Registers a webview panel serializer. + * + * Extensions that support reviving should have an `"onWebviewPanel:viewType"` activation event and + * make sure that [registerWebviewPanelSerializer](#registerWebviewPanelSerializer) is called during activation. + * + * Only a single serializer may be registered at a time for a given `viewType`. + * + * @param viewType Type of the webview panel that can be serialized. + * @param serializer Webview serializer. + */ + export function registerWebviewPanelSerializer(viewType: string, serializer: WebviewPanelSerializer): Disposable; } /** @@ -6044,7 +6225,31 @@ declare module 'vscode' { /** * Element that is expanded or collapsed. */ - element: T; + readonly element: T; + + } + + /** + * The event that is fired when there is a change in [tree view's selection](#TreeView.selection) + */ + export interface TreeViewSelectionChangeEvent { + + /** + * Selected elements. + */ + readonly selection: T[]; + + } + + /** + * The event that is fired when there is a change in [tree view's visibility](#TreeView.visible) + */ + export interface TreeViewVisibilityChangeEvent { + + /** + * `true` if the [tree view](#TreeView) is visible otherwise `false`. + */ + readonly visible: boolean; } @@ -6066,19 +6271,36 @@ declare module 'vscode' { /** * Currently selected elements. */ - readonly selection: ReadonlyArray; + readonly selection: T[]; /** - * Reveal an element. By default revealed element is selected. + * Event that is fired when the [selection](#TreeView.selection) has changed + */ + readonly onDidChangeSelection: Event>; + + /** + * `true` if the [tree view](#TreeView) is visible otherwise `false`. + */ + readonly visible: boolean; + + /** + * Event that is fired when [visibility](TreeView.visible) has changed + */ + readonly onDidChangeVisibility: Event; + + /** + * Reveals the given element in the tree view. + * If the tree view is not visible then the tree view is shown and element is revealed. * + * By default revealed element is selected and not focused. * In order to not to select, set the option `select` to `false`. + * In order to focus, set the option `focus` to `true`. * * **NOTE:** [TreeDataProvider](#TreeDataProvider) is required to implement [getParent](#TreeDataProvider.getParent) method to access this API. */ - reveal(element: T, options?: { select?: boolean }): Thenable; + reveal(element: T, options?: { select?: boolean, focus?: boolean }): Thenable; } - /** * A data provider that provides tree data */ @@ -6152,7 +6374,7 @@ declare module 'vscode' { tooltip?: string | undefined; /** - * The [command](#Command) which should be run when the tree item is selected. + * The [command](#Command) that should be executed when the tree item is selected. */ command?: Command; @@ -6753,7 +6975,7 @@ declare module 'vscode' { * @param options Immutable metadata about the provider. * @return A [disposable](#Disposable) that unregisters this provider when being disposed. */ - export function registerFileSystemProvider(scheme: string, provider: FileSystemProvider, options: { isCaseSensitive?: boolean }): Disposable; + export function registerFileSystemProvider(scheme: string, provider: FileSystemProvider, options?: { isCaseSensitive?: boolean, isReadonly?: boolean }): Disposable; } /** @@ -7660,7 +7882,7 @@ declare module 'vscode' { /** * Namespace for dealing with installed extensions. Extensions are represented - * by an [extension](#Extension)-interface which allows to reflect on them. + * by an [extension](#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.