feat(api): expose window target option on event APIs (#7132)

.changes/event-api-window-label.md

@@ -0,0 +1,5 @@
+---
+"@tauri-apps/api": patch
+---
+
+Expose the window target option on event APIs.

tooling/api/src/event.ts

@@ -9,15 +9,41 @@
  * @module
  */
 
-import * as eventApi from './helpers/event'
-import type { EventCallback, UnlistenFn, Event } from './helpers/event'
+import { invoke, transformCallback } from './tauri'
 
-export type EventName = `${TauriEvent}` | (string & Record<never, never>)
+interface Event<T> {
+  /** Event name */
+  event: EventName
+  /** The label of the window that emitted this event. */
+  windowLabel: string
+  /** Event identifier used to unlisten */
+  id: number
+  /** Event payload */
+  payload: T
+}
+
+type EventCallback<T> = (event: Event<T>) => void
+
+type UnlistenFn = () => void
+
+type EventName = `${TauriEvent}` | (string & Record<never, never>)
+
+interface Options {
+  /**
+   * Label of the window the function targets.
+   *
+   * When listening to events and using this value,
+   * only events triggered by the window with the given label are received.
+   *
+   * When emitting events, only the window with the given label will receive it.
+   */
+  target?: string
+}
 
 /**
  * @since 1.1.0
  */
-export enum TauriEvent {
+enum TauriEvent {
   WINDOW_RESIZED = 'tauri://resize',
   WINDOW_MOVED = 'tauri://move',
   WINDOW_CLOSE_REQUESTED = 'tauri://close-requested',
@@ -33,6 +59,21 @@ export enum TauriEvent {
   MENU = 'tauri://menu'
 }
 
+/**
+ * Unregister the event listener associated with the given name and id.
+ *
+ * @ignore
+ * @param event The event name
+ * @param eventId Event identifier
+ * @returns
+ */
+async function _unlisten(event: string, eventId: number): Promise<void> {
+  await invoke('plugin:event|unlisten', {
+    event,
+    eventId
+  })
+}
+
 /**
  * Listen to an event from the backend.
  *
@@ -56,9 +97,16 @@ export enum TauriEvent {
  */
 async function listen<T>(
   event: EventName,
-  handler: EventCallback<T>
+  handler: EventCallback<T>,
+  options?: Options
 ): Promise<UnlistenFn> {
-  return eventApi.listen(event, null, handler)
+  return invoke<number>('plugin:event|listen', {
+    event,
+    windowLabel: options?.target,
+    handler: transformCallback(handler)
+  }).then((eventId) => {
+    return async () => _unlisten(event, eventId)
+  })
 }
 
 /**
@@ -87,9 +135,17 @@ async function listen<T>(
  */
 async function once<T>(
   event: EventName,
-  handler: EventCallback<T>
+  handler: EventCallback<T>,
+  options?: Options
 ): Promise<UnlistenFn> {
-  return eventApi.once(event, null, handler)
+  return listen<T>(
+    event,
+    (eventData) => {
+      handler(eventData)
+      _unlisten(event, eventData.id).catch(() => {})
+    },
+    options
+  )
 }
 
 /**
@@ -104,10 +160,18 @@ async function once<T>(
  *
  * @since 1.0.0
  */
-async function emit(event: string, payload?: unknown): Promise<void> {
-  return eventApi.emit(event, undefined, payload)
+async function emit(
+  event: string,
+  payload?: unknown,
+  options?: Options
+): Promise<void> {
+  await invoke('plugin:event|emit', {
+    event,
+    windowLabel: options?.target,
+    payload
+  })
 }
 
-export type { Event, EventCallback, UnlistenFn }
+export type { Event, EventCallback, UnlistenFn, EventName, Options }
 
-export { listen, once, emit }
+export { listen, once, emit, TauriEvent }

tooling/api/src/helpers/event.ts

@@ -1,97 +0,0 @@
-// Copyright 2019-2023 Tauri Programme within The Commons Conservancy
-// SPDX-License-Identifier: Apache-2.0
-// SPDX-License-Identifier: MIT
-
-import { invoke, transformCallback } from '../tauri'
-import { type EventName } from '../event'
-
-export interface Event<T> {
-  /** Event name */
-  event: EventName
-  /** The label of the window that emitted this event. */
-  windowLabel: string
-  /** Event identifier used to unlisten */
-  id: number
-  /** Event payload */
-  payload: T
-}
-
-export type EventCallback<T> = (event: Event<T>) => void
-
-export type UnlistenFn = () => void
-
-/**
- * Unregister the event listener associated with the given name and id.
- *
- * @ignore
- * @param event The event name
- * @param eventId Event identifier
- * @returns
- */
-async function _unlisten(event: string, eventId: number): Promise<void> {
-  await invoke('plugin:event|unlisten', {
-    event,
-    eventId
-  })
-}
-
-/**
- * Emits an event to the backend.
- *
- * @param event Event name. Must include only alphanumeric characters, `-`, `/`, `:` and `_`.
- * @param [windowLabel] The label of the window to which the event is sent, if null/undefined the event will be sent to all windows
- * @param [payload] Event payload
- * @returns
- */
-async function emit(
-  event: string,
-  windowLabel?: string,
-  payload?: unknown
-): Promise<void> {
-  await invoke('plugin:event|emit', {
-    event,
-    windowLabel,
-    payload
-  })
-}
-
-/**
- * Listen to an event from the backend.
- *
- * @param event Event name. Must include only alphanumeric characters, `-`, `/`, `:` and `_`.
- * @param handler Event handler callback.
- * @return A promise resolving to a function to unlisten to the event.
- */
-async function listen<T>(
-  event: EventName,
-  windowLabel: string | null,
-  handler: EventCallback<T>
-): Promise<UnlistenFn> {
-  return invoke<number>('plugin:event|listen', {
-    event,
-    windowLabel,
-    handler: transformCallback(handler)
-  }).then((eventId) => {
-    return async () => _unlisten(event, eventId)
-  })
-}
-
-/**
- * Listen to an one-off event from the backend.
- *
- * @param event Event name. Must include only alphanumeric characters, `-`, `/`, `:` and `_`.
- * @param handler Event handler callback.
- * @returns A promise resolving to a function to unlisten to the event.
- */
-async function once<T>(
-  event: EventName,
-  windowLabel: string | null,
-  handler: EventCallback<T>
-): Promise<UnlistenFn> {
-  return listen<T>(event, windowLabel, (eventData) => {
-    handler(eventData)
-    _unlisten(event, eventData.id).catch(() => {})
-  })
-}
-
-export { emit, listen, once }