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