blob: adad5364c09665f79b046cdaed14c66169c76d06 [file] [log] [blame]
// Copyright 2019 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.
@available(added=8, deprecated=13, note="Use fuchsia.ui.composition.Flatland instead.")
library fuchsia.ui.annotation;
using fuchsia.ui.views;
/// Annotation allows a privileged client service to create an "annotation"
/// `ViewHolder`, linked with an annotation `View` drawn within the View-space
/// of the existing client `View`.
@discoverable
closed protocol Registry {
/// Creates a new annotation `ViewHolder`. The created ViewHolder holds an
/// annotation `View` which renders within the existing client's View-space
/// without that client's knowledge.
///
/// The client should create a `ViewToken` / `ViewHolderToken` pair, pass
/// the `ViewHolderToken` as an argument to this function to create the
/// annotation `ViewHolder`, and create an annotation `View` in its own
/// `Session` using the corresponding `ViewToken`.
///
/// The annotation `View` has the following properties:
/// + It is a descendent of `client_view`'s ViewNode in the scene graph
/// but it's not visible by the Session of `client_view`.
/// + It does not receive or intercept any hit event.
/// + It always has the same rendering state as `client_view` and always
/// match the size and metrics.
///
/// When `client_view`'s Session receives the following Events, all its
/// annotation `View`s' Sessions will receive the corresponding Events of
/// the annotation `View`s:
/// + ViewAttachedToSceneEvent
/// + ViewDetachedFromSceneEvent
/// + ViewPropertiesChangedEvent
/// + ViewStateChangedEvent
///
/// Since creating a ViewHolder modifies the SceneGraph, this function won't
/// take effect until we schedule a new frame by calling Present() on any
/// Session.
///
/// EPITAPH
///
/// There are a few erroneous conditions where the annotation `ViewHolder`
/// will not be created and the the FIDL binding will be disconnected.
/// Clients should remove the annotation `View` and `Session` they create.
///
/// It may return the following epitaphs:
///
/// - ZX_ERR_INVALID_ARGS, if the provided `ViewRef` is invalid.
/// - ZX_ERR_PEER_CLOSED, if Scenic fails creating the annotation `ViewHolder`.
///
strict CreateAnnotationViewHolder(resource struct {
client_view fuchsia.ui.views.ViewRef;
view_holder_token fuchsia.ui.views.ViewHolderToken;
}) -> ();
};