// Copyright 2020 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.input3;

using fuchsia.ui.views;

/// Components may request this service from their namespace to be notified of
/// physical key events.
@discoverable
protocol Keyboard {
    /// Add a key event listener for the specified View.
    /// If multiple listeners are added, each will receive key events independently and
    /// should respond with a `Status`.
    ///
    /// The client calling `AddListener` should keep the connection to `Keyboard` alive
    /// for as long as the events from `KeyboardListener` need to be received.  Dropping the
    /// connection to the `Keyboard` protocol will terminate `KeyboardListener` as well.
    AddListener(resource struct {
        view_ref fuchsia.ui.views.ViewRef;
        listener client_end:KeyboardListener;
    }) -> ();
};

/// Client should implement this protocol to get notified of key events.
protocol KeyboardListener {
    /// Called when a key event takes place, such as key press or release.
    ///
    /// Protocol implementers must respond to acknowledge the event by returning Status
    /// in a timely manner, i.e. not introducing significant delays to the
    /// input pipeline (typically 10s of milliseconds).
    ///
    /// Returning `NOT_HANDLED` means the event may be offered to other
    /// clients of other related APIs.
    ///
    /// Clients that do not acknowledge their events will eventually be disconnected.
    ///
    /// Notification is only dispatched to a view that has focus. No other views,
    /// including parents or children, will get notified specifically via `OnKeyEvent`.
    OnKeyEvent(struct {
        event KeyEvent;
    }) -> (struct {
        status KeyEventStatus;
    });
};

/// Provides the ability to inject `KeyEvent`s into the keyboard subsystem.
///
/// # Roles
/// This protocol will typically be:
/// * Implemented by platform components which process and deliver keyboard
///   events.
/// * Consumed by components which originiate keyboard events. E.g.
///   an on-screen keyboard, or the Session Framework Input Pipeline.
///
/// # Related protocols
/// This protocol should be using in preference to legacy protocols which provide
/// similar functionality. Specifically, this means this protocol should be preferred
/// over
/// * `fuchsia.ui.input.ImeService` which provides `InjectInput()`, `DispatchKey()`,
///   and `DispatchKey3()`
/// * `fuchsia.ui.input.InputMethodEditor`, which provides `InjectInput()` and
///   `DispatchKey3()`
///
/// # Notes
/// Products should take care to limit access to this protocol, as events injected
/// with this protocol are indistinguishable from those coming from physical devices.
@discoverable
protocol KeyEventInjector {
    /// Inject an event into the keyboard subsystem.
    ///
    /// # Returns
    /// * `HANDLED` if the keyboard subsystem delivered the event to a consumer,
    ///   and the consumer reported that it `HANDLED` the event
    /// * `NOT_HANDLED` if the keyboard subsystem did not deliever the event to
    ///   any consumers, or no consumer reported that it `HANDLED` the event.
    Inject(struct {
        key_event KeyEvent;
    }) -> (struct {
        status KeyEventStatus;
    });
};

/// Return type for clients key events listener.
///
/// We do not expect new values to be added to this enum.
type KeyEventStatus = strict enum {
    /// The key event was handled and its further propagation should be stopped.
    HANDLED = 1;

    /// The key event wasn't handled and should be delivered to other clients or listeners.
    NOT_HANDLED = 2;
};