|
OLD | NEW |
---|---|
(Empty) | |
1 /* Copyright (c) 2011 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 #ifndef PPAPI_C_PPB_INPUT_EVENT_H_ | |
7 #define PPAPI_C_PPB_INPUT_EVENT_H_ | |
8 | |
9 #include "ppapi/c/pp_instance.h" | |
10 #include "ppapi/c/pp_macros.h" | |
11 #include "ppapi/c/pp_point.h" | |
12 #include "ppapi/c/pp_resource.h" | |
13 #include "ppapi/c/pp_stdint.h" | |
14 #include "ppapi/c/pp_time.h" | |
15 #include "ppapi/c/pp_var.h" | |
16 | |
17 #define PPB_INPUT_EVENT_INTERFACE_0_1 "PPB_InputEvent;0.1" | |
18 #define PPB_INPUT_EVENT_INTERFACE PPB_INPUT_EVENT_INTERFACE_0_1 | |
19 | |
20 #define PPB_MOUSE_INPUT_EVENT_INTERFACE_0_1 "PPB_MouseInputEvent;0.1" | |
21 #define PPB_MOUSE_INPUT_EVENT_INTERFACE PPB_MOUSE_INPUT_EVENT_INTERFACE_0_1 | |
22 | |
23 #define PPB_WHEEL_INPUT_EVENT_INTERFACE_0_1 "PPB_WheelInputEvent;0.1" | |
24 #define PPB_WHEEL_INPUT_EVENT_INTERFACE PPB_WHEEL_INPUT_EVENT_INTERFACE_0_1 | |
25 | |
26 #define PPB_KEYBOARD_INPUT_EVENT_INTERFACE_0_1 "PPB_KeyboardInputEvent;0.1" | |
27 #define PPB_KEYBOARD_INPUT_EVENT_INTERFACE \ | |
28 PPB_KEYBOARD_INPUT_EVENT_INTERFACE_0_1 | |
29 | |
30 /** | |
31 * @addtogroup Enums | |
32 * @{ | |
33 */ | |
34 | |
35 /** | |
36 * This enumeration contains the types of input events. | |
37 */ | |
38 typedef enum { | |
39 PP_INPUTEVENT_TYPE_UNDEFINED = -1, | |
40 | |
41 /** | |
42 * Notification that a mouse button was pressed. | |
43 * | |
44 * Register for this event using the PP_INPUTEVENT_CLASS_MOUSE class. | |
45 */ | |
46 PP_INPUTEVENT_TYPE_MOUSEDOWN = 0, | |
47 | |
48 /** | |
49 * Notification that a mouse button was released. | |
50 * | |
51 * Register for this event using the PP_INPUTEVENT_CLASS_MOUSE class. | |
52 */ | |
53 PP_INPUTEVENT_TYPE_MOUSEUP = 1, | |
54 | |
55 /** | |
56 * Notification that a mouse button was moved when it is over the instance | |
57 * or dragged out of it. | |
58 * | |
59 * Register for this event using the PP_INPUTEVENT_CLASS_MOUSE class. | |
60 */ | |
61 PP_INPUTEVENT_TYPE_MOUSEMOVE = 2, | |
62 | |
63 /** | |
64 * Notification that the mouse entered the instance's bounds. | |
65 * | |
66 * Register for this event using the PP_INPUTEVENT_CLASS_MOUSE class. | |
67 */ | |
68 PP_INPUTEVENT_TYPE_MOUSEENTER = 3, | |
69 | |
70 /** | |
71 * Notification that a mouse left the instance's bounds. | |
72 * | |
73 * Register for this event using the PP_INPUTEVENT_CLASS_MOUSE class. | |
74 */ | |
75 PP_INPUTEVENT_TYPE_MOUSELEAVE = 4, | |
76 | |
77 /** | |
78 * Notification that the scroll wheel was used. | |
79 * | |
80 * Register for this event using the PP_INPUTEVENT_CLASS_WHEEL class. | |
81 */ | |
82 PP_INPUTEVENT_TYPE_MOUSEWHEEL = 5, | |
83 | |
84 /** | |
85 * Notification that a key transitioned from "up" to "down". | |
86 * TODO(brettw) differentiate from KEYDOWN. | |
87 * | |
88 * Register for this event using the PP_INPUTEVENT_CLASS_KEYBOARD class. | |
89 */ | |
90 PP_INPUTEVENT_TYPE_RAWKEYDOWN = 6, | |
91 | |
92 /** | |
93 * Notification that a key was pressed. This does not necessarily correspond | |
94 * to a character depending on the key and language. Use the | |
95 * PP_INPUTEVENT_TYPE_CHAR for character input. | |
96 * | |
97 * Register for this event using the PP_INPUTEVENT_CLASS_KEYBOARD class. | |
98 */ | |
99 PP_INPUTEVENT_TYPE_KEYDOWN = 7, | |
100 | |
101 /** | |
102 * Notification that a key was released. | |
103 * | |
104 * Register for this event using the PP_INPUTEVENT_CLASS_KEYBOARD class. | |
105 */ | |
106 PP_INPUTEVENT_TYPE_KEYUP = 8, | |
107 | |
108 /** | |
109 * Notification that a character was typed. Use this for text input. Key | |
110 * down events may generate 0, 1, or more than one character event depending | |
111 * on the key, locale, and operating system. | |
112 * | |
113 * Register for this event using the PP_INPUTEVENT_CLASS_KEYBOARD class. | |
114 */ | |
115 PP_INPUTEVENT_TYPE_CHAR = 9, | |
116 | |
117 /** | |
118 * TODO(brettw) when is this used? | |
119 * | |
120 * Register for this event using the PP_INPUTEVENT_CLASS_MOUSE class. | |
121 */ | |
122 PP_INPUTEVENT_TYPE_CONTEXTMENU = 10 | |
123 } PP_InputEvent_Type; | |
124 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_InputEvent_Type, 4); | |
125 | |
126 /** | |
127 * This enumeration contains event modifier constants. Each modifier is one | |
128 * bit. Retrieve the modifiers from an input event using the GetEventModifiers | |
129 * function on PPB_InputEvent. | |
130 */ | |
131 typedef enum { | |
132 PP_INPUTEVENT_MODIFIER_SHIFTKEY = 1 << 0, | |
133 PP_INPUTEVENT_MODIFIER_CONTROLKEY = 1 << 1, | |
134 PP_INPUTEVENT_MODIFIER_ALTKEY = 1 << 2, | |
135 PP_INPUTEVENT_MODIFIER_METAKEY = 1 << 3, | |
136 PP_INPUTEVENT_MODIFIER_ISKEYPAD = 1 << 4, | |
137 PP_INPUTEVENT_MODIFIER_ISAUTOREPEAT = 1 << 5, | |
138 PP_INPUTEVENT_MODIFIER_LEFTBUTTONDOWN = 1 << 6, | |
139 PP_INPUTEVENT_MODIFIER_MIDDLEBUTTONDOWN = 1 << 7, | |
140 PP_INPUTEVENT_MODIFIER_RIGHTBUTTONDOWN = 1 << 8, | |
141 PP_INPUTEVENT_MODIFIER_CAPSLOCKKEY = 1 << 9, | |
142 PP_INPUTEVENT_MODIFIER_NUMLOCKKEY = 1 << 10 | |
143 } PP_InputEvent_Modifier; | |
144 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_InputEvent_Modifier, 4); | |
145 | |
146 /** | |
147 * This enumeration contains constants representing each mouse button. To get | |
148 * the mouse button for a mouse down or up event, use GetMouseButton on | |
149 * PPB_InputEvent. | |
150 */ | |
151 typedef enum { | |
152 PP_INPUTEVENT_MOUSEBUTTON_NONE = -1, | |
153 PP_INPUTEVENT_MOUSEBUTTON_LEFT = 0, | |
154 PP_INPUTEVENT_MOUSEBUTTON_MIDDLE = 1, | |
155 PP_INPUTEVENT_MOUSEBUTTON_RIGHT = 2 | |
156 } PP_InputEvent_MouseButton; | |
157 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_InputEvent_MouseButton, 4); | |
158 | |
159 /** | |
160 * @} | |
161 */ | |
162 | |
163 typedef enum { | |
164 /** | |
165 * Request mouse input events. | |
166 * | |
167 * Normally you will request mouse events by calling RequestInputEvents(). | |
168 * The only use case for filtered events (via RequestFilteringInputEvents()) | |
169 * is for instances that have irregular outlines and you want to perform hit | |
170 * testing, which is very uncommon. Requesting non-filtered mouse events will | |
171 * lead to higher performance. | |
172 */ | |
173 PP_INPUTEVENT_CLASS_MOUSE = 1 << 0, | |
174 | |
175 /** | |
176 * Requests keyboard events. Keyboard events must be requested in filtering | |
177 * mode via RequestFilteringInputEvents(). This is because many commands | |
178 * should be forwarded to the page. | |
179 * | |
180 * A small number of tab and window management commands like Alt-F4 are never | |
181 * sent to the page. You can not request these keyboard commands since it | |
182 * would allow pages to trap users on a page. | |
183 */ | |
184 PP_INPUTEVENT_CLASS_KEYBOARD = 1 << 1, | |
185 | |
186 /** | |
187 * Identifies scroll wheel input event. Wheel events must be requested in | |
188 * filtering mode via RequestFilteringInputEvents(). This is because many | |
189 * wheel commands should be forwarded to the page. | |
190 * | |
191 * Most instances will not need this event. Consuming wheel events by | |
192 * returning true from your filtered event handler will prevent the user from | |
193 * scrolling the page when the mouse is over the instance which can be very | |
194 * annoying. | |
195 * | |
196 * If you handle wheel events (for example, you have a document viewer which | |
197 * the user can scroll), the recommended behavior is to return false only if | |
198 * the wheel event actually causes your document to scroll. When the user | |
199 * reaches the end of the document, return false to indicating that the event | |
200 * was not handled. This will then forward the event to the containing page | |
201 * for scrolling, producing the nested scrolling behavior users expect from | |
202 * frames in a page. | |
203 */ | |
204 PP_INPUTEVENT_CLASS_WHEEL = 1 << 2, | |
205 | |
206 /** | |
207 * Identifies touch input events. | |
208 * | |
209 * Request touch events only if you intend to handle them. If the browser | |
210 * knows you do not need to handle touch events, it can handle them at a | |
211 * higher level and achieve higher performance. | |
212 */ | |
213 PP_INPUTEVENT_CLASS_TOUCH = 1 << 3, | |
214 | |
215 /** | |
216 * Identifies IME composition input events. | |
217 * | |
218 * Request this input event class if you allow on-the-spot IME input. | |
219 */ | |
220 PP_INPUTEVENT_CLASS_IME = 1 << 4 | |
221 } PP_InputEvent_Class; | |
222 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_InputEvent_Class, 4); | |
223 | |
224 struct PPB_InputEvent { | |
225 /** | |
226 * Request that input events corresponding to the given input events are | |
227 * delivered to the instance. | |
228 * | |
229 * You can not use this function to request keyboard events | |
230 * (PP_INPUTEVENT_CLASS_KEYBOARD). You must use RequestFilteringInputEvents() | |
231 * for this class of input. | |
kochi
2011/07/04 13:39:57
I'm still not clear about why KEYBOARD class is sp
brettw
2011/07/04 16:21:23
The reason I special-cased keyboard is that taking
dmichael (off chromium)
2011/07/05 15:37:24
Thanks for explaining; that makes sense. So the t
brettw
2011/07/06 16:31:43
Yeah, something like that.
| |
232 * | |
233 * By default, no input events are delivered. Call this function with the | |
234 * classes of events you are interested in to have them be delivered to | |
235 * the instance. Calling this function will override any previous setting for | |
236 * each specified class of input events (for example, if you previously | |
237 * called RequestFilteringInputEvents(), this function will set those events | |
238 * to non-filtering mode). | |
239 * | |
240 * Input events may have high overhead, so you should only request input | |
241 * events that your plugin will actually handle. For example, the browser may | |
242 * do optimizations for scroll or touch events that can be processed | |
243 * substantially faster if it knows there are no non-default receivers for | |
244 * that message. Requesting that such messages be delivered, even if they are | |
245 * processed very quickly, may have a noticable effect on the performance of | |
246 * the page. | |
247 * | |
248 * When requesting input events through this function, the events will be | |
249 * delivered and <i>not</i> bubbled to the page. This means that even if you | |
250 * aren't interested in the message, no other parts of the page will get | |
251 * a crack at the message. | |
252 * | |
253 * Example: | |
254 * RequestInputEvents(instance, PP_INPUTEVENT_CLASS_MOUSE); | |
255 * RequestFilteringInputEvents(instance, | |
256 * PP_INPUTEVENT_CLASS_WHEEL | PP_INPUTEVENT_CLASS_KEYBOARD); | |
257 * | |
258 * @param instance The <code>PP_Instance</code> of the instance requesting | |
259 * the given events. | |
260 * | |
261 * @param event_classes A combination of flags from PP_InputEvent_Class that | |
262 * identifies the classes of events the instance is requesting. The flags | |
263 * are combined by logically ORing their values. | |
264 * | |
265 * @return PP_OK if the operation succeeded, PP_ERROR_BADARGUMENT if instance | |
266 * is invalid, or PP_ERROR_NOTSUPPORTED if one of the event class bits were | |
267 * illegal. In the case of an invalid bit, all valid bits will be applied | |
268 * and only the illegal bits will be ignored. The most common cause of a | |
269 * PP_ERROR_NOTSUPPORTED return value is requesting keyboard events, these | |
270 * must use RequestFilteringInputEvents(). | |
271 */ | |
272 int32_t (*RequestInputEvents)(PP_Instance instance, | |
273 uint32_t event_classes); | |
274 | |
275 /** | |
276 * Request that input events corresponding to the given input events are | |
277 * delivered to the instance for filtering. | |
278 * | |
279 * By default, no input events are delivered. In most cases you would | |
280 * register to receive events by calling RequestInputEvents(). In some cases, | |
281 * however, you may wish to filter events such that they can be bubbled up | |
282 * to the DOM. In this case, register for those classes of events using | |
283 * this function instead of RequestInputEvents(). Keyboard events must always | |
284 * be registered in filtering mode. | |
285 * | |
286 * Filtering input events requires significantly more overhead than just | |
287 * delivering them to the instance. As such, you should only request | |
288 * filtering in those cases where it's absolutely necessary. The reason is | |
289 * that it requires the browser to stop and block for the instance to handle | |
290 * the input event, rather than sending the input event asynchronously. This | |
291 * can have significant overhead. | |
292 * | |
293 * Example: | |
294 * RequestInputEvents(instance, PP_INPUTEVENT_CLASS_MOUSE); | |
295 * RequestFilteringInputEvents(instance, | |
296 * PP_INPUTEVENT_CLASS_WHEEL | PP_INPUTEVENT_CLASS_KEYBOARD); | |
297 * | |
298 * @return PP_OK if the operation succeeded, PP_ERROR_BADARGUMENT if instance | |
299 * is invalid, or PP_ERROR_NOTSUPPORTED if one of the event class bits were | |
300 * illegal. In the case of an invalid bit, all valid bits will be applied | |
301 * and only the illegal bits will be ignored. | |
302 */ | |
303 int32_t (*RequestFilteringInputEvents)(PP_Instance instance, | |
304 uint32_t event_classes); | |
305 | |
306 /** | |
307 * Request that input events corresponding to the given input classes no | |
308 * longer be delivered to the instance. | |
309 * | |
310 * By default, no input events are delivered. If you have previously | |
311 * requested input events via RequestInputEvents() or | |
312 * RequestFilteringInputEvents(), this function will unregister handling | |
313 * for the given instance. This will allow greater browser performance for | |
314 * those events. | |
315 * | |
316 * Note that you may still get some input events after clearing the flag if | |
317 * they were dispatched before the request was cleared. For example, if | |
318 * there are 3 mouse move events waiting to be delivered, and you clear the | |
319 * mouse event class during the processing of the first one, you'll still | |
320 * receive the next two. You just won't get more events generated. | |
321 * | |
322 * @param instance The <code>PP_Instance</code> of the instance requesting | |
323 * to no longer receive the given events. | |
324 * | |
325 * @param event_classes A combination of flags from PP_InputEvent_Class that | |
326 * identifies the classes of events the instance is no longer interested in. | |
327 */ | |
328 void (*ClearInputEventRequest)(PP_Instance instance, | |
329 uint32_t event_classes); | |
330 | |
331 /** | |
332 * Returns true if the given resource is a valid input event resource. | |
333 */ | |
334 PP_Bool (*IsInputEvent)(PP_Resource resource); | |
335 | |
336 /** | |
337 * Returns the type of input event for the given input event resource. | |
338 * This is valid for all input events. Returns PP_INPUTEVENT_TYPE_UNDEFINED | |
339 * if the resource is invalid. | |
340 */ | |
341 PP_InputEvent_Type (*GetType)(PP_Resource event); | |
342 | |
343 /** | |
344 * Returns the time that the event was generated. This will be before the | |
345 * current time since processing and dispatching the event has some overhead. | |
346 * Use this value to compare the times the user generated two events without | |
347 * being sensitive to variable processing time. | |
348 * | |
349 * The return value is in time ticks, which is a monotonically increasing | |
350 * clock not related to the wall clock time. It will not change if the user | |
351 * changes their clock or daylight savings time starts, so can be reliably | |
352 * used to compare events. This means, however, that you can't correlate | |
353 * event times to a particular time of day on the system clock. | |
354 */ | |
355 PP_TimeTicks (*GetTimeStamp)(PP_Resource event); | |
356 | |
357 /** | |
358 * Returns a bitfield indicating which modifiers were down at the time of | |
359 * the event. This is a combination of the flags in the | |
360 * PP_InputEvent_Modifier enum. | |
361 * | |
362 * @return The modifiers associated with the event, or 0 if the given | |
363 * resource is not a valid event resource. | |
364 */ | |
365 uint32_t (*GetModifiers)(PP_Resource event); | |
366 }; | |
367 | |
368 struct PPB_MouseInputEvent { | |
369 /** | |
370 * Determines if a resource is a mouse event. | |
371 * | |
372 * @return PP_TRUE if the given resource is a valid mouse input event. | |
373 */ | |
374 PP_Bool (*IsMouseInputEvent)(PP_Resource resource); | |
375 | |
376 /** | |
377 * Returns which mouse button generated a mouse down or up event. | |
378 * | |
379 * @return The mouse button associated with mouse down and up events. This | |
380 * value will be PP_EVENT_MOUSEBUTTON_NONE for mouse move, enter, and leave | |
381 * events, and for all non-mouse events. | |
382 */ | |
383 PP_InputEvent_MouseButton (*GetMouseButton)(PP_Resource mouse_event); | |
384 | |
385 /** | |
386 * Returns the pixel location of a mouse input event. | |
387 * | |
388 * @return The point associated with the mouse event, relative to the upper- | |
389 * left of the instance receiving the event. These values can be negative for | |
390 * mouse drags. The return value will be (0, 0) for non-mouse events. | |
391 */ | |
392 struct PP_Point (*GetMousePosition)(PP_Resource mouse_event); | |
393 | |
394 /** | |
395 * TODO(brettw) figure out exactly what this means. | |
396 */ | |
397 int32_t (*GetMouseClickCount)(PP_Resource mouse_event); | |
398 }; | |
399 | |
400 struct PPB_WheelInputEvent { | |
401 /** | |
402 * Determines if a resource is a wheel event. | |
403 * | |
404 * @return PP_TRUE if the given resource is a valid wheel input event. | |
405 */ | |
406 PP_Bool (*IsWheelInputEvent)(PP_Resource resource); | |
407 | |
408 /** | |
409 * Indicates the amount vertically and horizontally the user has requested | |
410 * to scroll by with their mouse wheel. A scroll down or to the right (where | |
411 * the content moves up or left) is represented as positive values, and | |
412 * a scroll up or to the left (where the content moves down or right) is | |
413 * represented as negative values. | |
414 * | |
415 * The units are either in pixels (when scroll_by_page is false) or pages | |
416 * (when scroll_by_page is true). For example, y = -3 means scroll up 3 | |
417 * pixels when scroll_by_page is false, and scroll up 3 pages when | |
418 * scroll_by_page is true. | |
419 * | |
420 * This amount is system dependent and will take into account the user's | |
421 * preferred scroll sensitivity and potentially also nonlinear acceleration | |
422 * based on the speed of the scrolling. | |
423 * | |
424 * Devices will be of varying resolution. Some mice with large detents will | |
425 * only generate integer scroll amounts. But fractional values are also | |
426 * possible, for example, on some trackpads and newer mice that don't have | |
427 * "clicks". | |
428 */ | |
429 struct PP_FloatPoint (*GetWheelDelta)(PP_Resource wheel_event); | |
430 | |
431 /** | |
432 * The number of "clicks" of the scroll wheel that have produced the | |
433 * event. The value may have system-specific acceleration applied to it, | |
434 * depending on the device. The positive and negative meanings are the same | |
435 * as for GetWheelDelta(). | |
436 * | |
437 * If you are scrolling, you probably want to use the delta values. These | |
438 * tick events can be useful if you aren't doing actual scrolling and don't | |
439 * want or pixel values. An example may be cycling between different items in | |
440 * a game. | |
441 * | |
442 * You may receive fractional values for the wheel ticks if the mouse wheel | |
443 * is high resolution or doesn't have "clicks". If your program wants | |
444 * discrete events (as in the "picking items" example) you should accumulate | |
445 * fractional click values from multiple messages until the total value | |
446 * reaches positive or negative one. This should represent a similar amount | |
447 * of scrolling as for a mouse that has a discrete mouse wheel. | |
448 */ | |
449 struct PP_FloatPoint (*GetWheelTicks)(PP_Resource wheel_event); | |
450 | |
451 /** | |
452 * Indicates if the scroll delta x/y indicates pages or lines to | |
453 * scroll by. | |
454 * | |
455 * @return PP_TRUE if the event is a wheel event and the user is scrolling | |
456 * by pages. PP_FALSE if not or if the resource is not a wheel event. | |
457 */ | |
458 PP_Bool (*GetScrollByPage)(PP_Resource wheel_event); | |
459 }; | |
460 | |
461 struct PPB_KeyboardInputEvent { | |
462 /** | |
463 * Determines if a resource is a keyboard event. | |
464 * | |
465 * @return PP_TRUE if the given resource is a valid mouse input event. | |
466 */ | |
467 PP_Bool (*IsKeyboardInputEvent)(PP_Resource resource); | |
468 | |
469 /** | |
470 * Returns the DOM |keyCode| field for the keyboard event. | |
471 * Chrome populates this with the Windows-style Virtual Key code of the key. | |
472 */ | |
473 uint32_t (*GetKeyCode)(PP_Resource key_event); | |
474 | |
475 /** | |
476 * Returns the typed character for the given character event. | |
477 * | |
478 * @return A string var representing a single typed character for character | |
479 * input events. For non-character input events the return value will be an | |
480 * undefined var. | |
481 */ | |
482 struct PP_Var (*GetCharacterText)(PP_Resource character_event); | |
483 }; | |
484 | |
485 #endif // PPAPI_C_PPB_INPUT_EVENT_H_ | |
OLD | NEW |