// 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, `text_manager.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(resource struct {
        view_ref fuchsia.ui.views.ViewRef;
    }) -> ();
};