Files
archived-tauri-docs/docs/api/js/classes/window.WebviewWindow.md
2022-07-15 12:00:05 +02:00

36 KiB

@tauri-apps/api / window / WebviewWindow

Class: WebviewWindow

window.WebviewWindow

Create new webview windows and get a handle to existing ones.

Windows are identified by a label a unique identifier that can be used to reference it later. It may only contain alphanumeric characters a-zA-Z plus the following special characters -, /, : and _.

Example

// loading embedded asset:
const webview = new WebviewWindow('theUniqueLabel', {
  url: 'path/to/page.html'
});
// alternatively, load a remote URL:
const webview = new WebviewWindow('theUniqueLabel', {
  url: 'https://github.com/tauri-apps/tauri'
});

webview.once('tauri://created', function () {
 // webview window successfully created
});
webview.once('tauri://error', function (e) {
 // an error happened creating the webview window
});

// emit an event to the backend
await webview.emit("some event", "data");
// listen to an event from the backend
const unlisten = await webview.listen("event name", e => {});
unlisten();

Hierarchy

Constructors

constructor

new WebviewWindow(label, options?)

Creates a new WebviewWindow.

Example

import { WebviewWindow } from '@tauri-apps/api/window';
const webview = new WebviewWindow('my-label', {
  url: 'https://github.com/tauri-apps/tauri'
});
webview.once('tauri://created', function () {
 // webview window successfully created
});
webview.once('tauri://error', function (e) {
 // an error happened creating the webview window
});

Parameters

Name Type Description
label string The unique webview window label. Must be alphanumeric: a-zA-Z-/:_.
options WindowOptions -

Overrides

WindowManager.constructor

Properties

label

label: string

The window label. It is a unique identifier for the window, can be used to reference it later.

Inherited from

WindowManager.label

Defined in

window.ts:280


listeners

listeners: Object

Local event listeners.

Index signature

▪ [key: string]: EventCallback<any>[]

Inherited from

WindowManager.listeners

Defined in

window.ts:282

Methods

_handleTauriEvent

_handleTauriEvent<T>(event, handler): boolean

Type parameters

Name
T

Parameters

Name Type
event string
handler EventCallback<T>

Returns

boolean

Inherited from

WindowManager._handleTauriEvent


center

center(): Promise<void>

Centers the window.

Example

import { appWindow } from '@tauri-apps/api/window';
await appWindow.center();

Returns

Promise<void>

A promise indicating the success or failure of the operation.

Inherited from

WindowManager.center


close

close(): Promise<void>

Closes the window.

Example

import { appWindow } from '@tauri-apps/api/window';
await appWindow.close();

Returns

Promise<void>

A promise indicating the success or failure of the operation.

Inherited from

WindowManager.close


emit

emit(event, payload?): Promise<void>

Emits an event to the backend, tied to the webview window.

Example

import { appWindow } from '@tauri-apps/api/window';
await appWindow.emit('window-loaded', { loggedIn: true, token: 'authToken' });

Parameters

Name Type Description
event string Event name. Must include only alphanumeric characters, -, /, : and _.
payload? unknown Event payload.

Returns

Promise<void>

Inherited from

WindowManager.emit


hide

hide(): Promise<void>

Sets the window visibility to false.

Example

import { appWindow } from '@tauri-apps/api/window';
await appWindow.hide();

Returns

Promise<void>

A promise indicating the success or failure of the operation.

Inherited from

WindowManager.hide


innerPosition

innerPosition(): Promise<PhysicalPosition>

The position of the top-left hand corner of the window's client area relative to the top-left hand corner of the desktop.

Example

import { appWindow } from '@tauri-apps/api/window';
const position = await appWindow.innerPosition();

Returns

Promise<PhysicalPosition>

The window's inner position.

Inherited from

WindowManager.innerPosition


innerSize

innerSize(): Promise<PhysicalSize>

The physical size of the window's client area. The client area is the content of the window, excluding the title bar and borders.

Example

import { appWindow } from '@tauri-apps/api/window';
const size = await appWindow.innerSize();

Returns

Promise<PhysicalSize>

The window's inner size.

Inherited from

WindowManager.innerSize


isDecorated

isDecorated(): Promise<boolean>

