zng_ext_input/

gesture.rs

//! Aggregate events.
//!
//! Events this extension provides.
//!
//! * [`CLICK_EVENT`]
//! * [`SHORTCUT_EVENT`]
//!
//! Services this extension provides.
//!
//! * [`GESTURES`]

use parking_lot::Mutex;
use std::{
    collections::{HashMap, HashSet},
    convert::TryFrom,
    num::NonZeroU32,
    sync::Arc,
    time::Duration,
};
use zng_app::{
    APP, DInstant, HeadlessApp,
    access::{ACCESS_CLICK_EVENT, AccessClickArgs},
    event::{AnyEventArgs as _, Command, CommandScope, EVENTS, EventPropagationHandle, event, event_args},
    hn,
    shortcut::{
        CommandShortcutExt, GestureKey, KeyChord, KeyGesture, ModifierGesture, ModifiersState, Shortcut, ShortcutFilter, Shortcuts,
        shortcut,
    },
    view_process::raw_device_events::InputDeviceId,
    widget::{
        WidgetId,
        info::{HitTestInfo, InteractionPath, WidgetPath},
    },
    window::WindowId,
};
use zng_app_context::app_local;
use zng_env::on_process_start;
use zng_ext_window::WINDOWS;
use zng_handle::{Handle, HandleOwner, WeakHandle};
use zng_layout::unit::DipPoint;
use zng_var::{Var, var};
use zng_view_api::{
    keyboard::{Key, KeyCode, KeyLocation, KeyState, NativeKeyCode},
    mouse::MouseButton,
};

use crate::{
    focus::{FOCUS, FocusRequest, FocusTarget},
    keyboard::{HeadlessAppKeyboardExt, KEY_INPUT_EVENT, KeyInputArgs},
    mouse::{MOUSE_CLICK_EVENT, MouseClickArgs},
    touch::{TOUCH_LONG_PRESS_EVENT, TOUCH_TAP_EVENT, TouchLongPressArgs, TouchTapArgs},
};

/// Specific information from the source of a [`ClickArgs`].
#[derive(Debug, Clone, PartialEq)]
pub enum ClickArgsSource {
    /// Click event was generated by the [mouse click event](MOUSE_CLICK_EVENT).
    Mouse {
        /// Which mouse button generated the event.
        button: MouseButton,

        /// Position of the mouse in the window.
        position: DipPoint,

        /// Hit-test result for the mouse point in the window, at the moment the click event
        /// was generated.
        hits: HitTestInfo,
    },

    /// Click event was generated by the [touch tap event](TOUCH_TAP_EVENT) or [touch long press](TOUCH_LONG_PRESS_EVENT).
    Touch {
        /// Position of the touch point in the window.
        position: DipPoint,

        /// Hit-test result for the touch point in the window, at the moment the tap event
        /// was generated.
        hits: HitTestInfo,

        /// Is `true` if the source event was a tab, is `false` if the source event was long press.
        is_tap: bool,
    },

    /// Click event was generated by the [shortcut event](SHORTCUT_EVENT).
    Shortcut {
        /// The shortcut.
        shortcut: Shortcut,
        /// Kind of click represented by the `shortcut`.
        kind: ShortcutClick,
    },

    /// Click event was generated by [accessibility event](ACCESS_CLICK_EVENT).
    ///
    /// This is handled the same way as a `Shortcut` event.
    Access {
        /// Is `true` if the requested primary action, is `false` is requested context action.
        is_primary: bool,
    },
}

/// What kind of click a shortcut represents in a [`ClickArgsSource::Shortcut`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ShortcutClick {
    /// The shortcut represents a primary click on the focused widget.
    Primary,
    /// The shortcut represents a context click on the focused widget.
    Context,
}

