// 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]
interface 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.
  1: 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
  // |Mozart|, 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.
  2: CreateView(request<View> view,
               request<fuchsia.ui.viewsv1token.ViewOwner> view_owner,
               ViewListener view_listener,
               handle<eventpair> parent_export_token,
               string? label);

  3: 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.
  4: CreateViewTree(request<ViewTree> view_tree,
                   ViewTreeListener view_tree_listener,
                   string? label);
};