feat(core): add request_user_attention API, closes #2023 (#2026)

* feat(core): add `request_user_attention` API

* fix: api lint

* fix build without window allowlist

Author: lucasfernog

.changes/api-request-user-attention.md

@@ -0,0 +1,5 @@
+---
+"api": patch
+---
+
+Adds `requestUserAttention` API to the `window` module.

.changes/core-request-user-attention.md

@@ -0,0 +1,5 @@
+---
+"tauri": patch
+---
+
+Adds `request_user_attention` API to the `Window` struct.

.changes/runtime-request-user-attention.md

@@ -0,0 +1,6 @@
+---
+"tauri-runtime": patch
+"tauri-runtime-wry": patch
+---
+
+Adds `request_user_attention` API to the `Dispatcher` trait.

core/tauri-runtime-wry/src/lib.rs

@@ -14,6 +14,7 @@ use tauri_runtime::{
     DetachedWindow, PendingWindow, WindowEvent,
   },
   Dispatch, Error, Icon, Params, Result, RunEvent, RunIteration, Runtime, RuntimeHandle,
+  UserAttentionType,
 };
 
 #[cfg(feature = "menu")]
@@ -39,7 +40,10 @@ use wry::{
     event::{Event, WindowEvent as WryWindowEvent},
     event_loop::{ControlFlow, EventLoop, EventLoopProxy, EventLoopWindowTarget},
     monitor::MonitorHandle,
-    window::{Fullscreen, Icon as WindowIcon, Window, WindowBuilder as WryWindowBuilder, WindowId},
+    window::{
+      Fullscreen, Icon as WindowIcon, UserAttentionType as WryUserAttentionType, Window,
+      WindowBuilder as WryWindowBuilder, WindowId,
+    },
   },
   webview::{
     FileDropEvent as WryFileDropEvent, RpcRequest as WryRpcRequest, RpcResponse, WebContext,
@@ -245,6 +249,19 @@ impl From<Position> for PositionWrapper {
   }
 }
 