event_args! {
    /// [`CLICK_EVENT`] arguments.
    ///
    /// [`CLICK_EVENT`]: crate::gesture::CLICK_EVENT
    pub struct ClickArgs {
        /// Id of window that received the event.
        pub window_id: WindowId,

        /// Id of device that generated the event.
        ///
        /// Is `None` if the event was generated programmatically.
        pub device_id: Option<InputDeviceId>,

        /// Specific info from the source of this event.
        pub source: ClickArgsSource,

        /// Sequential click count. Number `1` is single click, `2` is double click, etc.
        ///
        /// Mouse clicks are translated directly, keyboard clicks are the key repeat count plus one.
        pub click_count: NonZeroU32,

        /// If the event was auto-generated by holding the key or button pressed.
        pub is_repeat: bool,

        /// What modifier keys where pressed when this event happened.
        pub modifiers: ModifiersState,

        /// The mouse input top-most hit or the focused element at the time of the key input.
        pub target: InteractionPath,

        ..

        /// If is in [`target`].
        ///
        /// [`target`]: Self::target
        fn is_in_target(&self, id: WidgetId) -> bool {
            self.target.contains(id)
        }
    }

    /// [`SHORTCUT_EVENT`] arguments.
    pub struct ShortcutArgs {
        /// Id of window that received the event.
        pub window_id: WindowId,

        /// Id of device that generated the event.
        ///
        /// Is `None` if the event was generated programmatically.
        pub device_id: Option<InputDeviceId>,

        /// The shortcut.
        pub shortcut: Shortcut,

        /// Number of repeats generated by holding the key pressed.
        ///
        /// This is zero for the first key press, increments by one for each event while the key is held pressed.
        pub repeat_count: u32,

        /// Actions that will run if this event propagation is not stopped.
        pub actions: ShortcutActions,

        ..

        /// No target, only app extensions.
        fn is_in_target(&self, _id: WidgetId) -> bool {
            false
        }
    }
}
impl From<MouseClickArgs> for ClickArgs {
    fn from(args: MouseClickArgs) -> Self {
        ClickArgs::new(
            args.timestamp,
            args.propagation.clone(),
            args.window_id,
            args.device_id,
            ClickArgsSource::Mouse {
                button: args.button,
                position: args.position,
                hits: args.hits,
            },
            args.click_count,
            args.is_repeat,
            args.modifiers,
            args.target,
        )
    }
}
impl From<TouchTapArgs> for ClickArgs {
    fn from(args: TouchTapArgs) -> Self {
        ClickArgs::new(
            args.timestamp,
            args.propagation.clone(),
            args.window_id,
            args.device_id,
            ClickArgsSource::Touch {
                position: args.position,
                hits: args.hits,
                is_tap: true,
            },
            args.tap_count,
            false,
            args.modifiers,
            args.target,
        )
    }
}
impl From<TouchLongPressArgs> for ClickArgs {
    fn from(args: TouchLongPressArgs) -> Self {
        ClickArgs::new(
            args.timestamp,
            args.propagation.clone(),
            args.window_id,
            args.device_id,
            ClickArgsSource::Touch {
                position: args.position,
                hits: args.hits,
                is_tap: false,
            },
            NonZeroU32::new(1).unwrap(),
            false,
            args.modifiers,
            args.target,
        )
    }
}
impl ClickArgs {
    /// If the event counts as *primary* click.
    ///
    /// A primary click causes the default widget function interaction.
    ///
    /// Returns `true` if the click source is a left mouse button click or a
    /// [primary click shortcut](GESTURES::click_focused) or a touch tap.
    pub fn is_primary(&self) -> bool {
        match &self.source {
            ClickArgsSource::Mouse { button, .. } => *button == MouseButton::Left,
            ClickArgsSource::Touch { is_tap, .. } => *is_tap,
            ClickArgsSource::Shortcut { kind, .. } => *kind == ShortcutClick::Primary,
            ClickArgsSource::Access { is_primary } => *is_primary,
        }
    }

    /// If the event counts as a *context menu* request.
    ///
    /// Returns `true` if the [`click_count`](Self::click_count) is `1` and the
    /// click source is a right mouse button click or a [context click shortcut](GESTURES::context_click_focused)
    /// or a touch long press.
    pub fn is_context(&self) -> bool {
        self.click_count.get() == 1
            && match &self.source {
                ClickArgsSource::Mouse { button, .. } => *button == MouseButton::Right,
                ClickArgsSource::Touch { is_tap, .. } => !*is_tap,
                ClickArgsSource::Shortcut { kind, .. } => *kind == ShortcutClick::Context,
                ClickArgsSource::Access { is_primary } => !*is_primary,
            }
    }

    /// If the event was caused by a press of `mouse_button`.
    pub fn is_mouse_btn(&self, mouse_button: MouseButton) -> bool {
        match &self.source {
            ClickArgsSource::Mouse { button, .. } => *button == mouse_button,
            _ => false,
        }
    }

    /// The shortcut the generated this event.
    pub fn shortcut(&self) -> Option<Shortcut> {
        match &self.source {
            ClickArgsSource::Shortcut { shortcut, .. } => Some(shortcut.clone()),
            _ => None,
        }
    }

    /// If the [`click_count`](Self::click_count) is `1`.
    pub fn is_single(&self) -> bool {
        self.click_count.get() == 1
    }

    /// If the [`click_count`](Self::click_count) is `2`.
    pub fn is_double(&self) -> bool {
        self.click_count.get() == 2
    }

    /// If the [`click_count`](Self::click_count) is `3`.
    pub fn is_triple(&self) -> bool {
        self.click_count.get() == 3
    }

    /// If this event was generated by a mouse device.
    pub fn is_from_mouse(&self) -> bool {
        matches!(&self.source, ClickArgsSource::Mouse { .. })
    }

    /// If this event was generated by a touch device.
    pub fn is_from_touch(&self) -> bool {
        matches!(&self.source, ClickArgsSource::Touch { .. })
    }

    /// If this event was generated by a keyboard device.
    pub fn is_from_keyboard(&self) -> bool {
        matches!(&self.source, ClickArgsSource::Shortcut { .. })
    }

    /// If this event was generated by accessibility automation event.
    ///
    /// Note that accessibility assistants can also simulate mouse click events, these events
    /// are not classified as accessibility sourced.
    pub fn is_from_access(&self) -> bool {
        matches!(&self.source, ClickArgsSource::Access { .. })
    }

