// 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`.
    AddListener(fuchsia.ui.views.ViewRef view_ref, KeyboardListener listener) -> ();
};

/// 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 will propagate to another client or listener.
    /// Clients that do not acknowledge their events will eventually be disconnected.
    /// Notification is only dispatched when the View is focused (ViewRef is on FocusChain).
    /// Parent Views receive the notification first, child Views last.
    /// Returning `HANDLED` will stop event propagation to other clients and listeners.
    OnKeyEvent(KeyEvent event) -> (KeyEventStatus status);
};

/// Return type for clients key events listener.
enum KeyEventStatus {
    /// 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;
};