mojo/services/ui/views/interfaces/view_associates.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/hit_tests.mojom";
import "mojo/services/gfx/composition/interfaces/scene_token.mojom";
import "mojo/services/ui/views/interfaces/view_token.mojom";
import "mojo/services/ui/views/interfaces/view_tree_token.mojom";

// View associates are trusted components that are attached to a view manager
// instance with the purpose of offering additional services to views and
// view trees registered beyond the basic operations performed by the
// view manager itself.  Associates may be used to implement input,
// accessibility, editing, and other capabilities.
//
// Associates are coupled to a view manager instance for the entire life
// of that view manager.  Associates cannot be dynamically added or removed
// since applications rely on the services that they offer and expect them
// to be available for the lifetime of their views.  Moreover, all views and
// view trees registered with a particular view manager instance share
// the same set of associates.
//
// This mechanism is designed to avoid a potential explosion in complexity
// if all features which depend on the state of views were implemented
// in one place.
//
// TODO(jeffbrown): In the current implementation, the view manager binds
// to a hard coded set of associates at start up time which can be overridden
// from the command-line.  We should find a better way to register associates
// once we decide how the system as a whole should be initialized.
[ServiceName="mojo::ui::ViewAssociate"]
interface ViewAssociate {
  // Connects to the associate.
  //
  // The |inspector| provides a means for the view associate to query state
  // from the view manager.
  //
  // The associate must return information about the services that it
  // offers in |info|.
  Connect(ViewInspector inspector) => (ViewAssociateInfo info);

  // Asks the associate to provide the view service identified by
  // |interface_name| through the message |pipe| endpoint supplied by
  // the caller.  If the associate is not willing or able to provide the
  // requested service, it should close the |pipe|.
  //
  // The |view_token| is the token of the view which requested the service.
  ConnectToViewService(ViewToken view_token,
                       string service_name,
                       handle<message_pipe> pipe);

  // Asks the associate to provide the view tree service identified by
  // |interface_name| through the message |pipe| endpoint supplied by
  // the caller.  If the associate is not willing or able to provide the
  // requested service, it should close the |pipe|.
  //
  // The |view_tree_token| is the token of the view tree which requested
  // the service.
  ConnectToViewTreeService(ViewTreeToken view_tree_token,
                           string service_name,
                           handle<message_pipe> pipe);
};

// Provides information about the services offered by an associate.
struct ViewAssociateInfo {
  // The names of view services offered by the associate.
  // May be null if none.
  array<string>? view_service_names;

  // The names of view tree services offered by the associate.
  // May be null if none.
  array<string>? view_tree_service_names;
};

// Provides a view associate with the ability to inspect and perform operations
// on the contents of views and view trees.
interface ViewInspector {
  // Provides an interface which can be used to perform hit tests on the
  // contents of the view tree's scene graph.
  //
  // The |hit_tester| will be closed if the view tree is not attached to a
  // renderer, when it is reattached to a different renderer, or when the
  // view tree is destroyed.
  //
  // The callback will be invoked the hit tester is invalidated.
  // If |renderer_changed| is true, the client should call |GetHitTester|
  // again to obtain a new one.  Otherwise it should assume that the view
  // tree has become unavailable (so no hit tester is available).
  GetHitTester(ViewTreeToken view_tree_token,
               mojo.gfx.composition.HitTester& hit_tester)
      => (bool renderer_changed);

  // Given an array of scene tokens, produces an array of view tokens
  // of equal size containing the view to which the scene belongs or null
  // if the scene token does not belong to any view.
  //
  // It is safe to cache the results of this operation because a scene will
  // only ever be associated with at most one view although a view may
  // create several scenes during its lifetime.
  ResolveScenes(array<mojo.gfx.composition.SceneToken> scene_tokens)
      => (array<ViewToken?> view_tokens);
};