Gets the window's current decorated state.

Example

import { appWindow } from '@tauri-apps/api/window';
const decorated = await appWindow.isDecorated();

Returns

Promise<boolean>

Whether the window is decorated or not.

Inherited from

WindowManager.isDecorated


isFullscreen

isFullscreen(): Promise<boolean>

Gets the window's current fullscreen state.

Example

import { appWindow } from '@tauri-apps/api/window';
const fullscreen = await appWindow.isFullscreen();

Returns

Promise<boolean>

Whether the window is in fullscreen mode or not.

Inherited from

WindowManager.isFullscreen


isMaximized

isMaximized(): Promise<boolean>

Gets the window's current maximized state.

Example

import { appWindow } from '@tauri-apps/api/window';
const maximized = await appWindow.isMaximized();

Returns

Promise<boolean>

Whether the window is maximized or not.

Inherited from

WindowManager.isMaximized


isResizable

isResizable(): Promise<boolean>

Gets the window's current resizable state.

Example

import { appWindow } from '@tauri-apps/api/window';
const resizable = await appWindow.isResizable();

Returns

Promise<boolean>

Whether the window is resizable or not.

Inherited from

WindowManager.isResizable


isVisible

isVisible(): Promise<boolean>

Gets the window's current visible state.

Example

import { appWindow } from '@tauri-apps/api/window';
const visible = await appWindow.isVisible();

Returns

Promise<boolean>

Whether the window is visible or not.

Inherited from

WindowManager.isVisible


listen

listen<T>(event, handler): Promise<UnlistenFn>

Listen to an event emitted by the backend that is tied to the webview window.

Example

import { appWindow } from '@tauri-apps/api/window';
const unlisten = await appWindow.listen<string>('state-changed', (event) => {
  console.log(`Got error: ${payload}`);
});

// you need to call unlisten if your handler goes out of scope e.g. the component is unmounted
unlisten();

Type parameters

Name
T

Parameters

Name Type Description
event string Event name. Must include only alphanumeric characters, -, /, : and _.
handler EventCallback<T> Event handler.

Returns

Promise<UnlistenFn>

A promise resolving to a function to unlisten to the event. Note that removing the listener is required if your listener goes out of scope e.g. the component is unmounted.

Inherited from

WindowManager.listen


maximize

maximize(): Promise<void>

Maximizes the window.

Example

import { appWindow } from '@tauri-apps/api/window';
await appWindow.maximize();

Returns

Promise<void>

A promise indicating the success or failure of the operation.

Inherited from

WindowManager.maximize


minimize

minimize(): Promise<void>

Minimizes the window.

Example

import { appWindow } from '@tauri-apps/api/window';
await appWindow.minimize();

Returns

Promise<void>

A promise indicating the success or failure of the operation.

Inherited from

WindowManager.minimize


onCloseRequested

onCloseRequested(handler): Promise<UnlistenFn>

Listen to window close requested. Emitted when the user requests to closes the window.

Example

import { appWindow } from "@tauri-apps/api/window";
import { confirm } from '@tauri-apps/api/dialog';
const unlisten = await appWindow.onCloseRequested(async (event) => {
  const confirmed = await confirm('Are you sure?');
  if (!confirmed) {
    // user did not confirm closing the window; let's prevent it
    event.preventDefault();
  }
});

// you need to call unlisten if your handler goes out of scope e.g. the component is unmounted
unlisten();

Parameters

Name Type
handler (event: CloseRequestedEvent) => void

Returns

Promise<UnlistenFn>

A promise resolving to a function to unlisten to the event. Note that removing the listener is required if your listener goes out of scope e.g. the component is unmounted.

Inherited from

WindowManager.onCloseRequested


onFileDropEvent

onFileDropEvent(handler): Promise<UnlistenFn>

Listen to a file drop event. The listener is triggered when the user hovers the selected files on the window, drops the files or cancels the operation.

Example

import { appWindow } from "@tauri-apps/api/window";
const unlisten = await appWindow.onFileDropEvent((event) => {
 if (event.payload.type === 'hover') {
   console.log('User hovering', event.payload.paths);
 } else if (event.payload.type === 'drop') {
   console.log('User dropped', event.payload.paths);
 } else {
   console.log('File drop cancelled');
 }
});

