// 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.
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
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`.
    ///
    CreateAnnotationViewHolder(resource struct {
        client_view fuchsia.ui.views.ViewRef;
        view_holder_token fuchsia.ui.views.ViewHolderToken;
    }) -> ();
};