feat(window): add `setEffects` API (#392)

.changes/window-set-effects.md

@@ -0,0 +1,6 @@
+---
+"window": "patch"
+"window-js": "patch"
+---
+
+Added the `setEffects` and `clearEffects` API.

examples/api/src-tauri/src/lib.rs

@@ -56,7 +56,7 @@ pub fn run() {
             #[cfg(desktop)]
             {
                 window_builder = window_builder
-                    .user_agent("Tauri API")
+                    .user_agent(&format!("Tauri API - {}", std::env::consts::OS))
                     .title("Tauri API Validation")
                     .inner_size(1000., 800.)
                     .min_inner_size(600., 400.)
@@ -71,6 +71,11 @@ pub fn run() {
                     .decorations(false);
             }
 
+            #[cfg(target_os = "macos")]
+            {
+                window_builder = window_builder.transparent(true);
+            }
+
             let window = window_builder.build().unwrap();
 
             #[cfg(debug_assertions)]

examples/api/src/views/Window.svelte

@@ -6,6 +6,8 @@
     UserAttentionType,
     PhysicalSize,
     PhysicalPosition,
+    Effect,
+    EffectState,
   } from "@tauri-apps/plugin-window";
   import { open as openDialog } from "@tauri-apps/plugin-dialog";
   import { open } from "@tauri-apps/plugin-shell";
@@ -57,7 +59,20 @@
     "rowResize",
   ];
 
+  const windowsEffects = ["mica", "blur", "acrylic"];
+  const isWindows = navigator.appVersion.includes("windows");
+  const isMacOS = navigator.appVersion.includes("macos");
+  let effectOptions = isWindows
+    ? windowsEffects
+    : Object.keys(Effect)
+        .map((effect) => Effect[effect])
+        .filter((e) => !windowsEffects.includes(e));
+  const effectStateOptions = Object.keys(EffectState).map(
+    (state) => EffectState[state]
+  );
+
   export let onMessage;
+  const mainEl = document.querySelector("main");
 
   let newWindowLabel;
 
@@ -91,6 +106,12 @@
   let cursorIgnoreEvents = false;
   let windowTitle = "Awesome Tauri Example!";
 
+  let effects = [];
+  let selectedEffect;
+  let effectState;
+  let effectRadius;
+  let effectR, effectG, effectB, effectA;
+
   function openUrl() {
     open(urlValue);
   }
@@ -172,6 +193,38 @@
     await windowMap[selectedWindow].requestUserAttention(null);
   }
 
