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)] 28 struct 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)] 62 struct 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)] 80 struct 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
