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