Skip to content

Commit

Permalink
feat(api): WindowManager extends WebviewWindowHandle, add events docs (
Browse files Browse the repository at this point in the history
  • Loading branch information
lucasfernog authored Jul 4, 2021
1 parent acb8892 commit 5d7626f
Show file tree
Hide file tree
Showing 5 changed files with 93 additions and 10 deletions.
5 changes: 5 additions & 0 deletions .changes/appwindow-events.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"api": patch
---

You can now use `emit`, `listen` and `once` using the `appWindow` exported by the window module.
2 changes: 1 addition & 1 deletion core/tauri-runtime/src/window.rs
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ pub enum WindowEvent {
///
/// The parameter is true if the window has gained focus, and false if it has lost focus.
Focused(bool),
///The window's scale factor has changed.
/// The window's scale factor has changed.
///
/// The following user actions can cause DPI changes:
///
Expand Down
2 changes: 1 addition & 1 deletion core/tauri/scripts/bundle.js

Large diffs are not rendered by default.

24 changes: 21 additions & 3 deletions tooling/api/src/event.ts
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,24 @@ interface Event<T> {
payload: T
}

type EventName =
| 'tauri://update'
| 'tauri://update-available'
| 'tauri://update-install'
| 'tauri://update-status'
| 'tauri://resize'
| 'tauri://move'
| 'tauri://close-requested'
| 'tauri://destroyed'
| 'tauri://focus'
| 'tauri://blur'
| 'tauri://scale-change'
| 'tauri://menu'
| 'tauri://file-drop'
| 'tauri://file-drop-hover'
| 'tauri://file-drop-cancelled'
| string

type EventCallback<T> = (event: Event<T>) => void

type UnlistenFn = () => void
Expand Down Expand Up @@ -51,7 +69,7 @@ async function _unlisten(eventId: number): Promise<void> {
* @return A promise resolving to a function to unlisten to the event.
*/
async function listen<T>(
event: string,
event: EventName,
handler: EventCallback<T>
): Promise<UnlistenFn> {
return invokeTauriCommand<number>({
Expand All @@ -74,7 +92,7 @@ async function listen<T>(
* @returns A promise resolving to a function to unlisten to the event.
*/
async function once<T>(
event: string,
event: EventName,
handler: EventCallback<T>
): Promise<UnlistenFn> {
return listen<T>(event, (eventData) => {
Expand All @@ -94,6 +112,6 @@ async function emit(event: string, payload?: string): Promise<void> {
return emitEvent(event, undefined, payload)
}

export type { Event, EventCallback, UnlistenFn }
export type { Event, EventName, EventCallback, UnlistenFn }

export { listen, once, emit }
70 changes: 65 additions & 5 deletions tooling/api/src/window.ts
Original file line number Diff line number Diff line change
Expand Up @@ -21,11 +21,71 @@
* }
* ```
* It is recommended to allowlist only the APIs you use for optimal bundle size and security.
*
* # Window events
*
* Events can be listened using `appWindow.listen`:
* ```typescript
* import { appWindow } from '@tauri-apps/api/window'
* appWindow.listen('tauri://move', ({ event, payload }) => {
* const { x, y } = payload // payload here is a `PhysicalPosition`
* })
* ```
*
* Window-specific events emitted by the backend:
*
* #### 'tauri://resize'
* Emitted when the size of the window has changed.
* *EventPayload*:
* ```typescript
* type ResizePayload = PhysicalSize
* ```
*
* #### 'tauri://move'
* Emitted when the position of the window has changed.
* *EventPayload*:
* ```typescript
* type MovePayload = PhysicalPosition
* ```
*
* #### 'tauri://close-requested'
* Emitted when the user requests the window to be closed.
*
* #### 'tauri://destroyed'
* Emitted after the window is closed.
*
* #### 'tauri://focus'
* Emitted when the window gains focus.
*
* #### 'tauri://blur'
* Emitted when the window loses focus.
*
* #### 'tauri://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.
* *Event payload*:
* ```typescript
* interface ScaleFactorChanged {
* scaleFactor: number
* size: PhysicalSize
* }
* ```
*
* #### 'tauri://menu'
* Emitted when a menu item is clicked.
* *EventPayload*:
* ```typescript
* type MenuClicked = string
* ```
*
* @packageDocumentation
*/

import { invokeTauriCommand } from './helpers/tauri'
import { EventCallback, UnlistenFn, listen, once } from './event'
import { EventName, EventCallback, UnlistenFn, listen, once } from './event'
import { emit } from './helpers/event'

/** Allows you to retrieve information about a given monitor. */
Expand Down Expand Up @@ -174,7 +234,7 @@ class WebviewWindowHandle {
* @returns A promise resolving to a function to unlisten to the event.
*/
async listen<T>(
event: string,
event: EventName,
handler: EventCallback<T>
): Promise<UnlistenFn> {
if (this._handleTauriEvent(event, handler)) {
Expand Down Expand Up @@ -300,7 +360,7 @@ class WebviewWindow extends WebviewWindowHandle {
/**
* Manage the current window object.
*/
class WindowManager {
class WindowManager extends WebviewWindowHandle {
// Getters
/** The scale factor that can be used to map physical pixels to logical pixels. */
async scaleFactor(): Promise<number> {
Expand Down Expand Up @@ -842,8 +902,8 @@ class WindowManager {
}
}

/** The manager for the current window. Allows you to manipulate the window object. */
const appWindow = new WindowManager()
/** The manager for the current window. Allows you to manipulate the window object, listen and emit events. */
const appWindow = new WindowManager(window.__TAURI__.__currentWindow.label)

/** Configuration for the window to create. */
interface WindowOptions {
Expand Down

0 comments on commit 5d7626f

Please sign in to comment.