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

// A view token is an opaque transferable reference to a view.
//
// The ViewManager provides each view with a unique view token when
// it is registered.  The token can subsequently be passed to other
// applications and may be used to add the view as a child of some
// other view or to set it as the root of a view tree.
//
// View tokens should be kept secret and should only be shared with
// the view's intended container.
//
// TODO(jeffbrown): This implementation is a temporary placeholder until
// we extend Mojo to provide a way to create tokens which cannot be forged.
struct ViewToken {
  uint32 value;
};

// A view owner provides access to the view's token and keeps the
// view alive.  When the view owner is closed, the view will be
// unregistered from the view manager.
//
// This interface is only intended to be implemented by the view manager
// to obtain the desired ownership semantics.
interface ViewOwner {
  // Gets the |ViewToken| associated with the view.
  GetToken() => (ViewToken token);
};

// A view is a graphical user interface component which is responsible
// for drawing and supporting user interactions in the area of the screen
// that it occupies.
//
// A view may also act as a container for other views (known as the
// view's children) which it may freely layout and position anywhere
// within its bounds to form a composite user interface.  The hierarchy
// of views thus formed is called a view tree.
//
// LIFECYCLE
//
// Use |ViewManager.CreateView()| to create a view.  The application
// uses the |View| interface to manage the view's content and implements
// the |ViewListener| interface to handle events.
//
// To destroy a view, simply close the |View| message pipe.
//
// SCENES
//
// Each view must provide content for its main scene, created using the
// |View.CreateScene()| interface.  To perform graphical composition of
// other components, the view's main scene may contain references to
// scenes belonging to child views or scenes created by other application
// components which interact with the compositor.
//
// See |mojo.gfx.compositor.Scene| for more information.
//
// EMBEDDING
//
// The following steps are required to embed another view into your own:
//
// 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.
//
// GETTING SERVICES
//
// The view's |ServiceProvider| offers access to many services which
// are not directly expressed by the |View| interface itself, such
// as input, accessiblity, and editing capabilities.
//
// For example, perform the following actions to receive input events:
//
// 1. Call |GetServiceProvider()| to obtain the view's service provider.
//
// 2. Ask the service provider for its |mojo.ui.InputConnection|.
//
// 3. Set listeners on the input connection to receive events.
interface View {
  // Gets the view's token.
  GetToken() => (ViewToken token);

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

  // Creates the view's scene, replacing any previous scene the view
  // might have had.
  //
  // The |scene| is used to supply content for the scene.  The scene pipe
  // is private to the scene and should not be shared with anyone else.
  //
  // To destroy the scene, simply close the |scene| message pipe.
  //
  // See also: |mojo.gfx.composition.Compositor.CreateScene()|.
  CreateScene(mojo.gfx.composition.Scene& scene);

  // Requests that the view's OnLayout() method be called to compute a
  // new layout due to a change in the view's layout information.
  RequestLayout();

  // 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 parent 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 parent 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 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
  // (re-)added to its new parent 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 parent and then back again.
  //
  // Note that an unavailable child will remain in its parent's list of
  // children until its parent 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.
  AddChild(uint32 child_key, mojo.ui.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 parent's list of children; the connection will be closed.
  RemoveChild(uint32 child_key, mojo.ui.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.
interface ViewListener {
  // Called when the view needs to update its layout and provide its size.
  //
  // This method may be called for one or more of the following reasons:
  //
  //   1. The view called RequestLayout() to mark itself as needing layout.
  //   2. The view's parent called LayoutChild() for the first time to
  //      provide layout parameters to this view.
  //   3. The view's parent called LayoutChild() and provided a
  //      set of layout parameters which differ from its prior call to
  //      OnLayout().
  //   4. One or more of the view's children were just added to the view
  //      tree using AddChild() or removed from the tree using RemoveChild().
  //   5. One or more of the view's children produced different layout
  //      information during their last layout pass causing a recursive
  //      layout to occur.
  //
  // The |children_needing_layout| array includes the keys of all children
  // which require a layout.  The view is responsible for calling LayoutChild()
  // at least once for each child in the array in addition to any other
  // children which might also need to be updated.
  //
  // Layout requests are coalesced for efficiency.  Certain intermediate
  // updates may be dropped if the view 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 is ready to be shown in its new aspect.
  //
  // The result of the layout may cause the parent's layout to be invalidated.
  // When this happens, the parent's own OnLayout() method will be called
  // and will be informed that this child needs layout.
  //
  // Recursive layout happens in any of the following circumstances:
  //
  //   1. If the resulting scene has changed since the last layout.
  //   2. If the resulting size has changed since the last layout.
  //
  // It is an error to return a malformed |result| which does not satisfy
  // the requested |layout_params|, such as by returning a size which
  // exceeds the requested constraints; the view's connection will be closed.
  OnLayout(mojo.ui.ViewLayoutParams layout_params,
    array<uint32> children_needing_layout) => (mojo.ui.ViewLayoutResult result);

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