Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 1 | /* |
| 2 | * Copyright (C) 2010 The Android Open Source Project |
| 3 | * |
| 4 | * Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 | * you may not use this file except in compliance with the License. |
| 6 | * You may obtain a copy of the License at |
| 7 | * |
| 8 | * http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | * |
| 10 | * Unless required by applicable law or agreed to in writing, software |
| 11 | * distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | * See the License for the specific language governing permissions and |
| 14 | * limitations under the License. |
| 15 | */ |
| 16 | |
| 17 | #ifndef _ANDROID_INPUT_H |
| 18 | #define _ANDROID_INPUT_H |
| 19 | |
| 20 | /****************************************************************** |
| 21 | * |
| 22 | * IMPORTANT NOTICE: |
| 23 | * |
| 24 | * This file is part of Android's set of stable system headers |
| 25 | * exposed by the Android NDK (Native Development Kit). |
| 26 | * |
| 27 | * Third-party source AND binary code relies on the definitions |
| 28 | * here to be FROZEN ON ALL UPCOMING PLATFORM RELEASES. |
| 29 | * |
| 30 | * - DO NOT MODIFY ENUMS (EXCEPT IF YOU ADD NEW 32-BIT VALUES) |
| 31 | * - DO NOT MODIFY CONSTANTS OR FUNCTIONAL MACROS |
| 32 | * - DO NOT CHANGE THE SIGNATURE OF FUNCTIONS IN ANY WAY |
| 33 | * - DO NOT CHANGE THE LAYOUT OR SIZE OF STRUCTURES |
| 34 | */ |
| 35 | |
| 36 | /* |
| 37 | * Structures and functions to receive and process input events in |
| 38 | * native code. |
| 39 | * |
| 40 | * NOTE: These functions MUST be implemented by /system/lib/libui.so |
| 41 | */ |
| 42 | |
| 43 | #include <sys/types.h> |
| 44 | #include <android/keycodes.h> |
Dianne Hackborn | 6826741 | 2010-07-02 18:52:01 -0700 | [diff] [blame] | 45 | #include <android/looper.h> |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 46 | |
| 47 | #ifdef __cplusplus |
| 48 | extern "C" { |
| 49 | #endif |
| 50 | |
| 51 | /* |
| 52 | * Input device classes. |
| 53 | */ |
| 54 | enum { |
| 55 | /* The input device is a keyboard. */ |
| 56 | INPUT_DEVICE_CLASS_KEYBOARD = 0x00000001, |
| 57 | |
| 58 | /* The input device is an alpha-numeric keyboard (not just a dial pad). */ |
| 59 | INPUT_DEVICE_CLASS_ALPHAKEY = 0x00000002, |
| 60 | |
| 61 | /* The input device is a touchscreen (either single-touch or multi-touch). */ |
| 62 | INPUT_DEVICE_CLASS_TOUCHSCREEN = 0x00000004, |
| 63 | |
| 64 | /* The input device is a trackball. */ |
| 65 | INPUT_DEVICE_CLASS_TRACKBALL = 0x00000008, |
| 66 | |
| 67 | /* The input device is a multi-touch touchscreen. */ |
| 68 | INPUT_DEVICE_CLASS_TOUCHSCREEN_MT= 0x00000010, |
| 69 | |
| 70 | /* The input device is a directional pad. */ |
Jeff Brown | fd035829 | 2010-06-30 16:10:35 -0700 | [diff] [blame] | 71 | INPUT_DEVICE_CLASS_DPAD = 0x00000020, |
| 72 | |
| 73 | /* The input device is a gamepad (implies keyboard). */ |
| 74 | INPUT_DEVICE_CLASS_GAMEPAD = 0x00000040 |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 75 | }; |
| 76 | |
| 77 | /* |
| 78 | * Key states (may be returned by queries about the current state of a |
| 79 | * particular key code, scan code or switch). |
| 80 | * |
| 81 | * XXX should we call this BUTTON_STATE_XXX? |
| 82 | */ |
| 83 | enum { |
| 84 | /* The key state is unknown or the requested key itself is not supported. */ |
| 85 | KEY_STATE_UNKNOWN = -1, |
| 86 | |
| 87 | /* The key is up. */ |
| 88 | KEY_STATE_UP = 0, |
| 89 | |
| 90 | /* The key is down. */ |
| 91 | KEY_STATE_DOWN = 1, |
| 92 | |
| 93 | /* The key is down but is a virtual key press that is being emulated by the system. */ |
| 94 | KEY_STATE_VIRTUAL = 2 |
| 95 | }; |
| 96 | |
| 97 | /* |
| 98 | * Meta key / modifer state. |
| 99 | */ |
| 100 | enum { |
| 101 | /* No meta keys are pressed. */ |
| 102 | META_NONE = 0, |
| 103 | |
| 104 | /* This mask is used to check whether one of the ALT meta keys is pressed. */ |
| 105 | META_ALT_ON = 0x02, |
| 106 | |
| 107 | /* This mask is used to check whether the left ALT meta key is pressed. */ |
| 108 | META_ALT_LEFT_ON = 0x10, |
| 109 | |
| 110 | /* This mask is used to check whether the right ALT meta key is pressed. */ |
| 111 | META_ALT_RIGHT_ON = 0x20, |
| 112 | |
| 113 | /* This mask is used to check whether one of the SHIFT meta keys is pressed. */ |
| 114 | META_SHIFT_ON = 0x01, |
| 115 | |
| 116 | /* This mask is used to check whether the left SHIFT meta key is pressed. */ |
| 117 | META_SHIFT_LEFT_ON = 0x40, |
| 118 | |
| 119 | /* This mask is used to check whether the right SHIFT meta key is pressed. */ |
| 120 | META_SHIFT_RIGHT_ON = 0x80, |
| 121 | |
| 122 | /* This mask is used to check whether the SYM meta key is pressed. */ |
| 123 | META_SYM_ON = 0x04 |
| 124 | }; |
| 125 | |
| 126 | /* |
| 127 | * Input events. |
| 128 | * |
| 129 | * Input events are opaque structures. Use the provided accessors functions to |
| 130 | * read their properties. |
| 131 | */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 132 | struct AInputEvent; |
| 133 | typedef struct AInputEvent AInputEvent; |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 134 | |
| 135 | /* |
| 136 | * Input event types. |
| 137 | */ |
| 138 | enum { |
| 139 | /* Indicates that the input event is a key event. */ |
| 140 | INPUT_EVENT_TYPE_KEY = 1, |
| 141 | |
| 142 | /* Indicates that the input event is a motion event. */ |
| 143 | INPUT_EVENT_TYPE_MOTION = 2 |
| 144 | }; |
| 145 | |
| 146 | /* |
| 147 | * Key event actions. |
| 148 | */ |
| 149 | enum { |
| 150 | /* The key has been pressed down. */ |
| 151 | KEY_EVENT_ACTION_DOWN = 0, |
| 152 | |
| 153 | /* The key has been released. */ |
| 154 | KEY_EVENT_ACTION_UP = 1, |
| 155 | |
| 156 | /* Multiple duplicate key events have occurred in a row, or a complex string is |
| 157 | * being delivered. The repeat_count property of the key event contains the number |
| 158 | * of times the given key code should be executed. |
| 159 | */ |
| 160 | KEY_EVENT_ACTION_MULTIPLE = 2 |
| 161 | }; |
| 162 | |
| 163 | /* |
| 164 | * Key event flags. |
| 165 | */ |
| 166 | enum { |
| 167 | /* This mask is set if the device woke because of this key event. */ |
| 168 | KEY_EVENT_FLAG_WOKE_HERE = 0x1, |
| 169 | |
| 170 | /* This mask is set if the key event was generated by a software keyboard. */ |
| 171 | KEY_EVENT_FLAG_SOFT_KEYBOARD = 0x2, |
| 172 | |
| 173 | /* This mask is set if we don't want the key event to cause us to leave touch mode. */ |
| 174 | KEY_EVENT_FLAG_KEEP_TOUCH_MODE = 0x4, |
| 175 | |
| 176 | /* This mask is set if an event was known to come from a trusted part |
| 177 | * of the system. That is, the event is known to come from the user, |
| 178 | * and could not have been spoofed by a third party component. */ |
| 179 | KEY_EVENT_FLAG_FROM_SYSTEM = 0x8, |
| 180 | |
| 181 | /* This mask is used for compatibility, to identify enter keys that are |
| 182 | * coming from an IME whose enter key has been auto-labelled "next" or |
| 183 | * "done". This allows TextView to dispatch these as normal enter keys |
| 184 | * for old applications, but still do the appropriate action when |
| 185 | * receiving them. */ |
| 186 | KEY_EVENT_FLAG_EDITOR_ACTION = 0x10, |
| 187 | |
| 188 | /* When associated with up key events, this indicates that the key press |
| 189 | * has been canceled. Typically this is used with virtual touch screen |
| 190 | * keys, where the user can slide from the virtual key area on to the |
| 191 | * display: in that case, the application will receive a canceled up |
| 192 | * event and should not perform the action normally associated with the |
| 193 | * key. Note that for this to work, the application can not perform an |
| 194 | * action for a key until it receives an up or the long press timeout has |
| 195 | * expired. */ |
| 196 | KEY_EVENT_FLAG_CANCELED = 0x20, |
| 197 | |
| 198 | /* This key event was generated by a virtual (on-screen) hard key area. |
| 199 | * Typically this is an area of the touchscreen, outside of the regular |
| 200 | * display, dedicated to "hardware" buttons. */ |
| 201 | KEY_EVENT_FLAG_VIRTUAL_HARD_KEY = 0x40, |
| 202 | |
| 203 | /* This flag is set for the first key repeat that occurs after the |
| 204 | * long press timeout. */ |
| 205 | KEY_EVENT_FLAG_LONG_PRESS = 0x80, |
| 206 | |
| 207 | /* Set when a key event has KEY_EVENT_FLAG_CANCELED set because a long |
| 208 | * press action was executed while it was down. */ |
| 209 | KEY_EVENT_FLAG_CANCELED_LONG_PRESS = 0x100, |
| 210 | |
| 211 | /* Set for KEY_EVENT_ACTION_UP when this event's key code is still being |
| 212 | * tracked from its initial down. That is, somebody requested that tracking |
| 213 | * started on the key down and a long press has not caused |
| 214 | * the tracking to be canceled. */ |
| 215 | KEY_EVENT_FLAG_TRACKING = 0x200 |
| 216 | }; |
| 217 | |
| 218 | /* |
| 219 | * Motion event actions. |
| 220 | */ |
| 221 | |
| 222 | /* Bit shift for the action bits holding the pointer index as |
| 223 | * defined by MOTION_EVENT_ACTION_POINTER_INDEX_MASK. |
| 224 | */ |
| 225 | #define MOTION_EVENT_ACTION_POINTER_INDEX_SHIFT 8 |
| 226 | |
| 227 | enum { |
| 228 | /* Bit mask of the parts of the action code that are the action itself. |
| 229 | */ |
| 230 | MOTION_EVENT_ACTION_MASK = 0xff, |
| 231 | |
| 232 | /* Bits in the action code that represent a pointer index, used with |
| 233 | * MOTION_EVENT_ACTION_POINTER_DOWN and MOTION_EVENT_ACTION_POINTER_UP. Shifting |
| 234 | * down by MOTION_EVENT_ACTION_POINTER_INDEX_SHIFT provides the actual pointer |
| 235 | * index where the data for the pointer going up or down can be found. |
| 236 | */ |
| 237 | MOTION_EVENT_ACTION_POINTER_INDEX_MASK = 0xff00, |
| 238 | |
| 239 | /* A pressed gesture has started, the motion contains the initial starting location. |
| 240 | */ |
| 241 | MOTION_EVENT_ACTION_DOWN = 0, |
| 242 | |
| 243 | /* A pressed gesture has finished, the motion contains the final release location |
| 244 | * as well as any intermediate points since the last down or move event. |
| 245 | */ |
| 246 | MOTION_EVENT_ACTION_UP = 1, |
| 247 | |
| 248 | /* A change has happened during a press gesture (between MOTION_EVENT_ACTION_DOWN and |
| 249 | * MOTION_EVENT_ACTION_UP). The motion contains the most recent point, as well as |
| 250 | * any intermediate points since the last down or move event. |
| 251 | */ |
| 252 | MOTION_EVENT_ACTION_MOVE = 2, |
| 253 | |
| 254 | /* The current gesture has been aborted. |
| 255 | * You will not receive any more points in it. You should treat this as |
| 256 | * an up event, but not perform any action that you normally would. |
| 257 | */ |
| 258 | MOTION_EVENT_ACTION_CANCEL = 3, |
| 259 | |
| 260 | /* A movement has happened outside of the normal bounds of the UI element. |
| 261 | * This does not provide a full gesture, but only the initial location of the movement/touch. |
| 262 | */ |
| 263 | MOTION_EVENT_ACTION_OUTSIDE = 4, |
| 264 | |
| 265 | /* A non-primary pointer has gone down. |
| 266 | * The bits in MOTION_EVENT_ACTION_POINTER_INDEX_MASK indicate which pointer changed. |
| 267 | */ |
| 268 | MOTION_EVENT_ACTION_POINTER_DOWN = 5, |
| 269 | |
| 270 | /* A non-primary pointer has gone up. |
| 271 | * The bits in MOTION_EVENT_ACTION_POINTER_INDEX_MASK indicate which pointer changed. |
| 272 | */ |
| 273 | MOTION_EVENT_ACTION_POINTER_UP = 6 |
| 274 | }; |
| 275 | |
| 276 | /* |
| 277 | * Motion event edge touch flags. |
| 278 | */ |
| 279 | enum { |
| 280 | /* No edges intersected */ |
| 281 | MOTION_EVENT_EDGE_FLAG_NONE = 0, |
| 282 | |
| 283 | /* Flag indicating the motion event intersected the top edge of the screen. */ |
| 284 | MOTION_EVENT_EDGE_FLAG_TOP = 0x01, |
| 285 | |
| 286 | /* Flag indicating the motion event intersected the bottom edge of the screen. */ |
| 287 | MOTION_EVENT_EDGE_FLAG_BOTTOM = 0x02, |
| 288 | |
| 289 | /* Flag indicating the motion event intersected the left edge of the screen. */ |
| 290 | MOTION_EVENT_EDGE_FLAG_LEFT = 0x04, |
| 291 | |
| 292 | /* Flag indicating the motion event intersected the right edge of the screen. */ |
| 293 | MOTION_EVENT_EDGE_FLAG_RIGHT = 0x08 |
| 294 | }; |
| 295 | |
| 296 | /* |
| 297 | * Specifies the logical nature of an input event. |
| 298 | * For example, the nature distinguishes between motion events that represent touches and |
| 299 | * those that represent trackball moves. |
| 300 | * |
| 301 | * XXX This concept is tentative. Another idea would be to associate events with logical |
| 302 | * controllers rather than physical devices. The interpretation of an event would |
| 303 | * be made with respect to the nature of the controller that is considered the logical |
| 304 | * source of an event. The decoupling is beneficial since multiple physical (and virtual) |
| 305 | * devices could be responsible for producing events that would be associated with |
| 306 | * various logical controllers. For example, the hard keyboard, on screen keyboard, |
| 307 | * and peripheral keyboard could be mapped onto a single logical "keyboard" controller |
| 308 | * (or treated independently, if desired). |
| 309 | */ |
| 310 | enum { |
| 311 | INPUT_EVENT_NATURE_KEY = 1, |
| 312 | INPUT_EVENT_NATURE_TOUCH = 2, |
| 313 | INPUT_EVENT_NATURE_TRACKBALL = 3 |
| 314 | }; |
| 315 | |
| 316 | /* |
| 317 | * Input event accessors. |
| 318 | * |
| 319 | * Note that most functions can only be used on input events that are of a given type. |
| 320 | * Calling these functions on input events of other types will yield undefined behavior. |
| 321 | */ |
| 322 | |
| 323 | /*** Accessors for all input events. ***/ |
| 324 | |
| 325 | /* Get the input event type. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 326 | int32_t AInputEvent_getType(const AInputEvent* event); |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 327 | |
| 328 | /* Get the id for the device that an input event came from. |
| 329 | * |
| 330 | * Input events can be generated by multiple different input devices. |
| 331 | * Use the input device id to obtain information about the input |
| 332 | * device that was responsible for generating a particular event. |
| 333 | * |
| 334 | * An input device id of 0 indicates that the event didn't come from a physical device; |
| 335 | * other numbers are arbitrary and you shouldn't depend on the values. |
| 336 | * Use the provided input device query API to obtain information about input devices. |
| 337 | */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 338 | int32_t AInputEvent_getDeviceId(const AInputEvent* event); |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 339 | |
| 340 | /* Get the input event nature. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 341 | int32_t AInputEvent_getNature(const AInputEvent* event); |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 342 | |
| 343 | /*** Accessors for key events only. ***/ |
| 344 | |
| 345 | /* Get the key event action. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 346 | int32_t AKeyEvent_getAction(const AInputEvent* key_event); |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 347 | |
| 348 | /* Get the key event flags. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 349 | int32_t AKeyEvent_getFlags(const AInputEvent* key_event); |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 350 | |
| 351 | /* Get the key code of the key event. |
| 352 | * This is the physical key that was pressed, not the Unicode character. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 353 | int32_t AKeyEvent_getKeyCode(const AInputEvent* key_event); |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 354 | |
| 355 | /* Get the hardware key id of this key event. |
| 356 | * These values are not reliable and vary from device to device. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 357 | int32_t AKeyEvent_getScanCode(const AInputEvent* key_event); |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 358 | |
| 359 | /* Get the meta key state. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 360 | int32_t AKeyEvent_getMetaState(const AInputEvent* key_event); |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 361 | |
| 362 | /* Get the repeat count of the event. |
| 363 | * For both key up an key down events, this is the number of times the key has |
| 364 | * repeated with the first down starting at 0 and counting up from there. For |
| 365 | * multiple key events, this is the number of down/up pairs that have occurred. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 366 | int32_t AKeyEvent_getRepeatCount(const AInputEvent* key_event); |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 367 | |
| 368 | /* Get the time of the most recent key down event, in the |
| 369 | * java.lang.System.nanoTime() time base. If this is a down event, |
| 370 | * this will be the same as eventTime. |
| 371 | * Note that when chording keys, this value is the down time of the most recently |
| 372 | * pressed key, which may not be the same physical key of this event. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 373 | int64_t AKeyEvent_getDownTime(const AInputEvent* key_event); |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 374 | |
| 375 | /* Get the time this event occurred, in the |
| 376 | * java.lang.System.nanoTime() time base. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 377 | int64_t AKeyEvent_getEventTime(const AInputEvent* key_event); |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 378 | |
| 379 | /*** Accessors for motion events only. ***/ |
| 380 | |
| 381 | /* Get the combined motion event action code and pointer index. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 382 | int32_t AMotionEvent_getAction(const AInputEvent* motion_event); |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 383 | |
| 384 | /* Get the state of any meta / modifier keys that were in effect when the |
| 385 | * event was generated. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 386 | int32_t AMotionEvent_getMetaState(const AInputEvent* motion_event); |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 387 | |
| 388 | /* Get a bitfield indicating which edges, if any, were touched by this motion event. |
| 389 | * For touch events, clients can use this to determine if the user's finger was |
| 390 | * touching the edge of the display. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 391 | int32_t AMotionEvent_getEdgeFlags(const AInputEvent* motion_event); |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 392 | |
| 393 | /* Get the time when the user originally pressed down to start a stream of |
| 394 | * position events, in the java.lang.System.nanoTime() time base. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 395 | int64_t AMotionEvent_getDownTime(const AInputEvent* motion_event); |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 396 | |
| 397 | /* Get the time when this specific event was generated, |
| 398 | * in the java.lang.System.nanoTime() time base. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 399 | int64_t AMotionEvent_getEventTime(const AInputEvent* motion_event); |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 400 | |
Jeff Brown | 5c225b1 | 2010-06-16 01:53:36 -0700 | [diff] [blame] | 401 | /* Get the X coordinate offset. |
| 402 | * For touch events on the screen, this is the delta that was added to the raw |
| 403 | * screen coordinates to adjust for the absolute position of the containing windows |
| 404 | * and views. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 405 | float AMotionEvent_getXOffset(const AInputEvent* motion_event); |
Jeff Brown | 5c225b1 | 2010-06-16 01:53:36 -0700 | [diff] [blame] | 406 | |
| 407 | /* Get the precision of the Y coordinates being reported. |
| 408 | * For touch events on the screen, this is the delta that was added to the raw |
| 409 | * screen coordinates to adjust for the absolute position of the containing windows |
| 410 | * and views. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 411 | float AMotionEvent_getYOffset(const AInputEvent* motion_event); |
Jeff Brown | 5c225b1 | 2010-06-16 01:53:36 -0700 | [diff] [blame] | 412 | |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 413 | /* Get the precision of the X coordinates being reported. |
| 414 | * You can multiply this number with an X coordinate sample to find the |
| 415 | * actual hardware value of the X coordinate. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 416 | float AMotionEvent_getXPrecision(const AInputEvent* motion_event); |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 417 | |
| 418 | /* Get the precision of the Y coordinates being reported. |
| 419 | * You can multiply this number with a Y coordinate sample to find the |
| 420 | * actual hardware value of the Y coordinate. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 421 | float AMotionEvent_getYPrecision(const AInputEvent* motion_event); |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 422 | |
| 423 | /* Get the number of pointers of data contained in this event. |
| 424 | * Always >= 1. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 425 | size_t AMotionEvent_getPointerCount(const AInputEvent* motion_event); |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 426 | |
| 427 | /* Get the pointer identifier associated with a particular pointer |
| 428 | * data index is this event. The identifier tells you the actual pointer |
| 429 | * number associated with the data, accounting for individual pointers |
| 430 | * going up and down since the start of the current gesture. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 431 | int32_t AMotionEvent_getPointerId(const AInputEvent* motion_event, size_t pointer_index); |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 432 | |
Jeff Brown | 5c225b1 | 2010-06-16 01:53:36 -0700 | [diff] [blame] | 433 | /* Get the original raw X coordinate of this event. |
| 434 | * For touch events on the screen, this is the original location of the event |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 435 | * on the screen, before it had been adjusted for the containing window |
| 436 | * and views. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 437 | float AMotionEvent_getRawX(const AInputEvent* motion_event, size_t pointer_index); |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 438 | |
Jeff Brown | 5c225b1 | 2010-06-16 01:53:36 -0700 | [diff] [blame] | 439 | /* Get the original raw X coordinate of this event. |
| 440 | * For touch events on the screen, this is the original location of the event |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 441 | * on the screen, before it had been adjusted for the containing window |
| 442 | * and views. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 443 | float AMotionEvent_getRawY(const AInputEvent* motion_event, size_t pointer_index); |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 444 | |
| 445 | /* Get the current X coordinate of this event for the given pointer index. |
| 446 | * Whole numbers are pixels; the value may have a fraction for input devices |
| 447 | * that are sub-pixel precise. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 448 | float AMotionEvent_getX(const AInputEvent* motion_event, size_t pointer_index); |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 449 | |
| 450 | /* Get the current Y coordinate of this event for the given pointer index. |
| 451 | * Whole numbers are pixels; the value may have a fraction for input devices |
| 452 | * that are sub-pixel precise. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 453 | float AMotionEvent_getY(const AInputEvent* motion_event, size_t pointer_index); |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 454 | |
| 455 | /* Get the current pressure of this event for the given pointer index. |
| 456 | * The pressure generally ranges from 0 (no pressure at all) to 1 (normal pressure), |
| 457 | * however values higher than 1 may be generated depending on the calibration of |
| 458 | * the input device. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 459 | float AMotionEvent_getPressure(const AInputEvent* motion_event, size_t pointer_index); |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 460 | |
| 461 | /* Get the current scaled value of the approximate size for the given pointer index. |
| 462 | * This represents some approximation of the area of the screen being |
| 463 | * pressed; the actual value in pixels corresponding to the |
| 464 | * touch is normalized with the device specific range of values |
| 465 | * and scaled to a value between 0 and 1. The value of size can be used to |
| 466 | * determine fat touch events. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 467 | float AMotionEvent_getSize(const AInputEvent* motion_event, size_t pointer_index); |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 468 | |
| 469 | /* Get the number of historical points in this event. These are movements that |
| 470 | * have occurred between this event and the previous event. This only applies |
| 471 | * to MOTION_EVENT_ACTION_MOVE events -- all other actions will have a size of 0. |
| 472 | * Historical samples are indexed from oldest to newest. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 473 | size_t AMotionEvent_get_history_size(const AInputEvent* motion_event); |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 474 | |
| 475 | /* Get the time that a historical movement occurred between this event and |
| 476 | * the previous event, in the java.lang.System.nanoTime() time base. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 477 | int64_t AMotionEvent_getHistoricalEventTime(AInputEvent* motion_event, |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 478 | size_t history_index); |
| 479 | |
Jeff Brown | 5c225b1 | 2010-06-16 01:53:36 -0700 | [diff] [blame] | 480 | /* Get the historical raw X coordinate of this event for the given pointer index that |
| 481 | * occurred between this event and the previous motion event. |
| 482 | * For touch events on the screen, this is the original location of the event |
| 483 | * on the screen, before it had been adjusted for the containing window |
| 484 | * and views. |
| 485 | * Whole numbers are pixels; the value may have a fraction for input devices |
| 486 | * that are sub-pixel precise. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 487 | float AMotionEvent_getHistoricalRawX(const AInputEvent* motion_event, size_t pointer_index); |
Jeff Brown | 5c225b1 | 2010-06-16 01:53:36 -0700 | [diff] [blame] | 488 | |
| 489 | /* Get the historical raw Y coordinate of this event for the given pointer index that |
| 490 | * occurred between this event and the previous motion event. |
| 491 | * For touch events on the screen, this is the original location of the event |
| 492 | * on the screen, before it had been adjusted for the containing window |
| 493 | * and views. |
| 494 | * Whole numbers are pixels; the value may have a fraction for input devices |
| 495 | * that are sub-pixel precise. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 496 | float AMotionEvent_getHistoricalRawY(const AInputEvent* motion_event, size_t pointer_index); |
Jeff Brown | 5c225b1 | 2010-06-16 01:53:36 -0700 | [diff] [blame] | 497 | |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 498 | /* Get the historical X coordinate of this event for the given pointer index that |
| 499 | * occurred between this event and the previous motion event. |
| 500 | * Whole numbers are pixels; the value may have a fraction for input devices |
| 501 | * that are sub-pixel precise. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 502 | float AMotionEvent_getHistoricalX(AInputEvent* motion_event, size_t pointer_index, |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 503 | size_t history_index); |
| 504 | |
| 505 | /* Get the historical Y coordinate of this event for the given pointer index that |
| 506 | * occurred between this event and the previous motion event. |
| 507 | * Whole numbers are pixels; the value may have a fraction for input devices |
| 508 | * that are sub-pixel precise. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 509 | float AMotionEvent_getHistoricalY(AInputEvent* motion_event, size_t pointer_index, |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 510 | size_t history_index); |
| 511 | |
| 512 | /* Get the historical pressure of this event for the given pointer index that |
| 513 | * occurred between this event and the previous motion event. |
| 514 | * The pressure generally ranges from 0 (no pressure at all) to 1 (normal pressure), |
| 515 | * however values higher than 1 may be generated depending on the calibration of |
| 516 | * the input device. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 517 | float AMotionEvent_getHistoricalPressure(AInputEvent* motion_event, size_t pointer_index, |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 518 | size_t history_index); |
| 519 | |
| 520 | /* Get the current scaled value of the approximate size for the given pointer index that |
| 521 | * occurred between this event and the previous motion event. |
| 522 | * This represents some approximation of the area of the screen being |
| 523 | * pressed; the actual value in pixels corresponding to the |
| 524 | * touch is normalized with the device specific range of values |
| 525 | * and scaled to a value between 0 and 1. The value of size can be used to |
| 526 | * determine fat touch events. */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 527 | float AMotionEvent_getHistoricalSize(AInputEvent* motion_event, size_t pointer_index, |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 528 | size_t history_index); |
| 529 | |
Dianne Hackborn | a95e4cb | 2010-06-18 18:09:33 -0700 | [diff] [blame] | 530 | /* |
| 531 | * Input queue |
| 532 | * |
| 533 | * An input queue is the facility through which you retrieve input |
| 534 | * events. |
| 535 | */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 536 | struct AInputQueue; |
| 537 | typedef struct AInputQueue AInputQueue; |
Dianne Hackborn | a95e4cb | 2010-06-18 18:09:33 -0700 | [diff] [blame] | 538 | |
| 539 | /* |
Dianne Hackborn | 85448bb | 2010-07-07 14:27:31 -0700 | [diff] [blame] | 540 | * Add this input queue to a looper for processing. See |
| 541 | * ALooper_addFd() for information on the callback and data params. |
Dianne Hackborn | a95e4cb | 2010-06-18 18:09:33 -0700 | [diff] [blame] | 542 | */ |
Dianne Hackborn | 6826741 | 2010-07-02 18:52:01 -0700 | [diff] [blame] | 543 | void AInputQueue_attachLooper(AInputQueue* queue, ALooper* looper, |
Dianne Hackborn | 85448bb | 2010-07-07 14:27:31 -0700 | [diff] [blame] | 544 | ALooper_callbackFunc* callback, void* data); |
Dianne Hackborn | 6826741 | 2010-07-02 18:52:01 -0700 | [diff] [blame] | 545 | |
| 546 | /* |
| 547 | * Remove the input queue from the looper it is currently attached to. |
| 548 | */ |
| 549 | void AInputQueue_detachLooper(AInputQueue* queue); |
Dianne Hackborn | a95e4cb | 2010-06-18 18:09:33 -0700 | [diff] [blame] | 550 | |
| 551 | /* |
| 552 | * Returns true if there are one or more events available in the |
| 553 | * input queue. Returns 1 if the queue has events; 0 if |
| 554 | * it does not have events; and a negative value if there is an error. |
| 555 | */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 556 | int AInputQueue_hasEvents(AInputQueue* queue); |
Dianne Hackborn | a95e4cb | 2010-06-18 18:09:33 -0700 | [diff] [blame] | 557 | |
| 558 | /* |
| 559 | * Returns the next available event from the queue. Returns a negative |
| 560 | * value if no events are available or an error has occurred. |
| 561 | */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 562 | int32_t AInputQueue_getEvent(AInputQueue* queue, AInputEvent** outEvent); |
Dianne Hackborn | a95e4cb | 2010-06-18 18:09:33 -0700 | [diff] [blame] | 563 | |
| 564 | /* |
| 565 | * Report that dispatching has finished with the given event. |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 566 | * This must be called after receiving an event with AInputQueue_get_event(). |
Dianne Hackborn | a95e4cb | 2010-06-18 18:09:33 -0700 | [diff] [blame] | 567 | */ |
Dianne Hackborn | 2e9f93e | 2010-06-28 15:27:30 -0700 | [diff] [blame] | 568 | void AInputQueue_finishEvent(AInputQueue* queue, AInputEvent* event, int handled); |
Dianne Hackborn | a95e4cb | 2010-06-18 18:09:33 -0700 | [diff] [blame] | 569 | |
Jeff Brown | 46b9ac0a | 2010-04-22 18:58:52 -0700 | [diff] [blame] | 570 | #ifdef __cplusplus |
| 571 | } |
| 572 | #endif |
| 573 | |
| 574 | #endif // _ANDROID_INPUT_H |