// you need to call unlisten if your handler goes out of scope e.g. the component is unmounted
unlisten();

Parameters

Name Type
handler EventCallback<FileDropEvent>

Returns

Promise<UnlistenFn>

A promise resolving to a function to unlisten to the event. Note that removing the listener is required if your listener goes out of scope e.g. the component is unmounted.

Inherited from

WindowManager.onFileDropEvent


onFocusChanged

onFocusChanged(handler): Promise<UnlistenFn>

Listen to window focus change.

Example

import { appWindow } from "@tauri-apps/api/window";
const unlisten = await appWindow.onFocusChanged(({ payload: focused }) => {
 console.log('Focus changed, window is focused? ' + focused);
});

// you need to call unlisten if your handler goes out of scope e.g. the component is unmounted
unlisten();

Parameters

Name Type
handler EventCallback<boolean>

Returns

Promise<UnlistenFn>

A promise resolving to a function to unlisten to the event. Note that removing the listener is required if your listener goes out of scope e.g. the component is unmounted.

Inherited from

WindowManager.onFocusChanged


onMenuClicked

onMenuClicked(handler): Promise<UnlistenFn>

Listen to the window menu item click. The payload is the item id.

Example

import { appWindow } from "@tauri-apps/api/window";
const unlisten = await appWindow.onMenuClicked(({ payload: menuId }) => {
 console.log('Menu clicked: ' + menuId);
});

// you need to call unlisten if your handler goes out of scope e.g. the component is unmounted
unlisten();

Parameters

Name Type
handler EventCallback<string>

Returns

Promise<UnlistenFn>

A promise resolving to a function to unlisten to the event. Note that removing the listener is required if your listener goes out of scope e.g. the component is unmounted.

Inherited from

WindowManager.onMenuClicked


onMoved

onMoved(handler): Promise<UnlistenFn>

Listen to window move.

Example

import { appWindow } from "@tauri-apps/api/window";
const unlisten = await appWindow.onMoved(({ payload: position }) => {
 console.log('Window moved', position);
});

// you need to call unlisten if your handler goes out of scope e.g. the component is unmounted
unlisten();

Parameters

Name Type
handler EventCallback<PhysicalPosition>

Returns

Promise<UnlistenFn>

A promise resolving to a function to unlisten to the event. Note that removing the listener is required if your listener goes out of scope e.g. the component is unmounted.

Inherited from

WindowManager.onMoved


onResized

onResized(handler): Promise<UnlistenFn>

Listen to window resize.

Example

import { appWindow } from "@tauri-apps/api/window";
const unlisten = await appWindow.onResized(({ payload: size }) => {
 console.log('Window resized', size);
});

// you need to call unlisten if your handler goes out of scope e.g. the component is unmounted
unlisten();

Parameters

Name Type
handler EventCallback<PhysicalSize>

Returns

Promise<UnlistenFn>

A promise resolving to a function to unlisten to the event. Note that removing the listener is required if your listener goes out of scope e.g. the component is unmounted.

Inherited from

WindowManager.onResized


onScaleChanged

onScaleChanged(handler): Promise<UnlistenFn>

Listen to window scale change. Emitted when the window's scale factor has changed. The following user actions can cause DPI changes:

  • Changing the display's resolution.
  • Changing the display's scale factor (e.g. in Control Panel on Windows).
  • Moving the window to a display with a different scale factor.

Example

import { appWindow } from "@tauri-apps/api/window";
const unlisten = await appWindow.onScaleChanged(({ payload }) => {
 console.log('Scale changed', payload.scaleFactor, payload.size);
});

// you need to call unlisten if your handler goes out of scope e.g. the component is unmounted
unlisten();

Parameters

Name Type
handler EventCallback<ScaleFactorChanged>

Returns

Promise<UnlistenFn>

A promise resolving to a function to unlisten to the event. Note that removing the listener is required if your listener goes out of scope e.g. the component is unmounted.

Inherited from

WindowManager.onScaleChanged


onThemeChanged

onThemeChanged(handler): Promise<UnlistenFn>

Listen to the system theme change.

Example

