// 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/view_properties.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 |SetChildProperties()| to provide layout parameters and other
//    properties for the new child using the same key that was provided
//    to |AddChild()|.
//
// 4. After receiving |OnChildAttached()|, publish an update to your
//    |Scene| which includes a |SceneNodeOp| and a |SceneReference| to the
//    child's |SceneToken| as specified in its |ViewInfo|. The |SceneNodeOp|
//    should reference the same scene version that was provided to
//    |SetChildProperties()|.
//
// 5. Whenever the container set new child properties using
//    |SetChildProperties()|, it should provide a new scene version and
//    update its corresponding |SceneNodeOp| to match.
//
// 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.
//
// VIEW PROPERTIES AND LAYOUT
//
// The container controls the presentation of its children by setting
// |ViewProperties| for each of them.  View properties include layout
// information and other parameters the child needs to know to participate
// in the view hierarchy.
//
// The container must set properties for each of its children after adding
// them, as otherwise the children cannot be rendered (since they lack enough
// context to know what to draw).
//
// SYNCHRONIZATION
//
// When setting properties for a child, the container must provide a
// |child_scene_version| which will be used to mark the version of the
// child's scene which includes these properties.  The container must then
// update its own scene to reference the same version number in its
// |SceneNodeOp| for the child.  This mechanism ensures synchronization
// of child property changes with the container's own scene updates.
//
// See also |mojo.gfx.composition.Node| for information on how scene node
// combinators can be combined with scene versions to provide a fallback
// mechanism to avoid stalling the container's rendering when some of its
// children are unresponsive.
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 view properties for the child, such as layout constraints.
  //
  // This method must be called at least once after a child is added to
  // set the view's properties before it can be rendered.  Rendering for
  // children without properties is blocked until properties are set.
  //
  // The child will receive the new properties along with a scene version
  // which it should apply to the first scene update which includes the
  // effects of the property change.
  //
  // The |child_scene_version| specifies the version number which
  // the child should use when publishing scene updates which incorporate
  // the new properties.  May be |kSceneVersionNone| if the version number
  // is not important (meaning that there is no need to coordinate the
  // scene updates with the child).
  //
  // The |child_view_properties| specifies the properties for the child, or
  // null to remove the properties from the child which will cause rendering
  // of the child's scene to be blocked until new properties are set.
  //
  // It is an error to specify a |child_key| that does not appear in
  // the container's list of children; the connection will be closed.
  //
  // It is an error to specify malformed |child_view_properties| such
  // as invalid layout properties; the connection will be closed.
  SetChildProperties(uint32 child_key, uint32 child_scene_version,
      ViewProperties? child_view_properties);
};

// 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) => ();

  // TODO(jeffbrown): Once we figure out measurement, add a |OnChildResized|
  // event or similar to allow the container to get the size along with the
  // scene version.
};

// 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;
};