// 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/layouts.mojom";
import "mojo/services/ui/views/interfaces/views.mojom";

// A view tree is a top-level container for a hierarchy of views.
//
// A view tree must registered with the view manager before it can be shown.
interface ViewTree {
  // Called when the tree needs to update its layout.
  //
  // This method may be called for one or more of the following reasons:
  //
  //   1. The root was just set.
  //   2. The root produced different layout information during its last
  //      layout pass causing a recursive layout to occur.
  //
  // Layout requests are coalesced for efficiency.  Certain intermediate
  // updates may be dropped if the view tree is unable to keep up with them
  // in a timely manner.  Do nothing updates are always dropped.
  //
  // The implementation should invoke the callback once the event has
  // been handled and the view tree is ready to be shown in its new aspect.
  OnLayout() => ();

  // Called when the root view has become unavailable.
  //
  // The root may become unavailable for many reasons such being unregistered
  // by its application, abnormal termination of its application, or
  // being reparented into a different view tree.
  //
  // The implementation should invoke the callback once the event has
  // been handled.
  OnRootUnavailable(uint32 root_key) => ();
};

// The view tree host provides an interface for a view tree to configure itself
// and interact with its views.
//
// Each view tree obtains its own view tree host when registered with the
// ViewManager.  To unregister the view tree, close its view tree
// and/or view tree host message pipes.
interface ViewTreeHost {
  // Requests that the view tree's OnLayout() method be called to compute a
  // new layout due to a change in the view tree's layout information.
  RequestLayout();

  // Sets the root of the view tree and assigns it the provided |root_key|
  // to distinguish it from any other roots this view tree has had.
  //
  // It is a good idea to provide a distinct |root_key| each time a new root
  // is set so that callbacks related to the root can be clearly distinguished
  // across these changes.
  //
  // If |root_view_token| refers to a view which is already unavailable
  // then the call proceeds as if it succeeded but an OnChildUnavailable()
  // message will be sent.
  //
  // If |root_view_token| refers to a view which already has a parent or is
  // the root of a view tree then an OnChildUnavailable() or OnRootUnavailable()
  // message will be sent to its old parent or root and the the view will be
  // used as the root of the new view tree as usual.  This special case also
  // applies when the specified view is already the root of this view tree, in
  // which case the behavior is similar to the view having been transferred to
  // some other view tree and then back again.
  SetRoot(uint32 root_key, mojo.ui.ViewToken root_view_token);

  // Removes the root of the view tree.
  //
  // Does nothing if the view tree currently does not have a root.
  ResetRoot();

  // Sets the layout parameters of the root of the view tree and retrieves
  // its layout information.
  //
  // The returned |info| is null if this layout request was canceled either
  // because it has been superceded by a subsequently issued layout request
  // or because the root has become unavailable.
  //
  // It is an error to call this function if the view tree does not currently
  // have a root; the connection will be closed.
  //
  // It is an error to specify malformed |root_layout_params| such
  // as invalid size constraints; the connection will be closed.
  LayoutRoot(mojo.ui.ViewLayoutParams root_layout_params) =>
      (mojo.ui.ViewLayoutInfo? info);
};