+#[derive(Debug, Clone)]
+struct UserAttentionTypeWrapper(WryUserAttentionType);
+
+impl From<UserAttentionType> for UserAttentionTypeWrapper {
+  fn from(request_type: UserAttentionType) -> UserAttentionTypeWrapper {
+    let o = match request_type {
+      UserAttentionType::Critical => WryUserAttentionType::Critical,
+      UserAttentionType::Informational => WryUserAttentionType::Informational,
+    };
+    Self(o)
+  }
+}
+
 #[derive(Debug, Clone, Default)]
 pub struct WindowBuilderWrapper {
   inner: WryWindowBuilder,
@@ -467,6 +484,7 @@ enum WindowMessage {
   Hwnd(Sender<Hwnd>),
   // Setters
   Center(Sender<Result<()>>),
+  RequestUserAttention(Option<UserAttentionTypeWrapper>),
   SetResizable(bool),
   SetTitle(String),
   Maximize,
@@ -680,6 +698,17 @@ impl Dispatch for WryDispatcher {
       .map_err(|_| Error::FailedToSendMessage)
   }
 
+  fn request_user_attention(&self, request_type: Option<UserAttentionType>) -> Result<()> {
+    self
+      .context
+      .proxy
+      .send_event(Message::Window(
+        self.window_id,
+        WindowMessage::RequestUserAttention(request_type.map(Into::into)),
+      ))
+      .map_err(|_| Error::FailedToSendMessage)
+  }
+
   // Creates a window by dispatching a message to the event loop.
   // Note that this must be called from a separate thread, otherwise the channel will introduce a deadlock.
   fn create_window<P: Params<Runtime = Self::Runtime>>(
@@ -1341,6 +1370,9 @@ fn handle_event_loop(
             WindowMessage::Center(tx) => {
               tx.send(center_window(window)).unwrap();
             }
+            WindowMessage::RequestUserAttention(request_type) => {
+              window.request_user_attention(request_type.map(|r| r.0));
+            }
             WindowMessage::SetResizable(resizable) => window.set_resizable(resizable),
             WindowMessage::SetTitle(title) => window.set_title(&title),
             WindowMessage::Maximize => window.set_maximized(true),

core/tauri-runtime/src/lib.rs

@@ -8,7 +8,7 @@
 
 use std::{fmt::Debug, hash::Hash, path::PathBuf};
 
-use serde::Serialize;
+use serde::{Deserialize, Serialize};
 use tauri_utils::assets::Assets;
 use uuid::Uuid;
 
@@ -76,6 +76,20 @@ impl<I: MenuId> SystemTray<I> {
   }
 }
 
+/// Type of user attention requested on a window.
+#[derive(Debug, Clone, Copy, PartialEq, Deserialize)]
+#[serde(tag = "type")]
+pub enum UserAttentionType {
+  /// ## Platform-specific
+  /// - **macOS:** Bounces the dock icon until the application is in focus.
+  /// - **Windows:** Flashes both the window and the taskbar button until the application is in focus.
+  Critical,
+  /// ## Platform-specific
+  /// - **macOS:** Bounces the dock icon once.
+  /// - **Windows:** Flashes the taskbar button until the application is in focus.
+  Informational,
+}
+
 #[derive(Debug, thiserror::Error)]
 #[non_exhaustive]
 pub enum Error {
@@ -338,6 +352,11 @@ pub trait Dispatch: Clone + Send + Sized + 'static {
   /// Opens the dialog to prints the contents of the webview.
   fn print(&self) -> crate::Result<()>;
 
+  /// Requests user attention to the window.
+  ///
+  /// Providing `None` will unset the request for user attention.
+  fn request_user_attention(&self, request_type: Option<UserAttentionType>) -> crate::Result<()>;
+
   /// Create a new webview window.
   fn create_window<P: Params<Runtime = Self::Runtime>>(
     &mut self,

core/tauri/scripts/bundle.js

@@ -7,7 +7,10 @@ use crate::runtime::{webview::WindowBuilder, Dispatch, Runtime};
 use crate::{
   api::config::WindowConfig,
   endpoints::InvokeResponse,
-  runtime::window::dpi::{Position, Size},
+  runtime::{
+    window::dpi::{Position, Size},
+    UserAttentionType,
+  },
   Params, Window,
 };
 use serde::Deserialize;
@@ -54,6 +57,7 @@ pub enum Cmd {
   AvailableMonitors,
   // Setters
   Center,
+  RequestUserAttention(Option<UserAttentionType>),
   SetResizable(bool),
   SetTitle(String),
   Maximize,
@@ -143,6 +147,7 @@ impl Cmd {
         Self::AvailableMonitors => return Ok(window.available_monitors()?.into()),
         // Setters
         Self::Center => window.center()?,
+        Self::RequestUserAttention(request_type) => window.request_user_attention(request_type)?,
         Self::SetResizable(resizable) => window.set_resizable(resizable)?,
         Self::SetTitle(title) => window.set_title(&title)?,
         Self::Maximize => window.maximize()?,

core/tauri/src/endpoints/window.rs

@@ -91,7 +91,7 @@ pub use {
       dpi::{LogicalPosition, LogicalSize, PhysicalPosition, PhysicalSize, Pixel, Position, Size},
       WindowEvent,
     },
-    Icon, MenuId, Params, RunIteration,
+    Icon, MenuId, Params, RunIteration, UserAttentionType,
   },
   self::state::{State, StateManager},
   self::window::{Monitor, Window},

core/tauri/src/lib.rs

@@ -19,7 +19,7 @@ use crate::{
       dpi::{PhysicalPosition, PhysicalSize, Position, Size},
       DetachedWindow, PendingWindow, WindowEvent,
     },
-    Dispatch, Icon, Params, Runtime,
+    Dispatch, Icon, Params, Runtime, UserAttentionType,
   },
   sealed::ManagerBase,
   sealed::RuntimeOrDispatch,
@@ -490,6 +490,27 @@ impl<P: Params> Window<P> {
     self.window.dispatcher.center().map_err(Into::into)
   }
 
+  /// Requests user attention to the window, this has no effect if the application
+  /// is already focused. How requesting for user attention manifests is platform dependent,
+  /// see `UserAttentionType` for details.
+  ///
+  /// Providing `None` will unset the request for user attention. Unsetting the request for
+  /// user attention might not be done automatically by the WM when the window receives input.
+  ///
+  /// ## Platform-specific
+  ///
+  /// - **macOS:** `None` has no effect.
+  pub fn request_user_attention(
+    &self,
+    request_type: Option<UserAttentionType>,
+  ) -> crate::Result<()> {
+    self
+      .window
+      .dispatcher
+      .request_user_attention(request_type)
+      .map_err(Into::into)
+  }
+
   /// Opens the dialog to prints the contents of the webview.
   /// Currently only supported on macOS on `wry`.
   /// `window.print()` works on all platforms.