Skip to content

Commit

Permalink
Promote webview Api to stable
Browse files Browse the repository at this point in the history 
Fixes microsoft#43713
Fixes microsoft#28263
  • Loading branch information
@mjbvz
mjbvz committed Apr 18, 2018
1 parent 039a1d4 commit bcc3ecc
Show file tree
Hide file tree
Showing 3 changed files with 180 additions and 180 deletions.
176 changes: 176 additions & 0 deletions src/vs/vscode.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4820,6 +4820,170 @@ declare module 'vscode' {
resolveTask(task: Task, token?: CancellationToken): ProviderResult<Task>;
}

/**
* Content settings for a webview.
*/
export interface WebviewOptions {
/**
* Should scripts be enabled in the webview content?
*
* Defaults to false (scripts-disabled).
*/
readonly enableScripts?: boolean;

/**
* Should command uris be enabled in webview content?
*
* Defaults to false.
*/
readonly enableCommandUris?: boolean;

/**
* Root paths from which the webview can load local (filesystem) resources using the `vscode-resource:` scheme.
*
* Default to the root folders of the current workspace plus the extension's install directory.
*
* Pass in an empty array to disallow access to any local resources.
*/
readonly localResourceRoots?: ReadonlyArray<Uri>;
}

/**
* A webview displays html content, like an iframe.
*/
export interface Webview {
/**
* Content settings for the webview.
*/
readonly options: WebviewOptions;

/**
* Title of the webview shown in UI.
*/
title: string;

/**
* Contents of the webview.
*
* Should be a complete html document.
*/
html: string;

/**
* Fired when the webview content posts a message.
*/
readonly onDidReceiveMessage: Event<any>;

/**
* Post a message to the webview content.
*
* Messages are only develivered if the webview is visible.
*
* @param message Body of the message.
*/
postMessage(message: any): Thenable<boolean>;
}

/**
* Content settings for a webview panel.
*/
export interface WebviewPanelOptions {
/**
* Should the find widget be enabled in the panel?
*
* Defaults to false.
*/
readonly enableFindWidget?: boolean;

/**
* Should the webview panel's content (iframe) be kept around even when the panel
* is no longer visible?
*
* Normally the webview panel's html context is created when the panel becomes visible
* and destroyed when it is 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
* the panel becomes visible again, the context is automatically restored
* in the exact same state it was in originally.
*
* `retainContextWhenHidden` has a high memory overhead and should only be used if
* your panel's context cannot be quickly saved and restored.
*/
readonly retainContextWhenHidden?: boolean;
}

/**
* A panel that contains a webview.
*/
interface WebviewPanel {
/**
* Type of the webview panel, such as `'markdown.preview'`.
*/
readonly viewType: string;

/**
* Webview belonging to the panel.
*/
readonly webview: Webview;

/**
* Content settings for the webview panel.
*/
readonly options: WebviewPanelOptions;

/**
* Editor position of the panel.
*/
readonly position?: ViewColumn;

/**
* Is the panel currently visible?
*/
readonly visible: boolean;

/**
* Fired when the panel's view state changes.
*/
readonly onDidChangeViewState: Event<WebviewPanelOnDidChangeViewStateEvent>;

/**
* Fired when the panel is disposed.
*
* This may be because the user closed the panel or because `.dispose()` was
* called on it.
*
* Trying to use the panel after it has been disposed throws an exception.
*/
readonly onDidDispose: Event<void>;

/**
* Show the webview panel in a given column.
*
* A webview panel may only show in a single column at a time. If it is already showing, this
* method moves it to a new column.
*/
reveal(viewColumn: ViewColumn): void;

/**
* Dispose of the webview panel.
*
* This closes the panel if it showing and disposes of the resources owned by the webview.
* Webview panels are also disposed when the user closes the webview panel. Both cases
* fire the `onDispose` event.
*/
dispose(): any;
}

/**
* Event fired when a webview panel's view state changes.
*/
export interface WebviewPanelOnDidChangeViewStateEvent {
/**
* Webview panel whose view state changed.
*/
readonly webviewPanel: WebviewPanel;
}

