// 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.views;

/// A ViewRef's state of focus.
type FocusState = table {
    /// Describes if a ViewRef has gained focus (true), or lost focus (false).
    ///
    /// Required field.
    1: focused bool;
};

/// A method of enabling a ViewRef creator to determine if its ViewRef has
/// gained or lost focus in the view tree.
///
/// The protocol client has implicit access to the ViewRef it created; the
/// protocol itself does not accept a ViewRef parameter. Clients, both trusted
/// or otherwise, need access to view-focus state, so the protocol is
/// deliberately minimal. Possession of a ViewRef (and this protocol) does not
/// grant the power to learn about a ViewRef's focus state.
closed protocol ViewRefFocused {
    /// Sets up a callback to fire when the implicit ViewRef has gained or lost
    /// focus. Typically, focus changes happen at a slow pace, such that every
    /// transition is captured by the callback. However, focus changes can
    /// happen rapidly, so the callback may "compress" focus change history into
    /// just the latest known focus state.
    ///
    /// The callback reports the last focus change spanning the duration from
    /// its issuance to the previous callback's issuance. The client may observe
    /// any of the following four transitions:
    /// - true -> true: The ViewRef has lost focus at least once, and has gained
    ///   focus by the time of callback issuance.
    /// - true -> false: The ViewRef has lost focus at least once, and has lost
    ///   focus by the time of callback issuance.
    /// - false -> true: The ViewRef has gained focus at least once, and has
    ///   gained focus by the time of callback issuance.
    /// - false -> false: The ViewRef has gained focus at least once, and has
    ///   lost focus by the time of callback issuance.
    ///
    /// The client avoids "focus flapping" and always sees the latest state.
    /// Every callback issuance is meaningful, and the client should renegotiate
    /// focus-related services appropriately, such as IME.
    ///
    /// Flow control: The caller is allowed at most one in-flight |Watch| call
    /// at at time: subsequent |Watch| calls must wait until the acknowledgment
    /// returns. Non-compliance results in channel closure.
    strict Watch() -> (struct {
        state FocusState;
    });
};