src/ppapi/api/ppb_input_event.idl

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