sdk/fidl/fuchsia.ui.shortcut/registry.fidl

// 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.ui.input2;
using fuchsia.ui.views;

/// Service to receive and handle shortcut activations.
///
/// Components may request this service from their namespace to
/// use shortcuts.
[Discoverable]
protocol Registry {
    /// Set shortcut activation listener.
    SetView(fuchsia.ui.views.ViewRef view_ref, Listener listener);

    /// Register new shortcut activation listener.
    RegisterShortcut(Shortcut shortcut) -> ();
};

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

    /// Modifier keys to be enabled for the shortcut activation.
    2: fuchsia.ui.input2.Modifiers modifiers;

    /// Optional: Key to be pressed to activate the shortcut.
    /// If not set, shortcut is interpreted as a modifiers-only shortcut.
    3: fuchsia.ui.input2.Key key;

    /// 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. Modifiers.META + Key.Q with with Trigger.KEY_PRESSED
    ///     2. Modifiers.META with Trigger.KEY_PRESSED_AND_RELEASED
    ///   In this case, pressing Meta + Q will activate only shortcut (1), while
    ///   pressing and releasing Meta key alone will activate shortcut (2).
    5: Trigger trigger;
};

/// 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.
protocol Listener {
    OnShortcut(uint32 id) -> (bool handled);
};