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

using zx;

/// 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.
type ViewRef = resource struct {
    reference zx.Handle:EVENTPAIR;
};

/// 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_EVENTPAIR_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.
type ViewRefControl = resource struct {
    reference zx.Handle:EVENTPAIR;
};

/// Convenience data type to self-identify the view, during view creation.
///
/// A ViewRef is used to identify the view, and can be freely cloned and
/// distributed to other components.
///
/// A ViewRefControl is used to implement lifecycle notification, and must not
/// be cloned, and cannot be distributed to other components. Scenic binds the
/// ViewRefControl object to the view, so when the view is destroyed, the
/// destruction of the ViewRefControl triggers a `ZX_EVENTPAIR_PEER_CLOSED`
/// signal to all ViewRef holders, thus notifying view death.
///
/// Usage: When creating a view, place a ViewRef and ViewRefControl together in
/// this struct, so that they travel as a unit to the destination component.
/// This convenience struct allows a protocol author to describe this traveling
/// pair as one argument. It improves readability and reduces mishandling.
type ViewIdentityOnCreation = resource struct {
    /// Stable identifier for the view to be created.
    view_ref ViewRef;

    /// A mechanism for lifecycle notification.
    view_ref_control ViewRefControl;
};