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

// TODO(jeffbrown): Redesign input event representation later.
import "mojo/services/input_events/interfaces/input_events.mojom";

// The input dispatcher service allows the component which owns and controls
// a view tree to dispatch input events to the views that it contains.
//
// This service can be retrieved from the |ViewTreeHost| service provider.
//
// TODO(jeffbrown): Elaborate how input devices are registered with the
// dispatcher so that applications can query their capabilities and distinguish
// input coming from multiple sources concurrently.
[ServiceName="mojo::ui::InputDispatcher"]
interface InputDispatcher {
  // Dispatches an event through the view tree.  The dispatcher will deliver
  // the event to the appropriate views based on the current state of the
  // tree, such as focus and the structure of the scene graph.
  //
  // The dispatcher expects the stream of events that it receives to be
  // internally consistent.  For example, each pointer down must be matched
  // by a corresponding pointer up.
  //
  // It is an error to supply an inconsistent stream events to the dispatcher;
  // the connection will be closed.
  //
  // TODO(jeffbrown): Is this the right policy?  It would certainly help
  // diagnose faults earlier.
  // TODO(jeffbrown): Decide whether there should be a way to track the
  // progress of input events.  For testing purposes it is often desirable
  // to block the test until a sequence of events have been delivered and
  // handled.  However these same mechanisms have proven to be brittle in
  // the past so it might be better to solve the problem some other way.
  DispatchEvent(mojo.Event event);
};