// 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 is a handle to a kernel object which identifies a unique View
/// across the system. Two ViewRefs to the same View have the same KOID.
///
/// Clients use a ViewRef to identify a View, to validate a View, and to
/// receive a View invalidation signal.
///
/// As part of View creation, the client creates a linked
/// ViewRef/ViewRefControl pair and hands the pair to Scenic (ViewRefControl is
/// described below).  The client must remove the ViewRef's signal
/// capabilities; otherwise the View is not created.
///
/// The client may freely clone its ViewRef and share it, even before sending
/// it to Scenic.
///
/// Example 1. Accessibility accepts a ViewRef from a client to group the
/// semantic nodes, and semantic operations, associated with a client's View.
/// It must validate a client's ViewRef with Scenic.
///
/// Example 2. We use ViewRefs to create a FocusChain, which identifies Views
/// considered as "in-focus" down the View hierarchy. When a View is destroyed,
/// Scenic signals to all FocusChain holders that the ViewRef is now invalid.
struct ViewRef {
    handle<eventpair> reference;
};

/// A ViewRefControl is the peer to a ViewRef. Their `reference`s are linked.
///
/// Like ViewRef, a ViewRefControl is a typed handle to an eventpair.  Unlike
/// ViewRef, a ViewRefControl's handle is unique. Scenic uses this property
/// when it ties a ViewRefControl to a View, arranged to share fate.  When a
/// View is destroyed, the associated destruction of its ViewRefControl
/// triggers an automatic `ZX_ERR_PEER_CLOSED` signal sent to all ViewRef
/// holders; hence ViewRef holders may track View lifetime.
///
/// As part of View creation, the client creates a linked
/// ViewRef/ViewRefControl pair and hands the pair to Scenic (ViewRef is
/// described above).  The client must not clone the ViewRefControl. It must
/// not remove or modify the ViewRefControl's capabilities; otherwise the View
/// is not created.
struct ViewRefControl {
    handle<eventpair> reference;
};