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