import { appWindow } from "@tauri-apps/api/window";
const unlisten = await appWindow.onThemeChanged(({ payload: theme }) => {
 console.log('New theme: ' + theme);
});

// you need to call unlisten if your handler goes out of scope e.g. the component is unmounted
unlisten();

Parameters

Name Type
handler EventCallback<Theme>

Returns

Promise<UnlistenFn>

A promise resolving to a function to unlisten to the event. Note that removing the listener is required if your listener goes out of scope e.g. the component is unmounted.

Inherited from

WindowManager.onThemeChanged


once

once<T>(event, handler): Promise<UnlistenFn>

Listen to an one-off event emitted by the backend that is tied to the webview window.

Example

import { appWindow } from '@tauri-apps/api/window';
const unlisten = await appWindow.once<null>('initialized', (event) => {
  console.log(`Window initialized!`);
});

// you need to call unlisten if your handler goes out of scope e.g. the component is unmounted
unlisten();

Type parameters

Name
T

Parameters

Name Type Description
event string Event name. Must include only alphanumeric characters, -, /, : and _.
handler EventCallback<T> Event handler.

Returns

Promise<UnlistenFn>

A promise resolving to a function to unlisten to the event. Note that removing the listener is required if your listener goes out of scope e.g. the component is unmounted.

Inherited from

WindowManager.once


outerPosition

outerPosition(): Promise<PhysicalPosition>

The position of the top-left hand corner of the window relative to the top-left hand corner of the desktop.

Example

import { appWindow } from '@tauri-apps/api/window';
const position = await appWindow.outerPosition();

Returns

Promise<PhysicalPosition>

The window's outer position.

Inherited from

WindowManager.outerPosition


outerSize

outerSize(): Promise<PhysicalSize>

The physical size of the entire window. These dimensions include the title bar and borders. If you don't want that (and you usually don't), use inner_size instead.

Example

import { appWindow } from '@tauri-apps/api/window';
const size = await appWindow.outerSize();

Returns

Promise<PhysicalSize>

The window's outer size.

Inherited from

WindowManager.outerSize


requestUserAttention

requestUserAttention(requestType): Promise<void>

Requests user attention to the window, this has no effect if the application is already focused. How requesting for user attention manifests is platform dependent, see UserAttentionType for details.

Providing null will unset the request for user attention. Unsetting the request for user attention might not be done automatically by the WM when the window receives input.

Platform-specific

  • macOS: null has no effect.
  • Linux: Urgency levels have the same effect.

Example

import { appWindow } from '@tauri-apps/api/window';
await appWindow.requestUserAttention();

Parameters

Name Type
requestType null | UserAttentionType

Returns

Promise<void>

A promise indicating the success or failure of the operation.

Inherited from

WindowManager.requestUserAttention


scaleFactor

scaleFactor(): Promise<number>

The scale factor that can be used to map physical pixels to logical pixels.

Example

import { appWindow } from '@tauri-apps/api/window';
const factor = await appWindow.scaleFactor();

Returns

Promise<number>

The window's monitor scale factor.

Inherited from

WindowManager.scaleFactor


setAlwaysOnTop

setAlwaysOnTop(alwaysOnTop): Promise<void>

Whether the window should always be on top of other windows.

Example

import { appWindow } from '@tauri-apps/api/window';
await appWindow.setAlwaysOnTop(true);

Parameters

Name Type Description
alwaysOnTop boolean Whether the window should always be on top of other windows or not.

Returns

Promise<void>

A promise indicating the success or failure of the operation.

Inherited from

WindowManager.setAlwaysOnTop


setCursorGrab

setCursorGrab(grab): Promise<void>

Grabs the cursor, preventing it from leaving the window.

There's no guarantee that the cursor will be hidden. You should hide it by yourself if you want so.

Platform-specific

  • Linux: Unsupported.
  • macOS: This locks the cursor in a fixed location, which looks visually awkward.

Example

import { appWindow } from '@tauri-apps/api/window';
await appWindow.setCursorGrab(true);

Parameters

Name Type Description
grab boolean true to grab the cursor icon, false to release it.

Returns

Promise<void>

A promise indicating the success or failure of the operation.

Inherited from

WindowManager.setCursorGrab


setCursorIcon

setCursorIcon(icon): Promise<void>

