// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

library fuchsia.ui.shortcut;

using fuchsia.input;
using fuchsia.ui.views;

/// The maximum number of shortcut keys, excluding the trigger key, that is required
/// to activate a shortcut.
/// Currently a low bound based on current use-cases.
const uint64 MAX_REQUIRED_KEYS = 2;

/// Components may request this service from their namespace to
/// register and be notified of shortcuts.
/// Registry supports multiple registrations simultaneously.
[Discoverable]
protocol Registry {
    /// Set shortcut activation listener.
    SetView(fuchsia.ui.views.ViewRef view_ref, Listener listener);

    /// Register new shortcut. Upon activation, `Listener` is invoked.
    /// Only focused ViewRefs will be notified of matching shortcut activations.
    /// For the full disambiguation procedure, see package-level documentation.
    RegisterShortcut(Shortcut shortcut) -> ();
};

/// Shortcut descriptor.
table Shortcut {
    /// Client-generated identifier, to distinguish activated shortcuts.
    1: uint32 id;

    // Was used for input2 modifiers field.
    2: reserved;

    // Was used for input2 key field.
    3: reserved;

    /// Optional: When set to true, parent's shortcuts take priority
    /// and are matched before those of its children.
    /// When use_priority is not set, shortcut uses use_priority == false.
    4: bool use_priority;

    /// Optional: Shortcut activation trigger.
    /// When trigger is not set, shortcuts are activated on Trigger.KEY_PRESSED.
    /// Activating a shortcut on one trigger (e.g. Trigger.KEY_PRESSED) will disable
    /// matching keys used for it for other Trigger options for other shortcuts.
    ///
    /// Example:
    ///   Shortcuts registered for:
    ///     1. Key.LEFT_META + Key.Q with with Trigger.KEY_PRESSED
    ///     2. Key.LEFT_META with Trigger.KEY_PRESSED_AND_RELEASED
    ///   In this case, pressing Left Meta + Q will activate only shortcut (1), while
    ///   pressing and releasing Meta key alone will activate shortcut (2).
    5: Trigger trigger;

    /// Key to be pressed to activate the shortcut.
    6: fuchsia.input.Key key3;

    /// Keys that should be pressed to activate the shortcut.
    ///
    /// Example:
    ///  `Shift` + `Alt` + `Tab`:
    ///    Setup:
    ///     - `Shift` and `Alt` are the prerequisite for the shortcut activation,
    ///       therefore `keys_required = [ Key.LEFT_SHIFT, Key.LEFT_ALT ]`
    ///     - `Tab` is the trigger key, therefore `key3 = Key.TAB`
    ///    Result:
    ///     Shortcut is activated on Tab key press if Left Alt and Left Shift are held down.
    7: vector<fuchsia.input.Key>:MAX_REQUIRED_KEYS keys_required;
};

/// Shortcut activation variations.
/// Enumerates keyboard interaction options for shortcuts' activations.
enum Trigger {
    /// Activate shortcut on key press.
    KEY_PRESSED = 1;

    /// Activate shortcut on key release which is preceded by a key press.
    KEY_PRESSED_AND_RELEASED = 2;

    // TODO: add later when needed
    // KEY_LONG_PRESSED = 3;
    // KEY_PRESSED_REPEATEDLY = 4;
};

/// Client should implement this protocol to get notified of shortcut activation.
/// Only focused ViewRefs will be notified of matching shortcut activations.
/// For the full disambiguation procedure, see package-level documentation.
protocol Listener {
    OnShortcut(uint32 id) -> (bool handled);
};