Add platform::startup_notify for Wayland/X11

The utils in this module should help the users to activate the windows
they create, as well as manage activation tokens environment variables.

The API is essential for Wayland in the first place, since some
compositors may decide initial focus of the window based on whether
the activation token was during the window creation.

Fixes rust-windowing#2279.

CHANGELOG.md

@@ -8,6 +8,7 @@ And please only add new entries to the top of this list, right below the `# Unre
 
 # Unreleased
 
+- **Breaking:** `ActivationTokenDone` event which could be requested with the new `startup_notify` module, see its docs for more.
 - **Breaking:** Rename `Window::set_inner_size` to `Window::request_inner_size` and indicate if the size was applied immediately.
 - On X11, fix false positive flagging of key repeats when pressing different keys with no release between presses.
 - Implement `PartialOrd` and `Ord` for `KeyCode` and `NativeKeyCode`.

src/event.rs

@@ -45,9 +45,10 @@ use web_time::Instant;
 use crate::window::Window;
 use crate::{
     dpi::{PhysicalPosition, PhysicalSize},
+    event_loop::AsyncRequestSerial,
     keyboard::{self, ModifiersKeyState, ModifiersKeys, ModifiersState},
     platform_impl,
-    window::{Theme, WindowId},
+    window::{ActivationToken, Theme, WindowId},
 };
 
 /// Describes a generic event.
@@ -356,6 +357,20 @@ pub enum StartCause {
 /// Describes an event from a [`Window`].
 #[derive(Debug, PartialEq)]
 pub enum WindowEvent<'a> {
+    /// The activation token was delivered back and now could be used.
+    ///
+    #[cfg_attr(
+        not(any(x11_platform, wayland_platfrom)),
+        allow(rustdoc::broken_intra_doc_links)
+    )]
+    /// Delivered in response to [`request_activation_token`].
+    ///
+    /// [`request_activation_token`]: crate::platform::startup_notify::WindowExtStartupNotify::request_activation_token
+    ActivationTokenDone {
+        serial: AsyncRequestSerial,
+        token: ActivationToken,
+    },
+
     /// The size of the window has changed. Contains the client area's new dimensions.
     Resized(PhysicalSize<u32>),
 
@@ -608,6 +623,10 @@ impl Clone for WindowEvent<'static> {
     fn clone(&self) -> Self {
         use self::WindowEvent::*;
         return match self {
+            ActivationTokenDone { serial, token } => ActivationTokenDone {
+                serial: *serial,
+                token: token.clone(),
+            },
             Resized(size) => Resized(*size),
             Moved(pos) => Moved(*pos),
             CloseRequested => CloseRequested,
@@ -711,6 +730,7 @@ impl<'a> WindowEvent<'a> {
     pub fn to_static(self) -> Option<WindowEvent<'static>> {
         use self::WindowEvent::*;
         match self {
+            ActivationTokenDone { serial, token } => Some(ActivationTokenDone { serial, token }),
             Resized(size) => Some(Resized(size)),
             Moved(position) => Some(Moved(position)),
             CloseRequested => Some(CloseRequested),

src/event_loop.rs

@@ -9,7 +9,7 @@
 //! handle events.
 use std::marker::PhantomData;
 use std::ops::Deref;
-use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
 use std::{error, fmt};
 
 use raw_window_handle::{HasRawDisplayHandle, RawDisplayHandle};
@@ -437,3 +437,29 @@ pub enum DeviceEvents {
     /// Never capture device events.
     Never,
 }
+
+/// A unique identifier of the winit's async request.
+///
+/// This could be used to identify the async request once it's done
+/// and a specific action must be taken.
+///
+/// One of the handling scenarious could be to maintain a working list
+/// containing [`AsyncRequestSerial`] and some closure associated with it.
+/// Then once event is arriving the working list is being traversed and a job
+/// executed and removed from the list.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct AsyncRequestSerial {
+    serial: u64,
+}
+
+impl AsyncRequestSerial {
+    // TODO(kchibisov) remove `cfg` when the clipboard will be added.
+    #[allow(dead_code)]
+    pub(crate) fn get() -> Self {
+        static CURRENT_SERIAL: AtomicU64 = AtomicU64::new(0);
+        // NOTE: we rely on wrap around here, while the user may just request
+        // in the loop u64::MAX times that's issue is considered on them.
+        let serial = CURRENT_SERIAL.fetch_add(1, Ordering::Relaxed);
+        Self { serial }
+    }
+}

src/platform/mod.rs

@@ -31,6 +31,8 @@ pub mod web;
 pub mod windows;
 #[cfg(x11_platform)]
 pub mod x11;
+#[cfg(any(x11_platform, wayland_platform))]
+pub mod startup_notify;
 
 pub mod modifier_supplement;
 #[cfg(any(

src/platform/startup_notify.rs

@@ -0,0 +1,99 @@
+//! Window startup notification to handle window raising.
+//!
+//! The [`ActivationToken`] is essential to ensure that your newly
+//! created window will obtain the focus, otherwise the user could
+//! be requered to click on the window.
+//!
+//! Such token is usually delivered via the environment variable and
+//! could be read from it with the [`EventLoopExtStartupNotify::read_token_from_env`].
+//!
+//! Such token must also be reset after reading it from your environment with
+//! [`reset_activation_token_env`] otherwise child processes could inherit it.
+//!
+//! When starting a new child process with a newly obtained [`ActivationToken`] from
+//! [`WindowExtStartupNotify::request_activation_token`] the [`set_activation_token_env`]
+//! must be used to propagate it to the child
+//!
+//! To ensure the delivery of such token by other processes to you, the user should
+//! set `StartupNotify=true` inside the `.desktop` file of their application.
+//!
+//! The specification could be found [`here`].
+//!
+//! [`here`]: https://specifications.freedesktop.org/startup-notification-spec/startup-notification-latest.txt
+
+use std::env;
+
+use crate::error::NotSupportedError;
+use crate::event_loop::{AsyncRequestSerial, EventLoopWindowTarget};
+use crate::window::{ActivationToken, Window, WindowBuilder};
+
+/// The variable which is used mostly on X11.
+const X11_VAR: &str = "DESKTOP_STARTUP_ID";
+
+/// The variable which is used mostly on Wayland.
+const WAYLAND_VAR: &str = "XDG_ACTIVATION_TOKEN";
+
+pub trait EventLoopExtStartupNotify {
+    /// Read the token from the environment.
+    ///
+    /// It's recommended **to unset** this environment variable for child processes.
+    fn read_token_from_env(&self) -> Option<ActivationToken>;
+}
+
+pub trait WindowExtStartupNotify {
+    /// Request a new activation token.
+    ///
+    /// The token will be delivered inside
+    fn request_activation_token(&self) -> Result<AsyncRequestSerial, NotSupportedError>;
+}
+
+pub trait WindowBuilderExtStartupNotify {
+    /// Use this [`ActivationToken`] during window creation.
+    ///
+    /// Not using such a token upon a window could make your window not gaining
+    /// focus until the user clicks on the window.
+    fn with_activation_token(self, token: ActivationToken) -> Self;
+}
+
+impl<T> EventLoopExtStartupNotify for EventLoopWindowTarget<T> {
+    fn read_token_from_env(&self) -> Option<ActivationToken> {
+        match self.p {
+            #[cfg(wayland_platform)]
+            crate::platform_impl::EventLoopWindowTarget::Wayland(_) => env::var(WAYLAND_VAR),
+            #[cfg(x11_platform)]
+            crate::platform_impl::EventLoopWindowTarget::X(_) => env::var(X11_VAR),
+        }
+        .ok()
+        .map(ActivationToken::_new)
+    }
+}
+
+impl WindowExtStartupNotify for Window {
+    fn request_activation_token(&self) -> Result<AsyncRequestSerial, NotSupportedError> {
+        self.window.request_activation_token()
+    }
+}
+
+impl WindowBuilderExtStartupNotify for WindowBuilder {
+    fn with_activation_token(mut self, token: ActivationToken) -> Self {
+        self.platform_specific.activation_token = Some(token);
+        self
+    }
+}
+
+/// Remove the activation environment variables from the current process.
+///
+/// This is wise to do before running child processes,
+/// which may not to support the activation token.
+pub fn reset_activation_token_env() {
+    env::remove_var(X11_VAR);
+    env::remove_var(WAYLAND_VAR);
+}
+
+/// Set environment variables responsible for activation token.
+///
+/// This could be used before running daemon processes.
+pub fn set_activation_token_env(token: ActivationToken) {
+    env::set_var(X11_VAR, &token._token);
+    env::set_var(WAYLAND_VAR, token._token);
+}

src/platform_impl/linux/mod.rs

@@ -30,13 +30,16 @@ use crate::{
     dpi::{PhysicalPosition, PhysicalSize, Position, Size},
     error::{ExternalError, NotSupportedError, OsError as RootOsError},
     event::{Event, KeyEvent},
-    event_loop::{ControlFlow, DeviceEvents, EventLoopClosed, EventLoopWindowTarget as RootELW},
+    event_loop::{
+        AsyncRequestSerial, ControlFlow, DeviceEvents, EventLoopClosed,
+        EventLoopWindowTarget as RootELW,
+    },
     icon::Icon,
     keyboard::{Key, KeyCode},
     platform::{modifier_supplement::KeyEventExtModifierSupplement, scancode::KeyCodeExtScancode},
     window::{
-        CursorGrabMode, CursorIcon, ImePurpose, ResizeDirection, Theme, UserAttentionType,
-        WindowAttributes, WindowButtons, WindowLevel,
+        ActivationToken, CursorGrabMode, CursorIcon, ImePurpose, ResizeDirection, Theme,
+        UserAttentionType, WindowAttributes, WindowButtons, WindowLevel,
     },
 };
 
@@ -87,6 +90,7 @@ impl ApplicationName {
 #[derive(Clone)]
 pub struct PlatformSpecificWindowBuilderAttributes {
     pub name: Option<ApplicationName>,
+    pub activation_token: Option<ActivationToken>,
     #[cfg(x11_platform)]
     pub visual_infos: Option<XVisualInfo>,
     #[cfg(x11_platform)]
@@ -103,6 +107,7 @@ impl Default for PlatformSpecificWindowBuilderAttributes {
     fn default() -> Self {
         Self {
             name: None,
+            activation_token: None,
             #[cfg(x11_platform)]
             visual_infos: None,
             #[cfg(x11_platform)]
@@ -371,6 +376,11 @@ impl Window {
         x11_or_wayland!(match self; Window(w) => w.request_inner_size(size))
     }
 
+    #[inline]
+    pub(crate) fn request_activation_token(&self) -> Result<AsyncRequestSerial, NotSupportedError> {
+        x11_or_wayland!(match self; Window(w) => w.request_activation_token())
+    }
+
     #[inline]
     pub fn set_min_inner_size(&self, dimensions: Option<Size>) {
         x11_or_wayland!(match self; Window(w) => w.set_min_inner_size(dimensions))

src/platform_impl/linux/wayland/event_loop/mod.rs

@@ -17,9 +17,11 @@ use sctk::reexports::client::globals;
 use sctk::reexports::client::{Connection, Proxy, QueueHandle, WaylandSource};
 
 use crate::dpi::{LogicalSize, PhysicalSize};
+
 use crate::event::{Event, StartCause, WindowEvent};
 use crate::event_loop::{ControlFlow, EventLoopWindowTarget as RootEventLoopWindowTarget};
 use crate::platform_impl::platform::sticky_exit_callback;
+
 use crate::platform_impl::EventLoopWindowTarget as PlatformEventLoopWindowTarget;
 
 mod proxy;
@@ -29,6 +31,7 @@ pub use proxy::EventLoopProxy;
 use sink::EventSink;
 
 use super::state::{WindowCompositorUpdate, WinitState};
+
 use super::{DeviceId, WindowId};
 
 type WaylandDispatcher = calloop::Dispatcher<'static, WaylandSource<WinitState>, WinitState>;

src/platform_impl/linux/wayland/types/xdg_activation.rs

@@ -16,7 +16,10 @@ use sctk::reexports::protocols::xdg::activation::v1::client::xdg_activation_v1::
 
 use sctk::globals::GlobalData;
 
+use crate::event_loop::AsyncRequestSerial;
 use crate::platform_impl::wayland::state::WinitState;
+use crate::platform_impl::WindowId;
+use crate::window::ActivationToken;
 
 pub struct XdgActivationState {
     xdg_activation: XdgActivationV1,
@@ -62,41 +65,41 @@ impl Dispatch<XdgActivationTokenV1, XdgActivationTokenData, WinitState> for XdgA
             _ => return,
         };
 
-        state
+        let global = state
             .xdg_activation
             .as_ref()
             .expect("got xdg_activation event without global.")
-            .global()
-            .activate(token, &data.surface);
-
-        // Mark that no request attention is in process.
-        if let Some(attention_requested) = data.attention_requested.upgrade() {
-            attention_requested.store(false, std::sync::atomic::Ordering::Relaxed);
+            .global();
+
+        match data {
+            XdgActivationTokenData::Attention((surface, fence)) => {
+                global.activate(token, surface);
+                // Mark that no request attention is in process.
+                if let Some(attention_requested) = fence.upgrade() {
+                    attention_requested.store(false, std::sync::atomic::Ordering::Relaxed);
+                }
+            }
+            XdgActivationTokenData::Obtain((window_id, serial)) => {
+                state.events_sink.push_window_event(
+                    crate::event::WindowEvent::ActivationTokenDone {
+                        serial: *serial,
+                        token: ActivationToken::_new(token),
+                    },
+                    *window_id,
+                );
+            }
         }
 
         proxy.destroy();
     }
 }
 
 /// The data associated with the activation request.
-pub struct XdgActivationTokenData {
-    /// The surface we're raising.
-    surface: WlSurface,
-
-    /// Flag to throttle attention requests.
-    attention_requested: Weak<AtomicBool>,
-}
-
-impl XdgActivationTokenData {
-    /// Create a new data.
-    ///
-    /// The `attenteion_requested` is marked as `false` on complition.
-    pub fn new(surface: WlSurface, attention_requested: Weak<AtomicBool>) -> Self {
-        Self {
-            surface,
-            attention_requested,
-        }
-    }
+pub enum XdgActivationTokenData {
+    /// Request user attention for the given surface.
+    Attention((WlSurface, Weak<AtomicBool>)),
+    /// Get a token to be passed outside of the winit.
+    Obtain((WindowId, AsyncRequestSerial)),
 }
 
 delegate_dispatch!(WinitState: [ XdgActivationV1: GlobalData] => XdgActivationState);