sdk/fidl/fuchsia.ui.annotation/annotation.fidl

// 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(fuchsia.ui.views.ViewRef client_view,
                               fuchsia.ui.views.ViewHolderToken view_holder_token) -> ();
};