    /// Gets the click position, if the click was generated by a device with position.
    ///
    /// The position is in the coordinates of [`target`](ClickArgs::target).
    pub fn position(&self) -> Option<DipPoint> {
        match &self.source {
            ClickArgsSource::Mouse { position, .. } => Some(*position),
            ClickArgsSource::Touch { position, .. } => Some(*position),
            ClickArgsSource::Shortcut { .. } | ClickArgsSource::Access { .. } => None,
        }
    }
}

event! {
    /// Aggregate click event.
    ///
    /// Can be a mouse click, a shortcut press or a touch tap.
    pub static CLICK_EVENT: ClickArgs {
        let _ = GESTURES_SV.read();
    };

    /// Shortcut input event.
    ///
    /// Event happens every time a full [`Shortcut`] is completed by key press.
    ///
    /// This event is not send to any widget, use the [`GESTURES`] service to setup widget targets for shortcuts.
    ///
    /// [`Shortcut`]: zng_app::shortcut::Shortcut
    pub static SHORTCUT_EVENT: ShortcutArgs {
        let _ = GESTURES_SV.read();
    };
}

fn hooks() {
    // Generate click events from mouse clicks.
    MOUSE_CLICK_EVENT
        .hook(|args| {
            CLICK_EVENT.notify(args.clone().into());
            true
        })
        .perm();
    // Generate click events from taps.
    TOUCH_TAP_EVENT
        .hook(|args| {
            CLICK_EVENT.notify(args.clone().into());
            true
        })
        .perm();

    // Generate shortcut events from keyboard input.
    KEY_INPUT_EVENT
        .hook(|args| {
            GESTURES_SV.write().on_key_input(args);
            true
        })
        .perm();

    // Generate click events from touch long press.
    TOUCH_LONG_PRESS_EVENT
        .hook(|args| {
            CLICK_EVENT.notify(args.clone().into());
            true
        })
        .perm();

    // Run access click.
    ACCESS_CLICK_EVENT
        .hook(|args| {
            GESTURES_SV.write().on_access(args);
            true
        })
        .perm();

    // Run shortcut actions.
    SHORTCUT_EVENT
        .hook(|args| {
            GESTURES_SV.write().on_shortcut(args);
            true
        })
        .perm();
}

app_local! {
    static GESTURES_SV: GesturesService = {
        hooks();
        GesturesService::new()
    };
}

struct GesturesService {
    click_focused: Var<Shortcuts>,
    context_click_focused: Var<Shortcuts>,
    shortcut_pressed_duration: Var<Duration>,

    pressed_modifier: Option<(WindowId, ModifierGesture)>,
    primed_starter: Option<KeyGesture>,
    chords: HashMap<KeyGesture, HashSet<KeyGesture>>,

    primary_clicks: Vec<(Shortcut, Arc<ShortcutTarget>)>,
    context_clicks: Vec<(Shortcut, Arc<ShortcutTarget>)>,
    focus: Vec<(Shortcut, Arc<ShortcutTarget>)>,
}
impl GesturesService {
    fn new() -> Self {
        Self {
            click_focused: var([shortcut!(Enter), shortcut!(Space)].into()),
            context_click_focused: var([shortcut!(ContextMenu)].into()),
            shortcut_pressed_duration: var(Duration::from_millis(50)),

            pressed_modifier: None,
            primed_starter: None,
            chords: HashMap::default(),

            primary_clicks: vec![],
            context_clicks: vec![],
            focus: vec![],
        }
    }

    fn register_target(&mut self, shortcuts: Shortcuts, kind: Option<ShortcutClick>, target: WidgetId) -> ShortcutsHandle {
        if shortcuts.is_empty() {
            return ShortcutsHandle::dummy();
        }

        let (owner, handle) = ShortcutsHandle::new();
        let target = Arc::new(ShortcutTarget {
            widget_id: target,
            last_found: Mutex::new(None),
            handle: owner,
        });

        let collection = match kind {
            Some(ShortcutClick::Primary) => &mut self.primary_clicks,
            Some(ShortcutClick::Context) => &mut self.context_clicks,
            None => &mut self.focus,
        };

        if collection.len() > 500 {
            collection.retain(|(_, e)| !e.handle.is_dropped());
        }

        for s in shortcuts.0 {
            if let Shortcut::Chord(c) = &s {
                self.chords.entry(c.starter.clone()).or_default().insert(c.complement.clone());
            }

            collection.push((s, target.clone()));
        }

        handle
    }

