Merge pull request #1584 from Night-Hunter-NF/RequestUserAttention

add action to request user attention

Author: hecrj

native/src/window.rs

@@ -2,7 +2,9 @@
 mod action;
 mod event;
 mod mode;
+mod user_attention;
 
 pub use action::Action;
 pub use event::Event;
 pub use mode::Mode;
+pub use user_attention::UserAttention;

native/src/window/action.rs

@@ -1,4 +1,4 @@
-use crate::window::Mode;
+use crate::window::{Mode, UserAttention};
 
 use iced_futures::MaybeSend;
 use std::fmt;
@@ -35,15 +35,29 @@ pub enum Action<T> {
     },
     /// Set the [`Mode`] of the window.
     SetMode(Mode),
+    /// Fetch the current [`Mode`] of the window.
+    FetchMode(Box<dyn FnOnce(Mode) -> T + 'static>),
     /// Sets the window to maximized or back
     ToggleMaximize,
     /// Toggles whether window has decorations
     /// ## Platform-specific
     /// - **X11:** Not implemented.
     /// - **Web:** Unsupported.
     ToggleDecorations,
-    /// Fetch the current [`Mode`] of the window.
-    FetchMode(Box<dyn FnOnce(Mode) -> T + 'static>),
+    /// 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
+    ///
+    /// - **iOS / Android / Web:** Unsupported.
+    /// - **macOS:** `None` has no effect.
+    /// - **X11:** Requests for user attention must be manually cleared.
+    /// - **Wayland:** Requires `xdg_activation_v1` protocol, `None` has no effect.
+    RequestUserAttention(Option<UserAttention>),
 }
 
 impl<T> Action<T> {
@@ -63,9 +77,12 @@ impl<T> Action<T> {
             Self::Minimize(bool) => Action::Minimize(bool),
             Self::Move { x, y } => Action::Move { x, y },
             Self::SetMode(mode) => Action::SetMode(mode),
+            Self::FetchMode(o) => Action::FetchMode(Box::new(move |s| f(o(s)))),
             Self::ToggleMaximize => Action::ToggleMaximize,
             Self::ToggleDecorations => Action::ToggleDecorations,
-            Self::FetchMode(o) => Action::FetchMode(Box::new(move |s| f(o(s)))),
+            Self::RequestUserAttention(attention_type) => {
+                Action::RequestUserAttention(attention_type)
+            }
         }
     }
 }
@@ -86,9 +103,12 @@ impl<T> fmt::Debug for Action<T> {
                 write!(f, "Action::Move {{ x: {}, y: {} }}", x, y)
             }
             Self::SetMode(mode) => write!(f, "Action::SetMode({:?})", mode),
+            Self::FetchMode(_) => write!(f, "Action::FetchMode"),
             Self::ToggleMaximize => write!(f, "Action::ToggleMaximize"),
             Self::ToggleDecorations => write!(f, "Action::ToggleDecorations"),
-            Self::FetchMode(_) => write!(f, "Action::FetchMode"),
+            Self::RequestUserAttention(_) => {
+                write!(f, "Action::RequestUserAttention")
+            }
         }
     }
 }

native/src/window/user_attention.rs

@@ -0,0 +1,21 @@
+/// The type of user attention to request.
+///
+/// ## Platform-specific
+///
+/// - **X11:** Sets the WM's `XUrgencyHint`. No distinction between [`Critical`] and [`Informational`].
+///
+/// [`Critical`]: Self::Critical
+/// [`Informational`]: Self::Informational
+#[derive(Debug, Clone, Copy)]
+pub enum UserAttention {
+    /// ## 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,
+}

winit/src/application.rs

@@ -657,12 +657,6 @@ pub fn run_command<A, E>(
                         mode,
                     ));
                 }
-                window::Action::ToggleMaximize => {
-                    window.set_maximized(!window.is_maximized())
-                }
-                window::Action::ToggleDecorations => {
-                    window.set_decorations(!window.is_decorated())
-                }
                 window::Action::FetchMode(tag) => {
                     let mode = if window.is_visible().unwrap_or(true) {
                         conversion::mode(window.fullscreen())
@@ -674,6 +668,16 @@ pub fn run_command<A, E>(
                         .send_event(tag(mode))
                         .expect("Send message to event loop");
                 }
+                window::Action::ToggleMaximize => {
+                    window.set_maximized(!window.is_maximized())
+                }
+                window::Action::ToggleDecorations => {
+                    window.set_decorations(!window.is_decorated())
+                }
+                window::Action::RequestUserAttention(user_attention) => window
+                    .request_user_attention(
+                        user_attention.map(conversion::user_attention),
+                    ),
             },
             command::Action::System(action) => match action {
                 system::Action::QueryInformation(_tag) => {

winit/src/conversion.rs

@@ -493,6 +493,22 @@ pub fn key_code(
     }
 }
 
+/// Converts some [`UserAttention`] into it's `winit` counterpart.
+///
+/// [`UserAttention`]: window::UserAttention
+pub fn user_attention(
+    user_attention: window::UserAttention,
+) -> winit::window::UserAttentionType {
+    match user_attention {
+        window::UserAttention::Critical => {
+            winit::window::UserAttentionType::Critical
+        }
+        window::UserAttention::Informational => {
+            winit::window::UserAttentionType::Informational
+        }
+    }
+}
+
 // As defined in: http://www.unicode.org/faq/private_use.html
 pub(crate) fn is_private_use_character(c: char) -> bool {
     matches!(

winit/src/window.rs

@@ -2,7 +2,7 @@
 use crate::command::{self, Command};
 use iced_native::window;
 
-pub use window::{Event, Mode};
+pub use window::{Event, Mode, UserAttention};
 
 /// Closes the current window and exits the application.
 pub fn close<Message>() -> Command<Message> {