Fix iOS build for XCode 4.6.
[chromium-blink-merge.git] / ppapi / api / ppb_input_event.idl
blob496a0a68b313e01a31c23f54796a65552773db62
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 */
6 /**
7 * This file defines the Input Event interfaces.
8 */
10 label Chrome {
11 M13 = 1.0,
12 M14 = 1.1
15 /**
16 * This enumeration contains the types of input events.
18 [assert_size(4)]
19 enum PP_InputEvent_Type {
20 PP_INPUTEVENT_TYPE_UNDEFINED = -1,
22 /**
23 * Notification that a mouse button was pressed.
25 * Register for this event using the PP_INPUTEVENT_CLASS_MOUSE class.
27 PP_INPUTEVENT_TYPE_MOUSEDOWN = 0,
29 /**
30 * Notification that a mouse button was released.
32 * Register for this event using the PP_INPUTEVENT_CLASS_MOUSE class.
34 PP_INPUTEVENT_TYPE_MOUSEUP = 1,
36 /**
37 * Notification that a mouse button was moved when it is over the instance
38 * or dragged out of it.
40 * Register for this event using the PP_INPUTEVENT_CLASS_MOUSE class.
42 PP_INPUTEVENT_TYPE_MOUSEMOVE = 2,
44 /**
45 * Notification that the mouse entered the instance's bounds.
47 * Register for this event using the PP_INPUTEVENT_CLASS_MOUSE class.
49 PP_INPUTEVENT_TYPE_MOUSEENTER = 3,
51 /**
52 * Notification that a mouse left the instance's bounds.
54 * Register for this event using the PP_INPUTEVENT_CLASS_MOUSE class.
56 PP_INPUTEVENT_TYPE_MOUSELEAVE = 4,
58 /**
59 * Notification that the scroll wheel was used.
61 * Register for this event using the PP_INPUTEVENT_CLASS_WHEEL class.
63 PP_INPUTEVENT_TYPE_WHEEL = 5,
65 /**
66 * Notification that a key transitioned from "up" to "down".
68 * Register for this event using the PP_INPUTEVENT_CLASS_KEYBOARD class.
72 * TODO(brettw) differentiate from KEYDOWN.
74 PP_INPUTEVENT_TYPE_RAWKEYDOWN = 6,
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.
81 * Register for this event using the PP_INPUTEVENT_CLASS_KEYBOARD class.
83 PP_INPUTEVENT_TYPE_KEYDOWN = 7,
85 /**
86 * Notification that a key was released.
88 * Register for this event using the PP_INPUTEVENT_CLASS_KEYBOARD class.
90 PP_INPUTEVENT_TYPE_KEYUP = 8,
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.
97 * Register for this event using the PP_INPUTEVENT_CLASS_KEYBOARD class.
99 PP_INPUTEVENT_TYPE_CHAR = 9,
102 * Notification that a context menu should be shown.
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.
110 * You will always get the normal mouse events. For example, you may see
111 * MOUSEDOWN,CONTEXTMENU,MOUSEUP or MOUSEDOWN,MOUSEUP,CONTEXTMENU.
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.
121 * Register for this event using the PP_INPUTEVENT_CLASS_MOUSE class.
123 PP_INPUTEVENT_TYPE_CONTEXTMENU = 10,
126 * Notification that an input method composition process has just started.
128 * Register for this event using the PP_INPUTEVENT_CLASS_IME class.
130 PP_INPUTEVENT_TYPE_IME_COMPOSITION_START = 11,
133 * Notification that the input method composition string is updated.
135 * Register for this event using the PP_INPUTEVENT_CLASS_IME class.
137 PP_INPUTEVENT_TYPE_IME_COMPOSITION_UPDATE = 12,
140 * Notification that an input method composition process has completed.
142 * Register for this event using the PP_INPUTEVENT_CLASS_IME class.
144 PP_INPUTEVENT_TYPE_IME_COMPOSITION_END = 13,
147 * Notification that an input method committed a string.
149 * Register for this event using the PP_INPUTEVENT_CLASS_IME class.
151 PP_INPUTEVENT_TYPE_IME_TEXT = 14,
154 * Notification that a finger was placed on a touch-enabled device.
156 * Register for this event using the PP_INPUTEVENT_CLASS_TOUCH class.
158 PP_INPUTEVENT_TYPE_TOUCHSTART = 15,
161 * Notification that a finger was moved on a touch-enabled device.
163 * Register for this event using the PP_INPUTEVENT_CLASS_TOUCH class.
165 PP_INPUTEVENT_TYPE_TOUCHMOVE = 16,
168 * Notification that a finger was released on a touch-enabled device.
170 * Register for this event using the PP_INPUTEVENT_CLASS_TOUCH class.
172 PP_INPUTEVENT_TYPE_TOUCHEND = 17,
175 * Notification that a touch event was canceled.
177 * Register for this event using the PP_INPUTEVENT_CLASS_TOUCH class.
179 PP_INPUTEVENT_TYPE_TOUCHCANCEL = 18
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.
187 [assert_size(4)]
188 enum 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
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.
209 [assert_size(4)]
210 enum 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
217 [assert_size(4)]
218 enum PP_InputEvent_Class {
220 * Request mouse input events.
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.
228 PP_INPUTEVENT_CLASS_MOUSE = 1 << 0,
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.
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.
241 PP_INPUTEVENT_CLASS_KEYBOARD = 1 << 1,
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.
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.
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.
261 PP_INPUTEVENT_CLASS_WHEEL = 1 << 2,
264 * Identifies touch input events.
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.
275 PP_INPUTEVENT_CLASS_TOUCH = 1 << 3,
278 * Identifies IME composition input events.
280 * Request this input event class if you allow on-the-spot IME input.
282 PP_INPUTEVENT_CLASS_IME = 1 << 4
286 * The <code>PPB_InputEvent</code> interface contains pointers to several
287 * functions related to generic input events on the browser.
289 [version=1.0, macro="PPB_INPUT_EVENT_INTERFACE"]
290 interface PPB_InputEvent {
292 * RequestInputEvent() requests that input events corresponding to the given
293 * input events are delivered to the instance.
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.
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).
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.
314 * Note that synthetic mouse events will be generated from touch events if
315 * (and only if) the you do not request touch events.
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.
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 * </code>
329 * @param instance The <code>PP_Instance</code> of the instance requesting
330 * the given events.
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.
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().
345 int32_t RequestInputEvents([in] PP_Instance instance,
346 [in] uint32_t event_classes);
349 * RequestFilteringInputEvents() requests that input events corresponding to
350 * the given input events are delivered to the instance for filtering.
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().
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.
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 * </code>
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.
378 int32_t RequestFilteringInputEvents([in] PP_Instance instance,
379 [in] uint32_t event_classes);
382 * ClearInputEventRequest() requests that input events corresponding to the
383 * given input classes no longer be delivered to the instance.
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.
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.
397 * @param instance The <code>PP_Instance</code> of the instance requesting
398 * to no longer receive the given events.
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.
404 void ClearInputEventRequest([in] PP_Instance instance,
405 [in] uint32_t event_classes);
408 * IsInputEvent() returns true if the given resource is a valid input event
409 * resource.
411 * @param[in] resource A <code>PP_Resource</code> corresponding to a generic
412 * resource.
414 * @return <code>PP_TRUE</code> if the given resource is a valid input event
415 * resource.
417 PP_Bool IsInputEvent([in] PP_Resource resource);
420 * GetType() returns the type of input event for the given input event
421 * resource.
423 * @param[in] resource A <code>PP_Resource</code> corresponding to an input
424 * event.
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.
429 PP_InputEvent_Type GetType([in] PP_Resource event);
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.
437 * @param[in] resource A <code>PP_Resource</code> corresponding to the event.
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.
445 PP_TimeTicks GetTimeStamp([in] PP_Resource event);
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.
452 * @param[in] resource A <code>PP_Resource</code> corresponding to an input
453 * event.
455 * @return The modifiers associated with the event, or 0 if the given
456 * resource is not a valid event resource.
458 uint32_t GetModifiers([in] PP_Resource event);
462 * The <code>PPB_MouseInputEvent</code> interface contains pointers to several
463 * functions related to mouse input events.
465 [macro="PPB_MOUSE_INPUT_EVENT_INTERFACE"]
466 interface PPB_MouseInputEvent {
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.
474 * @param[in] instance The instance for which this event occurred.
476 * @param[in] type A <code>PP_InputEvent_Type</code> identifying the type of
477 * input event.
479 * @param[in] time_stamp A <code>PP_TimeTicks</code> indicating the time
480 * when the event occurred.
482 * @param[in] modifiers A bit field combination of the
483 * <code>PP_InputEvent_Modifier</code> flags.
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.
489 * @param[in] mouse_position A <code>Point</code> containing the x and y
490 * position of the mouse when the event occurred.
492 * @return A <code>PP_Resource</code> containing the new mouse input event.
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);
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.
509 * @param[in] instance The instance for which this event occurred.
511 * @param[in] type A <code>PP_InputEvent_Type</code> identifying the type of
512 * input event.
514 * @param[in] time_stamp A <code>PP_TimeTicks</code> indicating the time
515 * when the event occurred.
517 * @param[in] modifiers A bit field combination of the
518 * <code>PP_InputEvent_Modifier</code> flags.
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.
524 * @param[in] mouse_position A <code>Point</code> containing the x and y
525 * position of the mouse when the event occurred.
527 * @param[in] mouse_movement The change in position of the mouse.
529 * @return A <code>PP_Resource</code> containing the new mouse input event.
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);
541 * IsMouseInputEvent() determines if a resource is a mouse event.
543 * @param[in] resource A <code>PP_Resource</code> corresponding to an event.
545 * @return <code>PP_TRUE</code> if the given resource is a valid mouse input
546 * event, otherwise <code>PP_FALSE</code>.
548 PP_Bool IsMouseInputEvent([in] PP_Resource resource);
551 * GetButton() returns the mouse button that generated a mouse down or up
552 * event.
554 * @param[in] mouse_event A <code>PP_Resource</code> corresponding to a
555 * mouse event.
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.
561 PP_InputEvent_MouseButton GetButton([in] PP_Resource mouse_event);
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.
568 * @param[in] mouse_event A <code>PP_Resource</code> corresponding to a
569 * mouse event.
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.
575 [returnByValue] PP_Point GetPosition([in] PP_Resource mouse_event);
578 * TODO(brettw) figure out exactly what this means.
580 int32_t GetClickCount([in] PP_Resource mouse_event);
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.
588 * @param[in] mouse_event A <code>PP_Resource</code> corresponding to a
589 * mouse event.
591 * @return The change in position of the mouse, relative to the previous
592 * position.
594 [version=1.1]
595 PP_Point GetMovement([in] PP_Resource mouse_event);
600 * The <code>PPB_WheelIputEvent</code> interface contains pointers to several
601 * functions related to wheel input events.
603 [version=1.0, macro="PPB_WHEEL_INPUT_EVENT_INTERFACE"]
604 interface PPB_WheelInputEvent {
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.
611 * @param[in] instance The instance for which this event occurred.
613 * @param[in] time_stamp A <code>PP_TimeTicks</code> indicating the time
614 * when the event occurred.
616 * @param[in] modifiers A bit field combination of the
617 * <code>PP_InputEvent_Modifier</code> flags.
619 * @param[in] wheel_delta The scroll wheel's horizontal and vertical scroll
620 * amounts.
622 * @param[in] wheel_ticks The number of "clicks" of the scroll wheel that
623 * have produced the event.
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.
628 * @return A <code>PP_Resource</code> containing the new wheel input event.
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);
638 * IsWheelInputEvent() determines if a resource is a wheel event.
640 * @param[in] wheel_event A <code>PP_Resource</code> corresponding to an
641 * event.
643 * @return <code>PP_TRUE</code> if the given resource is a valid wheel input
644 * event.
646 PP_Bool IsWheelInputEvent([in] PP_Resource resource);
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.
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.
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".
664 * @param[in] wheel_event A <code>PP_Resource</code> corresponding to a wheel
665 * event.
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.
672 PP_FloatPoint GetDelta([in] PP_Resource wheel_event);
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().
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.
685 * @param[in] wheel_event A <code>PP_Resource</code> corresponding to a wheel
686 * event.
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.
696 PP_FloatPoint GetTicks([in] PP_Resource wheel_event);
699 * GetScrollByPage() indicates if the scroll delta x/y indicates pages or
700 * lines to scroll by.
702 * @param[in] wheel_event A <code>PP_Resource</code> corresponding to a wheel
703 * event.
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.
709 PP_Bool GetScrollByPage([in] PP_Resource wheel_event);
713 * The <code>PPB_KeyboardInputEvent</code> interface contains pointers to
714 * several functions related to keyboard input events.
716 [version=1.0, macro="PPB_KEYBOARD_INPUT_EVENT_INTERFACE"]
717 interface PPB_KeyboardInputEvent {
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.
724 * @param[in] instance The instance for which this event occurred.
726 * @param[in] type A <code>PP_InputEvent_Type</code> identifying the type of
727 * input event.
729 * @param[in] time_stamp A <code>PP_TimeTicks</code> indicating the time
730 * when the event occurred.
732 * @param[in] modifiers A bit field combination of the
733 * <code>PP_InputEvent_Modifier</code> flags.
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.
739 * @param[in] character_text This value represents the typed character as a
740 * UTF-8 string.
742 * @return A <code>PP_Resource</code> containing the new keyboard input
743 * event.
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);
753 * IsKeyboardInputEvent() determines if a resource is a keyboard event.
755 * @param[in] resource A <code>PP_Resource</code> corresponding to an event.
757 * @return <code>PP_TRUE</code> if the given resource is a valid input event.
759 PP_Bool IsKeyboardInputEvent([in] PP_Resource resource);
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.
765 * @param[in] key_event A <code>PP_Resource</code> corresponding to a
766 * keyboard event.
768 * @return The DOM keyCode field for the keyboard event.
770 uint32_t GetKeyCode([in] PP_Resource key_event);
773 * GetCharacterText() returns the typed character as a UTF-8 string for the
774 * given character event.
776 * @param[in] character_event A <code>PP_Resource</code> corresponding to a
777 * keyboard event.
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.
783 PP_Var GetCharacterText([in] PP_Resource character_event);
786 [assert_size(4)]
787 enum PP_TouchListType {
789 * The list of all TouchPoints which are currently down.
791 PP_TOUCHLIST_TYPE_TOUCHES = 0,
794 * The list of all TouchPoints whose state has changed since the last
795 * TouchInputEvent.
797 PP_TOUCHLIST_TYPE_CHANGEDTOUCHES = 1,
800 * The list of all TouchPoints which are targeting this plugin. This is a
801 * subset of Touches.
803 PP_TOUCHLIST_TYPE_TARGETTOUCHES = 2
807 * The <code>PPB_TouchInputEvent</code> interface contains pointers to several
808 * functions related to touch events.
810 [version=1.0, macro="PPB_TOUCH_INPUT_EVENT_INTERFACE"]
811 interface PPB_TouchInputEvent {
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.
821 * @param[in] instance The instance for which this event occurred.
823 * @param[in] type A <code>PP_InputEvent_Type</code> identifying the type of
824 * input event.
826 * @param[in] time_stamp A <code>PP_TimeTicks</code> indicating the time
827 * when the event occurred.
829 * @param[in] modifiers A bit field combination of the
830 * <code>PP_InputEvent_Modifier</code> flags.
832 * @return A <code>PP_Resource</code> containing the new touch input event.
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);
840 * Adds a touch point to the touch event in the specified touch-list.
842 * @param[in] touch_event A <code>PP_Resource</code> corresponding to a touch
843 * event.
845 * @param[in] list The list to add the touch point to.
847 * @param[in] point The point to add to the list.
849 void AddTouchPoint([in] PP_Resource touch_event,
850 [in] PP_TouchListType list,
851 [in] PP_TouchPoint point);
854 * IsTouchInputEvent() determines if a resource is a touch event.
856 * @param[in] resource A <code>PP_Resource</code> corresponding to an event.
858 * @return <code>PP_TRUE</code> if the given resource is a valid touch input
859 * event, otherwise <code>PP_FALSE</code>.
861 PP_Bool IsTouchInputEvent([in] PP_Resource resource);
864 * Returns the number of touch-points in the specified list.
866 * @param[in] resource A <code>PP_Resource</code> corresponding to a touch
867 * event.
869 * @param[in] list The list.
871 * @return The number of touch-points in the specified list.
873 uint32_t GetTouchCount([in] PP_Resource resource,
874 [in] PP_TouchListType list);
877 * Returns the touch-point at the specified index from the specified list.
879 * @param[in] resource A <code>PP_Resource</code> corresponding to a touch
880 * event.
882 * @param[in] list The list.
884 * @param[in] index The index.
886 * @return A <code>PP_TouchPoint</code> representing the touch-point.
888 PP_TouchPoint GetTouchByIndex([in] PP_Resource resource,
889 [in] PP_TouchListType list,
890 [in] uint32_t index);
893 * Returns the touch-point with the spcified touch-id in the specified list.
895 * @param[in] resource A <code>PP_Resource</code> corresponding to a touch
896 * event.
898 * @param[in] list The list.
900 * @param[in] touch_id The id of the touch-point.
902 * @return A <code>PP_TouchPoint</code> representing the touch-point.
904 PP_TouchPoint GetTouchById([in] PP_Resource resource,
905 [in] PP_TouchListType list,
906 [in] uint32_t touch_id);