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

// 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.
//
// ADDING CHILD VIEWS
//
// Use |GetContainer()| to obtain an interface for manipulating child views.
//
// See |mojo.ui.ViewContainer| for more information.
//
// 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();

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

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