[macos] Add support for setting icon & template at same time

Calling set_icon and then set_icon_as_template in sequence
cause a flicker as they both run on the main thread and update
the UI. This exposes a single function to do both at once,
preventing the flicker.

Author: ykogan-discord

.changes/changed.md

@@ -0,0 +1,5 @@
+---
+'tauri': 'patch:feat'
+---
+
+Add macos support for setting the icon and icon template state in the same step of the main thread, to prevent flickering.

crates/tauri/build.rs

@@ -219,6 +219,7 @@ const PLUGINS: &[(&str, &[(&str, bool)])] = &[
       ("set_visible", true),
       ("set_temp_dir_path", true),
       ("set_icon_as_template", true),
+      ("set_icon_with_as_template", true),
       ("set_show_menu_on_left_click", true),
     ],
   ),

crates/tauri/permissions/tray/autogenerated/reference.md

@@ -14,6 +14,7 @@ Default permissions for the plugin, which enables all commands.
 - `allow-set-visible`
 - `allow-set-temp-dir-path`
 - `allow-set-icon-as-template`
+- `allow-set-icon-with-as-template`
 - `allow-set-show-menu-on-left-click`
 
 ## Permission Table
@@ -158,6 +159,32 @@ Denies the set_icon_as_template command without any pre-configured scope.
 <tr>
 <td>
 
+`core:tray:allow-set-icon-with-as-template`
+
+</td>
+<td>
+
+Enables the set_icon_with_as_template command without any pre-configured scope.
+
+</td>
+</tr>
+
+<tr>
+<td>
+
+`core:tray:deny-set-icon-with-as-template`
+
+</td>
+<td>
+
+Denies the set_icon_with_as_template command without any pre-configured scope.
+
+</td>
+</tr>
+
+<tr>
+<td>
+
 `core:tray:allow-set-menu`
 
 </td>

crates/tauri/scripts/bundle.global.js

@@ -576,6 +576,38 @@ impl<R: Runtime> TrayIcon<R> {
     Ok(())
   }
 
+/// Sets the tray icon and template status atomically. **macOS only**.
+///
+/// On macOS, calling `set_icon` followed by `set_icon_as_template` causes a visible
+/// flicker as the icon is rendered twice. This method sets both atomically to prevent that.
+///
+/// ## Platform-specific:
+///
+/// - **Linux / Windows:** Falls back to calling `set_icon`.
+pub fn set_icon_with_as_template(
+  &self,
+  icon: Option<Image<'_>>,
+  #[allow(unused)] is_template: bool,
+) -> crate::Result<()> {
+  #[cfg(target_os = "macos")]
+  {
+    let tray_icon = match icon {
+      Some(i) => Some(i.try_into()?),
+      None => None,
+    };
+    run_item_main_thread!(self, |self_: Self| {
+      self_
+        .inner
+        .set_icon_with_as_template(tray_icon, is_template)
+    })??;
+  }
+  #[cfg(not(target_os = "macos"))]
+  {
+    self.set_icon(icon)?;
+  }
+  Ok(())
+}
+
   /// Disable or enable showing the tray menu on left click.
   ///
   ///

crates/tauri/src/tray/mod.rs

@@ -203,6 +203,24 @@ fn set_icon_as_template<R: Runtime>(
   tray.set_icon_as_template(as_template)
 }
 
+#[command(root = "crate")]
+fn set_icon_with_as_template<R: Runtime>(
+  app: AppHandle<R>,
+  webview: Webview<R>,
+  rid: ResourceId,
+  icon: Option<JsImage>,
+  as_template: bool,
+) -> crate::Result<()> {
+  let resources_table = app.resources_table();
+  let tray = resources_table.get::<TrayIcon<R>>(rid)?;
+  let webview_resources_table = webview.resources_table();
+  let icon = match icon {
+    Some(i) => Some(i.into_img(&webview_resources_table)?.as_ref().clone()),
+    None => None,
+  };
+  tray.set_icon_with_as_template(icon, as_template)
+}
+
 #[command(root = "crate")]
 fn set_show_menu_on_left_click<R: Runtime>(
   app: AppHandle<R>,
@@ -228,6 +246,7 @@ pub(crate) fn init<R: Runtime>() -> TauriPlugin<R> {
       set_visible,
       set_temp_dir_path,
       set_icon_as_template,
+      set_icon_with_as_template,
       set_show_menu_on_left_click,
     ])
     .build()

crates/tauri/src/tray/plugin.rs

@@ -296,6 +296,27 @@ export class TrayIcon extends Resource {
     })
   }
 
+ /**
+   * Sets a new tray icon and template status atomically. **macOS only**.
+   *
+   * Note that you may need the `image-ico` or `image-png` Cargo features to use this API.
+   * To enable it, change your Cargo.toml file:
+   * ```toml
+   * [dependencies]
+   * tauri = { version = "...", features = ["...", "image-png"] }
+   * ```
+   */
+ async setIconWithAsTemplate(
+  icon: string | Image | Uint8Array | ArrayBuffer | number[] | null,
+  asTemplate: boolean
+): Promise<void> {
+  let trayIcon = null
+  if (icon) {
+    trayIcon = transformImage(icon)
+  }
+  return invoke('plugin:tray|set_icon_with_as_template', { rid: this.rid, icon: trayIcon, asTemplate })
+}
+
   /**
    *  Disable or enable showing the tray menu on left click.
    *