    fn on_key_input(&mut self, args: &KeyInputArgs) {
        let key = args.shortcut_key();
        if !args.propagation.is_stopped() && !matches!(key, Key::Unidentified) {
            match args.state {
                KeyState::Pressed => {
                    if let Ok(gesture_key) = GestureKey::try_from(key.clone()) {
                        self.on_shortcut_pressed(Shortcut::Gesture(KeyGesture::new(args.modifiers, gesture_key)), args);
                        self.pressed_modifier = None;
                    } else if let Ok(mod_gesture) = ModifierGesture::try_from(key) {
                        if args.repeat_count == 0 {
                            self.pressed_modifier = Some((args.target.window_id(), mod_gesture));
                        }
                    } else {
                        self.pressed_modifier = None;
                        self.primed_starter = None;
                    }
                }
                KeyState::Released => {
                    if let Ok(mod_gesture) = ModifierGesture::try_from(key)
                        && let Some((window_id, gesture)) = self.pressed_modifier.take()
                        && args.modifiers.is_empty()
                        && window_id == args.target.window_id()
                        && mod_gesture == gesture
                    {
                        self.on_shortcut_pressed(Shortcut::Modifier(mod_gesture), args);
                    }
                }
            }
        } else {
            // Scancode only or already handled.
            self.primed_starter = None;
            self.pressed_modifier = None;
        }
    }
    fn on_shortcut_pressed(&mut self, mut shortcut: Shortcut, key_args: &KeyInputArgs) {
        if let Some(starter) = self.primed_starter.take()
            && let Shortcut::Gesture(g) = &shortcut
            && let Some(complements) = self.chords.get(&starter)
            && complements.contains(g)
        {
            shortcut = Shortcut::Chord(KeyChord {
                starter,
                complement: g.clone(),
            });
        }

        let actions = ShortcutActions::new(self, shortcut.clone());

        SHORTCUT_EVENT.notify(ShortcutArgs::new(
            key_args.timestamp,
            key_args.propagation.clone(),
            key_args.window_id,
            key_args.device_id,
            shortcut,
            key_args.repeat_count,
            actions,
        ));
    }

    fn on_shortcut(&mut self, args: &ShortcutArgs) {
        if args.actions.has_actions() {
            tracing::trace!("shortcut pressed {:?}", &args.shortcut);
            args.actions
                .run(args.timestamp, args.propagation(), args.device_id, args.repeat_count);
        } else if let Shortcut::Gesture(k) = &args.shortcut
            && self.chords.contains_key(k)
        {
            tracing::trace!("shortcut primed chord {k:?}");
            self.primed_starter = Some(k.clone());
        }
    }

    fn on_access(&mut self, args: &AccessClickArgs) {
        if let Some(tree) = WINDOWS.widget_tree(args.target.window_id())
            && let Some(wgt) = tree.get(args.target.widget_id())
        {
            let path = wgt.interaction_path();
            if !path.interactivity().is_blocked() {
                let args = ClickArgs::now(
                    args.target.window_id(),
                    None,
                    ClickArgsSource::Access {
                        is_primary: args.is_primary,
                    },
                    NonZeroU32::new(1).unwrap(),
                    false,
                    ModifiersState::empty(),
                    path,
                );
                CLICK_EVENT.notify(args);
            }
        }
    }

    fn cleanup(&mut self) {
        self.primary_clicks.retain(|(_, e)| !e.handle.is_dropped());
        self.context_clicks.retain(|(_, e)| !e.handle.is_dropped());
        self.focus.retain(|(_, e)| !e.handle.is_dropped());
    }
}

