// 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 collection of error codes related to |ViewRefInstalled|.
enum ViewRefInstalledError {
    /// The ViewRef being watched is invalid, or has become invalid.
    INVALID_VIEW_REF = 1;
};

/// A method of enabling ViewRef holders to determine if a ViewRef has been
/// "installed" in the view tree: the time it is first connected, transitively,
/// to the root view.  Typically, after installation, view focus may be
/// transferred to that ViewRef.
///
/// Note: It's important to distinguish between a ViewRef's installed status and
///       current connected-to-view-tree status.  The former undergoes a state
///       change once, from "no" to "yes".  The latter may change continuously,
///       depending on view tree topology.  As such, "installed" cannot imply
///       "currently connected to view tree"; even a hypothetical
///       "ViewRefConnected" protocol is fundamentally racy.
[Discoverable]
protocol ViewRefInstalled {
    /// Sets up a callback to fire when the requested |view_ref| is installed.
    /// - If |view_ref| has not already been installed, the |Watch| response
    ///   will fire when it is.
    /// - If |view_ref| has already been installed, the |Watch| response will
    ///   fire immediately.
    /// - If |view_ref| is invalid, or becomes invalid (perhaps because the view
    ///   was destroyed), the |Watch| call returns with an error.  The error is
    ///   not guaranteed to be immediate, but a ViewRef holder can itself
    ///   determine ViewRef validity by listening for ZX_EVENTPAIR_PEER_CLOSED.
    ///
    /// Flow control: The caller is allowed multiple |Watch| calls on multiple
    /// ViewRefs. There is at most one response per call back to the client.
    ///
    /// Note: Prior to installation, this |Watch| call is kept alive as long as
    ///       the ViewRef is valid.
    Watch(ViewRef view_ref) -> () error ViewRefInstalledError;
};