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

  // 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 receives new properties from its container.
  //
  // Property change 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 |scene_version| specifies the version number which the view should
  // use when publishing scene updates which incorporate the new properties.
  // May be |kSceneVersionNone| if the version number is not important
  // (meaning that the container is not interested in coordinating scene
  // updates with the child).
  //
  // The implementation should invoke the callback once the event has
  // been handled and the view is ready to be shown in its new aspect.
  OnPropertiesChanged(uint32 scene_version, ViewProperties properties) => ();
};