/// Gesture events config service.
///
/// # Shortcuts
///
/// This service coordinates shortcut associations with widgets and commands. To define a command's shortcut use
/// the [`CommandShortcutExt`] methods. To define the shortcut that *focus* and *clicks* a widget use [`click_shortcut`].
/// To define the shortcut that only focuses on a widget use [`focus_shortcut`]. To define a custom handle for a shortcut
/// use [`on_pre_event`] or [`on_event`] with the [`SHORTCUT_EVENT`].
///
/// ## Event Order
///
/// The same shortcut can end-up registered for multiple targets, activation of a shortcut causes these effects in this order:
///
/// 0. The gestures manager receives a [`KEY_INPUT_EVENT`] in the [`event`] track, if a shortcut is completed it gets combined with
///    any primed chords and become the shortcut that will cause the following actions:
///
/// 1. The click, command and focus shortcuts are resolved in this order:
///
///    **First exclusively**:
///    
///    * Primary [`click_shortcut`] targeting a widget that is enabled and focused.
///    * Command scoped in a widget that is enabled and focused.
///    * Contextual [`click_shortcut`] targeting a widget that is enabled and focused.
///    * Primary, command scoped or contextual targeting a widget that is enabled and closest to the focused widget,
///      child first (of the focused).
///    * Primary, command scoped or contextual targeting a widget that is enabled in the focused window.
///    * Primary, command scoped or contextual targeting a widget that is enabled.
///    * [`focus_shortcut`] targeting a widget that is in the focused window.
///    * [`focus_shortcut`] targeting a widget that is enabled.
///    * The [`click_focused`] and [`context_click_focused`].
///    * *Same as the above, but for disabled widgets*
///
///     **And then:**
///
///    a. All enabled commands targeting the focused window.
///
///    b. All enabled commands targeting the app.
///
/// 2. The app level [`SHORTCUT_EVENT`] is notified, with the list of actions that will run, app extensions can handle it before [`event`]
///    to stop the resolved actions.
///
/// 3. The gestures manager receives the shortcut in [`event`], if propagation is not stopped and it contains any actions they are run,
///    the click and command events are linked by the same propagation. If the shortcut contains no action and it
///
/// 3. If the shortcut is a [`KeyChord::starter`] for one of the registered shortcuts, and was not claimed by
///    any of the above, the chord starter is primed for the next shortcut press.
///
/// The event propagation flag of shortcut, click and command events are linked, so stopping [`propagation`] in one signal
/// all others.
///
///
/// [`click_focused`]: Self::click_focused
/// [`context_click_focused`]: Self::context_click_focused
/// [`click_shortcut`]: Self::click_shortcut
/// [`focus_shortcut`]: Self::focus_shortcut
/// [`on_pre_event`]: zng_app::event::Event::on_pre_event
/// [`on_event`]: zng_app::event::Event::on_event
/// [`BLOCKED`]: zng_app::widget::info::Interactivity::BLOCKED
/// [`propagation`]: zng_app::event::AnyEventArgs::propagation
/// [`KeyChord::starter`]: zng_app::shortcut::KeyChord::starter
/// [`CommandShortcutExt`]: zng_app::shortcut::CommandShortcutExt
pub struct GESTURES;
struct ShortcutTarget {
    widget_id: WidgetId,
    last_found: Mutex<Option<WidgetPath>>,
    handle: HandleOwner<()>,
}
impl ShortcutTarget {
    fn resolve_path(&self) -> Option<InteractionPath> {
        let mut found = self.last_found.lock();
        if let Some(found) = &mut *found
            && let Some(tree) = WINDOWS.widget_tree(found.window_id())
            && let Some(w) = tree.get(found.widget_id())
        {
            let path = w.interaction_path();
            *found = path.as_path().clone();

            return path.unblocked();
        }

        if let Some(w) = WINDOWS.widget_info(self.widget_id) {
            let path = w.interaction_path();
            *found = Some(path.as_path().clone());

            return path.unblocked();
        }

        None
    }
}
impl GESTURES {
    /// Shortcuts that generate a primary [`CLICK_EVENT`] for the focused widget.
    /// The shortcut only works if no widget or command claims it.
    ///
    /// Clicks generated by this shortcut count as [primary](ClickArgs::is_primary).
    ///
    /// Initial shortcuts are [`Enter`](Key::Enter) and [`Space`](Key::Space).
    pub fn click_focused(&self) -> Var<Shortcuts> {
        GESTURES_SV.read().click_focused.clone()
    }

    /// Shortcuts that generate a context [`CLICK_EVENT`] for the focused widget.
    /// The shortcut only works if no widget or command claims it.
    ///
    /// Clicks generated by this shortcut count as [context](ClickArgs::is_context).
    ///
    /// Initial shortcut is [`ContextMenu`](Key::ContextMenu).
    pub fn context_click_focused(&self) -> Var<Shortcuts> {
        GESTURES_SV.read().context_click_focused.clone()
    }

    /// When a shortcut or access primary click happens, targeted widgets can indicate that
    /// they are pressed for this duration.
    ///
    /// Initial value is `50ms`, set to `0` to deactivate this type of indication.
    pub fn shortcut_pressed_duration(&self) -> Var<Duration> {
        GESTURES_SV.read().shortcut_pressed_duration.clone()
    }

    /// Register a widget to receive shortcut clicks when any of the `shortcuts` are pressed.
    pub fn click_shortcut(&self, shortcuts: impl Into<Shortcuts>, kind: ShortcutClick, target: WidgetId) -> ShortcutsHandle {
        GESTURES_SV.write().register_target(shortcuts.into(), Some(kind), target)
    }

    /// Register a widget to receive keyboard focus when any of the `shortcuts` are pressed.
    ///
    /// If the widget is not focusable the focus moves to the first focusable descendant or the first focusable ancestor.
    pub fn focus_shortcut(&self, shortcuts: impl Into<Shortcuts>, target: WidgetId) -> ShortcutsHandle {
        GESTURES_SV.write().register_target(shortcuts.into(), None, target)
    }

    /// Gets all the event notifications that are send if the `shortcut` was pressed at this moment.
    ///
    /// See the [struct] level docs for details of how shortcut targets are resolved.
    ///
    /// [struct]: Self
    pub fn shortcut_actions(&self, shortcut: Shortcut) -> ShortcutActions {
        ShortcutActions::new(&mut GESTURES_SV.write(), shortcut)
    }
}

/// Represents the resolved targets for a shortcut at a time.
///
/// You can use the [`GESTURES.shortcut_actions`] method to get a value of this.
///
/// [`GESTURES.shortcut_actions`]: GESTURES::shortcut_actions
#[derive(Debug, Clone, PartialEq)]
pub struct ShortcutActions {
    shortcut: Shortcut,