Modifies the cursor icon of the window.

Example

import { appWindow } from '@tauri-apps/api/window';
await appWindow.setCursorIcon('help');

Parameters

Name Type Description
icon CursorIcon The new cursor icon.

Returns

Promise<void>

A promise indicating the success or failure of the operation.

Inherited from

WindowManager.setCursorIcon


setCursorPosition

setCursorPosition(position): Promise<void>

Changes the position of the cursor in window coordinates.

Example

import { appWindow, LogicalPosition } from '@tauri-apps/api/window';
await appWindow.setCursorPosition(new LogicalPosition(600, 300));

Parameters

Name Type Description
position PhysicalPosition | LogicalPosition The new cursor position.

Returns

Promise<void>

A promise indicating the success or failure of the operation.

Inherited from

WindowManager.setCursorPosition


setCursorVisible

setCursorVisible(visible): Promise<void>

Modifies the cursor's visibility.

Platform-specific

  • Windows: The cursor is only hidden within the confines of the window.
  • macOS: The cursor is hidden as long as the window has input focus, even if the cursor is outside of the window.

Example

import { appWindow } from '@tauri-apps/api/window';
await appWindow.setCursorVisible(false);

Parameters

Name Type Description
visible boolean If false, this will hide the cursor. If true, this will show the cursor.

Returns

Promise<void>

A promise indicating the success or failure of the operation.

Inherited from

WindowManager.setCursorVisible


setDecorations

setDecorations(decorations): Promise<void>

Whether the window should have borders and bars.

Example

import { appWindow } from '@tauri-apps/api/window';
await appWindow.setDecorations(false);

Parameters

Name Type Description
decorations boolean Whether the window should have borders and bars.

Returns

Promise<void>

A promise indicating the success or failure of the operation.

Inherited from

WindowManager.setDecorations


setFocus

setFocus(): Promise<void>

Bring the window to front and focus.

Example

import { appWindow } from '@tauri-apps/api/window';
await appWindow.setFocus();

Returns

Promise<void>

A promise indicating the success or failure of the operation.

Inherited from

WindowManager.setFocus


setFullscreen

setFullscreen(fullscreen): Promise<void>

Sets the window fullscreen state.

Example

import { appWindow } from '@tauri-apps/api/window';
await appWindow.setFullscreen(true);

Parameters

Name Type Description
fullscreen boolean Whether the window should go to fullscreen or not.

Returns

Promise<void>

A promise indicating the success or failure of the operation.

Inherited from

WindowManager.setFullscreen


setIcon

setIcon(icon): Promise<void>

Sets the window icon.

Example

import { appWindow } from '@tauri-apps/api/window';
await appWindow.setIcon('/tauri/awesome.png');

Note that you need the icon-ico or icon-png Cargo features to use this API. To enable it, change your Cargo.toml file:

[dependencies]
tauri = { version = "...", features = ["...", "icon-png"] }

Parameters

Name Type Description
icon string | Uint8Array Icon bytes or path to the icon file.

Returns

Promise<void>

A promise indicating the success or failure of the operation.

Inherited from

WindowManager.setIcon


setMaxSize

setMaxSize(size): Promise<void>

Sets the window maximum inner size. If the size argument is undefined, the constraint is unset.

Example

import { appWindow, LogicalSize } from '@tauri-apps/api/window';
await appWindow.setMaxSize(new LogicalSize(600, 500));

Parameters

Name Type Description
size undefined | null | PhysicalSize | LogicalSize The logical or physical inner size, or null to unset the constraint.

Returns

Promise<void>

A promise indicating the success or failure of the operation.

Inherited from

WindowManager.setMaxSize


setMinSize

setMinSize(size): Promise<void>

Sets the window minimum inner size. If the size argument is not provided, the constraint is unset.

Example

import { appWindow, PhysicalSize } from '@tauri-apps/api/window';
await appWindow.setMinSize(new PhysicalSize(600, 500));

Parameters

Name Type Description
size undefined | null | PhysicalSize | LogicalSize The logical or physical inner size, or null to unset the constraint.

Returns

Promise<void>

A promise indicating the success or failure of the operation.

Inherited from

WindowManager.setMinSize


setPosition

