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 10label 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)] 20enum 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)] 189enum 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)] 211enum 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)] 219enum 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"] 291interface 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"] 465interface 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"] 603interface 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"] 716interface 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)] 838enum 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"] 862interface 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"] 961interface 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}; 1088