feat: add the special action protocol client

Carries the device's special key — the HUMAIN button — from the compositor to
a window. The compositor owns the gesture, because the key is usually a
modifier it also needs for its own chords, and sends the resolved meaning
rather than the key.

`window::register_special_action(id, is_default)` registers a window, and
gestures arrive as `Event::SpecialAction`: `Activate` for a tap (focus your
input), `HoldStart`/`HoldEnd` around a hold (push-to-talk), `Cancel` when the
gesture is abandoned and anything captured should be discarded.

`is_default` also makes the window the fallback receiver, used whenever no
registered surface is focused.

Also bumps winit to 18bb0187, which carries the client bindings.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: Ericky Dos Santos

Cargo.lock

@@ -8,6 +8,7 @@ use crate::focus;
 use crate::input_method;
 use crate::keyboard;
 use crate::mouse;
+use crate::special_action;
 use crate::surface_visibility;
 use crate::touch;
 use crate::window;
@@ -35,6 +36,9 @@ pub enum Event {
     /// An input method event
     InputMethod(input_method::Event),
 
+    /// The device's special key was used while this surface was the receiver
+    SpecialAction(special_action::Event),
+
     /// An auto-hide visibility event from the compositor
     AutoHide(auto_hide::Event),
 

core/src/event.rs

@@ -29,6 +29,7 @@ pub mod mouse;
 pub mod overlay;
 pub mod padding;
 pub mod renderer;
+pub mod special_action;
 pub mod surface_visibility;
 pub mod svg;
 pub mod text;

core/src/lib.rs

@@ -0,0 +1,21 @@
+//! The device's special key, resolved by the compositor.
+//!
+//! The key — the HUMAIN button — is usually bound to a modifier the compositor
+//! also needs for its own chords, so only the compositor can tell a tap from
+//! the start of one. It resolves the gesture and sends the meaning rather than
+//! the key. Register a window with
+//! [`register_special_action`](crate::window::register_special_action) to
+//! receive these.
+
+/// A resolved gesture on the special key.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Event {
+    /// Tapped. Focus the text input; no voice is involved.
+    Activate,
+    /// A hold began. Start capturing audio.
+    HoldStart,
+    /// The hold ended. Stop capturing and process what was captured.
+    HoldEnd,
+    /// The gesture was abandoned. Discard any capture rather than process it.
+    Cancel,
+}

core/src/special_action.rs

@@ -253,6 +253,13 @@ pub enum Action {
 
     /// Enable or disable blur behind the window at runtime.
     SetBlur(Id, bool),
+
+    /// Register the window to receive the device's special key.
+    /// Parameters are (window_id, is_default_receiver).
+    RegisterSpecialAction(Id, bool),
+
+    /// Stop receiving the device's special key.
+    UnregisterSpecialAction(Id),
 }
 
 /// A window managed by iced.
@@ -332,6 +339,35 @@ pub fn close_requests() -> Subscription<Id> {
     })
 }
 