setPosition(position): Promise<void>

Sets the window outer position.

Example

import { appWindow, LogicalPosition } from '@tauri-apps/api/window';
await appWindow.setPosition(new LogicalPosition(600, 500));

Parameters

Name Type Description
position PhysicalPosition | LogicalPosition The new position, in logical or physical pixels.

Returns

Promise<void>

A promise indicating the success or failure of the operation.

Inherited from

WindowManager.setPosition


setResizable

setResizable(resizable): Promise<void>

Updates the window resizable flag.

Example

import { appWindow } from '@tauri-apps/api/window';
await appWindow.setResizable(false);

Parameters

Name Type
resizable boolean

Returns

Promise<void>

A promise indicating the success or failure of the operation.

Inherited from

WindowManager.setResizable


setSize

setSize(size): Promise<void>

Resizes the window with a new inner size.

Example

import { appWindow, LogicalSize } from '@tauri-apps/api/window';
await appWindow.setSize(new LogicalSize(600, 500));

Parameters

Name Type Description
size PhysicalSize | LogicalSize The logical or physical inner size.

Returns

Promise<void>

A promise indicating the success or failure of the operation.

Inherited from

WindowManager.setSize


setSkipTaskbar

setSkipTaskbar(skip): Promise<void>

Whether to show the window icon in the task bar or not.

Example

import { appWindow } from '@tauri-apps/api/window';
await appWindow.setSkipTaskbar(true);

Parameters

Name Type Description
skip boolean true to hide window icon, false to show it.

Returns

Promise<void>

A promise indicating the success or failure of the operation.

Inherited from

WindowManager.setSkipTaskbar


setTitle

setTitle(title): Promise<void>

Sets the window title.

Example

import { appWindow } from '@tauri-apps/api/window';
await appWindow.setTitle('Tauri');

Parameters

Name Type Description
title string The new title

Returns

Promise<void>

A promise indicating the success or failure of the operation.

Inherited from

WindowManager.setTitle


show

show(): Promise<void>

Sets the window visibility to true.

Example

import { appWindow } from '@tauri-apps/api/window';
await appWindow.show();

Returns

Promise<void>

A promise indicating the success or failure of the operation.

Inherited from

WindowManager.show


startDragging

startDragging(): Promise<void>

Starts dragging the window.

Example

import { appWindow } from '@tauri-apps/api/window';
await appWindow.startDragging();

Returns

Promise<void>

A promise indicating the success or failure of the operation.

Inherited from

WindowManager.startDragging


theme

theme(): Promise<null | Theme>

Gets the window's current theme.

Platform-specific

  • Linux: Not implemented, always returns light.
  • macOS: Theme was introduced on macOS 10.14. Returns light on macOS 10.13 and below.

Example

import { appWindow } from '@tauri-apps/api/window';
const theme = await appWindow.theme();

Returns

Promise<null | Theme>

The window theme.

Inherited from

WindowManager.theme


toggleMaximize

toggleMaximize(): Promise<void>

Toggles the window maximized state.

Example

import { appWindow } from '@tauri-apps/api/window';
await appWindow.toggleMaximize();

Returns

Promise<void>

A promise indicating the success or failure of the operation.

Inherited from

WindowManager.toggleMaximize


unmaximize

unmaximize(): Promise<void>

Unmaximizes the window.

Example

import { appWindow } from '@tauri-apps/api/window';
await appWindow.unmaximize();

Returns

Promise<void>

A promise indicating the success or failure of the operation.

Inherited from

WindowManager.unmaximize


unminimize

unminimize(): Promise<void>

Unminimizes the window.

Example

import { appWindow } from '@tauri-apps/api/window';
await appWindow.unminimize();

Returns

Promise<void>

A promise indicating the success or failure of the operation.

Inherited from

WindowManager.unminimize


getByLabel

Static getByLabel(label): null | WebviewWindow

Gets the WebviewWindow for the webview associated with the given label.

Example

import { WebviewWindow } from '@tauri-apps/api/window';
const mainWindow = WebviewWindow.getByLabel('main');

Parameters

Name Type Description
label string The webview window label.

Returns

null | WebviewWindow

The WebviewWindow instance to communicate with the webview or null if the webview doesn't exist.