Update api proposal

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' });
 		}
 	}

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<void>;
+
+		/**
+		 * 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<T = unknown> {
 		/**
 		 * 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
 }