mojo/services/ui/views/interfaces/view_manager.mojom

// Copyright 2015 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

[DartPackage="mojo_services"]
module mojo.ui;

import "mojo/services/ui/views/interfaces/view_associates.mojom";
import "mojo/services/ui/views/interfaces/view_trees.mojom";
import "mojo/services/ui/views/interfaces/views.mojom";

// 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.
[ServiceName="mojo::ui::ViewManager"]
interface ViewManager {
  // Creates a view.
  //
  // The |view| is used to configure the view and interact with its
  // local environment.  The view pipe is private to the view and should
  // not be shared with anyone else.
  //
  // 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|.
  //
  // To destroy the view and cause it to be removed from the view tree,
  // simply close the |view|, |view_listener|, or |view_owner| message pipes.
  CreateView(mojo.ui.View& view,
             mojo.ui.ViewOwner& view_owner,
             mojo.ui.ViewListener view_listener,
             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 is private to the view
  // and should not be shared with anyone else.
  //
  // 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| message pipes.
  CreateViewTree(mojo.ui.ViewTree& view_tree,
                 mojo.ui.ViewTreeListener view_tree_listener,
                 string? label);

  // Registers a view associate with the view manager.
  //
  // The services provided by |view_associate| will be made available to views.
  //
  // You receive a |view_associate_owner| which will receive a connection error
  // callback if |view_associate| is closed. Conversely, the service for
  // |view_associate| will be destroyed if |view_associate_owner| is destroyed.
  //
  // |label| is used to identify the ViewAssociate for debug purposes.
  //
  // TODO(mikejurka): This method should only be made accessible to trusted
  // services, once we have a security story
  RegisterViewAssociate(mojo.ui.ViewAssociate view_associate,
    mojo.ui.ViewAssociateOwner& view_associate_owner, string? label);

  // Tells the view manager we've registered all our view associates.
  //
  // This allows it to prevent views from requesting services from ViewAssociate
  // before all the ViewAssociates have been registered.
  //
  // TODO(mikejurka): This method should only be made accessible to trusted
  // services, once we have a security story
  // TODO(mikejurka): We should remove this method once we have a way of
  // dynamically registering and unregistering ViewAssociates
  FinishedRegisteringViewAssociates();
};