blob: 25dd68ef7e17fa63bac7bc7a3805eff366bc5d31 [file] [log] [blame]
Jeff Brown46b9ac0a2010-04-22 18:58:52 -07001/*
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 Hackborn68267412010-07-02 18:52:01 -070045#include <android/looper.h>
Jeff Brown46b9ac0a2010-04-22 18:58:52 -070046
47#ifdef __cplusplus
48extern "C" {
49#endif
50
51/*
52 * Input device classes.
53 */
54enum {
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 Brownfd0358292010-06-30 16:10:35 -070071 INPUT_DEVICE_CLASS_DPAD = 0x00000020,
72
73 /* The input device is a gamepad (implies keyboard). */
74 INPUT_DEVICE_CLASS_GAMEPAD = 0x00000040
Jeff Brown46b9ac0a2010-04-22 18:58:52 -070075};
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 */
83enum {
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 */
100enum {
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 Hackborn2e9f93e2010-06-28 15:27:30 -0700132struct AInputEvent;
133typedef struct AInputEvent AInputEvent;
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700134
135/*
136 * Input event types.
137 */
138enum {
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 */
149enum {
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 */
166enum {
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
227enum {
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 */
279enum {
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 */
310enum {
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 Hackborn2e9f93e2010-06-28 15:27:30 -0700326int32_t AInputEvent_getType(const AInputEvent* event);
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700327
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 Hackborn2e9f93e2010-06-28 15:27:30 -0700338int32_t AInputEvent_getDeviceId(const AInputEvent* event);
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700339
340/* Get the input event nature. */
Dianne Hackborn2e9f93e2010-06-28 15:27:30 -0700341int32_t AInputEvent_getNature(const AInputEvent* event);
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700342
343/*** Accessors for key events only. ***/
344
345/* Get the key event action. */
Dianne Hackborn2e9f93e2010-06-28 15:27:30 -0700346int32_t AKeyEvent_getAction(const AInputEvent* key_event);
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700347
348/* Get the key event flags. */
Dianne Hackborn2e9f93e2010-06-28 15:27:30 -0700349int32_t AKeyEvent_getFlags(const AInputEvent* key_event);
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700350
351/* Get the key code of the key event.
352 * This is the physical key that was pressed, not the Unicode character. */
Dianne Hackborn2e9f93e2010-06-28 15:27:30 -0700353int32_t AKeyEvent_getKeyCode(const AInputEvent* key_event);
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700354
355/* Get the hardware key id of this key event.
356 * These values are not reliable and vary from device to device. */
Dianne Hackborn2e9f93e2010-06-28 15:27:30 -0700357int32_t AKeyEvent_getScanCode(const AInputEvent* key_event);
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700358
359/* Get the meta key state. */
Dianne Hackborn2e9f93e2010-06-28 15:27:30 -0700360int32_t AKeyEvent_getMetaState(const AInputEvent* key_event);
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700361
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 Hackborn2e9f93e2010-06-28 15:27:30 -0700366int32_t AKeyEvent_getRepeatCount(const AInputEvent* key_event);
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700367
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 Hackborn2e9f93e2010-06-28 15:27:30 -0700373int64_t AKeyEvent_getDownTime(const AInputEvent* key_event);
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700374
375/* Get the time this event occurred, in the
376 * java.lang.System.nanoTime() time base. */
Dianne Hackborn2e9f93e2010-06-28 15:27:30 -0700377int64_t AKeyEvent_getEventTime(const AInputEvent* key_event);
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700378
379/*** Accessors for motion events only. ***/
380
381/* Get the combined motion event action code and pointer index. */
Dianne Hackborn2e9f93e2010-06-28 15:27:30 -0700382int32_t AMotionEvent_getAction(const AInputEvent* motion_event);
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700383
384/* Get the state of any meta / modifier keys that were in effect when the
385 * event was generated. */
Dianne Hackborn2e9f93e2010-06-28 15:27:30 -0700386int32_t AMotionEvent_getMetaState(const AInputEvent* motion_event);
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700387
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 Hackborn2e9f93e2010-06-28 15:27:30 -0700391int32_t AMotionEvent_getEdgeFlags(const AInputEvent* motion_event);
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700392
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 Hackborn2e9f93e2010-06-28 15:27:30 -0700395int64_t AMotionEvent_getDownTime(const AInputEvent* motion_event);
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700396
397/* Get the time when this specific event was generated,
398 * in the java.lang.System.nanoTime() time base. */
Dianne Hackborn2e9f93e2010-06-28 15:27:30 -0700399int64_t AMotionEvent_getEventTime(const AInputEvent* motion_event);
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700400
Jeff Brown5c225b12010-06-16 01:53:36 -0700401/* 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 Hackborn2e9f93e2010-06-28 15:27:30 -0700405float AMotionEvent_getXOffset(const AInputEvent* motion_event);
Jeff Brown5c225b12010-06-16 01:53:36 -0700406
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 Hackborn2e9f93e2010-06-28 15:27:30 -0700411float AMotionEvent_getYOffset(const AInputEvent* motion_event);
Jeff Brown5c225b12010-06-16 01:53:36 -0700412
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700413/* 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 Hackborn2e9f93e2010-06-28 15:27:30 -0700416float AMotionEvent_getXPrecision(const AInputEvent* motion_event);
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700417
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 Hackborn2e9f93e2010-06-28 15:27:30 -0700421float AMotionEvent_getYPrecision(const AInputEvent* motion_event);
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700422
423/* Get the number of pointers of data contained in this event.
424 * Always >= 1. */
Dianne Hackborn2e9f93e2010-06-28 15:27:30 -0700425size_t AMotionEvent_getPointerCount(const AInputEvent* motion_event);
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700426
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 Hackborn2e9f93e2010-06-28 15:27:30 -0700431int32_t AMotionEvent_getPointerId(const AInputEvent* motion_event, size_t pointer_index);
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700432
Jeff Brown5c225b12010-06-16 01:53:36 -0700433/* 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 Brown46b9ac0a2010-04-22 18:58:52 -0700435 * on the screen, before it had been adjusted for the containing window
436 * and views. */
Dianne Hackborn2e9f93e2010-06-28 15:27:30 -0700437float AMotionEvent_getRawX(const AInputEvent* motion_event, size_t pointer_index);
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700438
Jeff Brown5c225b12010-06-16 01:53:36 -0700439/* 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 Brown46b9ac0a2010-04-22 18:58:52 -0700441 * on the screen, before it had been adjusted for the containing window
442 * and views. */
Dianne Hackborn2e9f93e2010-06-28 15:27:30 -0700443float AMotionEvent_getRawY(const AInputEvent* motion_event, size_t pointer_index);
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700444
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 Hackborn2e9f93e2010-06-28 15:27:30 -0700448float AMotionEvent_getX(const AInputEvent* motion_event, size_t pointer_index);
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700449
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 Hackborn2e9f93e2010-06-28 15:27:30 -0700453float AMotionEvent_getY(const AInputEvent* motion_event, size_t pointer_index);
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700454
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 Hackborn2e9f93e2010-06-28 15:27:30 -0700459float AMotionEvent_getPressure(const AInputEvent* motion_event, size_t pointer_index);
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700460
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 Hackborn2e9f93e2010-06-28 15:27:30 -0700467float AMotionEvent_getSize(const AInputEvent* motion_event, size_t pointer_index);
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700468
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 Hackborn2e9f93e2010-06-28 15:27:30 -0700473size_t AMotionEvent_get_history_size(const AInputEvent* motion_event);
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700474
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 Hackborn2e9f93e2010-06-28 15:27:30 -0700477int64_t AMotionEvent_getHistoricalEventTime(AInputEvent* motion_event,
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700478 size_t history_index);
479
Jeff Brown5c225b12010-06-16 01:53:36 -0700480/* 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 Hackborn2e9f93e2010-06-28 15:27:30 -0700487float AMotionEvent_getHistoricalRawX(const AInputEvent* motion_event, size_t pointer_index);
Jeff Brown5c225b12010-06-16 01:53:36 -0700488
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 Hackborn2e9f93e2010-06-28 15:27:30 -0700496float AMotionEvent_getHistoricalRawY(const AInputEvent* motion_event, size_t pointer_index);
Jeff Brown5c225b12010-06-16 01:53:36 -0700497
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700498/* 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 Hackborn2e9f93e2010-06-28 15:27:30 -0700502float AMotionEvent_getHistoricalX(AInputEvent* motion_event, size_t pointer_index,
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700503 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 Hackborn2e9f93e2010-06-28 15:27:30 -0700509float AMotionEvent_getHistoricalY(AInputEvent* motion_event, size_t pointer_index,
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700510 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 Hackborn2e9f93e2010-06-28 15:27:30 -0700517float AMotionEvent_getHistoricalPressure(AInputEvent* motion_event, size_t pointer_index,
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700518 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 Hackborn2e9f93e2010-06-28 15:27:30 -0700527float AMotionEvent_getHistoricalSize(AInputEvent* motion_event, size_t pointer_index,
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700528 size_t history_index);
529
Dianne Hackborna95e4cb2010-06-18 18:09:33 -0700530/*
531 * Input queue
532 *
533 * An input queue is the facility through which you retrieve input
534 * events.
535 */
Dianne Hackborn2e9f93e2010-06-28 15:27:30 -0700536struct AInputQueue;
537typedef struct AInputQueue AInputQueue;
Dianne Hackborna95e4cb2010-06-18 18:09:33 -0700538
539/*
Dianne Hackborn85448bb2010-07-07 14:27:31 -0700540 * Add this input queue to a looper for processing. See
541 * ALooper_addFd() for information on the callback and data params.
Dianne Hackborna95e4cb2010-06-18 18:09:33 -0700542 */
Dianne Hackborn68267412010-07-02 18:52:01 -0700543void AInputQueue_attachLooper(AInputQueue* queue, ALooper* looper,
Dianne Hackborn85448bb2010-07-07 14:27:31 -0700544 ALooper_callbackFunc* callback, void* data);
Dianne Hackborn68267412010-07-02 18:52:01 -0700545
546/*
547 * Remove the input queue from the looper it is currently attached to.
548 */
549void AInputQueue_detachLooper(AInputQueue* queue);
Dianne Hackborna95e4cb2010-06-18 18:09:33 -0700550
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 Hackborn2e9f93e2010-06-28 15:27:30 -0700556int AInputQueue_hasEvents(AInputQueue* queue);
Dianne Hackborna95e4cb2010-06-18 18:09:33 -0700557
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 Hackborn2e9f93e2010-06-28 15:27:30 -0700562int32_t AInputQueue_getEvent(AInputQueue* queue, AInputEvent** outEvent);
Dianne Hackborna95e4cb2010-06-18 18:09:33 -0700563
564/*
565 * Report that dispatching has finished with the given event.
Dianne Hackborn2e9f93e2010-06-28 15:27:30 -0700566 * This must be called after receiving an event with AInputQueue_get_event().
Dianne Hackborna95e4cb2010-06-18 18:09:33 -0700567 */
Dianne Hackborn2e9f93e2010-06-28 15:27:30 -0700568void AInputQueue_finishEvent(AInputQueue* queue, AInputEvent* event, int handled);
Dianne Hackborna95e4cb2010-06-18 18:09:33 -0700569
Jeff Brown46b9ac0a2010-04-22 18:58:52 -0700570#ifdef __cplusplus
571}
572#endif
573
574#endif // _ANDROID_INPUT_H