    focus: Option<WidgetId>,
    click: Option<(InteractionPath, ShortcutClick)>,
    commands: Vec<Command>,
}
impl ShortcutActions {
    fn new(gestures: &mut GesturesService, shortcut: Shortcut) -> ShortcutActions {
        //    **First exclusively**:
        //
        //    * Primary [`click_shortcut`] targeting a widget that is enabled and focused.
        //    * Command scoped in a widget that is enabled and focused.
        //    * Contextual [`click_shortcut`] targeting a widget that is enabled and focused.
        //    * Primary, command scoped or contextual targeting a widget that is enabled and closest to the focused widget,
        //      child first (of the focused).
        //    * Primary, command scoped or contextual targeting a widget that is enabled in the focused window.
        //    * Primary, command scoped or contextual targeting a widget that is enabled.
        //    * [`focus_shortcut`] targeting a widget that is in the focused window.
        //    * [`focus_shortcut`] targeting a widget that is enabled.
        //    * The [`click_focused`] and [`context_click_focused`].
        //    * *Same as the above, but for disabled widgets*
        //
        //     **And then:**
        //
        //    a. All enabled commands targeting the focused window.
        //
        //    b. All enabled commands targeting the app.

        let focused = FOCUS.focused().get();

        enum Kind {
            Click(InteractionPath, ShortcutClick),
            Command(InteractionPath, Command),
            Focus(InteractionPath),
        }
        impl Kind {
            fn kind_key(&self) -> u8 {
                match self {
                    Kind::Click(p, s) => {
                        if p.interactivity().is_enabled() {
                            match s {
                                ShortcutClick::Primary => 0,
                                ShortcutClick::Context => 2,
                            }
                        } else {
                            match s {
                                ShortcutClick::Primary => 10,
                                ShortcutClick::Context => 12,
                            }
                        }
                    }
                    Kind::Command(p, _) => {
                        if p.interactivity().is_enabled() {
                            1
                        } else {
                            11
                        }
                    }
                    Kind::Focus(p) => {
                        if p.interactivity().is_enabled() {
                            4
                        } else {
                            14
                        }
                    }
                }
            }
        }

        fn distance_key(focused: &Option<InteractionPath>, p: &InteractionPath) -> u32 {
            let mut key = u32::MAX - 1;
            if let Some(focused) = focused
                && p.window_id() == focused.window_id()
            {
                key -= 1;
                if let Some(i) = p.widgets_path().iter().position(|&id| id == focused.widget_id()) {
                    // is descendant of focused (or it)
                    key = (p.widgets_path().len() - i) as u32;
                } else if let Some(i) = focused.widgets_path().iter().position(|&id| id == p.widget_id()) {
                    // is ancestor of focused
                    key = key / 2 + (focused.widgets_path().len() - i) as u32;
                }
            }
            key
        }

        let mut some_primary_dropped = false;
        let primary_click_matches = gestures.primary_clicks.iter().filter_map(|(s, entry)| {
            if entry.handle.is_dropped() {
                some_primary_dropped = true;
                return None;
            }
            if *s != shortcut {
                return None;
            }

            let p = entry.resolve_path()?;
            Some((distance_key(&focused, &p), Kind::Click(p, ShortcutClick::Primary)))
        });

        let mut some_ctx_dropped = false;
        let context_click_matches = gestures.context_clicks.iter().filter_map(|(s, entry)| {
            if entry.handle.is_dropped() {
                some_ctx_dropped = true;
                return None;
            }
            if *s != shortcut {
                return None;
            }

            let p = entry.resolve_path()?;
            Some((distance_key(&focused, &p), Kind::Click(p, ShortcutClick::Context)))
        });

        let mut some_focus_dropped = false;
        let focus_matches = gestures.focus.iter().filter_map(|(s, entry)| {
            if entry.handle.is_dropped() {
                some_focus_dropped = true;
                return None;
            }
            if *s != shortcut {
                return None;
            }

            let p = entry.resolve_path()?;
            Some((distance_key(&focused, &p), Kind::Focus(p)))
        });

        let mut cmd_window = vec![];
        let mut cmd_app = vec![];
        let cmd_matches = EVENTS.commands().into_iter().filter_map(|cmd| {
            if !cmd.shortcut_matches(&shortcut) {
                return None;
            }

            match cmd.scope() {
                CommandScope::Window(w) => {
                    if let Some(f) = &focused
                        && f.window_id() == w
                    {
                        cmd_window.push(cmd);
                    }
                }
                CommandScope::Widget(id) => {
                    if let Some(info) = WINDOWS.widget_info(id) {
                        let p = info.interaction_path();
                        return Some((distance_key(&focused, &p), Kind::Command(p, cmd)));
                    }
                }
                CommandScope::App => cmd_app.push(cmd),
            }

            None
        });

        let mut best_kind = u8::MAX;
        let mut best_distance = u32::MAX;
        let mut best = None;

        for (distance_key, choice) in primary_click_matches
            .chain(cmd_matches)
            .chain(context_click_matches)
            .chain(focus_matches)
        {
            let kind_key = choice.kind_key();
            match kind_key.cmp(&best_kind) {
                std::cmp::Ordering::Less => {
                    best_kind = kind_key;
                    best_distance = distance_key;
                    best = Some(choice);
                }
                std::cmp::Ordering::Equal => {
                    if distance_key < best_distance {
                        best_distance = distance_key;
                        best = Some(choice);
                    }
                }
                std::cmp::Ordering::Greater => {}
            }
        }

        let mut click = None;
        let mut focus = None;
        let mut commands = vec![];

        match best {
            Some(k) => match k {
                Kind::Click(p, s) => click = Some((p, s)),
                Kind::Command(_, cmd) => commands.push(cmd),
                Kind::Focus(p) => focus = Some(p.widget_id()),
            },
            None => {
                if let Some(p) = focused {
                    click = if gestures.click_focused.with(|c| c.contains(&shortcut)) {
                        Some((p, ShortcutClick::Primary))
                    } else if gestures.context_click_focused.with(|c| c.contains(&shortcut)) {
                        Some((p, ShortcutClick::Context))
                    } else {
                        None
                    };
                }
            }
        }

        commands.append(&mut cmd_window);
        commands.append(&mut cmd_app);

        if some_primary_dropped || some_ctx_dropped || some_focus_dropped {
            gestures.cleanup();
        }

        Self {
            shortcut,
            focus,
            click,
            commands,
        }
    }

