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 pp_input_event.idl modified Thu Mar 28 10:52:59 2013. */
7
8#ifndef PPAPI_C_PP_INPUT_EVENT_H_
9#define PPAPI_C_PP_INPUT_EVENT_H_
10
11#include "ppapi/c/pp_bool.h"
12#include "ppapi/c/pp_macros.h"
13#include "ppapi/c/pp_stdint.h"
14#include "ppapi/c/ppb_input_event.h"
15
16/**
17 * @file
18 * This file defines the API used to handle mouse and keyboard input events.
19 */
20
21
22/**
23 * @addtogroup Structs
24 * @{
25 */
26/**
27 * The <code>PP_InputEvent_Key</code> struct represents a key up or key down
28 * event.
29 *
30 * Key up and key down events correspond to physical keys on the keyboard. The
31 * actual character that the user typed (if any) will be delivered in a
32 * "character" event.
33 *
34 * If the user loses focus on the module while a key is down, a key up
35 * event might not occur. For example, if the module has focus and the user
36 * presses and holds the shift key, the module will see a "shift down" message.
37 * Then if the user clicks elsewhere on the web page, the module's focus will
38 * be lost and no more input events will be delivered.
39 *
40 * If your module depends on receiving key up events, it should also handle
41 * "lost focus" as the equivalent of "all keys up."
42 */
43struct PP_InputEvent_Key {
44  /** This value is a bit field combination of the EVENT_MODIFIER flags. */
45  uint32_t modifier;
46  /**
47   * This value reflects the DOM KeyboardEvent <code>keyCode</code> field.
48   * Chrome populates this with the Windows-style Virtual Key code of the key.
49   */
50  uint32_t key_code;
51};
52PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_InputEvent_Key, 8);
53
54/**
55 * The <code>PP_InputEvent_Character</code> struct represents a typed character
56 * event.
57 *
58 * Normally, the program will receive a key down event, followed by a character
59 * event, followed by a key up event. The character event will have any
60 * modifier keys applied. Obvious examples are symbols, where Shift-5 gives you
61 * a '%'. The key down and up events will give you the scan code for the "5"
62 * key, and the character event will give you the '%' character.
63 *
64 * You may not get a character event for all key down events if the key doesn't
65 * generate a character. Likewise, you may actually get multiple character
66 * events in a row. For example, some locales have an accent key that modifies
67 * the next character typed. You might get this stream of events: accent down,
68 * accent up (it didn't generate a character), letter key down, letter with
69 * accent character event (it was modified by the previous accent key), letter
70 * key up.  If the letter can't be combined with the accent, like an umlaut and
71 * an 'R', the system might send umlaut down, umlaut up, 'R' key down, umlaut
72 * character (can't combine it with 'R', so just send the raw umlaut so it
73 * isn't lost"), 'R' character event, 'R' key up.
74 */
75struct PP_InputEvent_Character {
76  /** A combination of the <code>PP_InputEvent_Modifier</code> flags. */
77  uint32_t modifier;
78  /**
79   * This value represents the typed character as a single null-terminated UTF-8
80   * character. Any unused bytes will be filled with null bytes. Since the
81   * maximum UTF-8 character is 4 bytes, there will always be at least one null
82   * at the end so you can treat this as a null-terminated UTF-8 string.
83   */
84  char text[5];
85};
86PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_InputEvent_Character, 12);
87
88/**
89 * The <code>PP_InputEvent_Mouse</code> struct represents all mouse events
90 * except mouse wheel events.
91 */
92struct PP_InputEvent_Mouse {
93  /**
94   * This value is a bit field combination of the
95   * <code>PP_InputEvent_Modifier</code> flags.
96   */
97  uint32_t modifier;
98  /**
99   * This value represents the button that changed for mouse down or up events.
100   * This value will be <code>PP_EVENT_MOUSEBUTTON_NONE</code> for mouse move,
101   * enter, and leave events.
102   */
103  PP_InputEvent_MouseButton button;
104  /**
105   * This values represents the x coordinate of the mouse when the event
106   * occurred.
107   *
108   * In most, but not all, cases these coordinates will just be integers.
109   * For example, the plugin element might be arbitrarily scaled or transformed
110   * in the DOM, and translating a mouse event into the coordinate space of the
111   * plugin will give non-integer values.
112   */
113  float x;
114  /**
115   * This values represents the y coordinate of the mouse when the event
116   * occurred.
117   *
118   * In most, but not all, cases these coordinates will just be integers.
119   * For example, the plugin element might be arbitrarily scaled or transformed
120   * in the DOM, and translating a mouse event into the coordinate space of the
121   * plugin will give non-integer values.
122   */
123  float y;
124  /* TODO(brettw) figure out exactly what this means. */
125  int32_t click_count;
126};
127PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_InputEvent_Mouse, 20);
128
129/**
130 * The <code>PP_InputEvent_Wheel</code> struct represents all mouse wheel
131 * events.
132 */
133struct PP_InputEvent_Wheel {
134  /**
135   * This value represents a combination of the <code>EVENT_MODIFIER</code>
136   * flags.
137   */
138  uint32_t modifier;
139  /**
140   * The mouse wheel's horizontal scroll amount. A scroll to the right
141   * (where the content moves left) is represented as positive values,
142   * and a scroll to the left (where the content moves right) is
143   * represented as negative values.
144   *
145   * The units are either in pixels (when scroll_by_page is false) or pages
146   * (when scroll_by_page is true). For example, delta_y = -3 means scroll up 3
147   * pixels when scroll_by_page is false, and scroll up 3 pages when
148   * scroll_by_page is true.
149   *
150   * This amount is system dependent and will take into account the user's
151   * preferred scroll sensitivity and potentially also nonlinear acceleration
152   * based on the speed of the scrolling.
153   *
154   * Devices will be of varying resolution. Some mice with large detents will
155   * only generate integer scroll amounts. But fractional values are also
156   * possible, for example, on some trackpads and newer mice that don't have
157   * "clicks".
158   */
159  float delta_x;
160  /**
161   * The mouse wheel's vertical scroll amount. A scroll down (where the
162   * content moves up) is represented as positive values, and a scroll up
163   * (where the content moves down) is represented as negative values.
164   *
165   * The units are either in pixels (when scroll_by_page is false) or pages
166   * (when scroll_by_page is true). For example, delta_y = -3 means scroll up 3
167   * pixels when scroll_by_page is false, and scroll up 3 pages when
168   * scroll_by_page is true.
169   *
170   * This amount is system dependent and will take into account the user's
171   * preferred scroll sensitivity and potentially also nonlinear acceleration
172   * based on the speed of the scrolling.
173   *
174   * Devices will be of varying resolution. Some mice with large detents will
175   * only generate integer scroll amounts. But fractional values are also
176   * possible, for example, on some trackpads and newer mice that don't have
177   * "clicks".
178   */
179  float delta_y;
180  /**
181   * The number of "clicks" of the scroll wheel that have produced the
182   * event. The value may have system-specific acceleration applied to it,
183   * depending on the device. The positive and negative meanings are the same
184   * as for <code>delta_x</code> and <code>delta_y</code>.
185   *
186   * If you are scrolling, you probably want to use the delta values above.
187   * These tick events can be useful if you aren't doing actual scrolling and
188   * don't want or pixel values. An example may be cycling between different
189   * items in a game.
190   *
191   * You may receive fractional values for the wheel ticks if the mouse wheel
192   * is high resolution or doesn't have "clicks". If your program wants
193   * discrete events (as in the "picking items" example) you should accumulate
194   * fractional click values from multiple messages until the total value
195   * reaches positive or negative one. This should represent a similar amount
196   * of scrolling as for a mouse that has a discrete mouse wheel.
197   */
198  float wheel_ticks_x;
199  /** This value represents */
200  float wheel_ticks_y;
201  /**
202   * Indicates if the scroll <code>delta_x</code>/<code>delta_y</code>
203   * indicates pages or lines to scroll by. When true, the user is requesting
204   * to scroll by pages.
205   */
206  PP_Bool scroll_by_page;
207};
208PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_InputEvent_Wheel, 24);
209/**
210 * @}
211 */
212
213#endif  /* PPAPI_C_PP_INPUT_EVENT_H_ */
214
215