src/ppapi/c/ppb_input_event.h

   1 /* Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2  * Use of this source code is governed by a BSD-style license that can be
   3  * found in the LICENSE file.
   4  */
   5
   6 /* From ppb_input_event.idl modified Thu Apr  3 14:52:10 2014. */
   7
   8 #ifndef PPAPI_C_PPB_INPUT_EVENT_H_
   9 #define PPAPI_C_PPB_INPUT_EVENT_H_
  10
  11 #include "ppapi/c/pp_bool.h"
  12 #include "ppapi/c/pp_instance.h"
  13 #include "ppapi/c/pp_macros.h"
  14 #include "ppapi/c/pp_point.h"
  15 #include "ppapi/c/pp_resource.h"
  16 #include "ppapi/c/pp_stdint.h"
  17 #include "ppapi/c/pp_time.h"
  18 #include "ppapi/c/pp_touch_point.h"
  19 #include "ppapi/c/pp_var.h"
  20
  21 #define PPB_INPUT_EVENT_INTERFACE_1_0 "PPB_InputEvent;1.0"
  22 #define PPB_INPUT_EVENT_INTERFACE PPB_INPUT_EVENT_INTERFACE_1_0
  23
  24 #define PPB_MOUSE_INPUT_EVENT_INTERFACE_1_0 "PPB_MouseInputEvent;1.0"
  25 #define PPB_MOUSE_INPUT_EVENT_INTERFACE_1_1 "PPB_MouseInputEvent;1.1"
  26 #define PPB_MOUSE_INPUT_EVENT_INTERFACE PPB_MOUSE_INPUT_EVENT_INTERFACE_1_1
  27
  28 #define PPB_WHEEL_INPUT_EVENT_INTERFACE_1_0 "PPB_WheelInputEvent;1.0"
  29 #define PPB_WHEEL_INPUT_EVENT_INTERFACE PPB_WHEEL_INPUT_EVENT_INTERFACE_1_0
  30
  31 #define PPB_KEYBOARD_INPUT_EVENT_INTERFACE_1_0 "PPB_KeyboardInputEvent;1.0"
  32 #define PPB_KEYBOARD_INPUT_EVENT_INTERFACE_1_2 "PPB_KeyboardInputEvent;1.2"
  33 #define PPB_KEYBOARD_INPUT_EVENT_INTERFACE \
  34     PPB_KEYBOARD_INPUT_EVENT_INTERFACE_1_2
  35
  36 #define PPB_TOUCH_INPUT_EVENT_INTERFACE_1_0 "PPB_TouchInputEvent;1.0"
  37 #define PPB_TOUCH_INPUT_EVENT_INTERFACE PPB_TOUCH_INPUT_EVENT_INTERFACE_1_0
  38
  39 #define PPB_IME_INPUT_EVENT_INTERFACE_1_0 "PPB_IMEInputEvent;1.0"
  40 #define PPB_IME_INPUT_EVENT_INTERFACE PPB_IME_INPUT_EVENT_INTERFACE_1_0
  41
  42 /**
  43  * @file
  44  * This file defines the Input Event interfaces.
  45  */
  46
  47
  48 /**
  49  * @addtogroup Enums
  50  * @{
  51  */
  52 /**
  53  * This enumeration contains the types of input events.
  54  */
  55 typedef enum {
  56   PP_INPUTEVENT_TYPE_UNDEFINED = -1,
  57   /**
  58    * Notification that a mouse button was pressed.
  59    *
  60    * Register for this event using the PP_INPUTEVENT_CLASS_MOUSE class.
  61    */
  62   PP_INPUTEVENT_TYPE_MOUSEDOWN = 0,
  63   /**
  64    * Notification that a mouse button was released.
  65    *
  66    * Register for this event using the PP_INPUTEVENT_CLASS_MOUSE class.
  67    */
  68   PP_INPUTEVENT_TYPE_MOUSEUP = 1,
  69   /**
  70    * Notification that a mouse button was moved when it is over the instance
  71    * or dragged out of it.
  72    *
  73    * Register for this event using the PP_INPUTEVENT_CLASS_MOUSE class.
  74    */
  75   PP_INPUTEVENT_TYPE_MOUSEMOVE = 2,
  76   /**
  77    * Notification that the mouse entered the instance's bounds.
  78    *
  79    * Register for this event using the PP_INPUTEVENT_CLASS_MOUSE class.
  80    */
  81   PP_INPUTEVENT_TYPE_MOUSEENTER = 3,
  82   /**
  83    * Notification that a mouse left the instance's bounds.
  84    *
  85    * Register for this event using the PP_INPUTEVENT_CLASS_MOUSE class.
  86    */
  87   PP_INPUTEVENT_TYPE_MOUSELEAVE = 4,
  88   /**
  89    * Notification that the scroll wheel was used.
  90    *
  91    * Register for this event using the PP_INPUTEVENT_CLASS_WHEEL class.
  92    */
  93   PP_INPUTEVENT_TYPE_WHEEL = 5,
  94   /**
  95    * Notification that a key transitioned from "up" to "down".
  96    *
  97    * Register for this event using the PP_INPUTEVENT_CLASS_KEYBOARD class.
  98    */
  99   /*
 100    * TODO(brettw) differentiate from KEYDOWN.
 101    */
 102   PP_INPUTEVENT_TYPE_RAWKEYDOWN = 6,
 103   /**
 104    * Notification that a key was pressed. This does not necessarily correspond
 105    * to a character depending on the key and language. Use the
 106    * PP_INPUTEVENT_TYPE_CHAR for character input.
 107    *
 108    * Register for this event using the PP_INPUTEVENT_CLASS_KEYBOARD class.
 109    */
 110   PP_INPUTEVENT_TYPE_KEYDOWN = 7,
 111   /**
 112    * Notification that a key was released.
 113    *
 114    * Register for this event using the PP_INPUTEVENT_CLASS_KEYBOARD class.
 115    */
 116   PP_INPUTEVENT_TYPE_KEYUP = 8,
 117   /**
 118    * Notification that a character was typed. Use this for text input. Key
 119    * down events may generate 0, 1, or more than one character event depending
 120    * on the key, locale, and operating system.
 121    *
 122    * Register for this event using the PP_INPUTEVENT_CLASS_KEYBOARD class.
 123    */
 124   PP_INPUTEVENT_TYPE_CHAR = 9,
 125   /**
 126    * Notification that a context menu should be shown.
 127    *
 128    * This message will be sent when the user right-clicks or performs another
 129    * OS-specific mouse command that should open a context menu. When this event
 130    * is delivered depends on the system, on some systems (Mac) it will
 131    * delivered after the mouse down event, and on others (Windows) it will be
 132    * delivered after the mouse up event.
 133    *
 134    * You will always get the normal mouse events. For example, you may see
 135    * MOUSEDOWN,CONTEXTMENU,MOUSEUP or MOUSEDOWN,MOUSEUP,CONTEXTMENU.
 136    *
 137    * The return value from the event handler determines if the context menu
 138    * event will be passed to the page when you are using filtered input events
 139    * (via RequestFilteringInputEvents()). In non-filtering mode the event will
 140    * never be propagated and no context menu will be displayed. If you are
 141    * handling mouse events in filtering mode, you may want to return true from
 142    * this event even if you do not support a context menu to suppress the
 143    * default one.
 144    *
 145    * Register for this event using the PP_INPUTEVENT_CLASS_MOUSE class.
 146    */
 147   PP_INPUTEVENT_TYPE_CONTEXTMENU = 10,
 148   /**
 149    * Notification that an input method composition process has just started.
 150    *
 151    * Register for this event using the PP_INPUTEVENT_CLASS_IME class.
 152    */
 153   PP_INPUTEVENT_TYPE_IME_COMPOSITION_START = 11,
 154   /**
 155    * Notification that the input method composition string is updated.
 156    *
 157    * Register for this event using the PP_INPUTEVENT_CLASS_IME class.
 158    */
 159   PP_INPUTEVENT_TYPE_IME_COMPOSITION_UPDATE = 12,
 160   /**
 161    * Notification that an input method composition process has completed.
 162    *
 163    * Register for this event using the PP_INPUTEVENT_CLASS_IME class.
 164    */
 165   PP_INPUTEVENT_TYPE_IME_COMPOSITION_END = 13,
 166   /**
 167    * Notification that an input method committed a string.
 168    *
 169    * Register for this event using the PP_INPUTEVENT_CLASS_IME class.
 170    */
 171   PP_INPUTEVENT_TYPE_IME_TEXT = 14,
 172   /**
 173    * Notification that a finger was placed on a touch-enabled device.
 174    *
 175    * Register for this event using the PP_INPUTEVENT_CLASS_TOUCH class.
 176    */
 177   PP_INPUTEVENT_TYPE_TOUCHSTART = 15,
 178   /**
 179    * Notification that a finger was moved on a touch-enabled device.
 180    *
 181    * Register for this event using the PP_INPUTEVENT_CLASS_TOUCH class.
 182    */
 183   PP_INPUTEVENT_TYPE_TOUCHMOVE = 16,
 184   /**
 185    * Notification that a finger was released on a touch-enabled device.
 186    *
 187    * Register for this event using the PP_INPUTEVENT_CLASS_TOUCH class.
 188    */
 189   PP_INPUTEVENT_TYPE_TOUCHEND = 17,
 190   /**
 191    * Notification that a touch event was canceled.
 192    *
 193    * Register for this event using the PP_INPUTEVENT_CLASS_TOUCH class.
 194    */
 195   PP_INPUTEVENT_TYPE_TOUCHCANCEL = 18
 196 } PP_InputEvent_Type;
 197 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_InputEvent_Type, 4);
 198
 199 /**
 200  * This enumeration contains event modifier constants. Each modifier is one
 201  * bit. Retrieve the modifiers from an input event using the GetEventModifiers
 202  * function on PPB_InputEvent.
 203  */
 204 typedef enum {
 205   PP_INPUTEVENT_MODIFIER_SHIFTKEY = 1 << 0,
 206   PP_INPUTEVENT_MODIFIER_CONTROLKEY = 1 << 1,
 207   PP_INPUTEVENT_MODIFIER_ALTKEY = 1 << 2,
 208   PP_INPUTEVENT_MODIFIER_METAKEY = 1 << 3,
 209   PP_INPUTEVENT_MODIFIER_ISKEYPAD = 1 << 4,
 210   PP_INPUTEVENT_MODIFIER_ISAUTOREPEAT = 1 << 5,
 211   PP_INPUTEVENT_MODIFIER_LEFTBUTTONDOWN = 1 << 6,
 212   PP_INPUTEVENT_MODIFIER_MIDDLEBUTTONDOWN = 1 << 7,
 213   PP_INPUTEVENT_MODIFIER_RIGHTBUTTONDOWN = 1 << 8,
 214   PP_INPUTEVENT_MODIFIER_CAPSLOCKKEY = 1 << 9,
 215   PP_INPUTEVENT_MODIFIER_NUMLOCKKEY = 1 << 10,
 216   PP_INPUTEVENT_MODIFIER_ISLEFT = 1 << 11,
 217   PP_INPUTEVENT_MODIFIER_ISRIGHT = 1 << 12
 218 } PP_InputEvent_Modifier;
 219 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_InputEvent_Modifier, 4);
 220
 221 /**
 222  * This enumeration contains constants representing each mouse button. To get
 223  * the mouse button for a mouse down or up event, use GetMouseButton on
 224  * PPB_InputEvent.
 225  */
 226 typedef enum {
 227   PP_INPUTEVENT_MOUSEBUTTON_NONE = -1,
 228   PP_INPUTEVENT_MOUSEBUTTON_LEFT = 0,
 229   PP_INPUTEVENT_MOUSEBUTTON_MIDDLE = 1,
 230   PP_INPUTEVENT_MOUSEBUTTON_RIGHT = 2
 231 } PP_InputEvent_MouseButton;
 232 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_InputEvent_MouseButton, 4);
 233
 234 typedef enum {
 235   /**
 236    * Request mouse input events.
 237    *
 238    * Normally you will request mouse events by calling RequestInputEvents().
 239    * The only use case for filtered events (via RequestFilteringInputEvents())
 240    * is for instances that have irregular outlines and you want to perform hit
 241    * testing, which is very uncommon. Requesting non-filtered mouse events will
 242    * lead to higher performance.
 243    */
 244   PP_INPUTEVENT_CLASS_MOUSE = 1 << 0,
 245   /**
 246    * Requests keyboard events. Often you will want to request filtered mode
 247    * (via RequestFilteringInputEvents) for keyboard events so you can pass on
 248    * events (by returning false) that you don't handle. For example, if you
 249    * don't request filtered mode and the user pressed "Page Down" when your
 250    * instance has focus, the page won't scroll which will be a poor experience.
 251    *
 252    * A small number of tab and window management commands like Alt-F4 are never
 253    * sent to the page. You can not request these keyboard commands since it
 254    * would allow pages to trap users on a page.
 255    */
 256   PP_INPUTEVENT_CLASS_KEYBOARD = 1 << 1,
 257   /**
 258    * Identifies scroll wheel input event. Wheel events must be requested in
 259    * filtering mode via RequestFilteringInputEvents(). This is because many
 260    * wheel commands should be forwarded to the page.
 261    *
 262    * Most instances will not need this event. Consuming wheel events by
 263    * returning true from your filtered event handler will prevent the user from
 264    * scrolling the page when the mouse is over the instance which can be very
 265    * annoying.
 266    *
 267    * If you handle wheel events (for example, you have a document viewer which
 268    * the user can scroll), the recommended behavior is to return false only if
 269    * the wheel event actually causes your document to scroll. When the user
 270    * reaches the end of the document, return false to indicating that the event
 271    * was not handled. This will then forward the event to the containing page
 272    * for scrolling, producing the nested scrolling behavior users expect from
 273    * frames in a page.
 274    */
 275   PP_INPUTEVENT_CLASS_WHEEL = 1 << 2,
 276   /**
 277    * Identifies touch input events.
 278    *
 279    * Request touch events only if you intend to handle them. If the browser
 280    * knows you do not need to handle touch events, it can handle them at a
 281    * higher level and achieve higher performance. If the plugin does not
 282    * register for touch-events, then it will receive synthetic mouse events that
 283    * are generated from the touch events (e.g. mouse-down for touch-start,
 284    * mouse-move for touch-move (with left-button down), and mouse-up for
 285    * touch-end. If the plugin does register for touch events, then the synthetic
 286    * mouse events are not created.
 287    */
 288   PP_INPUTEVENT_CLASS_TOUCH = 1 << 3,
 289   /**
 290    * Identifies IME composition input events.
 291    *
 292    * Request this input event class if you allow on-the-spot IME input.
 293    */
 294   PP_INPUTEVENT_CLASS_IME = 1 << 4
 295 } PP_InputEvent_Class;
 296 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_InputEvent_Class, 4);
 297 /**
 298  * @}
 299  */
 300
 301 /**
 302  * @addtogroup Interfaces
 303  * @{
 304  */
 305 /**
 306  * The <code>PPB_InputEvent</code> interface contains pointers to several
 307  * functions related to generic input events on the browser.
 308  */
 309 struct PPB_InputEvent_1_0 {
 310   /**
 311    * RequestInputEvent() requests that input events corresponding to the given
 312    * input events are delivered to the instance.
 313    *
 314    * It's recommended that you use RequestFilteringInputEvents() for keyboard
 315    * events instead of this function so that you don't interfere with normal
 316    * browser accelerators.
 317    *
 318    * By default, no input events are delivered. Call this function with the
 319    * classes of events you are interested in to have them be delivered to
 320    * the instance. Calling this function will override any previous setting for
 321    * each specified class of input events (for example, if you previously
 322    * called RequestFilteringInputEvents(), this function will set those events
 323    * to non-filtering mode).
 324    *
 325    * Input events may have high overhead, so you should only request input
 326    * events that your plugin will actually handle. For example, the browser may
 327    * do optimizations for scroll or touch events that can be processed
 328    * substantially faster if it knows there are no non-default receivers for
 329    * that message. Requesting that such messages be delivered, even if they are
 330    * processed very quickly, may have a noticeable effect on the performance of
 331    * the page.
 332    *
 333    * Note that synthetic mouse events will be generated from touch events if
 334    * (and only if) you do not request touch events.
 335    *
 336    * When requesting input events through this function, the events will be
 337    * delivered and <i>not</i> bubbled to the default handlers.
 338    *
 339    * <strong>Example:</strong>
 340    * @code
 341    *   RequestInputEvents(instance, PP_INPUTEVENT_CLASS_MOUSE);
 342    *   RequestFilteringInputEvents(instance,
 343    *       PP_INPUTEVENT_CLASS_WHEEL | PP_INPUTEVENT_CLASS_KEYBOARD);
 344    * @endcode
 345    *
 346    * @param instance The <code>PP_Instance</code> of the instance requesting
 347    * the given events.
 348    *
 349    * @param event_classes A combination of flags from
 350    * <code>PP_InputEvent_Class</code> that identifies the classes of events the
 351    * instance is requesting. The flags are combined by logically ORing their
 352    * values.
 353    *
 354    * @return <code>PP_OK</code> if the operation succeeded,
 355    * <code>PP_ERROR_BADARGUMENT</code> if instance is invalid, or
 356    * <code>PP_ERROR_NOTSUPPORTED</code> if one of the event class bits were
 357    * illegal. In the case of an invalid bit, all valid bits will be applied
 358    * and only the illegal bits will be ignored. The most common cause of a
 359    * <code>PP_ERROR_NOTSUPPORTED</code> return value is requesting keyboard
 360    * events, these must use RequestFilteringInputEvents().
 361    */
 362   int32_t (*RequestInputEvents)(PP_Instance instance, uint32_t event_classes);
 363   /**
 364    * RequestFilteringInputEvents() requests that input events corresponding to
 365    * the given input events are delivered to the instance for filtering.
 366    *
 367    * By default, no input events are delivered. In most cases you would
 368    * register to receive events by calling RequestInputEvents(). In some cases,
 369    * however, you may wish to filter events such that they can be bubbled up
 370    * to the default handlers. In this case, register for those classes of
 371    * events using this function instead of RequestInputEvents().
 372    *
 373    * Filtering input events requires significantly more overhead than just
 374    * delivering them to the instance. As such, you should only request
 375    * filtering in those cases where it's absolutely necessary. The reason is
 376    * that it requires the browser to stop and block for the instance to handle
 377    * the input event, rather than sending the input event asynchronously. This
 378    * can have significant overhead.
 379    *
 380    * <strong>Example:</strong>
 381    * @code
 382    *   RequestInputEvents(instance, PP_INPUTEVENT_CLASS_MOUSE);
 383    *   RequestFilteringInputEvents(instance,
 384    *       PP_INPUTEVENT_CLASS_WHEEL | PP_INPUTEVENT_CLASS_KEYBOARD);
 385    * @endcode
 386    *
 387    * @return <code>PP_OK</code> if the operation succeeded,
 388    * <code>PP_ERROR_BADARGUMENT</code> if instance is invalid, or
 389    * <code>PP_ERROR_NOTSUPPORTED</code> if one of the event class bits were
 390    * illegal. In the case of an invalid bit, all valid bits will be applied
 391    * and only the illegal bits will be ignored.
 392    */
 393   int32_t (*RequestFilteringInputEvents)(PP_Instance instance,
 394                                          uint32_t event_classes);
 395   /**
 396    * ClearInputEventRequest() requests that input events corresponding to the
 397    * given input classes no longer be delivered to the instance.
 398    *
 399    * By default, no input events are delivered. If you have previously
 400    * requested input events via RequestInputEvents() or
 401    * RequestFilteringInputEvents(), this function will unregister handling
 402    * for the given instance. This will allow greater browser performance for
 403    * those events.
 404    *
 405    * Note that you may still get some input events after clearing the flag if
 406    * they were dispatched before the request was cleared. For example, if
 407    * there are 3 mouse move events waiting to be delivered, and you clear the
 408    * mouse event class during the processing of the first one, you'll still
 409    * receive the next two. You just won't get more events generated.
 410    *
 411    * @param instance The <code>PP_Instance</code> of the instance requesting
 412    * to no longer receive the given events.
 413    *
 414    * @param event_classes A combination of flags from
 415    * <code>PP_InputEvent_Class</code> that identify the classes of events the
 416    * instance is no longer interested in.
 417    */
 418   void (*ClearInputEventRequest)(PP_Instance instance, uint32_t event_classes);
 419   /**
 420    * IsInputEvent() returns true if the given resource is a valid input event
 421    * resource.
 422    *
 423    * @param[in] resource A <code>PP_Resource</code> corresponding to a generic
 424    * resource.
 425    *
 426    * @return <code>PP_TRUE</code> if the given resource is a valid input event
 427    * resource.
 428    */
 429   PP_Bool (*IsInputEvent)(PP_Resource resource);
 430   /**
 431    * GetType() returns the type of input event for the given input event
 432    * resource.
 433    *
 434    * @param[in] resource A <code>PP_Resource</code> corresponding to an input
 435    * event.
 436    *
 437    * @return A <code>PP_InputEvent_Type</code> if its a valid input event or
 438    * <code>PP_INPUTEVENT_TYPE_UNDEFINED</code> if the resource is invalid.
 439    */
 440   PP_InputEvent_Type (*GetType)(PP_Resource event);
 441   /**
 442    * GetTimeStamp() Returns the time that the event was generated. This will be
 443    *  before the current time since processing and dispatching the event has
 444    * some overhead. Use this value to compare the times the user generated two
 445    * events without being sensitive to variable processing time.
 446    *
 447    * @param[in] resource A <code>PP_Resource</code> corresponding to the event.
 448    *
 449    * @return The return value is in time ticks, which is a monotonically
 450    * increasing clock not related to the wall clock time. It will not change
 451    * if the user changes their clock or daylight savings time starts, so can
 452    * be reliably used to compare events. This means, however, that you can't
 453    * correlate event times to a particular time of day on the system clock.
 454    */
 455   PP_TimeTicks (*GetTimeStamp)(PP_Resource event);
 456   /**
 457    * GetModifiers() returns a bitfield indicating which modifiers were down
 458    * at the time of the event. This is a combination of the flags in the
 459    * <code>PP_InputEvent_Modifier</code> enum.
 460    *
 461    * @param[in] resource A <code>PP_Resource</code> corresponding to an input
 462    * event.
 463    *
 464    * @return The modifiers associated with the event, or 0 if the given
 465    * resource is not a valid event resource.
 466    */
 467   uint32_t (*GetModifiers)(PP_Resource event);
 468 };
 469
 470 typedef struct PPB_InputEvent_1_0 PPB_InputEvent;
 471
 472 /**
 473  * The <code>PPB_MouseInputEvent</code> interface contains pointers to several
 474  * functions related to mouse input events.
 475  */
 476 struct PPB_MouseInputEvent_1_1 {
 477   /**
 478    * Create() creates a mouse input event with the given parameters. Normally
 479    * you will get a mouse event passed through the
 480    * <code>HandleInputEvent</code> and will not need to create them, but some
 481    * applications may want to create their own for internal use. The type must
 482    * be one of the mouse event types.
 483    *
 484    * @param[in] instance The instance for which this event occurred.
 485    *
 486    * @param[in] type A <code>PP_InputEvent_Type</code> identifying the type of
 487    * input event.
 488    *
 489    * @param[in] time_stamp A <code>PP_TimeTicks</code> indicating the time
 490    * when the event occurred.
 491    *
 492    * @param[in] modifiers A bit field combination of the
 493    * <code>PP_InputEvent_Modifier</code> flags.
 494    *
 495    * @param[in] mouse_button The button that changed for mouse down or up
 496    * events. This value will be <code>PP_EVENT_MOUSEBUTTON_NONE</code> for
 497    * mouse move, enter, and leave events.
 498    *
 499    * @param[in] mouse_position A <code>Point</code> containing the x and y
 500    * position of the mouse when the event occurred.
 501    *
 502    * @param[in] mouse_movement The change in position of the mouse.
 503    *
 504    * @return A <code>PP_Resource</code> containing the new mouse input event.
 505    */
 506   PP_Resource (*Create)(PP_Instance instance,
 507                         PP_InputEvent_Type type,
 508                         PP_TimeTicks time_stamp,
 509                         uint32_t modifiers,
 510                         PP_InputEvent_MouseButton mouse_button,
 511                         const struct PP_Point* mouse_position,
 512                         int32_t click_count,
 513                         const struct PP_Point* mouse_movement);
 514   /**
 515    * IsMouseInputEvent() determines if a resource is a mouse event.
 516    *
 517    * @param[in] resource A <code>PP_Resource</code> corresponding to an event.
 518    *
 519    * @return <code>PP_TRUE</code> if the given resource is a valid mouse input
 520    * event, otherwise <code>PP_FALSE</code>.
 521    */
 522   PP_Bool (*IsMouseInputEvent)(PP_Resource resource);
 523   /**
 524    * GetButton() returns the mouse button that generated a mouse down or up
 525    * event.
 526    *
 527    * @param[in] mouse_event A <code>PP_Resource</code> corresponding to a
 528    * mouse event.
 529    *
 530    * @return The mouse button associated with mouse down and up events. This
 531    * value will be <code>PP_EVENT_MOUSEBUTTON_NONE</code> for mouse move,
 532    * enter, and leave events, and for all non-mouse events.
 533    */
 534   PP_InputEvent_MouseButton (*GetButton)(PP_Resource mouse_event);
 535   /**
 536    * GetPosition() returns the pixel location of a mouse input event. When
 537    * the mouse is locked, it returns the last known mouse position just as
 538    * mouse lock was entered.
 539    *
 540    * @param[in] mouse_event A <code>PP_Resource</code> corresponding to a
 541    * mouse event.
 542    *
 543    * @return The point associated with the mouse event, relative to the upper-
 544    * left of the instance receiving the event. These values can be negative for
 545    * mouse drags. The return value will be (0, 0) for non-mouse events.
 546    */
 547   struct PP_Point (*GetPosition)(PP_Resource mouse_event);
 548   /*
 549    * TODO(brettw) figure out exactly what this means.
 550    */
 551   int32_t (*GetClickCount)(PP_Resource mouse_event);
 552   /**
 553    * Returns the change in position of the mouse. When the mouse is locked,
 554    * although the mouse position doesn't actually change, this function
 555    * still provides movement information, which indicates what the change in
 556    * position would be had the mouse not been locked.
 557    *
 558    * @param[in] mouse_event A <code>PP_Resource</code> corresponding to a
 559    * mouse event.
 560    *
 561    * @return The change in position of the mouse, relative to the previous
 562    * position.
 563    */
 564   struct PP_Point (*GetMovement)(PP_Resource mouse_event);
 565 };
 566
 567 typedef struct PPB_MouseInputEvent_1_1 PPB_MouseInputEvent;
 568
 569 struct PPB_MouseInputEvent_1_0 {
 570   PP_Resource (*Create)(PP_Instance instance,
 571                         PP_InputEvent_Type type,
 572                         PP_TimeTicks time_stamp,
 573                         uint32_t modifiers,
 574                         PP_InputEvent_MouseButton mouse_button,
 575                         const struct PP_Point* mouse_position,
 576                         int32_t click_count);
 577   PP_Bool (*IsMouseInputEvent)(PP_Resource resource);
 578   PP_InputEvent_MouseButton (*GetButton)(PP_Resource mouse_event);
 579   struct PP_Point (*GetPosition)(PP_Resource mouse_event);
 580   int32_t (*GetClickCount)(PP_Resource mouse_event);
 581 };
 582
 583 /**
 584  * The <code>PPB_WheelIputEvent</code> interface contains pointers to several
 585  * functions related to wheel input events.
 586  */
 587 struct PPB_WheelInputEvent_1_0 {
 588   /**
 589    * Create() creates a wheel input event with the given parameters. Normally
 590    * you will get a wheel event passed through the
 591    * <code>HandleInputEvent</code> and will not need to create them, but some
 592    * applications may want to create their own for internal use.
 593    *
 594    * @param[in] instance The instance for which this event occurred.
 595    *
 596    * @param[in] time_stamp A <code>PP_TimeTicks</code> indicating the time
 597    * when the event occurred.
 598    *
 599    * @param[in] modifiers A bit field combination of the
 600    * <code>PP_InputEvent_Modifier</code> flags.
 601    *
 602    * @param[in] wheel_delta The scroll wheel's horizontal and vertical scroll
 603    * amounts.
 604    *
 605    * @param[in] wheel_ticks The number of "clicks" of the scroll wheel that
 606    * have produced the event.
 607    *
 608    * @param[in] scroll_by_page When true, the user is requesting to scroll
 609    * by pages. When false, the user is requesting to scroll by lines.
 610    *
 611    * @return A <code>PP_Resource</code> containing the new wheel input event.
 612    */
 613   PP_Resource (*Create)(PP_Instance instance,
 614                         PP_TimeTicks time_stamp,
 615                         uint32_t modifiers,
 616                         const struct PP_FloatPoint* wheel_delta,
 617                         const struct PP_FloatPoint* wheel_ticks,
 618                         PP_Bool scroll_by_page);
 619   /**
 620    * IsWheelInputEvent() determines if a resource is a wheel event.
 621    *
 622    * @param[in] wheel_event A <code>PP_Resource</code> corresponding to an
 623    * event.
 624    *
 625    * @return <code>PP_TRUE</code> if the given resource is a valid wheel input
 626    * event.
 627    */
 628   PP_Bool (*IsWheelInputEvent)(PP_Resource resource);
 629   /**
 630    * GetDelta() returns the amount vertically and horizontally the user has
 631    * requested to scroll by with their mouse wheel. A scroll down or to the
 632    * right (where the content moves up or left) is represented as positive
 633    * values, and a scroll up or to the left (where the content moves down or
 634    * right) is represented as negative values.
 635    *
 636    * This amount is system dependent and will take into account the user's
 637    * preferred scroll sensitivity and potentially also nonlinear acceleration
 638    * based on the speed of the scrolling.
 639    *
 640    * Devices will be of varying resolution. Some mice with large detents will
 641    * only generate integer scroll amounts. But fractional values are also
 642    * possible, for example, on some trackpads and newer mice that don't have
 643    * "clicks".
 644    *
 645    * @param[in] wheel_event A <code>PP_Resource</code> corresponding to a wheel
 646    * event.
 647    *
 648    * @return The vertical and horizontal scroll values. The units are either in
 649    * pixels (when scroll_by_page is false) or pages (when scroll_by_page is
 650    * true). For example, y = -3 means scroll up 3 pixels when scroll_by_page
 651    * is false, and scroll up 3 pages when scroll_by_page is true.
 652    */
 653   struct PP_FloatPoint (*GetDelta)(PP_Resource wheel_event);
 654   /**
 655    * GetTicks() returns the number of "clicks" of the scroll wheel
 656    * that have produced the event. The value may have system-specific
 657    * acceleration applied to it, depending on the device. The positive and
 658    * negative meanings are the same as for GetDelta().
 659    *
 660    * If you are scrolling, you probably want to use the delta values.  These
 661    * tick events can be useful if you aren't doing actual scrolling and don't
 662    * want or pixel values. An example may be cycling between different items in
 663    * a game.
 664    *
 665    * @param[in] wheel_event A <code>PP_Resource</code> corresponding to a wheel
 666    * event.
 667    *
 668    * @return The number of "clicks" of the scroll wheel. You may receive
 669    * fractional values for the wheel ticks if the mouse wheel is high
 670    * resolution or doesn't have "clicks". If your program wants discrete
 671    * events (as in the "picking items" example) you should accumulate
 672    * fractional click values from multiple messages until the total value
 673    * reaches positive or negative one. This should represent a similar amount
 674    * of scrolling as for a mouse that has a discrete mouse wheel.
 675    */
 676   struct PP_FloatPoint (*GetTicks)(PP_Resource wheel_event);
 677   /**
 678    * GetScrollByPage() indicates if the scroll delta x/y indicates pages or
 679    * lines to scroll by.
 680    *
 681    * @param[in] wheel_event A <code>PP_Resource</code> corresponding to a wheel
 682    * event.
 683    *
 684    * @return <code>PP_TRUE</code> if the event is a wheel event and the user is
 685    * scrolling by pages. <code>PP_FALSE</code> if not or if the resource is not
 686    * a wheel event.
 687    */
 688   PP_Bool (*GetScrollByPage)(PP_Resource wheel_event);
 689 };
 690
 691 typedef struct PPB_WheelInputEvent_1_0 PPB_WheelInputEvent;
 692
 693 /**
 694  * The <code>PPB_KeyboardInputEvent</code> interface contains pointers to
 695  * several functions related to keyboard input events.
 696  */
 697 struct PPB_KeyboardInputEvent_1_2 {
 698   /**
 699    * Creates a keyboard input event with the given parameters. Normally you
 700    * will get a keyboard event passed through the HandleInputEvent and will not
 701    * need to create them, but some applications may want to create their own
 702    * for internal use. The type must be one of the keyboard event types.
 703    *
 704    * @param[in] instance The instance for which this event occurred.
 705    *
 706    * @param[in] type A <code>PP_InputEvent_Type</code> identifying the type of
 707    * input event.
 708    *
 709    * @param[in] time_stamp A <code>PP_TimeTicks</code> indicating the time
 710    * when the event occurred.
 711    *
 712    * @param[in] modifiers A bit field combination of the
 713    * <code>PP_InputEvent_Modifier</code> flags.
 714    *
 715    * @param[in] key_code This value reflects the DOM KeyboardEvent
 716    * <code>keyCode</code> field, which is the Windows-style Virtual Key
 717    * code of the key.
 718    *
 719    * @param[in] character_text This value represents the typed character as a
 720    * UTF-8 string.
 721    *
 722    * @param[in] code This value represents the DOM3 |code| string that
 723    * corresponds to the physical key being pressed.
 724    *
 725    * @return A <code>PP_Resource</code> containing the new keyboard input
 726    * event.
 727    */
 728   PP_Resource (*Create)(PP_Instance instance,
 729                         PP_InputEvent_Type type,
 730                         PP_TimeTicks time_stamp,
 731                         uint32_t modifiers,
 732                         uint32_t key_code,
 733                         struct PP_Var character_text,
 734                         struct PP_Var code);
 735   /**
 736    * IsKeyboardInputEvent() determines if a resource is a keyboard event.
 737    *
 738    * @param[in] resource A <code>PP_Resource</code> corresponding to an event.
 739    *
 740    * @return <code>PP_TRUE</code> if the given resource is a valid input event.
 741    */
 742   PP_Bool (*IsKeyboardInputEvent)(PP_Resource resource);
 743   /**
 744    * GetKeyCode() returns the DOM keyCode field for the keyboard event.
 745    * Chrome populates this with the Windows-style Virtual Key code of the key.
 746    *
 747    * @param[in] key_event A <code>PP_Resource</code> corresponding to a
 748    * keyboard event.
 749    *
 750    * @return The DOM keyCode field for the keyboard event.
 751    */
 752   uint32_t (*GetKeyCode)(PP_Resource key_event);
 753   /**
 754    * GetCharacterText() returns the typed character as a UTF-8 string for the
 755    * given character event.
 756    *
 757    * @param[in] character_event A <code>PP_Resource</code> corresponding to a
 758    * keyboard event.
 759    *
 760    * @return A string var representing a single typed character for character
 761    * input events. For non-character input events the return value will be an
 762    * undefined var.
 763    */
 764   struct PP_Var (*GetCharacterText)(PP_Resource character_event);
 765   /**
 766    * GetCode() returns the DOM |code| field for this keyboard event, as
 767    * defined in the DOM3 Events spec:
 768    * http://www.w3.org/TR/DOM-Level-3-Events/
 769    *
 770    * @param[in] key_event The key event for which to return the key code.
 771    *
 772    * @return The string that contains the DOM |code| for the keyboard event.
 773    */
 774   struct PP_Var (*GetCode)(PP_Resource key_event);
 775 };
 776
 777 typedef struct PPB_KeyboardInputEvent_1_2 PPB_KeyboardInputEvent;
 778
 779 struct PPB_KeyboardInputEvent_1_0 {
 780   PP_Resource (*Create)(PP_Instance instance,
 781                         PP_InputEvent_Type type,
 782                         PP_TimeTicks time_stamp,
 783                         uint32_t modifiers,
 784                         uint32_t key_code,
 785                         struct PP_Var character_text);
 786   PP_Bool (*IsKeyboardInputEvent)(PP_Resource resource);
 787   uint32_t (*GetKeyCode)(PP_Resource key_event);
 788   struct PP_Var (*GetCharacterText)(PP_Resource character_event);
 789 };
 790 /**
 791  * @}
 792  */
 793
 794 /**
 795  * @addtogroup Enums
 796  * @{
 797  */
 798 typedef enum {
 799   /**
 800    * The list of all TouchPoints which are currently down.
 801    */
 802   PP_TOUCHLIST_TYPE_TOUCHES = 0,
 803   /**
 804    * The list of all TouchPoints whose state has changed since the last
 805    * TouchInputEvent.
 806    */
 807   PP_TOUCHLIST_TYPE_CHANGEDTOUCHES = 1,
 808   /**
 809    * The list of all TouchPoints which are targeting this plugin.  This is a
 810    * subset of Touches.
 811    */
 812   PP_TOUCHLIST_TYPE_TARGETTOUCHES = 2
 813 } PP_TouchListType;
 814 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_TouchListType, 4);
 815 /**
 816  * @}
 817  */
 818
 819 /**
 820  * @addtogroup Interfaces
 821  * @{
 822  */
 823 /**
 824  * The <code>PPB_TouchInputEvent</code> interface contains pointers to several
 825  * functions related to touch events.
 826  */
 827 struct PPB_TouchInputEvent_1_0 {
 828   /**
 829    * Creates a touch input event with the given parameters. Normally you
 830    * will get a touch event passed through the HandleInputEvent and will not
 831    * need to create them, but some applications may want to create their own
 832    * for internal use. The type must be one of the touch event types.
 833    * This newly created touch input event does not have any touch point in any
 834    * of the touch-point lists. <code>AddTouchPoint</code> should be called to
 835    * add the touch-points.
 836    *
 837    * @param[in] instance The instance for which this event occurred.
 838    *
 839    * @param[in] type A <code>PP_InputEvent_Type</code> identifying the type of
 840    * input event.
 841    *
 842    * @param[in] time_stamp A <code>PP_TimeTicks</code> indicating the time
 843    * when the event occurred.
 844    *
 845    * @param[in]  modifiers A bit field combination of the
 846    * <code>PP_InputEvent_Modifier</code> flags.
 847    *
 848    * @return A <code>PP_Resource</code> containing the new touch input event.
 849    */
 850   PP_Resource (*Create)(PP_Instance instance,
 851                         PP_InputEvent_Type type,
 852                         PP_TimeTicks time_stamp,
 853                         uint32_t modifiers);
 854   /**
 855    * Adds a touch point to the touch event in the specified touch-list.
 856    *
 857    * @param[in] touch_event A <code>PP_Resource</code> corresponding to a touch
 858    * event.
 859    *
 860    * @param[in] list The list to add the touch point to.
 861    *
 862    * @param[in] point The point to add to the list.
 863    */
 864   void (*AddTouchPoint)(PP_Resource touch_event,
 865                         PP_TouchListType list,
 866                         const struct PP_TouchPoint* point);
 867   /**
 868    * IsTouchInputEvent() determines if a resource is a touch event.
 869    *
 870    * @param[in] resource A <code>PP_Resource</code> corresponding to an event.
 871    *
 872    * @return <code>PP_TRUE</code> if the given resource is a valid touch input
 873    * event, otherwise <code>PP_FALSE</code>.
 874    */
 875   PP_Bool (*IsTouchInputEvent)(PP_Resource resource);
 876   /**
 877    * Returns the number of touch-points in the specified list.
 878    *
 879    * @param[in] resource A <code>PP_Resource</code> corresponding to a touch
 880    * event.
 881    *
 882    * @param[in] list The list.
 883    *
 884    * @return The number of touch-points in the specified list.
 885    */
 886   uint32_t (*GetTouchCount)(PP_Resource resource, PP_TouchListType list);
 887   /**
 888    * Returns the touch-point at the specified index from the specified list.
 889    *
 890    * @param[in] resource A <code>PP_Resource</code> corresponding to a touch
 891    * event.
 892    *
 893    * @param[in] list The list.
 894    *
 895    * @param[in] index The index.
 896    *
 897    * @return A <code>PP_TouchPoint</code> representing the touch-point.
 898    */
 899   struct PP_TouchPoint (*GetTouchByIndex)(PP_Resource resource,
 900                                           PP_TouchListType list,
 901                                           uint32_t index);
 902   /**
 903    * Returns the touch-point with the specified touch-id in the specified list.
 904    *
 905    * @param[in] resource A <code>PP_Resource</code> corresponding to a touch
 906    * event.
 907    *
 908    * @param[in] list The list.
 909    *
 910    * @param[in] touch_id The id of the touch-point.
 911    *
 912    * @return A <code>PP_TouchPoint</code> representing the touch-point.
 913    */
 914   struct PP_TouchPoint (*GetTouchById)(PP_Resource resource,
 915                                        PP_TouchListType list,
 916                                        uint32_t touch_id);
 917 };
 918
 919 typedef struct PPB_TouchInputEvent_1_0 PPB_TouchInputEvent;
 920
 921 struct PPB_IMEInputEvent_1_0 {
 922   /**
 923    * Create() creates an IME input event with the given parameters. Normally
 924    * you will get an IME event passed through the <code>HandleInputEvent</code>
 925    * and will not need to create them, but some applications may want to create
 926    * their own for internal use.
 927    *
 928    * @param[in] instance The instance for which this event occurred.
 929    *
 930    * @param[in] type A <code>PP_InputEvent_Type</code> identifying the type of
 931    * input event. The type must be one of the IME event types.
 932    *
 933    * @param[in] time_stamp A <code>PP_TimeTicks</code> indicating the time
 934    * when the event occurred.
 935    *
 936    * @param[in] text The string returned by <code>GetText</code>.
 937    *
 938    * @param[in] segment_number The number returned by
 939    * <code>GetSegmentNumber</code>.
 940    *
 941    * @param[in] segment_offsets The array of numbers returned by
 942    * <code>GetSegmentOffset</code>. If <code>segment_number</code> is zero,
 943    * the number of elements of the array should be zero. If
 944    * <code>segment_number</code> is non-zero, the length of the array must be
 945    * <code>segment_number</code> + 1.
 946    *
 947    * @param[in] target_segment The number returned by
 948    * <code>GetTargetSegment</code>.
 949    *
 950    * @param[in] selection_start The start index returned by
 951    * <code>GetSelection</code>.
 952    *
 953    * @param[in] selection_end The end index returned by
 954    * <code>GetSelection</code>.
 955    *
 956    * @return A <code>PP_Resource</code> containing the new IME input event.
 957    */
 958   PP_Resource (*Create)(PP_Instance instance,
 959                         PP_InputEvent_Type type,
 960                         PP_TimeTicks time_stamp,
 961                         struct PP_Var text,
 962                         uint32_t segment_number,
 963                         const uint32_t segment_offsets[],
 964                         int32_t target_segment,
 965                         uint32_t selection_start,
 966                         uint32_t selection_end);
 967   /**
 968    * IsIMEInputEvent() determines if a resource is an IME event.
 969    *
 970    * @param[in] resource A <code>PP_Resource</code> corresponding to an event.
 971    *
 972    * @return <code>PP_TRUE</code> if the given resource is a valid input event.
 973    */
 974   PP_Bool (*IsIMEInputEvent)(PP_Resource resource);
 975   /**
 976    * GetText() returns the composition text as a UTF-8 string for the given IME
 977    * event.
 978    *
 979    * @param[in] ime_event A <code>PP_Resource</code> corresponding to an IME
 980    * event.
 981    *
 982    * @return A string var representing the composition text. For non-IME input
 983    * events the return value will be an undefined var.
 984    */
 985   struct PP_Var (*GetText)(PP_Resource ime_event);
 986   /**
 987    * GetSegmentNumber() returns the number of segments in the composition text.
 988    *
 989    * @param[in] ime_event A <code>PP_Resource</code> corresponding to an IME
 990    * event.
 991    *
 992    * @return The number of segments. For events other than COMPOSITION_UPDATE,
 993    * returns 0.
 994    */
 995   uint32_t (*GetSegmentNumber)(PP_Resource ime_event);
 996   /**
 997    * GetSegmentOffset() returns the position of the index-th segmentation point
 998    * in the composition text. The position is given by a byte-offset (not a
 999    * character-offset) of the string returned by GetText(). It always satisfies
1000    * 0=GetSegmentOffset(0) < ... < GetSegmentOffset(i) < GetSegmentOffset(i+1)
1001    * < ... < GetSegmentOffset(GetSegmentNumber())=(byte-length of GetText()).
1002    * Note that [GetSegmentOffset(i), GetSegmentOffset(i+1)) represents the range
1003    * of the i-th segment, and hence GetSegmentNumber() can be a valid argument
1004    * to this function instead of an off-by-1 error.
1005    *
1006    * @param[in] ime_event A <code>PP_Resource</code> corresponding to an IME
1007    * event.
1008    *
1009    * @param[in] index An integer indicating a segment.
1010    *
1011    * @return The byte-offset of the segmentation point. If the event is not
1012    * COMPOSITION_UPDATE or index is out of range, returns 0.
1013    */
1014   uint32_t (*GetSegmentOffset)(PP_Resource ime_event, uint32_t index);
1015   /**
1016    * GetTargetSegment() returns the index of the current target segment of
1017    * composition.
1018    *
1019    * @param[in] ime_event A <code>PP_Resource</code> corresponding to an IME
1020    * event.
1021    *
1022    * @return An integer indicating the index of the target segment. When there
1023    * is no active target segment, or the event is not COMPOSITION_UPDATE,
1024    * returns -1.
1025    */
1026   int32_t (*GetTargetSegment)(PP_Resource ime_event);
1027   /**
1028    * GetSelection() returns the range selected by caret in the composition text.
1029    *
1030    * @param[in] ime_event A <code>PP_Resource</code> corresponding to an IME
1031    * event.
1032    *
1033    * @param[out] start The start position of the current selection.
1034    *
1035    * @param[out] end The end position of the current selection.
1036    */
1037   void (*GetSelection)(PP_Resource ime_event, uint32_t* start, uint32_t* end);
1038 };
1039
1040 typedef struct PPB_IMEInputEvent_1_0 PPB_IMEInputEvent;
1041 /**
1042  * @}
1043  */
1044
1045 #endif  /* PPAPI_C_PPB_INPUT_EVENT_H_ */
1046