// 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);
};