// Copyright 2016 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/gfx/composition/interfaces/scene_token.mojom";
import "mojo/services/ui/views/interfaces/layouts.mojom";
import "mojo/services/ui/views/interfaces/view_token.mojom";

// A view container is an interface exposed by |View| and |ViewTree| to
// manage their child views.  Although |View| may have any number of children,
// a |ViewTree| can have at most one (its root view).
//
// EMBEDDING
//
// The following steps are required to embed another view as a child:
//
// 1. Obtain the |ViewOwner| belonging to the view you would like to embed.
//    The means for doing this is not specified by the view system.
//    You might create another view of your own to embed or connect to
//    another application using a mechanism such as |ViewProvider| (or
//    any suitable agreed-upon protocol) to create the view to embed.
//
// 2. Call |AddChild()| to add the view you would like to embed and assign
//    it a unique key.
//
// 3. Call |LayoutChild()| to provide layout parameters for the new child
//    using the key that was provided.
//
// 4. After obtaining the layout result from the child, publish an
//    update to your |Scene| which includes a reference to the child's own
//    scene using the |SceneToken| included in the layout result.
//
// 5. Watch for the child becoming unavailable, as reported by
//    |OnChildUnavailable()|, which indicates that the child is no longer
//    in a usable state (perhaps the application which provided it has
//    stopped).  When this happens, you are still responsible for calling
//    |RemoveChild()| to remove the child and discard any state that your
//    view has associated with it.
//
// LAYOUT
//
// TODO(jeffbrown): Elaborate this once the layout protocol has been
// redesigned.
interface ViewContainer {
  // Sets the view container listener, or null to remove.
  SetListener(ViewContainerListener? listener);

  // Adds the view referenced by |child_view_owner| as a child and assigns
  // it the provided |child_key| to identify it among its children.
  // The container may remove the child later by passing the same |child_key|
  // to |RemoveChild()|.
  //
  // This method takes ownership of the view.
  //
  // It is important for the container to choose locally unique values for
  // |child_key| to ensure that each child can be distinguished even as
  // more children are added or removed.  We recommend using a simple
  // counter which is incremented on each (re-)addition.
  //
  // If the child becomes unavailable at any time prior to being removed
  // then an |OnChildUnavailable()| message will be sent.
  //
  // If |child_view_owner| refers to a view which is already unavailable or
  // if adding the view would create a cycle in the view tree then the
  // call proceeds as if it succeeded but an |OnChildUnavailable()| message
  // will be sent.
  //
  // If |child_view_owner| refers to a view which already has a container or is
  // the root of a view tree then an |OnChildUnavailable()| message will
  // be sent to its old container or root and the the view will be
  // (re-)added to its new container as usual.  This special case also
  // applies when the specified view is already a child of this view, in which
  // case the behavior is similar to the view having been transferred to
  // some other container and then back again.
  //
  // Note that an unavailable child will remain in its container's list of
  // children until its container explicitly calls |RemoveChild()| to remove
  // it.
  //
  // It is an error to add a view whose |child_key| already appears
  // in the view's list of children; the connection will be closed.
  //
  // It is an error to add more than one child to a |ViewTree|'s container;
  // it can only have at most one child (its root).
  AddChild(uint32 child_key, ViewOwner child_view_owner);

  // Removes the view referenced by |child_key| from the view's
  // list of children.
  //
  // If |transferred_view_owner| is not null, associates it with the
  // previously added child to allow it to be transferred elsewhere or
  // closes the |transferred_view_owner| message pipe if there was none.
  //
  // It is an error to remove a view whose |child_key| does not appear
  // in the container's list of children; the connection will be closed.
  RemoveChild(uint32 child_key, ViewOwner&? transferred_view_owner);

  // Sets the layout parameters of the child view referenced by |child_key|
  // 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 child has become unavailable.
  //
  // It is an error to specify a |child_key| that does not appear in
  // the parent's list of children; the connection will be closed.
  //
  // It is an error to specify malformed |child_layout_params| such
  // as invalid size constraints; the connection will be closed.
  LayoutChild(uint32 child_key, mojo.ui.ViewLayoutParams child_layout_params)
      => (mojo.ui.ViewLayoutInfo? info);
};

// An interface clients may implement to receive events from a view container.
interface ViewContainerListener {
  // Called when a child view is attached along with embedding information.
  //
  // This method will be called at most once after the child is added.
  //
  // The implementation should invoke the callback once the event has
  // been handled.
  OnChildAttached(uint32 child_key, ViewInfo child_view_info) => ();

  // Called when a child view has become unavailable.
  //
  // A child may become unavailable for many reasons such being unregistered
  // by its application, abnormal termination of its application, or
  // cycles being introduced in the view tree.
  //
  // To complete removal of an unavailable child, this view component must
  // call RemoveChild() on its view with |child_key|.
  //
  // The implementation should invoke the callback once the event has
  // been handled.
  OnChildUnavailable(uint32 child_key) => ();
};

// Provides embedding information about a view for use by its container.
//
// This information is valid until the container removes the view.
struct ViewInfo {
  // The scene which represents the contents of the embedded view to be
  // included in its container's view.
  //
  // This scene is created by the view manager as a wrapper for the actual
  // scene generated by the embedded view.  It will be destroyed when the
  // container removes the view.
  mojo.gfx.composition.SceneToken scene_token;
};