api: add ActivationToken::{from,into}_raw

src/changelog/unreleased.md

@@ -71,6 +71,7 @@ changelog entry.
 - Added `Window::safe_area`, which describes the area of the surface that is unobstructed.
 - On X11, Wayland, Windows and macOS, improved scancode conversions for more obscure key codes.
 - Add ability to make non-activating window on macOS using `NSPanel` with `NSWindowStyleMask::NonactivatingPanel`.
+- `ActivationToken::from_raw` and `ActivationToken::into_raw`.
 - On X11, add a workaround for disabling IME on GNOME.
 
 ### Changed

src/platform/startup_notify.rs

@@ -65,9 +65,9 @@ impl EventLoopExtStartupNotify for dyn ActiveEventLoop + '_ {
         let _is_wayland = self.is_wayland();
 
         if _is_wayland {
-            env::var(WAYLAND_VAR).ok().map(ActivationToken::_new)
+            env::var(WAYLAND_VAR).ok().map(ActivationToken::from_raw)
         } else {
-            env::var(X11_VAR).ok().map(ActivationToken::_new)
+            env::var(X11_VAR).ok().map(ActivationToken::from_raw)
         }
     }
 }
@@ -111,6 +111,6 @@ pub fn reset_activation_token_env() {
 ///
 /// 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);
+    env::set_var(X11_VAR, &token.token);
+    env::set_var(WAYLAND_VAR, token.token);
 }

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

@@ -78,7 +78,7 @@ impl Dispatch<XdgActivationTokenV1, XdgActivationTokenData, WinitState> for XdgA
                 state.events_sink.push_window_event(
                     crate::event::WindowEvent::ActivationTokenDone {
                         serial: *serial,
-                        token: ActivationToken::_new(token),
+                        token: ActivationToken::from_raw(token),
                     },
                     *window_id,
                 );

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

@@ -165,7 +165,7 @@ impl Window {
         if let (Some(xdg_activation), Some(token)) =
             (xdg_activation.as_ref(), attributes.platform_specific.activation_token)
         {
-            xdg_activation.activate(token._token, &surface);
+            xdg_activation.activate(token.token, &surface);
         }
 
         // XXX Do initial commit.

src/platform_impl/linux/x11/mod.rs

@@ -532,7 +532,7 @@ impl EventLoop {
                 Some(Ok(token)) => {
                     let event = WindowEvent::ActivationTokenDone {
                         serial,
-                        token: crate::window::ActivationToken::_new(token),
+                        token: crate::window::ActivationToken::from_raw(token),
                     };
                     app.window_event(&self.event_processor.target, window_id, event);
                 },

src/platform_impl/linux/x11/window.rs

@@ -880,7 +880,7 @@ impl UnownedWindow {
 
         // Remove the startup notification if we have one.
         if let Some(startup) = window_attrs.platform_specific.activation_token.as_ref() {
-            leap!(xconn.remove_activation_token(xwindow, &startup._token));
+            leap!(xconn.remove_activation_token(xwindow, &startup.token));
         }
 
         // We never want to give the user a broken window, since by then, it's too late to handle.

src/window.rs

@@ -1544,11 +1544,34 @@ impl Default for ImePurpose {
 /// [`Window`]: crate::window::Window
 #[derive(Debug, PartialEq, Eq, Clone, Hash)]
 pub struct ActivationToken {
-    pub(crate) _token: String,
+    pub(crate) token: String,
 }
 
 impl ActivationToken {
-    pub(crate) fn _new(_token: String) -> Self {
-        Self { _token }
+    /// Make an [`ActivationToken`] from a string.
+    ///
+    /// This method should be used to wrap tokens passed by side channels to your application, like
+    /// dbus.
+    ///
+    /// The validity of the token is ensured by the windowing system. Using the invalid token will
+    /// only result in the side effect of the operation involving it being ignored (e.g. window
+    /// won't get focused automatically), but won't yield any errors.
+    ///
+    /// To obtain a valid token, use
+    #[cfg_attr(any(x11_platform, wayland_platform, docsrs), doc = " [`request_activation_token`].")]
+    #[cfg_attr(
+        not(any(x11_platform, wayland_platform, docsrs)),
+        doc = " `request_activation_token`."
+    )]
+    ///
+    #[rustfmt::skip]
+    /// [`request_activation_token`]: crate::platform::startup_notify::WindowExtStartupNotify::request_activation_token
+    pub fn from_raw(token: String) -> Self {
+        Self { token }
+    }
+
+    /// Convert the token to its string representation to later pass via IPC.
+    pub fn into_raw(self) -> String {
+        self.token
     }
 }