// Copyright 2022 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.accessibility.scene;

using fuchsia.ui.views;

@discoverable
protocol Provider {
    /// Prompts the server (a11y manager) to create a new accessibility `View`,
    /// which the client (scene manager) must connect to the root of the scene
    /// graph.
    ///
    /// The accessibility view is used to vend capabilities to a11y manager
    /// that a view confers, e.g. ability to request focus, consume and
    /// respond to input events, annotate underlying views, and apply
    /// coordinate transforms to its subtree.
    ///
    /// With the a11y view, the scene topology is roughly:
    ///
    ///          scene root (owned by scene manager)
    ///               |
    ///         a11y viewport (owned by scene manager)
    ///               |
    ///           a11y view (owned by a11y manager)
    ///               |
    ///        proxy viewport (owned by a11y manager)
    ///               |
    ///          proxy view (owned by scene manager)
    ///               |
    ///        client viewport (owned by scene manager)
    ///               |
    ///          client view (owned by UI client)
    ///
    /// ARGS
    ///
    /// a11y_view_token: Token generated by scene manager, which a11y manager
    /// uses to create the a11y view in its flatland instance.
    ///
    /// proxy_viewport_token: Token generated by scene manager, which a11y manager
    /// uses to create a "proxy viewport" within the a11y view. The client must
    /// subsequently create a "proxy view" using the corresponding view creation
    /// token it generated.
    ///
    /// SYNCHRONIZATION
    ///
    /// Callers may safely proceed once the accessibility `ViewRef` is returned
    /// to the accessibility `ViewPort` holder.
    ///
    /// LIFECYCLE
    ///
    /// The client is free to close the channel any time after calling CreateView().
    ///
    /// EPITAPH
    ///
    /// This method may return the following epitaphs:
    ///
    /// - ZX_ERR_INVALID_ARGS, if either of the provided tokens is invalid.
    /// - ZX_ERR_PEER_CLOSED, if Scenic fails creating the accessibility `Viewport`.
    CreateView(resource struct {
        a11y_view_token fuchsia.ui.views.ViewCreationToken;
        proxy_viewport_token fuchsia.ui.views.ViewportCreationToken;
    });
};