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 */ 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 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 */ 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 215