+/// Registers the window to receive the device's special key.
+///
+/// The compositor resolves the gesture and delivers it as
+/// [`Event::SpecialAction`](crate::core::Event::SpecialAction): a tap asks the
+/// window to focus its input, a hold brackets push-to-talk.
+///
+/// When `is_default_receiver` the window also becomes the fallback, used
+/// whenever no registered surface is focused. Only one fallback exists at a
+/// time; registering a second replaces the first.
+///
+/// ## Platform-specific
+/// - **COSMIC/Wayland:** Uses the `zcosmic_special_action_v1` protocol.
+/// - **Other platforms:** No effect.
+pub fn register_special_action<T>(id: Id, is_default_receiver: bool) -> Task<T> {
+    task::effect(crate::Action::Window(Action::RegisterSpecialAction(
+        id,
+        is_default_receiver,
+    )))
+}
+
+/// Stops the window receiving the device's special key.
+///
+/// ## Platform-specific
+/// - **COSMIC/Wayland:** Uses the `zcosmic_special_action_v1` protocol.
+/// - **Other platforms:** No effect.
+pub fn unregister_special_action<T>(id: Id) -> Task<T> {
+    task::effect(crate::Action::Window(Action::UnregisterSpecialAction(id)))
+}
+
 /// Opens a new window with the given [`Settings`]; producing the [`Id`]
 /// of the new window on completion.
 pub fn open(settings: Settings) -> (Id, Task<Id>) {

runtime/src/window.rs

@@ -636,6 +636,11 @@ pub mod touch {
     pub use crate::core::touch::{Event, Finger};
 }
 
+pub mod special_action {
+    //! Listen and react to the device's special key.
+    pub use crate::core::special_action::Event;
+}
+
 pub mod auto_hide {
     //! Listen and react to auto-hide visibility events from the compositor.
     pub use crate::core::auto_hide::Event;

src/lib.rs

@@ -5,6 +5,7 @@
 use crate::core::input_method;
 use crate::core::keyboard;
 use crate::core::mouse;
+use crate::core::special_action;
 use crate::core::theme;
 use crate::core::touch;
 use crate::core::window;
@@ -310,6 +311,9 @@ pub fn window_event(
             Some(Event::Window(window::Event::Rescaled(scale_factor as f32)))
         }
         WindowEvent::Dnd(dnd_event) => Some(Event::Dnd(dnd_window_event(dnd_event))),
+        WindowEvent::SpecialAction(action) => {
+            Some(Event::SpecialAction(special_action_event(action)))
+        }
         _ => None,
     }
 }
@@ -1153,6 +1157,28 @@ fn is_private_use(c: char) -> bool {
     ('\u{E000}'..='\u{F8FF}').contains(&c)
 }
 
+/// Converts a winit special action event into an iced one.
+#[cfg(all(
+    feature = "wayland",
+    any(
+        target_os = "linux",
+        target_os = "dragonfly",
+        target_os = "freebsd",
+        target_os = "netbsd",
+        target_os = "openbsd",
+    )
+))]
+fn special_action_event(event: winit::event::SpecialActionEvent) -> special_action::Event {
+    use winit::event::SpecialActionEvent;
+
+    match event {
+        SpecialActionEvent::Activate => special_action::Event::Activate,
+        SpecialActionEvent::HoldStart => special_action::Event::HoldStart,
+        SpecialActionEvent::HoldEnd => special_action::Event::HoldEnd,
+        SpecialActionEvent::Cancel => special_action::Event::Cancel,
+    }
+}
+
 /// Converts a winit DnD window event into an iced DnD event.
 fn dnd_window_event(event: winit::event::DndWindowEvent) -> crate::core::dnd::Event {
     use crate::core::dnd::{DndAction, Event as DndEvent, SourceEvent};

winit/src/conversion.rs

@@ -3017,6 +3017,42 @@ fn run_action<'a, P, C>(
                     window.raw.set_blur(blur);
                 }
             }
+            window::Action::RegisterSpecialAction(id, is_default) => {
+                #[cfg(all(
+                    feature = "wayland",
+                    any(
+                        target_os = "linux",
+                        target_os = "dragonfly",
+                        target_os = "freebsd",
+                        target_os = "netbsd",
+                        target_os = "openbsd",
+                    )
+                ))]
+                {
+                    use winit::platform::wayland::WindowExtWayland;
+                    if let Some(window) = window_manager.get_mut(id) {
+                        let _ = window.raw.register_special_action(is_default);
+                    }
+                }
+            }
+            window::Action::UnregisterSpecialAction(id) => {
+                #[cfg(all(
+                    feature = "wayland",
+                    any(
+                        target_os = "linux",
+                        target_os = "dragonfly",
+                        target_os = "freebsd",
+                        target_os = "netbsd",
+                        target_os = "openbsd",
+                    )
+                ))]
+                {
+                    use winit::platform::wayland::WindowExtWayland;
+                    if let Some(window) = window_manager.get_mut(id) {
+                        let _ = window.raw.unregister_special_action();
+                    }
+                }
+            }
         },
         Action::System(action) => match action {
             system::Action::GetInformation(_channel) => {