blob: 69657a506fe9be77bd7bf185d80be2cd3359c221 [file] [log] [blame]
// 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;