// Copyright 2021 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.keyboard.focus;

using fuchsia.ui.views;

/// Updates the focus of the keyboard subsystem.
///
/// # Roles
/// This protocol will typically be:
/// * Implemented by platform components implementing the keyboard
///   subsystem. For example, `ime_service.cmx`.
/// * Consumed by platform components which control UI policy.
///   E.g. Root Presenter, or the Workstation Session.
///
/// # Related protocols
/// * `fuchsia.ui.input3.Keyboard` (for receiving keystrokes)
/// * `fuchsia.ui.input.InputMethodEditor` (for text editing)
[Discoverable]
protocol Controller {
    /// Informs the implementer of `Controller` that further keyboard
    /// data should be routed to the keystroke/text consumer
    /// associated with `view_ref`.
    ///
    /// # Notes
    /// * The callee should monitor the provided `ViewRef` for a
    ///   `ZX_EVENTPAIR_PEER_CLOSED` signal (see documentation for
    ///   `fuchsia.ui.views.ViewRefControl`).
    /// * When the `ViewRef` receives `ZX_EVENTPAIR_PEER_CLOSED`, the
    ///   callee should stop delivering keystroke/text to
    ///   the consumer associated with `view_ref`.
    /// * The caller should wait for each call to be acknowledged
    ///   before calling again, to avoid queueing large numbers of
    ///   of updates.
    Notify(fuchsia.ui.views.ViewRef view_ref) -> ();
};