/**
* Namespace describing the environment the editor runs in.
*/
Expand Down Expand Up @@ -5302,6 +5466,18 @@ declare module 'vscode' {
*/
export function createOutputChannel(name: string): OutputChannel;

/**
* Create and show a new webview panel.
*
* @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 options Settings for the new panel.
*
* @return New webview panel.
*/
export function createWebviewPanel(viewType: string, title: string, position: ViewColumn, options: WebviewPanelOptions & WebviewOptions): WebviewPanel;

/**
* Set a message to the status bar. This is a short hand for the more powerful
* status bar [items](#window.createStatusBarItem).
Expand Down
178 changes: 1 addition & 177 deletions src/vs/vscode.proposed.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -469,171 +469,7 @@ declare module 'vscode' {

//#endregion

//#region Matt: WebView

/**
* Content settings for a webview.
*/
export interface WebviewOptions {
/**
* Should scripts be enabled in the webview content?
*
* Defaults to false (scripts-disabled).
*/
readonly enableScripts?: boolean;

/**
* Should command uris be enabled in webview content?
*
* Defaults to false.
*/
readonly enableCommandUris?: boolean;

/**
* Root paths from which the webview can load local (filesystem) resources using the `vscode-resource:` scheme.
*
* Default to the root folders of the current workspace plus the extension's install directory.
*
* Pass in an empty array to disallow access to any local resources.
*/
readonly localResourceRoots?: ReadonlyArray<Uri>;
}

/**
* A webview displays html content, like an iframe.
*/
export interface Webview {
/**
* Content settings for the webview.
*/
readonly options: WebviewOptions;

/**
* Title of the webview shown in UI.
*/
title: string;

/**
* Contents of the webview.
*
* Should be a complete html document.
*/
html: string;

/**
* Fired when the webview content posts a message.
*/
readonly onDidReceiveMessage: Event<any>;

/**
* Post a message to the webview content.
*
* Messages are only develivered if the webview is visible.
*
* @param message Body of the message.
*/
postMessage(message: any): Thenable<boolean>;
}

/**
* Content settings for a webview panel.
*/
export interface WebviewPanelOptions {
/**
* Should the find widget be enabled in the panel?
*
* Defaults to false.
*/
readonly enableFindWidget?: boolean;

/**
* Should the webview panel's content (iframe) be kept around even when the panel
* is no longer visible?
*
* Normally the webview panel's html context is created when the panel becomes visible
* and destroyed when it is 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
* the panel becomes visible again, the context is automatically restored
* in the exact same state it was in originally.
*
* `retainContextWhenHidden` has a high memory overhead and should only be used if
* your panel's context cannot be quickly saved and restored.
*/
readonly retainContextWhenHidden?: boolean;
}

/**
* A panel that contains a webview.
*/
interface WebviewPanel {
/**
* Type of the webview panel, such as `'markdown.preview'`.
*/
readonly viewType: string;

/**
* Webview belonging to the panel.
*/
readonly webview: Webview;

/**
* Content settings for the webview panel.
*/
readonly options: WebviewPanelOptions;

/**
* Editor position of the panel.
*/
readonly position?: ViewColumn;

/**
* Is the panel current visible?
*/
readonly visible: boolean;

/**
* Fired when the panel's view state changes.
*/
readonly onDidChangeViewState: Event<WebviewPanelOnDidChangeViewStateEvent>;

/**
* Fired when the panel is disposed.
*
* This may be because the user closed the panel or because `.dispose()` was
* called on it.
*
* Trying to use the panel after it has been disposed throws an exception.
*/
readonly onDidDispose: Event<void>;

/**
* Show the webview panel in a given column.
*
* A webview panel may only show in a single column at a time. If it is already showing, this
* method moves it to a new column.
*/
reveal(viewColumn: ViewColumn): void;

/**
* Dispose of the webview panel.
*
* This closes the panel if it showing and disposes of the resources owned by the webview.
* Webview panels are also disposed when the user closes the webview panel. Both cases
* fire the `onDispose` event.
*/
dispose(): any;
}

/**
* Event fired when a webview panel's view state changes.
*/
export interface WebviewPanelOnDidChangeViewStateEvent {
/**
* Webview panel whose view state changed.
*/
readonly webviewPanel: WebviewPanel;
}
//#region Matt: WebView Serializer

/**
* Save and restore webview panels that have been persisted when vscode shuts down.
Expand Down Expand Up @@ -665,18 +501,6 @@ declare module 'vscode' {
}

namespace window {
/**
* Create and show a new webview panel.
*
* @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 options Settings for the new webview panel.
*
* @return New webview panel.
*/
export function createWebviewPanel(viewType: string, title: string, position: ViewColumn, options: WebviewPanelOptions & WebviewOptions): WebviewPanel;

/**
* Registers a webview panel serializer.
*
Expand Down
Loading

0 comments on commit bcc3ecc

Please sign in to comment.