+  async function addEffect() {
+    if (!effects.includes(selectedEffect)) {
+      effects = [...effects, selectedEffect];
+    }
+
+    const payload = {
+      effects,
+      state: effectState,
+      radius: effectRadius,
+    };
+    if (
+      Number.isInteger(effectR) &&
+      Number.isInteger(effectG) &&
+      Number.isInteger(effectB) &&
+      Number.isInteger(effectA)
+    ) {
+      payload.color = [effectR, effectG, effectB, effectA];
+    }
+
+    mainEl.classList.remove("bg-primary");
+    mainEl.classList.remove("dark:bg-darkPrimary");
+    await windowMap[selectedWindow].clearEffects();
+    await windowMap[selectedWindow].setEffects(payload);
+  }
+
+  async function clearEffects() {
+    effects = [];
+    await windowMap[selectedWindow].clearEffects();
+    mainEl.classList.add("bg-primary");
+    mainEl.classList.add("dark:bg-darkPrimary");
+  }
+
   $: {
     windowMap[selectedWindow];
     loadWindowPosition();
@@ -455,5 +508,88 @@
         <button class="btn" id="open-url"> Open URL </button>
       </form>
     </div>
+
+    <br />
+
+    {#if isWindows || isMacOS}
+      <div class="flex flex-col gap-1">
+        <div class="flex">
+          <label>
+            Effect
+            <select class="input" bind:value={selectedEffect}>
+              {#each effectOptions as effect}
+                <option value={effect}>{effect}</option>
+              {/each}
+            </select>
+          </label>
+
+          <label>
+            State
+            <select class="input" bind:value={effectState}>
+              {#each effectStateOptions as state}
+                <option value={state}>{state}</option>
+              {/each}
+            </select>
+          </label>
+
+          <label>
+            Radius
+            <input class="input" type="number" bind:value={effectRadius} />
+          </label>
+        </div>
+
+        <div class="flex">
+          <label>
+            Color
+            <div class="flex">
+              <input
+                style="max-width: 120px;"
+                class="input"
+                type="number"
+                placeholder="R"
+                bind:value={effectR}
+              />
+              <input
+                style="max-width: 120px;"
+                class="input"
+                type="number"
+                placeholder="G"
+                bind:value={effectG}
+              />
+              <input
+                style="max-width: 120px;"
+                class="input"
+                type="number"
+                placeholder="B"
+                bind:value={effectB}
+              />
+              <input
+                style="max-width: 120px;"
+                class="input"
+                type="number"
+                placeholder="A"
+                bind:value={effectA}
+              />
+            </div>
+          </label>
+        </div>
+
+        <div class="flex">
+          <button class="btn" style="width: 80px;" on:click={addEffect}
+            >Add</button
+          >
+        </div>
+
+        <div class="flex">
+          <div>
+            Applied effects: {effects.length ? effects.join(",") : "None"}
+          </div>
+
+          <button class="btn" style="width: 80px;" on:click={clearEffects}
+            >Clear</button
+          >
+        </div>
+      </div>
+    {/if}
   {/if}
 </div>

plugins/window/guest-js/index.ts

@@ -950,6 +950,30 @@ class WindowManager extends WebviewWindowHandle {
     });
   }
 
+  /**
+   * Set window effects.
+   *
+   * @since 2.0
+   */
+  async setEffects(effects: Effects): Promise<void> {
+    return window.__TAURI_INVOKE__("plugin:window|set_effects", {
+      label: this.label,
+      value: effects,
+    });
+  }
+
+  /**
+   * Clear any applied effects if possible.
+   *
+   * @since 2.0
+   */
+  async clearEffects(): Promise<void> {
+    return window.__TAURI_INVOKE__("plugin:window|set_effects", {
+      label: this.label,
+      value: null,
+    });
+  }
+
   /**
    * Whether the window should always be on top of other windows.
    * @example
@@ -1777,6 +1801,174 @@ if ("__TAURI_METADATA__" in window) {
   });
 }
 
+/**
+ * an array RGBA colors. Each value has minimum of 0 and maximum of 255.
+ *
+ * @since 2.0
+ */
+type Color = [number, number, number, number];
+
+/**
+ * Platform-specific window effects
+ *
+ * @since 2.0
+ */
+enum Effect {
+  /**
+   * A default material appropriate for the view's effectiveAppearance.  **macOS 10.14-**
+   *
+   * @deprecated since macOS 10.14. You should instead choose an appropriate semantic material.
+   */
+  AppearanceBased = "appearanceBased",
+  /**
+   *  **macOS 10.14-**
+   *
+   * @deprecated since macOS 10.14. Use a semantic material instead.
+   */
+  Light = "light",
+  /**
+   *  **macOS 10.14-**
+   *
+   * @deprecated since macOS 10.14. Use a semantic material instead.
+   */
+  Dark = "dark",
+  /**
+   *  **macOS 10.14-**
+   *
+   * @deprecated since macOS 10.14. Use a semantic material instead.
+   */
+  MediumLight = "mediumLight",
+  /**
+   *  **macOS 10.14-**
+   *
+   * @deprecated since macOS 10.14. Use a semantic material instead.
+   */
+  UltraDark = "ultraDark",
+  /**
+   *  **macOS 10.10+**
+   */
+  Titlebar = "titlebar",
+  /**
+   *  **macOS 10.10+**
+   */
+  Selection = "selection",
+  /**
+   *  **macOS 10.11+**
+   */
+  Menu = "menu",
+  /**
+   *  **macOS 10.11+**
+   */
+  Popover = "popover",
+  /**
+   *  **macOS 10.11+**
+   */
+  Sidebar = "sidebar",
+  /**
+   *  **macOS 10.14+**
+   */
+  HeaderView = "headerView",
+  /**
+   *  **macOS 10.14+**
+   */
+  Sheet = "sheet",
+  /**
+   *  **macOS 10.14+**
+   */
+  WindowBackground = "windowBackground",
+  /**
+   *  **macOS 10.14+**
+   */
+  HudWindow = "hudWindow",
+  /**
+   *  **macOS 10.14+**
+   */
+  FullScreenUI = "fullScreenUI",
+  /**
+   *  **macOS 10.14+**
+   */
+  Tooltip = "tooltip",
+  /**
+   *  **macOS 10.14+**
+   */
+  ContentBackground = "contentBackground",
+  /**
+   *  **macOS 10.14+**
+   */
+  UnderWindowBackground = "underWindowBackground",
+  /**
+   *  **macOS 10.14+**
+   */
+  UnderPageBackground = "underPageBackground",
+  /**
+   *  **Windows 11 Only**
+   */
+  Mica = "mica",
+  /**
+   * **Windows 7/10/11(22H1) Only**
+   *
+   * ## Notes
+   *
+   * This effect has bad performance when resizing/dragging the window on Windows 11 build 22621.
+   */
+  Blur = "blur",
+  /**
+   * **Windows 10/11**
+   *
+   * ## Notes
+   *
+   * This effect has bad performance when resizing/dragging the window on Windows 10 v1903+ and Windows 11 build 22000.
+   */
+  Acrylic = "acrylic",
+}
+
+/**
+ * Window effect state **macOS only**
+ *
+ * @see https://developer.apple.com/documentation/appkit/nsvisualeffectview/state
+ *
+ * @since 2.0
+ */
+enum EffectState {
+  /**
+   *  Make window effect state follow the window's active state **macOS only**
+   */
+  FollowsWindowActiveState = "followsWindowActiveState",
+  /**
+   *  Make window effect state always active **macOS only**
+   */
+  Active = "active",
+  /**
+   *  Make window effect state always inactive **macOS only**
+   */
+  Inactive = "inactive",
+}
+
+/** The window effects configuration object
+ *
+ * @since 2.0
+ */
+interface Effects {
+  /**
+   *  List of Window effects to apply to the Window.
+   * Conflicting effects will apply the first one and ignore the rest.
+   */
+  effects: Effect[];
+  /**
+   * Window effect state **macOS Only**
+   */
+  state?: EffectState;
+  /**
+   * Window effect corner radius **macOS Only**
+   */
+  radius?: number;
+  /**
+   *  Window effect color. Affects {@link Effects.Blur} and {@link Effects.Acrylic} only
+   * on Windows 10 v1903+. Doesn't have any effect on Windows 7 or Windows 11.
+   */
+  color?: Color;
+}
+
 /**
  * Configuration for the window to create.
  *
@@ -1976,6 +2168,8 @@ export {
   LogicalPosition,
   PhysicalPosition,
   UserAttentionType,
+  Effect,
+  EffectState,
   currentMonitor,
   primaryMonitor,
   availableMonitors,
@@ -1988,4 +2182,5 @@ export type {
   ScaleFactorChanged,
   FileDropEvent,
   WindowOptions,
+  Color,
 };

plugins/window/src/desktop_commands.rs

@@ -4,8 +4,9 @@
 
 use serde::{Deserialize, Serialize, Serializer};
 use tauri::{
-    utils::config::WindowConfig, AppHandle, CursorIcon, Icon, Manager, Monitor, PhysicalPosition,
+    utils::config::{WindowConfig, WindowEffectsConfig},
-    PhysicalSize, Position, Runtime, Size, Theme, UserAttentionType, Window,
+    AppHandle, CursorIcon, Icon, Manager, Monitor, PhysicalPosition, PhysicalSize, Position,
+    Runtime, Size, Theme, UserAttentionType, Window,
 };
 
 #[derive(Debug, thiserror::Error)]
@@ -133,6 +134,7 @@ setter!(hide);
 setter!(close);
 setter!(set_decorations, bool);
 setter!(set_shadow, bool);
+setter!(set_effects, Option<WindowEffectsConfig>);
 setter!(set_always_on_top, bool);
 setter!(set_content_protected, bool);
 setter!(set_size, Size);

plugins/window/src/lib.rs

@@ -62,6 +62,7 @@ pub fn init<R: Runtime>() -> TauriPlugin<R> {
                         desktop_commands::close,
                         desktop_commands::set_decorations,
                         desktop_commands::set_shadow,
+                        desktop_commands::set_effects,
                         desktop_commands::set_always_on_top,
                         desktop_commands::set_content_protected,
                         desktop_commands::set_size,