ppapi: Opt-in to receive synthetic mouse events for touch-events.

ppapi/api/ppb_input_event.idl

 /* Copyright (c) 2012 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.
  */
 
 /**
  * This file defines the Input Event interfaces.
  */
 
 label Chrome {
@@ skipping 247 matching lines @@
    * for scrolling, producing the nested scrolling behavior users expect from
    * frames in a page.
    */
   PP_INPUTEVENT_CLASS_WHEEL = 1 << 2,
 
   /**
    * Identifies touch input events.
    *
    * Request touch events only if you intend to handle them. If the browser
    * knows you do not need to handle touch events, it can handle them at a
-   * higher level and achieve higher performance.
+   * higher level and achieve higher performance. If the plugin does not
+   * register for touch-events, then it will receive synthetic mouse events that
+   * are generated from the touch events (e.g. mouse-down for touch-start,
+   * mouse-move for touch-move (with left-button down), and mouse-up for
+   * touch-end. If the plugin does register for touch events, then the synthetic
+   * mouse events are not created.
    */
   PP_INPUTEVENT_CLASS_TOUCH = 1 << 3,
 
   /**
    * Identifies IME composition input events.
    *
    * Request this input event class if you allow on-the-spot IME input.
    */
   PP_INPUTEVENT_CLASS_IME = 1 << 4
 };
@@ skipping 20 matching lines @@
    * to non-filtering mode).
    *
    * Input events may have high overhead, so you should only request input
    * events that your plugin will actually handle. For example, the browser may
    * do optimizations for scroll or touch events that can be processed
    * substantially faster if it knows there are no non-default receivers for
    * that message. Requesting that such messages be delivered, even if they are
    * processed very quickly, may have a noticeable effect on the performance of
    * the page.
    *
+   * Note that synthetic mouse events will be generated from touch events if
+   * (and only if) the you do not request touch events.
+   *
    * When requesting input events through this function, the events will be
    * delivered and <i>not</i> bubbled to the page. This means that even if you
    * aren't interested in the message, no other parts of the page will get
    * a crack at the message.
    *
    * <strong>Example:</strong>
    * <code>
    *   RequestInputEvents(instance, PP_INPUTEVENT_CLASS_MOUSE);
    *   RequestFilteringInputEvents(instance,
    *       PP_INPUTEVENT_CLASS_WHEEL | PP_INPUTEVENT_CLASS_KEYBOARD);
@@ skipping 571 matching lines @@
    * @param[in] list The list.
    *
    * @param[in] touch_id The id of the touch-point.
    *
    * @return A <code>PP_TouchPoint</code> representing the touch-point.
    */
   PP_TouchPoint GetTouchById([in] PP_Resource resource,
                              [in] PP_TouchListType list,
                              [in] uint32_t touch_id);
 };