// 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/public/interfaces/application/service_provider.mojom";
import "mojo/services/gfx/composition/interfaces/renderers.mojom";
import "mojo/services/ui/views/interfaces/view_containers.mojom";
import "mojo/services/ui/views/interfaces/view_tree_token.mojom";

// A view tree is a top-level container for a hierarchy of views.
// Each view is intended to operate independently from others and will
// generally correspond to discrete interactive spaces such as separate
// displays or isolated environments in a multi-user system.
//
// Within a view tree, certain global invariants may be enforced such as
// ensuring that only one view has focus at a time.
//
// View trees will typically be created by system components responsible
// for managing the overall user interface rather than end-user applications.
//
// LIFECYCLE
//
// Use |ViewManager.CreateViewTree()| to create a view tree.  The client
// uses the |ViewTree| interface to manage the view tree's content
// and implements the |ViewTreeListener| interface to handle events.
//
// To destroy a view tree, simply close the |ViewTree| message pipe.
//
// SETTING A ROOT VIEW
//
// Use |GetContainer()| to obtain an interface for manipulating the root view.
//
// See |mojo.ui.ViewContainer| for more information.
//
// GETTING SERVICES
//
// The view tree's |ServiceProvider| offers access to many services which
// are not directly expressed by the |ViewTree| interface itself, such
// as input, accessiblity, and editing capabilities.
//
// For example, perform the following actions to dispatch input events:
//
// 1. Call |GetServiceProvider()| to obtain the view's service provider.
//
// 2. Ask the service provider for its |mojo.ui.InputDispatcher|.
//
// 3. Send input events to the dispatcher for delivery to views.
interface ViewTree {
  // Gets the view tree's token.
  GetToken() => (ViewTreeToken token);

  // Gets a service provider to access services which are associated with
  // the view tree such as input, accessibility and editing capabilities.
  // The view tree service provider is private to the view tree and should
  // not be shared with anyone else.
  //
  // See |mojo.ui.InputDispatcher|.
  GetServiceProvider(mojo.ServiceProvider& service_provider);

  // Sets where the view tree's scene graph will be rendered.
  //
  // If |renderer| is null, disconnects the view tree from the renderer
  // causing its previous renderer to be destroyed.
  //
  // See also: |mojo.gfx.composition.Compositor.CreateRenderer()|.
  SetRenderer(mojo.gfx.composition.Renderer? renderer);

  // Gets an interface for managing the view tree's root.
  GetContainer(ViewContainer& container);
};

// An interface clients may implement to receive events from a view tree.
interface ViewTreeListener {
  // Called when the tree's renderer connection closed unexpectedly.
  //
  // The implementation should invoke the callback once the event has
  // been handled.
  OnRendererDied() => ();
};