Convert input event to interface version 1.0. Rename some of the mouse and

wheel events to remove the redundant "Mouse" and "Wheel" in the getters.

Rename PP_INPUTEVENT_TYPE_MOUSEWHEEL to .._WHEEL so that it doesn't look
like a mouse event (it's its own type).

Add documentation to the C++ wrapper from the C wrappers. Do some minor
documentation updates.

Update IDL for some of the recent changes we've made. Update the way points
are passed for resource creation since IDL wanted to do it by pointer.

TEST=it compiles.
Review URL: http://codereview.chromium.org/7464003

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@93263 0039d316-1c4b-4281-b951-d872f2087c98

4 files changed, 82 insertions, 64 deletions

diff --git a/ppapi/api/pp_input_event.idl b/ppapi/api/pp_input_event.idl
index 1ed93cc..7e43b8f 100644
--- a/ppapi/api/pp_input_event.idl
+++ b/ppapi/api/pp_input_event.idl
@@ -184,47 +184,3 @@ struct PP_InputEvent_Mouse {
   PP_Bool scroll_by_page;
 };
 
-/**
- * The PP_InputEventData union represents all input event data types.
- */
-[union] struct PP_InputEventData {
-  [wcomment] PP_InputEvent_Key key;
-  [wcomment] PP_InputEvent_Character character;
-  [wcomment] PP_InputEvent_Mouse mouse;
-  [wcomment] PP_InputEvent_Wheel wheel;
-
-  /**
-   * This value allows new events to be added without changing the size of
-   * this struct.
-   */
-  char[64] padding;
-
-};
-
-/**
- * The PP_InputEvent struct represents all input events.
- */
-[assert_size(80)]
-struct PP_InputEvent {
-  /** This value represents the type of the event. */
-  PP_InputEvent_Type type;
-
-  /** This value ensure the time_stamp is aligned on an 8-byte boundary
-   * relative to the start of the struct. Some compilers align doubles
-   * on 8-byte boundaries for 32-bit x86, and some align on 4-byte boundaries.
-   */
-  int32_t padding;
-
-  /**
-   * This value represents the time that this event was generated. This value
-   * is not relative to any particular epoch; the most you can do is compare
-   * time stamps.
-   */
-  PP_TimeTicks time_stamp;
-
-  /**
-   * This value represents the event type and its specific data.
-   */
-  PP_InputEventData u;
-};
-
diff --git a/ppapi/api/ppb_input_event.idl b/ppapi/api/ppb_input_event.idl
index 07e3ea8..ba4536a 100644
--- a/ppapi/api/ppb_input_event.idl
+++ b/ppapi/api/ppb_input_event.idl
@@ -8,7 +8,7 @@
  */
 
 label Chrome {
-  M14 = 0.1
+  M14 = 1.0
 };
 
 /**
@@ -59,7 +59,7 @@ enum PP_InputEvent_Type {
    *
    * Register for this event using the PP_INPUTEVENT_CLASS_WHEEL class.
    */
-  PP_INPUTEVENT_TYPE_MOUSEWHEEL  = 5,
+  PP_INPUTEVENT_TYPE_WHEEL  = 5,
 
   /**
    * Notification that a key transitioned from "up" to "down".
@@ -196,7 +196,7 @@ enum PP_InputEvent_Class {
   PP_INPUTEVENT_CLASS_IME = 1 << 4
 };
 
-[version=0.1, macro="PPB_INPUT_EVENT_INTERFACE"]
+[version=1.0, macro="PPB_INPUT_EVENT_INTERFACE"]
 interface PPB_InputEvent {
   /**
    * Request that input events corresponding to the given input events are
@@ -341,9 +341,23 @@ interface PPB_InputEvent {
   uint32_t GetModifiers([in] PP_Resource event);
 };
 
-[version=0.1, macro="PPB_MOUSE_INPUT_EVENT_INTERFACE"]
+[version=1.0, macro="PPB_MOUSE_INPUT_EVENT_INTERFACE"]
 interface PPB_MouseInputEvent {
   /**
+   * Creates a mouse input event with the given parameters. Normally you will
+   * get a mouse event passed through the HandleInputEvent and will not need
+   * to create them, but some applications may want to create their own for
+   * internal use. The type must be one of the mouse event types.
+   */
+  PP_Resource Create([in] PP_Instance instance,
+                     [in] PP_InputEvent_Type type,
+                     [in] PP_TimeTicks time_stamp,
+                     [in] uint32_t modifiers,
+                     [in] PP_InputEvent_MouseButton mouse_button,
+                     [in] PP_Point mouse_position,
+                     [in] int32_t click_count);
+
+  /**
    * Determines if a resource is a mouse event.
    *
    * @return PP_TRUE if the given resource is a valid mouse input event.
@@ -357,7 +371,7 @@ interface PPB_MouseInputEvent {
    * value will be PP_EVENT_MOUSEBUTTON_NONE for mouse move, enter, and leave
    * events, and for all non-mouse events.
    */
-  PP_InputEvent_MouseButton GetMouseButton([in] PP_Resource mouse_event);
+  PP_InputEvent_MouseButton GetButton([in] PP_Resource mouse_event);
 
   /**
    * Returns the pixel location of a mouse input event.
@@ -366,17 +380,30 @@ interface PPB_MouseInputEvent {
    * left of the instance receiving the event. These values can be negative for
    * mouse drags. The return value will be (0, 0) for non-mouse events.
    */
-  [returnByValue] PP_Point GetMousePosition([in] PP_Resource mouse_event);
+  [returnByValue] PP_Point GetPosition([in] PP_Resource mouse_event);
 
   /**
    * TODO(brettw) figure out exactly what this means.
    */
-  int32_t GetMouseClickCount([in] PP_Resource mouse_event);
+  int32_t GetClickCount([in] PP_Resource mouse_event);
 };
 
