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

This is needed when passing and getting token from the IPC to activate
the window.

src/changelog/unreleased.md

@@ -42,6 +42,7 @@ changelog entry.
 
 ### Added
 
+- `ActivationToken::from_raw` and `ActivationToken::into_raw`.
 - On X11, add a workaround for disabling IME on GNOME.
 
 ### Fixed

src/platform/startup_notify.rs

@@ -64,7 +64,7 @@ impl EventLoopExtStartupNotify for ActiveEventLoop {
             crate::platform_impl::ActiveEventLoop::X(_) => env::var(X11_VAR),
         }
         .ok()
-        .map(ActivationToken::_new)
+        .map(ActivationToken::from_raw)
     }
 }
 
@@ -94,6 +94,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(X11_VAR, &token.token);
-    env::set_var(WAYLAND_VAR, token._token);
+    env::set_var(WAYLAND_VAR, token.token);
 }

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

@@ -80,7 +80,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

@@ -168,7 +168,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

@@ -531,7 +531,7 @@ impl<T: 'static> EventLoop<T> {
                         window_id: crate::window::WindowId(window_id),
                         event: WindowEvent::ActivationTokenDone {
                             serial,
-                            token: crate::window::ActivationToken::_new(token),
+                            token: crate::window::ActivationToken::from_raw(token),
                         },
                     };
                     callback(event, &self.event_processor.target)

src/platform_impl/linux/x11/window.rs

@@ -559,7 +559,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

@@ -1850,11 +1850,34 @@ impl Default for ImePurpose {
 /// [`Window`]: crate::window::Window
 #[derive(Debug, PartialEq, Eq, Clone)]
 pub struct ActivationToken {
-    pub(crate) _token: String,
+    pub(crate) token: String,
 }
 
 impl ActivationToken {
-    pub(crate) fn _new(_token: String) -> Self {
+    /// Make an [`ActivationToken`] from a string.
-        Self { _token }
+    ///
+    /// 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
     }
 }