From 62b8da7b17a5495df305910ce0ef8b2e4c202b1b Mon Sep 17 00:00:00 2001 From: Matt Bierner Date: Thu, 10 Sep 2020 15:12:18 -0700 Subject: [PATCH] Update api proposal --- webview-view-sample/src/extension.ts | 3 +- webview-view-sample/src/vscode.proposed.d.ts | 46 +++++++++++++++----- 2 files changed, 35 insertions(+), 14 deletions(-) diff --git a/webview-view-sample/src/extension.ts b/webview-view-sample/src/extension.ts index 7cf2c09d..657c3de8 100644 --- a/webview-view-sample/src/extension.ts +++ b/webview-view-sample/src/extension.ts @@ -60,9 +60,8 @@ class ColorsViewProvider implements vscode.WebviewViewProvider { } public addColor() { - // TODO: add call to reveal - if (this._view) { + this._view.show?.(true); // `show` is not implemented in 1.49 but is for 1.50 insiders this._view.webview.postMessage({ type: 'addColor' }); } } diff --git a/webview-view-sample/src/vscode.proposed.d.ts b/webview-view-sample/src/vscode.proposed.d.ts index c894cfb4..0a6e9834 100644 --- a/webview-view-sample/src/vscode.proposed.d.ts +++ b/webview-view-sample/src/vscode.proposed.d.ts @@ -39,13 +39,16 @@ declare module 'vscode' { */ title?: string; + /** + * Human-readable string which is rendered less prominently in the title. + */ + description?: string; + /** * Event fired when the view is disposed. * - * Views are disposed of in a few cases: - * - * - When a view is collapsed and `retainContextWhenHidden` has not been set. - * - When a view is hidden by a user. + * Views are disposed when they are explicitly hidden by a user (this happens when a user + * right clicks in a view and unchecks the webview view). * * Trying to use the view after it has been disposed throws an exception. */ @@ -59,17 +62,35 @@ declare module 'vscode' { readonly visible: boolean; /** - * Event fired when the visibility of the view changes + * Event fired when the visibility of the view changes. + * + * Actions that trigger a visibility change: + * + * - The view is collapsed or expanded. + * - The user switches to a different view group in the sidebar or panel. + * + * Note that hiding a view using the context menu instead disposes of the view and fires `onDidDispose`. */ readonly onDidChangeVisibility: Event; + + /** + * Reveal the view in the UI. + * + * If the view is collapsed, this will expand it. + * + * @param preserveFocus When `true` the view will not take focus. + */ + show(preserveFocus?: boolean): void; } interface WebviewViewResolveContext { /** * Persisted state from the webview content. * - * To save resources, VS Code normally deallocates webview views that are not visible. For example, if the user - * collapse a view or switching to another top level activity, the underlying webview document is deallocates. + * To save resources, VS Code normally deallocates webview documents (the iframe content) that are not visible. + * For example, when the user collapse a view or switches to another top level activity in the sidebar, the + * `WebviewView` itself is kept alive but the webview's underlying document is deallocated. It is recreated when + * the view becomes visible again. * * You can prevent this behavior by setting `retainContextWhenHidden` in the `WebviewOptions`. However this * increases resource usage and should be avoided wherever possible. Instead, you can use persisted state to @@ -105,7 +126,7 @@ declare module 'vscode' { * `resolveWebviewView` is called when a view first becomes visible. This may happen when the view is * first loaded or when the user hides and then shows a view again. * - * @param webviewView Webview panel to restore. The serializer should take ownership of this panel. The + * @param webviewView Webview view to restore. The serializer should take ownership of this view. The * provider must set the webview's `.html` and hook up all webview events it is interested in. * @param context Additional metadata about the view being resolved. * @param token Cancellation token indicating that the view being provided is no longer needed. @@ -131,24 +152,25 @@ declare module 'vscode' { */ readonly webviewOptions?: { /** - * Controls if the webview panel's content (iframe) is kept around even when the panel + * Controls if the webview element itself (iframe) is kept around even when the view * is no longer visible. * - * Normally the webview's html context is created when the panel becomes visible + * Normally the webview's html context is created when the view becomes visible * and destroyed when it is hidden. Extensions that have complex state * or UI can set the `retainContextWhenHidden` to make VS Code keep the webview * context around, even when the webview moves to a background tab. When a webview using * `retainContextWhenHidden` becomes hidden, its scripts and other dynamic content are suspended. - * When the panel becomes visible again, the context is automatically restored + * When the view becomes visible again, the context is automatically restored * in the exact same state it was in originally. You cannot send messages to a * hidden webview, even with `retainContextWhenHidden` enabled. * * `retainContextWhenHidden` has a high memory overhead and should only be used if - * your panel's context cannot be quickly saved and restored. + * your view's context cannot be quickly saved and restored. */ readonly retainContextWhenHidden?: boolean; }; }): Disposable; } + //#endregion }