-[version=0.1, macro="PPB_WHEEL_INPUT_EVENT_INTERFACE"]
+[version=1.0, macro="PPB_WHEEL_INPUT_EVENT_INTERFACE"]
 interface PPB_WheelInputEvent {
   /**
+   * Creates a wheel input event with the given parameters. Normally you will
+   * get a wheel event passed through the HandleInputEvent and will not need
+   * to create them, but some applications may want to create their own for
+   * internal use.
+   */
+  PP_Resource Create([in] PP_Instance instance,
+                     [in] PP_TimeTicks time_stamp,
+                     [in] uint32_t modifiers,
+                     [in] PP_FloatPoint wheel_delta,
+                     [in] PP_FloatPoint wheel_ticks,
+                     [in] PP_Bool scroll_by_page);
+
+  /**
    * Determines if a resource is a wheel event.
    *
    * @return PP_TRUE if the given resource is a valid wheel input event.
@@ -404,7 +431,7 @@ interface PPB_WheelInputEvent {
    * possible, for example, on some trackpads and newer mice that don't have
    * "clicks".
    */
-  PP_FloatPoint GetWheelDelta([in] PP_Resource wheel_event);
+  PP_FloatPoint GetDelta([in] PP_Resource wheel_event);
 
   /**
    * The number of "clicks" of the scroll wheel that have produced the
@@ -424,7 +451,7 @@ interface PPB_WheelInputEvent {
    * reaches positive or negative one. This should represent a similar amount
    * of scrolling as for a mouse that has a discrete mouse wheel.
    */
-  PP_FloatPoint GetWheelTicks([in] PP_Resource wheel_event);
+  PP_FloatPoint GetTicks([in] PP_Resource wheel_event);
 
   /**
    * Indicates if the scroll delta x/y indicates pages or lines to
@@ -436,9 +463,22 @@ interface PPB_WheelInputEvent {
   PP_Bool GetScrollByPage([in] PP_Resource wheel_event);
 };
 
-[version=0.1, macro="PPB_KEYBOARD_INPUT_EVENT_INTERFACE"]
+[version=1.0, macro="PPB_KEYBOARD_INPUT_EVENT_INTERFACE"]
 interface PPB_KeyboardInputEvent {
   /**
+   * Creates a keyboard input event with the given parameters. Normally you
+   * will get a keyboard event passed through the HandleInputEvent and will not
+   * need to create them, but some applications may want to create their own
+   * for internal use. The type must be one of the keyboard event types.
+   */
+  PP_Resource Create([in] PP_Instance instance,
+                     [in] PP_InputEvent_Type type,
+                     [in] PP_TimeTicks time_stamp,
+                     [in] uint32_t modifiers,
+                     [in] uint32_t key_code,
+                     [in] PP_Var character_text);
+
+  /**
    * Determines if a resource is a keyboard event.
    *
    * @return PP_TRUE if the given resource is a valid mouse input event.
diff --git a/ppapi/api/ppb_instance.idl b/ppapi/api/ppb_instance.idl
index fefc785..12bf46f 100644
--- a/ppapi/api/ppb_instance.idl
+++ b/ppapi/api/ppb_instance.idl
@@ -28,15 +28,14 @@ interface PPB_Instance {
   PP_Var GetOwnerElementObject([in] PP_Instance instance);
 
   /**
-   * BindGraphics() binds the given graphics as the current drawing surface.
-   * The contents of this device is what will be displayed in the module's
+   * BindGraphics() binds the given graphics as the current display surface.
+   * The contents of this device is what will be displayed in the instance's
    * area on the web page. The device must be a 2D or a 3D device.
    *
    * You can pass a <code>NULL</code> resource as the device parameter to
    * unbind all devices from the given instance. The instance will then appear
    * transparent. Re-binding the same device will return <code>PP_TRUE</code>
-   * and will do nothing. Unbinding a device will drop any pending flush
-   * callbacks.
+   * and will do nothing.
    *
    * Any previously-bound device will be released. It is an error to bind
    * a device when it is already bound to another instance. If you want
@@ -59,11 +58,11 @@ interface PPB_Instance {
       [in] PP_Resource device);
 
   /**
-   * IsFullFrame() determines if the module instance is full-frame (repr).
-   * Such a module represents the entire document in a frame rather than an
-   * embedded resource. This can happen if the user does a top-level
-   * navigation or the page specifies an iframe to a resource with a MIME
-   * type registered by the module.
+   * IsFullFrame() determines if the instance is full-frame. Such an instance
+   * represents the entire document in a frame rather than an embedded
+   * resource. This can happen if the user does a top-level navigation or the
+   * page specifies an iframe to a resource with a MIME type registered by the
+   * module.
    *
    * @param[in] instance A <code>PP_Instance</code> indentifying one instance
    * of a module.
diff --git a/ppapi/api/ppp_input_event.idl b/ppapi/api/ppp_input_event.idl
index cfaf398..41af2ad 100644
--- a/ppapi/api/ppp_input_event.idl
+++ b/ppapi/api/ppp_input_event.idl
@@ -20,6 +20,19 @@ interface PPP_InputEvent {
    * PPB_InputEvent.RequestInputEvents() or RequestFilteringInputEvents(). By
    * default, no events are delivered.
    *
+   * If the event was handled, it will not be forwarded to the web page or
+   * browser. If it was not handled, it will bubble according to the normal
+   * rules. So it is important that an instance respond accurately with whether
+   * event propagation should continue.
+   *
+   * Event propagation also controls focus. If you handle an event like a mouse
+   * event, typically the instance will be given focus. Returning false from
+   * a filtered event handler or not registering for an event type means that
+   * the click will be given to a lower part of the page and your instance will
+   * not receive focus. This allows an instance to be partially transparent,
+   * where clicks on the transparent areas will behave like clicks to the
+   * underlying page.
+   *
    * In general, you should try to keep input event handling short. Especially
    * for filtered input events, the browser or page may be blocked waiting for
    * you to respond.
@@ -28,6 +41,16 @@ interface PPP_InputEvent {
    * resource during this call. Unless you take a reference to the resource
    * to hold it for later, you don't need to release it.
    *
+   * <strong>Note:</strong> If you're not receiving input events, make sure you
+   * register for the event classes you want by calling RequestInputEvents or
+   * RequestFilteringInputEvents. If you're still not receiving keyboard input
+   * events, make sure you're returning true (or using a non-filtered event
+   * handler) for mouse events. Otherwise, the instance will not receive focus
+   * and keyboard events will not be sent.
+   *
+   * \see PPB_InputEvent.ReqeustInputEvents and
+   * PPB_InputEvent.RequestFilteringInputEvents
+   *
    * @return PP_TRUE if the event was handled, PP_FALSE if not. If you have
    * registered to filter this class of events by calling
    * RequestFilteringInputEvents, and you return PP_FALSE, the event will