refactor(api)!: renamed getCurrent functions to avoid ambiguity (#10229)

* refactor(api)!: renamed `getCurrent` functions to avoid ambiguity

closes #10193

* Update .changes/get-current-ambguity.md

* rename `getAll` and update docs and examples

Author: amrbashir

.changes/get-current-ambguity.md

@@ -0,0 +1,13 @@
+---
+"@tauri-apps/api": "patch:breaking"
+"tauri": "patch:breaking"
+---
+
+Renamed the JS `getCurrent` and `getAll` functions to a clearer name to avoid ambiguity:
+- `getCurrent` in `window` module has been renamed to `getCurrentWindow`
+- `getCurrent` in `webview` module has been renamed to `getCurrentWebview`
+- `getCurrent` in `webviewWindow` module has been renamed to `getCurrentWebviewWindow`
+- `getAll` in `window` module has been renamed to `getAllWindows`
+- `getAll` in `webview` module has been renamed to `getAllWebviews`
+- `getAll` in `webviewWindow` module has been renamed to `getAllWebviewWindows`
+

core/tauri/scripts/bundle.global.js

@@ -1,12 +1,12 @@
 <script>
-  import { getCurrent } from '@tauri-apps/api/webviewWindow'
+  import { getCurrentWebviewWindow } from '@tauri-apps/api/webviewWindow'
   import { invoke } from '@tauri-apps/api/core'
   import { onMount, onDestroy } from 'svelte'
 
   export let onMessage
   let unlisten
 
-  const webviewWindow = getCurrent()
+  const webviewWindow = getCurrentWebviewWindow()
 
   onMount(async () => {
     unlisten = await webviewWindow.listen('rust-event', onMessage)

examples/api/src/views/Communication.svelte

@@ -15,7 +15,7 @@
 
     <script>
       const WebviewWindow = window.__TAURI__.webviewWindow.WebviewWindow
-      const appWindow = window.__TAURI__.window.getCurrent()
+      const appWindow = window.__TAURI__.window.getCurrentWindow()
       const windowLabel = appWindow.label
       const windowLabelContainer = document.getElementById('window-label')
       windowLabelContainer.innerText = 'This is the ' + windowLabel + ' window.'
@@ -75,7 +75,7 @@
       })
       container.appendChild(globalMessageButton)
 
-      const allWindows = window.__TAURI__.window.getAll()
+      const allWindows = window.__TAURI__.window.getAllWindows()
       for (const index in allWindows) {
         const label = allWindows[index].label
         if (label === windowLabel) {

examples/multiwindow/index.html

@@ -15,7 +15,7 @@
 
     <script>
       const { WebviewWindow } = window.__TAURI__.webviewWindow
-      const thisTauriWindow = window.__TAURI__.window.getCurrent()
+      const thisTauriWindow = window.__TAURI__.window.getCurrentWindow()
       const windowLabel = thisTauriWindow.label
       const windowLabelContainer = document.getElementById('window-label')
       windowLabelContainer.innerText = 'This is the ' + windowLabel + ' window.'

examples/parent-window/index.html

@@ -37,8 +37,8 @@ class PhysicalSize {
    * Converts the physical size to a logical one.
    * @example
    * ```typescript
-   * import { getCurrent } from '@tauri-apps/api/window';
-   * const appWindow = getCurrent();
+   * import { getCurrentWindow } from '@tauri-apps/api/window';
+   * const appWindow = getCurrentWindow();
    * const factor = await appWindow.scaleFactor();
    * const size = await appWindow.innerSize();
    * const logical = size.toLogical(factor);
@@ -84,8 +84,8 @@ class PhysicalPosition {
    * Converts the physical position to a logical one.
    * @example
    * ```typescript
-   * import { getCurrent } from '@tauri-apps/api/window';
-   * const appWindow = getCurrent();
+   * import { getCurrentWindow } from '@tauri-apps/api/window';
+   * const appWindow = getCurrentWindow();
    * const factor = await appWindow.scaleFactor();
    * const position = await appWindow.innerPosition();
    * const logical = position.toLogical(factor);

tooling/api/src/dpi.ts

@@ -111,11 +111,11 @@ export function mockIPC(
  *
  * ```js
  * import { mockWindows } from "@tauri-apps/api/mocks";
- * import { getCurrent } from "@tauri-apps/api/window";
+ * import { getCurrentWindow } from "@tauri-apps/api/window";
  *
  * mockWindows("main", "second", "third");
  *
- * const win = getCurrent();
+ * const win = getCurrentWindow();
  *
  * win.label // "main"
  * ```

tooling/api/src/mocks.ts

@@ -9,8 +9,8 @@
  *
  * Events can be listened to using {@link Webview.listen}:
  * ```typescript
- * import { getCurrent } from "@tauri-apps/api/webview";
- * getCurrent().listen("my-webview-event", ({ event, payload }) => { });
+ * import { getCurrentWebview } from "@tauri-apps/api/webview";
+ * getCurrentWebview().listen("my-webview-event", ({ event, payload }) => { });
  * ```
  *
  * @module
@@ -29,7 +29,7 @@ import {
   once
 } from './event'
 import { invoke } from './core'
-import { Window, getCurrent as getCurrentWindow } from './window'
+import { Window, getCurrentWindow } from './window'
 import { WebviewWindow } from './webviewWindow'
 
 interface DragDropPayload {
@@ -53,7 +53,7 @@ type DragDropEvent =
  *
  * @since 2.0.0
  */
-function getCurrent(): Webview {
+function getCurrentWebview(): Webview {
   return new Webview(
     getCurrentWindow(),
     window.__TAURI_INTERNALS__.metadata.currentWebview.label,
@@ -69,7 +69,7 @@ function getCurrent(): Webview {
  *
  * @since 2.0.0
  */
-function getAll(): Webview[] {
+function getAllWebviews(): Webview[] {
   return window.__TAURI_INTERNALS__.metadata.webviews.map(
     (w) =>
       new Webview(Window.getByLabel(w.windowLabel)!, w.label, {
@@ -184,30 +184,30 @@ class Webview {
    * @returns The Webview instance to communicate with the webview or null if the webview doesn't exist.
    */
   static getByLabel(label: string): Webview | null {
-    return getAll().find((w) => w.label === label) ?? null
+    return getAllWebviews().find((w) => w.label === label) ?? null
   }
 
   /**
    * Get an instance of `Webview` for the current webview.
    */
   static getCurrent(): Webview {
-    return getCurrent()
+    return getCurrentWebview()
   }
 
   /**
    * Gets a list of instances of `Webview` for all available webviews.
    */
   static getAll(): Webview[] {
-    return getAll()
+    return getAllWebviews()
   }
 
   /**
    * Listen to an emitted event on this webview.
    *
    * @example
    * ```typescript
-   * import { getCurrent } from '@tauri-apps/api/webview';
-   * const unlisten = await getCurrent().listen<string>('state-changed', (event) => {
+   * import { getCurrentWebview } from '@tauri-apps/api/webview';
+   * const unlisten = await getCurrentWebview().listen<string>('state-changed', (event) => {
    *   console.log(`Got error: ${payload}`);
    * });
    *
@@ -241,7 +241,7 @@ class Webview {
    *
    * @example
    * ```typescript
-   * import { getCurrent } from '@tauri-apps/api/webview';
+   * import { getCurrentWebview } from '@tauri-apps/api/webview';
    * const unlisten = await getCurrent().once<null>('initialized', (event) => {
    *   console.log(`Webview initialized!`);
    * });
@@ -276,8 +276,8 @@ class Webview {
    *
    * @example
    * ```typescript
-   * import { getCurrent } from '@tauri-apps/api/webview';
-   * await getCurrent().emit('webview-loaded', { loggedIn: true, token: 'authToken' });
+   * import { getCurrentWebview } from '@tauri-apps/api/webview';
+   * await getCurrentWebview().emit('webview-loaded', { loggedIn: true, token: 'authToken' });
    * ```
    *
    * @param event Event name. Must include only alphanumeric characters, `-`, `/`, `:` and `_`.
@@ -303,8 +303,8 @@ class Webview {
    *
    * @example
    * ```typescript
-   * import { getCurrent } from '@tauri-apps/api/webview';
-   * await getCurrent().emitTo('main', 'webview-loaded', { loggedIn: true, token: 'authToken' });
+   * import { getCurrentWebview } from '@tauri-apps/api/webview';
+   * await getCurrentWebview().emitTo('main', 'webview-loaded', { loggedIn: true, token: 'authToken' });
    * ```
    *
    * @param target Label of the target Window/Webview/WebviewWindow or raw {@link EventTarget} object.
@@ -350,8 +350,8 @@ class Webview {
    * The position of the top-left hand corner of the webview's client area relative to the top-left hand corner of the desktop.
    * @example
    * ```typescript
-   * import { getCurrent } from '@tauri-apps/api/webview';
-   * const position = await getCurrent().position();
+   * import { getCurrentWebview } from '@tauri-apps/api/webview';
+   * const position = await getCurrentWebview().position();
    * ```
    *
    * @returns The webview's position.
@@ -367,8 +367,8 @@ class Webview {
    * The client area is the content of the webview, excluding the title bar and borders.
    * @example
    * ```typescript
-   * import { getCurrent } from '@tauri-apps/api/webview';
-   * const size = await getCurrent().size();
+   * import { getCurrentWebview } from '@tauri-apps/api/webview';
+   * const size = await getCurrentWebview().size();
    * ```
    *
    * @returns The webview's size.
@@ -388,8 +388,8 @@ class Webview {
    * Closes the webview.
    * @example
    * ```typescript
-   * import { getCurrent } from '@tauri-apps/api/webview';
-   * await getCurrent().close();
+   * import { getCurrentWebview } from '@tauri-apps/api/webview';
+   * await getCurrentWebview().close();
    * ```
    *
    * @returns A promise indicating the success or failure of the operation.
@@ -405,7 +405,7 @@ class Webview {
    * @example
    * ```typescript
    * import { getCurrent, LogicalSize } from '@tauri-apps/api/webview';
-   * await getCurrent().setSize(new LogicalSize(600, 500));
+   * await getCurrentWebview().setSize(new LogicalSize(600, 500));
    * ```
    *
    * @param size The logical or physical size.
@@ -435,7 +435,7 @@ class Webview {
    * @example
    * ```typescript
    * import { getCurrent, LogicalPosition } from '@tauri-apps/api/webview';
-   * await getCurrent().setPosition(new LogicalPosition(600, 500));
+   * await getCurrentWebview().setPosition(new LogicalPosition(600, 500));
    * ```
    *
    * @param position The new position, in logical or physical pixels.
@@ -469,8 +469,8 @@ class Webview {
    * Bring the webview to front and focus.
    * @example
    * ```typescript
-   * import { getCurrent } from '@tauri-apps/api/webview';
-   * await getCurrent().setFocus();
+   * import { getCurrentWebview } from '@tauri-apps/api/webview';
+   * await getCurrentWebview().setFocus();
    * ```
    *
    * @returns A promise indicating the success or failure of the operation.
@@ -485,8 +485,8 @@ class Webview {
    * Set webview zoom level.
    * @example
    * ```typescript
-   * import { getCurrent } from '@tauri-apps/api/webview';
-   * await getCurrent().setZoom(1.5);
+   * import { getCurrentWebview } from '@tauri-apps/api/webview';
+   * await getCurrentWebview().setZoom(1.5);
    * ```
    *
    * @returns A promise indicating the success or failure of the operation.
@@ -502,8 +502,8 @@ class Webview {
    * Moves this webview to the given label.
    * @example
    * ```typescript
-   * import { getCurrent } from '@tauri-apps/api/webview';
-   * await getCurrent().reparent('other-window');
+   * import { getCurrentWebview } from '@tauri-apps/api/webview';
+   * await getCurrentWebview().reparent('other-window');
    * ```
    *
    * @returns A promise indicating the success or failure of the operation.
@@ -525,7 +525,7 @@ class Webview {
    * @example
    * ```typescript
    * import { getCurrent } from "@tauri-apps/api/webview";
-   * const unlisten = await getCurrent().onDragDropEvent((event) => {
+   * const unlisten = await getCurrentWebview().onDragDropEvent((event) => {
    *  if (event.payload.type === 'hover') {
    *    console.log('User hovering', event.payload.paths);
    *  } else if (event.payload.type === 'drop') {
@@ -680,6 +680,6 @@ interface WebviewOptions {
   zoomHotkeysEnabled?: boolean
 }
 
-export { Webview, getCurrent, getAll }
+export { Webview, getCurrentWebview, getAllWebviews }
 
 export type { DragDropEvent, DragDropPayload, WebviewOptions }

tooling/api/src/webview.ts

@@ -3,7 +3,7 @@
 // SPDX-License-Identifier: MIT
 
 import {
-  getCurrent as getCurrentWebview,
+  getCurrentWebview,
   Webview,
   WebviewLabel,
   WebviewOptions
@@ -20,7 +20,7 @@ import type { DragDropEvent, DragDropPayload } from './webview'
  *
  * @since 2.0.0
  */
-function getCurrent(): WebviewWindow {
+function getCurrentWebviewWindow(): WebviewWindow {
   const webview = getCurrentWebview()
   // @ts-expect-error `skip` is not defined in the public API but it is handled by the constructor
   return new WebviewWindow(webview.label, { skip: true })
@@ -31,7 +31,7 @@ function getCurrent(): WebviewWindow {
  *
  * @since 2.0.0
  */
-function getAll(): WebviewWindow[] {
+function getAllWebviewWindows(): WebviewWindow[] {
   return window.__TAURI_INTERNALS__.metadata.webviews.map(
     (w) =>
       new WebviewWindow(w.label, {
@@ -108,7 +108,8 @@ class WebviewWindow {
    * @returns The Webview instance to communicate with the webview or null if the webview doesn't exist.
    */
   static getByLabel(label: string): WebviewWindow | null {
-    const webview = getAll().find((w) => w.label === label) ?? null
+    const webview =
+      getAllWebviewWindows().find((w) => w.label === label) ?? null
     if (webview) {
       // @ts-expect-error `skip` is not defined in the public API but it is handled by the constructor
       return new WebviewWindow(webview.label, { skip: true })
@@ -120,15 +121,17 @@ class WebviewWindow {
    * Get an instance of `Webview` for the current webview.
    */
   static getCurrent(): WebviewWindow {
-    return getCurrent()
+    return getCurrentWebviewWindow()
   }
 
   /**
    * Gets a list of instances of `Webview` for all available webviews.
    */
   static getAll(): WebviewWindow[] {
-    // @ts-expect-error `skip` is not defined in the public API but it is handled by the constructor
-    return getAll().map((w) => new WebviewWindow(w.label, { skip: true }))
+    return getAllWebviewWindows().map(
+      // @ts-expect-error `skip` is not defined in the public API but it is handled by the constructor
+      (w) => new WebviewWindow(w.label, { skip: true })
+    )
   }
 
   /**
@@ -232,5 +235,5 @@ function applyMixins(
   })
 }
 
-export { WebviewWindow, getCurrent, getAll }
+export { WebviewWindow, getCurrentWebviewWindow, getAllWebviewWindows }
 export type { DragDropEvent, DragDropPayload }