Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 | |
Torne (Richard Coles) | c2e0dbd | 2013-05-09 18:35:53 +0100 | [diff] [blame] | 6 | /* From pp_input_event.idl modified Thu Mar 28 10:52:59 2013. */ |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 | */ |
| 43 | struct 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 | }; |
| 52 | PP_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 |
Torne (Richard Coles) | c2e0dbd | 2013-05-09 18:35:53 +0100 | [diff] [blame] | 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 |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 73 | * isn't lost"), 'R' character event, 'R' key up. |
| 74 | */ |
| 75 | struct 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 | }; |
| 86 | PP_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 | */ |
| 92 | struct 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 | }; |
| 127 | PP_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 | */ |
| 133 | struct 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 | }; |
| 208 | PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_InputEvent_Wheel, 24); |
| 209 | /** |
| 210 | * @} |
| 211 | */ |
| 212 | |
| 213 | #endif /* PPAPI_C_PP_INPUT_EVENT_H_ */ |
| 214 | |