    /// The shortcut.
    pub fn shortcut(&self) -> &Shortcut {
        &self.shortcut
    }

    /// Focus target.
    ///
    /// If `click` is some, this is a direct focus request to it, or if the first command is scoped on a widget this
    /// is a direct focus request on the scope, or if this is some it is a direct or related request to the focus shortcut target.
    pub fn focus(&self) -> Option<FocusTarget> {
        if let Some((p, _)) = &self.click {
            return Some(FocusTarget::Direct { target: p.widget_id() });
        } else if let Some(c) = self.commands.first()
            && let CommandScope::Widget(w) = c.scope()
            && FOCUS.focused().with(|f| f.as_ref().map(|p| !p.contains(w)).unwrap_or(true))
        {
            return Some(FocusTarget::Direct { target: w });
        }
        self.focus.map(|target| FocusTarget::DirectOrRelated {
            target,
            navigation_origin: true,
        })
    }

    /// Click target and kind.
    pub fn click(&self) -> Option<(&InteractionPath, ShortcutClick)> {
        self.click.as_ref().map(|(p, k)| (p, *k))
    }

    /// Commands.
    ///
    /// Only the first command may be scoped in a widget, others are scoped on the focused window or app.
    pub fn commands(&self) -> &[Command] {
        &self.commands
    }

    /// If any action was found for the shortcut.
    pub fn has_actions(&self) -> bool {
        self.click.is_some() || self.focus.is_some() || !self.commands.is_empty()
    }

    /// Send all events and focus request.
    fn run(&self, timestamp: DInstant, propagation: &EventPropagationHandle, device_id: Option<InputDeviceId>, repeat_count: u32) {
        if let Some(target) = self.focus() {
            tracing::trace!("shortcut focus {target:?}");
            FOCUS.focus(FocusRequest::new(target, true));
        }

        if let Some((target, kind)) = &self.click {
            tracing::trace!("shortcut click {target:?} {kind:?}");
            let args = ClickArgs::new(
                timestamp,
                propagation.clone(),
                target.window_id(),
                device_id,
                ClickArgsSource::Shortcut {
                    shortcut: self.shortcut.clone(),
                    kind: *kind,
                },
                NonZeroU32::new(repeat_count.saturating_add(1)).unwrap(),
                repeat_count > 0,
                self.shortcut.modifiers_state(),
                target.clone(),
            );
            CLICK_EVENT.notify(args);
        }
        for command in &self.commands {
            tracing::trace!("shortcut cmd {:?}", command);
            command.notify_linked(propagation.clone(), None);
        }
    }
}

/// Represents shortcuts claim in [`click_shortcut`] or [`focus_shortcut`].
///
/// [`click_shortcut`]: GESTURES::click_shortcut
/// [`focus_shortcut`]: GESTURES::focus_shortcut
#[derive(Clone, PartialEq, Eq, Hash, Debug)]
#[repr(transparent)]
#[must_use = "the shortcuts claim is removed if the handle is dropped"]
pub struct ShortcutsHandle(Handle<()>);
impl ShortcutsHandle {
    pub(super) fn new() -> (HandleOwner<()>, Self) {
        let (owner, handle) = Handle::new(());
        (owner, ShortcutsHandle(handle))
    }

    /// Create dummy handle that is always in the *released* state.
    ///
    /// Note that `Option<ShortcutsHandle>` takes up the same space as `ShortcutsHandle` and avoids an allocation.
    pub fn dummy() -> Self {
        ShortcutsHandle(Handle::dummy(()))
    }

    /// Drops the handle but does **not** release.
    ///
    /// The claim stays registered for the duration of the app or until another handle calls [`release`](Self::release).
    /// Note that shortcut claims only work if the target widget is found and is not [`BLOCKED`].
    ///
    /// [`BLOCKED`]: zng_app::widget::info::Interactivity::BLOCKED
    pub fn perm(self) {
        self.0.perm();
    }

    /// If another handle has called [`perm`](Self::perm).
    ///
    /// If `true` the claim will stay active until the app exits, unless [`release`](Self::release) is called.
    pub fn is_permanent(&self) -> bool {
        self.0.is_permanent()
    }

