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