sdk/fidl/fuchsia.ui.viewsv1/view_manager.fidl

// Copyright 2015 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.viewsv1;

using fuchsia.ui.scenic;
using fuchsia.ui.viewsv1token;

// Maximum length for a view or view tree label.
const uint32 kLabelMaxLength = 32;

// The view manager manages trees of views which represent user interface
// components.
//
// Applications create views to describe user interface components
// to present content to the user and support user interaction.
//
// The system creates a view tree to hold the root of a view hierarchy
// containing views from various applications.
//

// Refer to `View` and `ViewTree` for more information about these objects.
[Discoverable]
protocol ViewManager {

    // Gets the scenic instance associated with this view manager.
    // All graphical content for this view manager's views and view trees
    // must come from sessions created by this `scenic` instance.
    GetScenic(request<fuchsia.ui.scenic.Scenic> scenic);

    // Creates a view.
    //
    // The `view` is used to configure the view and interact with its
    // local environment.
    //
    // The `view_owner` is used as a transferable reference which can
    // be passed to the view's intended container as part of a request to
    // add the view as a child.  The view manager itself does not describe
    // how this interaction should take place, only that ownership should
    // eventually be passed back through the container's view interface
    // as an argument to `View.AddChild()`.
    //
    // The `view_listener` is used to receive events from the view.
    //
    // The `label` is an optional name to associate with the view for
    // diagnostic purposes.  The label will be truncated if it is longer
    // than `kLabelMaxLength`.
    //
    // `parent_export_token` is an export token which the view manager
    // will use to export the node to which the view's content should be
    // attached.
    //
    // To present graphical content, the view must obtain a `Session` from
    // `Scenic`, create an event pair, bind one endpoint to an
    // `ImportResourceOp` using `ImportSpec.NODE`, attach its content nodes as
    // descendants of the imported node, and pass the other endpoint of the
    // event pair to this method as `parent_export_token`.
    //
    // To destroy the view and cause it to be removed from the view tree,
    // simply close the `view`, `view_listener`, or `view_owner` channels.
    //
    // This method is deprecated in favor of the eventpair-based one below.
    // TODO(SCN-1018): Remove this.
    CreateView(request<View> view,
               request<fuchsia.ui.viewsv1token.ViewOwner> view_owner,
               ViewListener view_listener,
               handle<eventpair> parent_export_token,
               string? label);

    CreateView2(request<View> view,
                handle<eventpair> view_token,
                ViewListener view_listener,
                handle<eventpair> parent_export_token,
                string? label);

    // Creates a view tree.
    //
    // The `view_tree` is used to configure the view tree and interact
    // with the views it contains.
    //
    // The `view_tree_listener` is used to receive events from the view tree.
    //
    // The `label` is an optional name to associate with the view tree for
    // diagnostic purposes.  The label will be truncated if it is longer
    // than `kLabelMaxLength`.
    //
    // To destroy the view tree simply close the `view_tree` or
    // `view_tree_listener` channels.
    CreateViewTree(request<ViewTree> view_tree,
                   ViewTreeListener view_tree_listener,
                   string? label);
};