    /// Drops the handle and releases the claim
    pub fn release(self) {
        self.0.force_drop();
    }

    /// If another handle has called [`release`](Self::release).
    ///
    /// The claim is already dropped or will be dropped in the next app update, this is irreversible.
    pub fn is_released(&self) -> bool {
        self.0.is_dropped()
    }

    /// Create a weak handle.
    pub fn downgrade(&self) -> WeakShortcutsHandle {
        WeakShortcutsHandle(self.0.downgrade())
    }
}

/// Weak [`ShortcutsHandle`].
#[derive(Clone, PartialEq, Eq, Hash, Default, Debug)]
pub struct WeakShortcutsHandle(pub(super) WeakHandle<()>);
impl WeakShortcutsHandle {
    /// New weak handle that does not upgrade.
    pub fn new() -> Self {
        Self(WeakHandle::new())
    }

    /// Get the shortcuts handle if it is still installed.
    pub fn upgrade(&self) -> Option<ShortcutsHandle> {
        self.0.upgrade().map(ShortcutsHandle)
    }
}

/// Extension trait that adds gesture simulation methods to [`HeadlessApp`].
///
/// [`HeadlessApp`]: zng_app::HeadlessApp
pub trait HeadlessAppGestureExt {
    /// Generates key press events to mimic the shortcut and updates.
    fn press_shortcut(&mut self, window_id: WindowId, shortcut: impl Into<Shortcut>);
}
impl HeadlessAppGestureExt for HeadlessApp {
    fn press_shortcut(&mut self, window_id: WindowId, shortcut: impl Into<Shortcut>) {
        let shortcut = shortcut.into();
        match shortcut {
            Shortcut::Modifier(m) => {
                let (code, key) = m.left_key();
                self.press_key(window_id, code, KeyLocation::Standard, key);
            }
            Shortcut::Gesture(g) => match g.key {
                GestureKey::Key(k) => self.press_modified_key(
                    window_id,
                    g.modifiers,
                    KeyCode::Unidentified(NativeKeyCode::Unidentified),
                    KeyLocation::Standard,
                    k,
                ),
                GestureKey::Code(c) => self.press_modified_key(window_id, g.modifiers, c, KeyLocation::Standard, Key::Unidentified),
            },
            Shortcut::Chord(c) => {
                self.press_shortcut(window_id, c.starter);
                self.press_shortcut(window_id, c.complement);
            }
        }
    }
}

/// Adds the `shortcut_matches` method to commands.
pub trait CommandShortcutMatchesExt: CommandShortcutExt {
    /// Returns `true` if the command has handlers, enabled or disabled, and the shortcut if one of the command shortcuts.
    fn shortcut_matches(self, shortcut: &Shortcut) -> bool;
}
impl CommandShortcutMatchesExt for Command {
    fn shortcut_matches(self, shortcut: &Shortcut) -> bool {
        if !self.has_handlers().get() {
            return false;
        }

        let s = self.shortcut();
        if s.with(|s| !s.contains(shortcut)) {
            return false;
        }

        let filter = self.shortcut_filter().get();
        if filter.is_empty() {
            return true;
        }
        if filter.contains(ShortcutFilter::CMD_ENABLED) && !self.is_enabled().get() {
            return false;
        }

        match self.scope() {
            CommandScope::App => filter == ShortcutFilter::CMD_ENABLED,
            CommandScope::Window(id) => {
                if filter.contains(ShortcutFilter::FOCUSED) {
                    FOCUS.focused().with(|p| {
                        let p = match p {
                            Some(p) => p,
                            None => return false,
                        };
                        if p.window_id() != id {
                            return false;
                        }
                        !filter.contains(ShortcutFilter::ENABLED) || p.interaction_path().next().map(|i| i.is_enabled()).unwrap_or(false)
                    })
                } else if filter.contains(ShortcutFilter::ENABLED) {
                    let tree = match WINDOWS.widget_tree(id) {
                        Some(t) => t,
                        None => return false,
                    };

                    tree.root().interactivity().is_enabled()
                } else {
                    true
                }
            }
            CommandScope::Widget(id) => {
                if filter.contains(ShortcutFilter::FOCUSED) {
                    FOCUS.focused().with(|p| {
                        let p = match p {
                            Some(p) => p,
                            None => return false,
                        };
                        if !p.contains(id) {
                            return false;
                        }
                        !filter.contains(ShortcutFilter::ENABLED) || p.contains_enabled(id)
                    })
                } else if filter.contains(ShortcutFilter::ENABLED) {
                    if let Some(w) = WINDOWS.widget_info(id) {
                        return w.interactivity().is_enabled();
                    }

                    false
                } else {
                    true
                }
            }
        }
    }
}

on_process_start!(|args| {
    if args.yield_until_app() {
        return;
    }
    APP.on_init(hn!(|args| {
        if !args.is_minimal {
            // command shortcuts are fully detached from the GESTURES service
            // so it will not init just by setting a shortcut and subscribing to the command
            let _ = GESTURES_SV.read();
        }
    }));
});