viewport-lib-types 0.3.0

Pure-data types for viewport-lib: submission payloads, handles, and frame config, free of any GPU dependency.
Documentation
#![allow(deprecated)]

use super::action::Action;
use super::binding::*;
use super::mode::InputMode;

/// Helper: key press trigger with given modifiers.
fn key_press(key: KeyCode, mods: Modifiers) -> Trigger {
    Trigger {
        kind: TriggerKind::Key(key),
        modifiers: mods,
        activation: ActivationMode::OnPress,
        ignore_modifiers: false,
    }
}

/// Helper: key held trigger that ignores modifiers (for fly mode WASD).
fn key_held_any_mod(key: KeyCode) -> Trigger {
    Trigger {
        kind: TriggerKind::Key(key),
        modifiers: Modifiers::NONE,
        activation: ActivationMode::WhileHeld,
        ignore_modifiers: true,
    }
}

/// Helper: mouse drag trigger.
fn mouse_drag(btn: MouseButton, mods: Modifiers) -> Trigger {
    Trigger {
        kind: TriggerKind::MouseButton(btn),
        modifiers: mods,
        activation: ActivationMode::OnDrag,
        ignore_modifiers: false,
    }
}

/// Helper: scroll trigger.
fn scroll(mods: Modifiers) -> Trigger {
    Trigger {
        kind: TriggerKind::Scroll,
        modifiers: mods,
        activation: ActivationMode::OnScroll,
        ignore_modifiers: false,
    }
}

/// Helper: mouse click trigger.
fn mouse_click(btn: MouseButton) -> Trigger {
    Trigger {
        kind: TriggerKind::MouseButton(btn),
        modifiers: Modifiers::NONE,
        activation: ActivationMode::OnPress,
        ignore_modifiers: false,
    }
}

/// Returns the default binding table for viewport navigation and fly mode.
#[deprecated(note = "superseded by viewport_default_bindings")]
pub fn default_bindings() -> Vec<Binding> {
    let normal = &[InputMode::Normal];
    let fly = &[InputMode::FlyMode];
    let fly_manip = &[InputMode::FlyMode, InputMode::Manipulating];

    vec![
        // -- Viewport navigation --
        Binding::in_modes(
            Action::Orbit,
            mouse_drag(MouseButton::Left, Modifiers::ALT),
            normal,
        ),
        Binding::in_modes(
            Action::Pan,
            mouse_drag(MouseButton::Left, Modifiers::SHIFT),
            normal,
        ),
        Binding::in_modes(
            Action::Pan,
            mouse_drag(MouseButton::Middle, Modifiers::NONE),
            normal,
        ),
        Binding::in_modes(Action::Zoom, scroll(Modifiers::NONE), normal),
        Binding::in_modes(
            Action::Zoom,
            mouse_drag(MouseButton::Right, Modifiers::ALT),
            normal,
        ),
        Binding::in_modes(
            Action::FocusObject,
            key_press(KeyCode::F, Modifiers::NONE),
            normal,
        ),
        Binding::in_modes(
            Action::ResetView,
            key_press(KeyCode::R, Modifiers::NONE),
            normal,
        ),
        // -- Fly mode --
        Binding::in_modes(
            Action::EnterFlyMode,
            key_press(KeyCode::Backtick, Modifiers::SHIFT),
            normal,
        ),
        Binding::in_modes(Action::FlyForward, key_held_any_mod(KeyCode::W), fly),
        Binding::in_modes(Action::FlyBackward, key_held_any_mod(KeyCode::S), fly),
        Binding::in_modes(Action::FlyLeft, key_held_any_mod(KeyCode::A), fly),
        Binding::in_modes(Action::FlyRight, key_held_any_mod(KeyCode::D), fly),
        Binding::in_modes(Action::FlyUp, key_held_any_mod(KeyCode::E), fly),
        Binding::in_modes(Action::FlyDown, key_held_any_mod(KeyCode::Q), fly),
        // FlySpeedBoost has no binding in this legacy set: Shift is a modifier, not a
        // key, and a Trigger names a key. viewport_default_bindings binds it with
        // ViewportGesture::ModifiersHeld.
        // -- Confirm / Cancel (fly mode + manipulation) --
        Binding::in_modes(
            Action::Confirm,
            key_press(KeyCode::Enter, Modifiers::NONE),
            fly_manip,
        ),
        Binding::in_modes(Action::Confirm, mouse_click(MouseButton::Left), fly_manip),
        Binding::in_modes(
            Action::Cancel,
            key_press(KeyCode::Escape, Modifiers::NONE),
            fly_manip,
        ),
        Binding::in_modes(Action::Cancel, mouse_click(MouseButton::Right), fly_manip),
    ]
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::input::viewport_default_bindings;
    use std::collections::HashSet;

    // One list of every named action, expanded into both the array the coverage
    // test walks and an exhaustive `match`. Adding an `Action` variant fails to
    // compile here until it is listed, which forces a decision: bind it, or add
    // it to the documented exceptions below. `Custom` is the application's and
    // is never bound by the library.
    macro_rules! all_actions {
        ($($v:ident),* $(,)?) => {
            const ALL_ACTIONS: &[Action] = &[$(Action::$v),*];
            #[allow(dead_code)]
            fn actions_are_exhaustive(a: Action) {
                match a { $(Action::$v => {}),* Action::Custom(_) => {} }
            }
        };
    }

    all_actions!(
        Orbit,
        Pan,
        Zoom,
        FocusObject,
        ResetView,
        EnterFlyMode,
        FlyForward,
        FlyBackward,
        FlyLeft,
        FlyRight,
        FlyUp,
        FlyDown,
        FlySpeedBoost,
        Confirm,
        Cancel,
    );

    /// Every action must be reachable from at least one of the two shipped
    /// binding sets (`default_bindings` or `viewport_default_bindings`), so no action
    /// is defined but impossible to trigger.
    #[test]
    fn every_action_is_bound_or_a_documented_exception() {
        let bound: HashSet<Action> = default_bindings()
            .iter()
            .map(|b| b.action)
            .chain(viewport_default_bindings().iter().map(|b| b.action))
            .collect();

        let unbound: Vec<Action> = ALL_ACTIONS
            .iter()
            .copied()
            .filter(|a| !bound.contains(a))
            .collect();

        assert_eq!(
            unbound,
            Vec::<Action>::new(),
            "actions with no binding in either set: bind them, or add to the \
             documented exceptions with a reason"
        );
    }
}