include/android/input.h

   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 /**
  18  * @addtogroup Input
  19  * @{
  20  */
  21
  22 /**
  23  * @file input.h
  24  */
  25
  26 #ifndef _ANDROID_INPUT_H
  27 #define _ANDROID_INPUT_H
  28
  29 #include <sys/cdefs.h>
  30
  31 /******************************************************************
  32  *
  33  * IMPORTANT NOTICE:
  34  *
  35  *   This file is part of Android's set of stable system headers
  36  *   exposed by the Android NDK (Native Development Kit).
  37  *
  38  *   Third-party source AND binary code relies on the definitions
  39  *   here to be FROZEN ON ALL UPCOMING PLATFORM RELEASES.
  40  *
  41  *   - DO NOT MODIFY ENUMS (EXCEPT IF YOU ADD NEW 32-BIT VALUES)
  42  *   - DO NOT MODIFY CONSTANTS OR FUNCTIONAL MACROS
  43  *   - DO NOT CHANGE THE SIGNATURE OF FUNCTIONS IN ANY WAY
  44  *   - DO NOT CHANGE THE LAYOUT OR SIZE OF STRUCTURES
  45  */
  46
  47 /*
  48  * Structures and functions to receive and process input events in
  49  * native code.
  50  *
  51  * NOTE: These functions MUST be implemented by /system/lib/libui.so
  52  */
  53
  54 #include <stdint.h>
  55 #include <sys/types.h>
  56 #include <android/keycodes.h>
  57 #include <android/looper.h>
  58
  59 #ifdef __cplusplus
  60 extern "C" {
  61 #endif
  62
  63 /**
  64  * Key states (may be returned by queries about the current state of a
  65  * particular key code, scan code or switch).
  66  */
  67 enum {
  68     /** The key state is unknown or the requested key itself is not supported. */
  69     AKEY_STATE_UNKNOWN = -1,
  70
  71     /** The key is up. */
  72     AKEY_STATE_UP = 0,
  73
  74     /** The key is down. */
  75     AKEY_STATE_DOWN = 1,
  76
  77     /** The key is down but is a virtual key press that is being emulated by the system. */
  78     AKEY_STATE_VIRTUAL = 2
  79 };
  80
  81 /**
  82  * Meta key / modifer state.
  83  */
  84 enum {
  85     /** No meta keys are pressed. */
  86     AMETA_NONE = 0,
  87
  88     /** This mask is used to check whether one of the ALT meta keys is pressed. */
  89     AMETA_ALT_ON = 0x02,
  90
  91     /** This mask is used to check whether the left ALT meta key is pressed. */
  92     AMETA_ALT_LEFT_ON = 0x10,
  93
  94     /** This mask is used to check whether the right ALT meta key is pressed. */
  95     AMETA_ALT_RIGHT_ON = 0x20,
  96
  97     /** This mask is used to check whether one of the SHIFT meta keys is pressed. */
  98     AMETA_SHIFT_ON = 0x01,
  99
 100     /** This mask is used to check whether the left SHIFT meta key is pressed. */
 101     AMETA_SHIFT_LEFT_ON = 0x40,
 102
 103     /** This mask is used to check whether the right SHIFT meta key is pressed. */
 104     AMETA_SHIFT_RIGHT_ON = 0x80,
 105
 106     /** This mask is used to check whether the SYM meta key is pressed. */
 107     AMETA_SYM_ON = 0x04,
 108
 109     /** This mask is used to check whether the FUNCTION meta key is pressed. */
 110     AMETA_FUNCTION_ON = 0x08,
 111
 112     /** This mask is used to check whether one of the CTRL meta keys is pressed. */
 113     AMETA_CTRL_ON = 0x1000,
 114
 115     /** This mask is used to check whether the left CTRL meta key is pressed. */
 116     AMETA_CTRL_LEFT_ON = 0x2000,
 117
 118     /** This mask is used to check whether the right CTRL meta key is pressed. */
 119     AMETA_CTRL_RIGHT_ON = 0x4000,
 120
 121     /** This mask is used to check whether one of the META meta keys is pressed. */
 122     AMETA_META_ON = 0x10000,
 123
 124     /** This mask is used to check whether the left META meta key is pressed. */
 125     AMETA_META_LEFT_ON = 0x20000,
 126
 127     /** This mask is used to check whether the right META meta key is pressed. */
 128     AMETA_META_RIGHT_ON = 0x40000,
 129
 130     /** This mask is used to check whether the CAPS LOCK meta key is on. */
 131     AMETA_CAPS_LOCK_ON = 0x100000,
 132
 133     /** This mask is used to check whether the NUM LOCK meta key is on. */
 134     AMETA_NUM_LOCK_ON = 0x200000,
 135
 136     /** This mask is used to check whether the SCROLL LOCK meta key is on. */
 137     AMETA_SCROLL_LOCK_ON = 0x400000,
 138 };
 139
 140 struct AInputEvent;
 141 /**
 142  * Input events.
 143  *
 144  * Input events are opaque structures.  Use the provided accessors functions to
 145  * read their properties.
 146  */
 147 typedef struct AInputEvent AInputEvent;
 148
 149 /**
 150  * Input event types.
 151  */
 152 enum {
 153     /** Indicates that the input event is a key event. */
 154     AINPUT_EVENT_TYPE_KEY = 1,
 155
 156     /** Indicates that the input event is a motion event. */
 157     AINPUT_EVENT_TYPE_MOTION = 2
 158 };
 159
 160 /**
 161  * Key event actions.
 162  */
 163 enum {
 164     /** The key has been pressed down. */
 165     AKEY_EVENT_ACTION_DOWN = 0,
 166
 167     /** The key has been released. */
 168     AKEY_EVENT_ACTION_UP = 1,
 169
 170     /**
 171      * Multiple duplicate key events have occurred in a row, or a
 172      * complex string is being delivered.  The repeat_count property
 173      * of the key event contains the number of times the given key
 174      * code should be executed.
 175      */
 176     AKEY_EVENT_ACTION_MULTIPLE = 2
 177 };
 178
 179 /**
 180  * Key event flags.
 181  */
 182 enum {
 183     /** This mask is set if the device woke because of this key event. */
 184     AKEY_EVENT_FLAG_WOKE_HERE = 0x1,
 185
 186     /** This mask is set if the key event was generated by a software keyboard. */
 187     AKEY_EVENT_FLAG_SOFT_KEYBOARD = 0x2,
 188
 189     /** This mask is set if we don't want the key event to cause us to leave touch mode. */
 190     AKEY_EVENT_FLAG_KEEP_TOUCH_MODE = 0x4,
 191
 192     /**
 193      * This mask is set if an event was known to come from a trusted
 194      * part of the system.  That is, the event is known to come from
 195      * the user, and could not have been spoofed by a third party
 196      * component.
 197      */
 198     AKEY_EVENT_FLAG_FROM_SYSTEM = 0x8,
 199
 200     /**
 201      * This mask is used for compatibility, to identify enter keys that are
 202      * coming from an IME whose enter key has been auto-labelled "next" or
 203      * "done".  This allows TextView to dispatch these as normal enter keys
 204      * for old applications, but still do the appropriate action when
 205      * receiving them.
 206      */
 207     AKEY_EVENT_FLAG_EDITOR_ACTION = 0x10,
 208
 209     /**
 210      * When associated with up key events, this indicates that the key press
 211      * has been canceled.  Typically this is used with virtual touch screen
 212      * keys, where the user can slide from the virtual key area on to the
 213      * display: in that case, the application will receive a canceled up
 214      * event and should not perform the action normally associated with the
 215      * key.  Note that for this to work, the application can not perform an
 216      * action for a key until it receives an up or the long press timeout has
 217      * expired.
 218      */
 219     AKEY_EVENT_FLAG_CANCELED = 0x20,
 220
 221     /**
 222      * This key event was generated by a virtual (on-screen) hard key area.
 223      * Typically this is an area of the touchscreen, outside of the regular
 224      * display, dedicated to "hardware" buttons.
 225      */
 226     AKEY_EVENT_FLAG_VIRTUAL_HARD_KEY = 0x40,
 227
 228     /**
 229      * This flag is set for the first key repeat that occurs after the
 230      * long press timeout.
 231      */
 232     AKEY_EVENT_FLAG_LONG_PRESS = 0x80,
 233
 234     /**
 235      * Set when a key event has AKEY_EVENT_FLAG_CANCELED set because a long
 236      * press action was executed while it was down.
 237      */
 238     AKEY_EVENT_FLAG_CANCELED_LONG_PRESS = 0x100,
 239
 240     /**
 241      * Set for AKEY_EVENT_ACTION_UP when this event's key code is still being
 242      * tracked from its initial down.  That is, somebody requested that tracking
 243      * started on the key down and a long press has not caused
 244      * the tracking to be canceled.
 245      */
 246     AKEY_EVENT_FLAG_TRACKING = 0x200,
 247
 248     /**
 249      * Set when a key event has been synthesized to implement default behavior
 250      * for an event that the application did not handle.
 251      * Fallback key events are generated by unhandled trackball motions
 252      * (to emulate a directional keypad) and by certain unhandled key presses
 253      * that are declared in the key map (such as special function numeric keypad
 254      * keys when numlock is off).
 255      */
 256     AKEY_EVENT_FLAG_FALLBACK = 0x400,
 257 };
 258
 259 /**
 260  * Bit shift for the action bits holding the pointer index as
 261  * defined by AMOTION_EVENT_ACTION_POINTER_INDEX_MASK.
 262  */
 263 #define AMOTION_EVENT_ACTION_POINTER_INDEX_SHIFT 8
 264
 265 /** Motion event actions */
 266 enum {
 267     /** Bit mask of the parts of the action code that are the action itself. */
 268     AMOTION_EVENT_ACTION_MASK = 0xff,
 269
 270     /**
 271      * Bits in the action code that represent a pointer index, used with
 272      * AMOTION_EVENT_ACTION_POINTER_DOWN and AMOTION_EVENT_ACTION_POINTER_UP.  Shifting
 273      * down by AMOTION_EVENT_ACTION_POINTER_INDEX_SHIFT provides the actual pointer
 274      * index where the data for the pointer going up or down can be found.
 275      */
 276     AMOTION_EVENT_ACTION_POINTER_INDEX_MASK  = 0xff00,
 277
 278     /** A pressed gesture has started, the motion contains the initial starting location. */
 279     AMOTION_EVENT_ACTION_DOWN = 0,
 280
 281     /**
 282      * A pressed gesture has finished, the motion contains the final release location
 283      * as well as any intermediate points since the last down or move event.
 284      */
 285     AMOTION_EVENT_ACTION_UP = 1,
 286
 287     /**
 288      * A change has happened during a press gesture (between AMOTION_EVENT_ACTION_DOWN and
 289      * AMOTION_EVENT_ACTION_UP).  The motion contains the most recent point, as well as
 290      * any intermediate points since the last down or move event.
 291      */
 292     AMOTION_EVENT_ACTION_MOVE = 2,
 293
 294     /**
 295      * The current gesture has been aborted.
 296      * You will not receive any more points in it.  You should treat this as
 297      * an up event, but not perform any action that you normally would.
 298      */
 299     AMOTION_EVENT_ACTION_CANCEL = 3,
 300
 301     /**
 302      * A movement has happened outside of the normal bounds of the UI element.
 303      * This does not provide a full gesture, but only the initial location of the movement/touch.
 304      */
 305     AMOTION_EVENT_ACTION_OUTSIDE = 4,
 306
 307     /**
 308      * A non-primary pointer has gone down.
 309      * The bits in AMOTION_EVENT_ACTION_POINTER_INDEX_MASK indicate which pointer changed.
 310      */
 311     AMOTION_EVENT_ACTION_POINTER_DOWN = 5,
 312
 313     /**
 314      * A non-primary pointer has gone up.
 315      * The bits in AMOTION_EVENT_ACTION_POINTER_INDEX_MASK indicate which pointer changed.
 316      */
 317     AMOTION_EVENT_ACTION_POINTER_UP = 6,
 318
 319     /**
 320      * A change happened but the pointer is not down (unlike AMOTION_EVENT_ACTION_MOVE).
 321      * The motion contains the most recent point, as well as any intermediate points since
 322      * the last hover move event.
 323      */
 324     AMOTION_EVENT_ACTION_HOVER_MOVE = 7,
 325
 326     /**
 327      * The motion event contains relative vertical and/or horizontal scroll offsets.
 328      * Use getAxisValue to retrieve the information from AMOTION_EVENT_AXIS_VSCROLL
 329      * and AMOTION_EVENT_AXIS_HSCROLL.
 330      * The pointer may or may not be down when this event is dispatched.
 331      * This action is always delivered to the winder under the pointer, which
 332      * may not be the window currently touched.
 333      */
 334     AMOTION_EVENT_ACTION_SCROLL = 8,
 335
 336     /** The pointer is not down but has entered the boundaries of a window or view. */
 337     AMOTION_EVENT_ACTION_HOVER_ENTER = 9,
 338
 339     /** The pointer is not down but has exited the boundaries of a window or view. */
 340     AMOTION_EVENT_ACTION_HOVER_EXIT = 10,
 341
 342     /* One or more buttons have been pressed. */
 343     AMOTION_EVENT_ACTION_BUTTON_PRESS = 11,
 344
 345     /* One or more buttons have been released. */
 346     AMOTION_EVENT_ACTION_BUTTON_RELEASE = 12,
 347 };
 348
 349 /**
 350  * Motion event flags.
 351  */
 352 enum {
 353     /**
 354      * This flag indicates that the window that received this motion event is partly
 355      * or wholly obscured by another visible window above it.  This flag is set to true
 356      * even if the event did not directly pass through the obscured area.
 357      * A security sensitive application can check this flag to identify situations in which
 358      * a malicious application may have covered up part of its content for the purpose
 359      * of misleading the user or hijacking touches.  An appropriate response might be
 360      * to drop the suspect touches or to take additional precautions to confirm the user's
 361      * actual intent.
 362      */
 363     AMOTION_EVENT_FLAG_WINDOW_IS_OBSCURED = 0x1,
 364 };
 365
 366 /**
 367  * Motion event edge touch flags.
 368  */
 369 enum {
 370     /** No edges intersected. */
 371     AMOTION_EVENT_EDGE_FLAG_NONE = 0,
 372
 373     /** Flag indicating the motion event intersected the top edge of the screen. */
 374     AMOTION_EVENT_EDGE_FLAG_TOP = 0x01,
 375
 376     /** Flag indicating the motion event intersected the bottom edge of the screen. */
 377     AMOTION_EVENT_EDGE_FLAG_BOTTOM = 0x02,
 378
 379     /** Flag indicating the motion event intersected the left edge of the screen. */
 380     AMOTION_EVENT_EDGE_FLAG_LEFT = 0x04,
 381
 382     /** Flag indicating the motion event intersected the right edge of the screen. */
 383     AMOTION_EVENT_EDGE_FLAG_RIGHT = 0x08
 384 };
 385
 386 /**
 387  * Constants that identify each individual axis of a motion event.
 388  * @anchor AMOTION_EVENT_AXIS
 389  */
 390 enum {
 391     /**
 392      * Axis constant: X axis of a motion event.
 393      *
 394      * - For a touch screen, reports the absolute X screen position of the center of
 395      * the touch contact area.  The units are display pixels.
 396      * - For a touch pad, reports the absolute X surface position of the center of the touch
 397      * contact area. The units are device-dependent.
 398      * - For a mouse, reports the absolute X screen position of the mouse pointer.
 399      * The units are display pixels.
 400      * - For a trackball, reports the relative horizontal displacement of the trackball.
 401      * The value is normalized to a range from -1.0 (left) to 1.0 (right).
 402      * - For a joystick, reports the absolute X position of the joystick.
 403      * The value is normalized to a range from -1.0 (left) to 1.0 (right).
 404      */
 405     AMOTION_EVENT_AXIS_X = 0,
 406     /**
 407      * Axis constant: Y axis of a motion event.
 408      *
 409      * - For a touch screen, reports the absolute Y screen position of the center of
 410      * the touch contact area.  The units are display pixels.
 411      * - For a touch pad, reports the absolute Y surface position of the center of the touch
 412      * contact area. The units are device-dependent.
 413      * - For a mouse, reports the absolute Y screen position of the mouse pointer.
 414      * The units are display pixels.
 415      * - For a trackball, reports the relative vertical displacement of the trackball.
 416      * The value is normalized to a range from -1.0 (up) to 1.0 (down).
 417      * - For a joystick, reports the absolute Y position of the joystick.
 418      * The value is normalized to a range from -1.0 (up or far) to 1.0 (down or near).
 419      */
 420     AMOTION_EVENT_AXIS_Y = 1,
 421     /**
 422      * Axis constant: Pressure axis of a motion event.
 423      *
 424      * - For a touch screen or touch pad, reports the approximate pressure applied to the surface
 425      * by a finger or other tool.  The value is normalized to a range from
 426      * 0 (no pressure at all) to 1 (normal pressure), although values higher than 1
 427      * may be generated depending on the calibration of the input device.
 428      * - For a trackball, the value is set to 1 if the trackball button is pressed
 429      * or 0 otherwise.
 430      * - For a mouse, the value is set to 1 if the primary mouse button is pressed
 431      * or 0 otherwise.
 432      */
 433     AMOTION_EVENT_AXIS_PRESSURE = 2,
 434     /**
 435      * Axis constant: Size axis of a motion event.
 436      *
 437      * - For a touch screen or touch pad, reports the approximate size of the contact area in
 438      * relation to the maximum detectable size for the device.  The value is normalized
 439      * to a range from 0 (smallest detectable size) to 1 (largest detectable size),
 440      * although it is not a linear scale. This value is of limited use.
 441      * To obtain calibrated size information, see
 442      * {@link AMOTION_EVENT_AXIS_TOUCH_MAJOR} or {@link AMOTION_EVENT_AXIS_TOOL_MAJOR}.
 443      */
 444     AMOTION_EVENT_AXIS_SIZE = 3,
 445     /**
 446      * Axis constant: TouchMajor axis of a motion event.
 447      *
 448      * - For a touch screen, reports the length of the major axis of an ellipse that
 449      * represents the touch area at the point of contact.
 450      * The units are display pixels.
 451      * - For a touch pad, reports the length of the major axis of an ellipse that
 452      * represents the touch area at the point of contact.
 453      * The units are device-dependent.
 454      */
 455     AMOTION_EVENT_AXIS_TOUCH_MAJOR = 4,
 456     /**
 457      * Axis constant: TouchMinor axis of a motion event.
 458      *
 459      * - For a touch screen, reports the length of the minor axis of an ellipse that
 460      * represents the touch area at the point of contact.
 461      * The units are display pixels.
 462      * - For a touch pad, reports the length of the minor axis of an ellipse that
 463      * represents the touch area at the point of contact.
 464      * The units are device-dependent.
 465      *
 466      * When the touch is circular, the major and minor axis lengths will be equal to one another.
 467      */
 468     AMOTION_EVENT_AXIS_TOUCH_MINOR = 5,
 469     /**
 470      * Axis constant: ToolMajor axis of a motion event.
 471      *
 472      * - For a touch screen, reports the length of the major axis of an ellipse that
 473      * represents the size of the approaching finger or tool used to make contact.
 474      * - For a touch pad, reports the length of the major axis of an ellipse that
 475      * represents the size of the approaching finger or tool used to make contact.
 476      * The units are device-dependent.
 477      *
 478      * When the touch is circular, the major and minor axis lengths will be equal to one another.
 479      *
 480      * The tool size may be larger than the touch size since the tool may not be fully
 481      * in contact with the touch sensor.
 482      */
 483     AMOTION_EVENT_AXIS_TOOL_MAJOR = 6,
 484     /**
 485      * Axis constant: ToolMinor axis of a motion event.
 486      *
 487      * - For a touch screen, reports the length of the minor axis of an ellipse that
 488      * represents the size of the approaching finger or tool used to make contact.
 489      * - For a touch pad, reports the length of the minor axis of an ellipse that
 490      * represents the size of the approaching finger or tool used to make contact.
 491      * The units are device-dependent.
 492      *
 493      * When the touch is circular, the major and minor axis lengths will be equal to one another.
 494      *
 495      * The tool size may be larger than the touch size since the tool may not be fully
 496      * in contact with the touch sensor.
 497      */
 498     AMOTION_EVENT_AXIS_TOOL_MINOR = 7,
 499     /**
 500      * Axis constant: Orientation axis of a motion event.
 501      *
 502      * - For a touch screen or touch pad, reports the orientation of the finger
 503      * or tool in radians relative to the vertical plane of the device.
 504      * An angle of 0 radians indicates that the major axis of contact is oriented
 505      * upwards, is perfectly circular or is of unknown orientation.  A positive angle
 506      * indicates that the major axis of contact is oriented to the right.  A negative angle
 507      * indicates that the major axis of contact is oriented to the left.
 508      * The full range is from -PI/2 radians (finger pointing fully left) to PI/2 radians
 509      * (finger pointing fully right).
 510      * - For a stylus, the orientation indicates the direction in which the stylus
 511      * is pointing in relation to the vertical axis of the current orientation of the screen.
 512      * The range is from -PI radians to PI radians, where 0 is pointing up,
 513      * -PI/2 radians is pointing left, -PI or PI radians is pointing down, and PI/2 radians
 514      * is pointing right.  See also {@link AMOTION_EVENT_AXIS_TILT}.
 515      */
 516     AMOTION_EVENT_AXIS_ORIENTATION = 8,
 517     /**
 518      * Axis constant: Vertical Scroll axis of a motion event.
 519      *
 520      * - For a mouse, reports the relative movement of the vertical scroll wheel.
 521      * The value is normalized to a range from -1.0 (down) to 1.0 (up).
 522      *
 523      * This axis should be used to scroll views vertically.
 524      */
 525     AMOTION_EVENT_AXIS_VSCROLL = 9,
 526     /**
 527      * Axis constant: Horizontal Scroll axis of a motion event.
 528      *
 529      * - For a mouse, reports the relative movement of the horizontal scroll wheel.
 530      * The value is normalized to a range from -1.0 (left) to 1.0 (right).
 531      *
 532      * This axis should be used to scroll views horizontally.
 533      */
 534     AMOTION_EVENT_AXIS_HSCROLL = 10,
 535     /**
 536      * Axis constant: Z axis of a motion event.
 537      *
 538      * - For a joystick, reports the absolute Z position of the joystick.
 539      * The value is normalized to a range from -1.0 (high) to 1.0 (low).
 540      * <em>On game pads with two analog joysticks, this axis is often reinterpreted
 541      * to report the absolute X position of the second joystick instead.</em>
 542      */
 543     AMOTION_EVENT_AXIS_Z = 11,
 544     /**
 545      * Axis constant: X Rotation axis of a motion event.
 546      *
 547      * - For a joystick, reports the absolute rotation angle about the X axis.
 548      * The value is normalized to a range from -1.0 (counter-clockwise) to 1.0 (clockwise).
 549      */
 550     AMOTION_EVENT_AXIS_RX = 12,
 551     /**
 552      * Axis constant: Y Rotation axis of a motion event.
 553      *
 554      * - For a joystick, reports the absolute rotation angle about the Y axis.
 555      * The value is normalized to a range from -1.0 (counter-clockwise) to 1.0 (clockwise).
 556      */
 557     AMOTION_EVENT_AXIS_RY = 13,
 558     /**
 559      * Axis constant: Z Rotation axis of a motion event.
 560      *
 561      * - For a joystick, reports the absolute rotation angle about the Z axis.
 562      * The value is normalized to a range from -1.0 (counter-clockwise) to 1.0 (clockwise).
 563      * On game pads with two analog joysticks, this axis is often reinterpreted
 564      * to report the absolute Y position of the second joystick instead.
 565      */
 566     AMOTION_EVENT_AXIS_RZ = 14,
 567     /**
 568      * Axis constant: Hat X axis of a motion event.
 569      *
 570      * - For a joystick, reports the absolute X position of the directional hat control.
 571      * The value is normalized to a range from -1.0 (left) to 1.0 (right).
 572      */
 573     AMOTION_EVENT_AXIS_HAT_X = 15,
 574     /**
 575      * Axis constant: Hat Y axis of a motion event.
 576      *
 577      * - For a joystick, reports the absolute Y position of the directional hat control.
 578      * The value is normalized to a range from -1.0 (up) to 1.0 (down).
 579      */
 580     AMOTION_EVENT_AXIS_HAT_Y = 16,
 581     /**
 582      * Axis constant: Left Trigger axis of a motion event.
 583      *
 584      * - For a joystick, reports the absolute position of the left trigger control.
 585      * The value is normalized to a range from 0.0 (released) to 1.0 (fully pressed).
 586      */
 587     AMOTION_EVENT_AXIS_LTRIGGER = 17,
 588     /**
 589      * Axis constant: Right Trigger axis of a motion event.
 590      *
 591      * - For a joystick, reports the absolute position of the right trigger control.
 592      * The value is normalized to a range from 0.0 (released) to 1.0 (fully pressed).
 593      */
 594     AMOTION_EVENT_AXIS_RTRIGGER = 18,
 595     /**
 596      * Axis constant: Throttle axis of a motion event.
 597      *
 598      * - For a joystick, reports the absolute position of the throttle control.
 599      * The value is normalized to a range from 0.0 (fully open) to 1.0 (fully closed).
 600      */
 601     AMOTION_EVENT_AXIS_THROTTLE = 19,
 602     /**
 603      * Axis constant: Rudder axis of a motion event.
 604      *
 605      * - For a joystick, reports the absolute position of the rudder control.
 606      * The value is normalized to a range from -1.0 (turn left) to 1.0 (turn right).
 607      */
 608     AMOTION_EVENT_AXIS_RUDDER = 20,
 609     /**
 610      * Axis constant: Wheel axis of a motion event.
 611      *
 612      * - For a joystick, reports the absolute position of the steering wheel control.
 613      * The value is normalized to a range from -1.0 (turn left) to 1.0 (turn right).
 614      */
 615     AMOTION_EVENT_AXIS_WHEEL = 21,
 616     /**
 617      * Axis constant: Gas axis of a motion event.
 618      *
 619      * - For a joystick, reports the absolute position of the gas (accelerator) control.
 620      * The value is normalized to a range from 0.0 (no acceleration)
 621      * to 1.0 (maximum acceleration).
 622      */
 623     AMOTION_EVENT_AXIS_GAS = 22,
 624     /**
 625      * Axis constant: Brake axis of a motion event.
 626      *
 627      * - For a joystick, reports the absolute position of the brake control.
 628      * The value is normalized to a range from 0.0 (no braking) to 1.0 (maximum braking).
 629      */
 630     AMOTION_EVENT_AXIS_BRAKE = 23,
 631     /**
 632      * Axis constant: Distance axis of a motion event.
 633      *
 634      * - For a stylus, reports the distance of the stylus from the screen.
 635      * A value of 0.0 indicates direct contact and larger values indicate increasing
 636      * distance from the surface.
 637      */
 638     AMOTION_EVENT_AXIS_DISTANCE = 24,
 639     /**
 640      * Axis constant: Tilt axis of a motion event.
 641      *
 642      * - For a stylus, reports the tilt angle of the stylus in radians where
 643      * 0 radians indicates that the stylus is being held perpendicular to the
 644      * surface, and PI/2 radians indicates that the stylus is being held flat
 645      * against the surface.
 646      */
 647     AMOTION_EVENT_AXIS_TILT = 25,
 648     /**
 649      * Axis constant:  Generic scroll axis of a motion event.
 650      *
 651      * - This is used for scroll axis motion events that can't be classified as strictly
 652      *   vertical or horizontal. The movement of a rotating scroller is an example of this.
 653      */
 654     AMOTION_EVENT_AXIS_SCROLL = 26,
 655     /**
 656      * Axis constant: The movement of x position of a motion event.
 657      *
 658      * - For a mouse, reports a difference of x position between the previous position.
 659      * This is useful when pointer is captured, in that case the mouse pointer doesn't
 660      * change the location but this axis reports the difference which allows the app
 661      * to see how the mouse is moved.
 662      */
 663     AMOTION_EVENT_AXIS_RELATIVE_X = 27,
 664     /**
 665      * Axis constant: The movement of y position of a motion event.
 666      *
 667      * Same as {@link RELATIVE_X}, but for y position.
 668      */
 669     AMOTION_EVENT_AXIS_RELATIVE_Y = 28,
 670     /**
 671      * Axis constant: Generic 1 axis of a motion event.
 672      * The interpretation of a generic axis is device-specific.
 673      */
 674     AMOTION_EVENT_AXIS_GENERIC_1 = 32,
 675     /**
 676      * Axis constant: Generic 2 axis of a motion event.
 677      * The interpretation of a generic axis is device-specific.
 678      */
 679     AMOTION_EVENT_AXIS_GENERIC_2 = 33,
 680     /**
 681      * Axis constant: Generic 3 axis of a motion event.
 682      * The interpretation of a generic axis is device-specific.
 683      */
 684     AMOTION_EVENT_AXIS_GENERIC_3 = 34,
 685     /**
 686      * Axis constant: Generic 4 axis of a motion event.
 687      * The interpretation of a generic axis is device-specific.
 688      */
 689     AMOTION_EVENT_AXIS_GENERIC_4 = 35,
 690     /**
 691      * Axis constant: Generic 5 axis of a motion event.
 692      * The interpretation of a generic axis is device-specific.
 693      */
 694     AMOTION_EVENT_AXIS_GENERIC_5 = 36,
 695     /**
 696      * Axis constant: Generic 6 axis of a motion event.
 697      * The interpretation of a generic axis is device-specific.
 698      */
 699     AMOTION_EVENT_AXIS_GENERIC_6 = 37,
 700     /**
 701      * Axis constant: Generic 7 axis of a motion event.
 702      * The interpretation of a generic axis is device-specific.
 703      */
 704     AMOTION_EVENT_AXIS_GENERIC_7 = 38,
 705     /**
 706      * Axis constant: Generic 8 axis of a motion event.
 707      * The interpretation of a generic axis is device-specific.
 708      */
 709     AMOTION_EVENT_AXIS_GENERIC_8 = 39,
 710     /**
 711      * Axis constant: Generic 9 axis of a motion event.
 712      * The interpretation of a generic axis is device-specific.
 713      */
 714     AMOTION_EVENT_AXIS_GENERIC_9 = 40,
 715     /**
 716      * Axis constant: Generic 10 axis of a motion event.
 717      * The interpretation of a generic axis is device-specific.
 718      */
 719     AMOTION_EVENT_AXIS_GENERIC_10 = 41,
 720     /**
 721      * Axis constant: Generic 11 axis of a motion event.
 722      * The interpretation of a generic axis is device-specific.
 723      */
 724     AMOTION_EVENT_AXIS_GENERIC_11 = 42,
 725     /**
 726      * Axis constant: Generic 12 axis of a motion event.
 727      * The interpretation of a generic axis is device-specific.
 728      */
 729     AMOTION_EVENT_AXIS_GENERIC_12 = 43,
 730     /**
 731      * Axis constant: Generic 13 axis of a motion event.
 732      * The interpretation of a generic axis is device-specific.
 733      */
 734     AMOTION_EVENT_AXIS_GENERIC_13 = 44,
 735     /**
 736      * Axis constant: Generic 14 axis of a motion event.
 737      * The interpretation of a generic axis is device-specific.
 738      */
 739     AMOTION_EVENT_AXIS_GENERIC_14 = 45,
 740     /**
 741      * Axis constant: Generic 15 axis of a motion event.
 742      * The interpretation of a generic axis is device-specific.
 743      */
 744     AMOTION_EVENT_AXIS_GENERIC_15 = 46,
 745     /**
 746      * Axis constant: Generic 16 axis of a motion event.
 747      * The interpretation of a generic axis is device-specific.
 748      */
 749     AMOTION_EVENT_AXIS_GENERIC_16 = 47,
 750
 751     // NOTE: If you add a new axis here you must also add it to several other files.
 752     //       Refer to frameworks/base/core/java/android/view/MotionEvent.java for the full list.
 753 };
 754
 755 /**
 756  * Constants that identify buttons that are associated with motion events.
 757  * Refer to the documentation on the MotionEvent class for descriptions of each button.
 758  */
 759 enum {
 760     /** primary */
 761     AMOTION_EVENT_BUTTON_PRIMARY = 1 << 0,
 762     /** secondary */
 763     AMOTION_EVENT_BUTTON_SECONDARY = 1 << 1,
 764     /** tertiary */
 765     AMOTION_EVENT_BUTTON_TERTIARY = 1 << 2,
 766     /** back */
 767     AMOTION_EVENT_BUTTON_BACK = 1 << 3,
 768     /** forward */
 769     AMOTION_EVENT_BUTTON_FORWARD = 1 << 4,
 770     AMOTION_EVENT_BUTTON_STYLUS_PRIMARY = 1 << 5,
 771     AMOTION_EVENT_BUTTON_STYLUS_SECONDARY = 1 << 6,
 772 };
 773
 774 /**
 775  * Constants that identify tool types.
 776  * Refer to the documentation on the MotionEvent class for descriptions of each tool type.
 777  */
 778 enum {
 779     /** unknown */
 780     AMOTION_EVENT_TOOL_TYPE_UNKNOWN = 0,
 781     /** finger */
 782     AMOTION_EVENT_TOOL_TYPE_FINGER = 1,
 783     /** stylus */
 784     AMOTION_EVENT_TOOL_TYPE_STYLUS = 2,
 785     /** mouse */
 786     AMOTION_EVENT_TOOL_TYPE_MOUSE = 3,
 787     /** eraser */
 788     AMOTION_EVENT_TOOL_TYPE_ERASER = 4,
 789 };
 790
 791 /**
 792  * Input source masks.
 793  *
 794  * Refer to the documentation on android.view.InputDevice for more details about input sources
 795  * and their correct interpretation.
 796  */
 797 enum {
 798     /** mask */
 799     AINPUT_SOURCE_CLASS_MASK = 0x000000ff,
 800
 801     /** none */
 802     AINPUT_SOURCE_CLASS_NONE = 0x00000000,
 803     /** button */
 804     AINPUT_SOURCE_CLASS_BUTTON = 0x00000001,
 805     /** pointer */
 806     AINPUT_SOURCE_CLASS_POINTER = 0x00000002,
 807     /** navigation */
 808     AINPUT_SOURCE_CLASS_NAVIGATION = 0x00000004,
 809     /** position */
 810     AINPUT_SOURCE_CLASS_POSITION = 0x00000008,
 811     /** joystick */
 812     AINPUT_SOURCE_CLASS_JOYSTICK = 0x00000010,
 813 };
 814
 815 /**
 816  * Input sources.
 817  */
 818 enum {
 819     /** unknown */
 820     AINPUT_SOURCE_UNKNOWN = 0x00000000,
 821
 822     /** keyboard */
 823     AINPUT_SOURCE_KEYBOARD = 0x00000100 | AINPUT_SOURCE_CLASS_BUTTON,
 824     /** dpad */
 825     AINPUT_SOURCE_DPAD = 0x00000200 | AINPUT_SOURCE_CLASS_BUTTON,
 826     /** gamepad */
 827     AINPUT_SOURCE_GAMEPAD = 0x00000400 | AINPUT_SOURCE_CLASS_BUTTON,
 828     /** touchscreen */
 829     AINPUT_SOURCE_TOUCHSCREEN = 0x00001000 | AINPUT_SOURCE_CLASS_POINTER,
 830     /** mouse */
 831     AINPUT_SOURCE_MOUSE = 0x00002000 | AINPUT_SOURCE_CLASS_POINTER,
 832     /** stylus */
 833     AINPUT_SOURCE_STYLUS = 0x00004000 | AINPUT_SOURCE_CLASS_POINTER,
 834     /** bluetooth stylus */
 835     AINPUT_SOURCE_BLUETOOTH_STYLUS = 0x00008000 | AINPUT_SOURCE_STYLUS,
 836     /** trackball */
 837     AINPUT_SOURCE_TRACKBALL = 0x00010000 | AINPUT_SOURCE_CLASS_NAVIGATION,
 838     /** mouse relative */
 839     AINPUT_SOURCE_MOUSE_RELATIVE = 0x00020000 | AINPUT_SOURCE_CLASS_NAVIGATION,
 840     /** touchpad */
 841     AINPUT_SOURCE_TOUCHPAD = 0x00100000 | AINPUT_SOURCE_CLASS_POSITION,
 842     /** navigation */
 843     AINPUT_SOURCE_TOUCH_NAVIGATION = 0x00200000 | AINPUT_SOURCE_CLASS_NONE,
 844     /** joystick */
 845     AINPUT_SOURCE_JOYSTICK = 0x01000000 | AINPUT_SOURCE_CLASS_JOYSTICK,
 846     /** rotary encoder */
 847     AINPUT_SOURCE_ROTARY_ENCODER = 0x00400000 | AINPUT_SOURCE_CLASS_NONE,
 848
 849     /** any */
 850     AINPUT_SOURCE_ANY = 0xffffff00,
 851 };
 852
 853 /**
 854  * Keyboard types.
 855  *
 856  * Refer to the documentation on android.view.InputDevice for more details.
 857  */
 858 enum {
 859     /** none */
 860     AINPUT_KEYBOARD_TYPE_NONE = 0,
 861     /** non alphabetic */
 862     AINPUT_KEYBOARD_TYPE_NON_ALPHABETIC = 1,
 863     /** alphabetic */
 864     AINPUT_KEYBOARD_TYPE_ALPHABETIC = 2,
 865 };
 866
 867 /**
 868  * Constants used to retrieve information about the range of motion for a particular
 869  * coordinate of a motion event.
 870  *
 871  * Refer to the documentation on android.view.InputDevice for more details about input sources
 872  * and their correct interpretation.
 873  *
 874  * @deprecated These constants are deprecated. Use {@link AMOTION_EVENT_AXIS AMOTION_EVENT_AXIS_*} constants instead.
 875  */
 876 enum {
 877     /** x */
 878     AINPUT_MOTION_RANGE_X = AMOTION_EVENT_AXIS_X,
 879     /** y */
 880     AINPUT_MOTION_RANGE_Y = AMOTION_EVENT_AXIS_Y,
 881     /** pressure */
 882     AINPUT_MOTION_RANGE_PRESSURE = AMOTION_EVENT_AXIS_PRESSURE,
 883     /** size */
 884     AINPUT_MOTION_RANGE_SIZE = AMOTION_EVENT_AXIS_SIZE,
 885     /** touch major */
 886     AINPUT_MOTION_RANGE_TOUCH_MAJOR = AMOTION_EVENT_AXIS_TOUCH_MAJOR,
 887     /** touch minor */
 888     AINPUT_MOTION_RANGE_TOUCH_MINOR = AMOTION_EVENT_AXIS_TOUCH_MINOR,
 889     /** tool major */
 890     AINPUT_MOTION_RANGE_TOOL_MAJOR = AMOTION_EVENT_AXIS_TOOL_MAJOR,
 891     /** tool minor */
 892     AINPUT_MOTION_RANGE_TOOL_MINOR = AMOTION_EVENT_AXIS_TOOL_MINOR,
 893     /** orientation */
 894     AINPUT_MOTION_RANGE_ORIENTATION = AMOTION_EVENT_AXIS_ORIENTATION,
 895 };
 896
 897
 898 /**
 899  * Input event accessors.
 900  *
 901  * Note that most functions can only be used on input events that are of a given type.
 902  * Calling these functions on input events of other types will yield undefined behavior.
 903  */
 904
 905 /*** Accessors for all input events. ***/
 906
 907 /** Get the input event type. */
 908 int32_t AInputEvent_getType(const AInputEvent* event);
 909
 910 /** Get the id for the device that an input event came from.
 911  *
 912  * Input events can be generated by multiple different input devices.
 913  * Use the input device id to obtain information about the input
 914  * device that was responsible for generating a particular event.
 915  *
 916  * An input device id of 0 indicates that the event didn't come from a physical device;
 917  * other numbers are arbitrary and you shouldn't depend on the values.
 918  * Use the provided input device query API to obtain information about input devices.
 919  */
 920 int32_t AInputEvent_getDeviceId(const AInputEvent* event);
 921
 922 /** Get the input event source. */
 923 int32_t AInputEvent_getSource(const AInputEvent* event);
 924
 925 /*** Accessors for key events only. ***/
 926
 927 /** Get the key event action. */
 928 int32_t AKeyEvent_getAction(const AInputEvent* key_event);
 929
 930 /** Get the key event flags. */
 931 int32_t AKeyEvent_getFlags(const AInputEvent* key_event);
 932
 933 /**
 934  * Get the key code of the key event.
 935  * This is the physical key that was pressed, not the Unicode character.
 936  */
 937 int32_t AKeyEvent_getKeyCode(const AInputEvent* key_event);
 938
 939 /**
 940  * Get the hardware key id of this key event.
 941  * These values are not reliable and vary from device to device.
 942  */
 943 int32_t AKeyEvent_getScanCode(const AInputEvent* key_event);
 944
 945 /** Get the meta key state. */
 946 int32_t AKeyEvent_getMetaState(const AInputEvent* key_event);
 947
 948 /**
 949  * Get the repeat count of the event.
 950  * For both key up an key down events, this is the number of times the key has
 951  * repeated with the first down starting at 0 and counting up from there.  For
 952  * multiple key events, this is the number of down/up pairs that have occurred.
 953  */
 954 int32_t AKeyEvent_getRepeatCount(const AInputEvent* key_event);
 955
 956 /**
 957  * Get the time of the most recent key down event, in the
 958  * java.lang.System.nanoTime() time base.  If this is a down event,
 959  * this will be the same as eventTime.
 960  * Note that when chording keys, this value is the down time of the most recently
 961  * pressed key, which may not be the same physical key of this event.
 962  */
 963 int64_t AKeyEvent_getDownTime(const AInputEvent* key_event);
 964
 965 /**
 966  * Get the time this event occurred, in the
 967  * java.lang.System.nanoTime() time base.
 968  */
 969 int64_t AKeyEvent_getEventTime(const AInputEvent* key_event);
 970
 971 /*** Accessors for motion events only. ***/
 972
 973 /** Get the combined motion event action code and pointer index. */
 974 int32_t AMotionEvent_getAction(const AInputEvent* motion_event);
 975
 976 /** Get the motion event flags. */
 977 int32_t AMotionEvent_getFlags(const AInputEvent* motion_event);
 978
 979 /**
 980  * Get the state of any meta / modifier keys that were in effect when the
 981  * event was generated.
 982  */
 983 int32_t AMotionEvent_getMetaState(const AInputEvent* motion_event);
 984
 985 #if __ANDROID_API__ >= 14
 986 /** Get the button state of all buttons that are pressed. */
 987 int32_t AMotionEvent_getButtonState(const AInputEvent* motion_event);
 988 #endif
 989
 990 /**
 991  * Get a bitfield indicating which edges, if any, were touched by this motion event.
 992  * For touch events, clients can use this to determine if the user's finger was
 993  * touching the edge of the display.
 994  */
 995 int32_t AMotionEvent_getEdgeFlags(const AInputEvent* motion_event);
 996
 997 /**
 998  * Get the time when the user originally pressed down to start a stream of
 999  * position events, in the java.lang.System.nanoTime() time base.
1000  */
1001 int64_t AMotionEvent_getDownTime(const AInputEvent* motion_event);
1002
1003 /**
1004  * Get the time when this specific event was generated,
1005  * in the java.lang.System.nanoTime() time base.
1006  */
1007 int64_t AMotionEvent_getEventTime(const AInputEvent* motion_event);
1008
1009 /**
1010  * Get the X coordinate offset.
1011  * For touch events on the screen, this is the delta that was added to the raw
1012  * screen coordinates to adjust for the absolute position of the containing windows
1013  * and views.
1014  */
1015 float AMotionEvent_getXOffset(const AInputEvent* motion_event);
1016
1017 /**
1018  * Get the Y coordinate offset.
1019  * For touch events on the screen, this is the delta that was added to the raw
1020  * screen coordinates to adjust for the absolute position of the containing windows
1021  * and views.
1022  */
1023 float AMotionEvent_getYOffset(const AInputEvent* motion_event);
1024
1025 /**
1026  * Get the precision of the X coordinates being reported.
1027  * You can multiply this number with an X coordinate sample to find the
1028  * actual hardware value of the X coordinate.
1029  */
1030 float AMotionEvent_getXPrecision(const AInputEvent* motion_event);
1031
1032 /**
1033  * Get the precision of the Y coordinates being reported.
1034  * You can multiply this number with a Y coordinate sample to find the
1035  * actual hardware value of the Y coordinate.
1036  */
1037 float AMotionEvent_getYPrecision(const AInputEvent* motion_event);
1038
1039 /**
1040  * Get the number of pointers of data contained in this event.
1041  * Always >= 1.
1042  */
1043 size_t AMotionEvent_getPointerCount(const AInputEvent* motion_event);
1044
1045 /**
1046  * Get the pointer identifier associated with a particular pointer
1047  * data index in this event.  The identifier tells you the actual pointer
1048  * number associated with the data, accounting for individual pointers
1049  * going up and down since the start of the current gesture.
1050  */
1051 int32_t AMotionEvent_getPointerId(const AInputEvent* motion_event, size_t pointer_index);
1052
1053 #if __ANDROID_API__ >= 14
1054 /**
1055  * Get the tool type of a pointer for the given pointer index.
1056  * The tool type indicates the type of tool used to make contact such as a
1057  * finger or stylus, if known.
1058  */
1059 int32_t AMotionEvent_getToolType(const AInputEvent* motion_event, size_t pointer_index);
1060 #endif
1061
1062 /**
1063  * Get the original raw X coordinate of this event.
1064  * For touch events on the screen, this is the original location of the event
1065  * on the screen, before it had been adjusted for the containing window
1066  * and views.
1067  */
1068 float AMotionEvent_getRawX(const AInputEvent* motion_event, size_t pointer_index);
1069
1070 /**
1071  * Get the original raw X coordinate of this event.
1072  * For touch events on the screen, this is the original location of the event
1073  * on the screen, before it had been adjusted for the containing window
1074  * and views.
1075  */
1076 float AMotionEvent_getRawY(const AInputEvent* motion_event, size_t pointer_index);
1077
1078 /**
1079  * Get the current X coordinate of this event for the given pointer index.
1080  * Whole numbers are pixels; the value may have a fraction for input devices
1081  * that are sub-pixel precise.
1082  */
1083 float AMotionEvent_getX(const AInputEvent* motion_event, size_t pointer_index);
1084
1085 /**
1086  * Get the current Y coordinate of this event for the given pointer index.
1087  * Whole numbers are pixels; the value may have a fraction for input devices
1088  * that are sub-pixel precise.
1089  */
1090 float AMotionEvent_getY(const AInputEvent* motion_event, size_t pointer_index);
1091
1092 /**
1093  * Get the current pressure of this event for the given pointer index.
1094  * The pressure generally ranges from 0 (no pressure at all) to 1 (normal pressure),
1095  * although values higher than 1 may be generated depending on the calibration of
1096  * the input device.
1097  */
1098 float AMotionEvent_getPressure(const AInputEvent* motion_event, size_t pointer_index);
1099
1100 /**
1101  * Get the current scaled value of the approximate size for the given pointer index.
1102  * This represents some approximation of the area of the screen being
1103  * pressed; the actual value in pixels corresponding to the
1104  * touch is normalized with the device specific range of values
1105  * and scaled to a value between 0 and 1.  The value of size can be used to
1106  * determine fat touch events.
1107  */
1108 float AMotionEvent_getSize(const AInputEvent* motion_event, size_t pointer_index);
1109
1110 /**
1111  * Get the current length of the major axis of an ellipse that describes the touch area
1112  * at the point of contact for the given pointer index.
1113  */
1114 float AMotionEvent_getTouchMajor(const AInputEvent* motion_event, size_t pointer_index);
1115
1116 /**
1117  * Get the current length of the minor axis of an ellipse that describes the touch area
1118  * at the point of contact for the given pointer index.
1119  */
1120 float AMotionEvent_getTouchMinor(const AInputEvent* motion_event, size_t pointer_index);
1121
1122 /**
1123  * Get the current length of the major axis of an ellipse that describes the size
1124  * of the approaching tool for the given pointer index.
1125  * The tool area represents the estimated size of the finger or pen that is
1126  * touching the device independent of its actual touch area at the point of contact.
1127  */
1128 float AMotionEvent_getToolMajor(const AInputEvent* motion_event, size_t pointer_index);
1129
1130 /**
1131  * Get the current length of the minor axis of an ellipse that describes the size
1132  * of the approaching tool for the given pointer index.
1133  * The tool area represents the estimated size of the finger or pen that is
1134  * touching the device independent of its actual touch area at the point of contact.
1135  */
1136 float AMotionEvent_getToolMinor(const AInputEvent* motion_event, size_t pointer_index);
1137
1138 /**
1139  * Get the current orientation of the touch area and tool area in radians clockwise from
1140  * vertical for the given pointer index.
1141  * An angle of 0 degrees indicates that the major axis of contact is oriented
1142  * upwards, is perfectly circular or is of unknown orientation.  A positive angle
1143  * indicates that the major axis of contact is oriented to the right.  A negative angle
1144  * indicates that the major axis of contact is oriented to the left.
1145  * The full range is from -PI/2 radians (finger pointing fully left) to PI/2 radians
1146  * (finger pointing fully right).
1147  */
1148 float AMotionEvent_getOrientation(const AInputEvent* motion_event, size_t pointer_index);
1149
1150 #if __ANDROID_API__ >= 13
1151 /** Get the value of the request axis for the given pointer index. */
1152 float AMotionEvent_getAxisValue(const AInputEvent* motion_event,
1153         int32_t axis, size_t pointer_index);
1154 #endif
1155
1156 /**
1157  * Get the number of historical points in this event.  These are movements that
1158  * have occurred between this event and the previous event.  This only applies
1159  * to AMOTION_EVENT_ACTION_MOVE events -- all other actions will have a size of 0.
1160  * Historical samples are indexed from oldest to newest.
1161  */
1162 size_t AMotionEvent_getHistorySize(const AInputEvent* motion_event);
1163
1164 /**
1165  * Get the time that a historical movement occurred between this event and
1166  * the previous event, in the java.lang.System.nanoTime() time base.
1167  */
1168 int64_t AMotionEvent_getHistoricalEventTime(const AInputEvent* motion_event,
1169         size_t history_index);
1170
1171 /**
1172  * Get the historical raw X coordinate of this event for the given pointer index that
1173  * occurred between this event and the previous motion event.
1174  * For touch events on the screen, this is the original location of the event
1175  * on the screen, before it had been adjusted for the containing window
1176  * and views.
1177  * Whole numbers are pixels; the value may have a fraction for input devices
1178  * that are sub-pixel precise.
1179  */
1180 float AMotionEvent_getHistoricalRawX(const AInputEvent* motion_event, size_t pointer_index,
1181         size_t history_index);
1182
1183 /**
1184  * Get the historical raw Y coordinate of this event for the given pointer index that
1185  * occurred between this event and the previous motion event.
1186  * For touch events on the screen, this is the original location of the event
1187  * on the screen, before it had been adjusted for the containing window
1188  * and views.
1189  * Whole numbers are pixels; the value may have a fraction for input devices
1190  * that are sub-pixel precise.
1191  */
1192 float AMotionEvent_getHistoricalRawY(const AInputEvent* motion_event, size_t pointer_index,
1193         size_t history_index);
1194
1195 /**
1196  * Get the historical X coordinate of this event for the given pointer index that
1197  * occurred between this event and the previous motion event.
1198  * Whole numbers are pixels; the value may have a fraction for input devices
1199  * that are sub-pixel precise.
1200  */
1201 float AMotionEvent_getHistoricalX(const AInputEvent* motion_event, size_t pointer_index,
1202         size_t history_index);
1203
1204 /**
1205  * Get the historical Y coordinate of this event for the given pointer index that
1206  * occurred between this event and the previous motion event.
1207  * Whole numbers are pixels; the value may have a fraction for input devices
1208  * that are sub-pixel precise.
1209  */
1210 float AMotionEvent_getHistoricalY(const AInputEvent* motion_event, size_t pointer_index,
1211         size_t history_index);
1212
1213 /**
1214  * Get the historical pressure of this event for the given pointer index that
1215  * occurred between this event and the previous motion event.
1216  * The pressure generally ranges from 0 (no pressure at all) to 1 (normal pressure),
1217  * although values higher than 1 may be generated depending on the calibration of
1218  * the input device.
1219  */
1220 float AMotionEvent_getHistoricalPressure(const AInputEvent* motion_event, size_t pointer_index,
1221         size_t history_index);
1222
1223 /**
1224  * Get the current scaled value of the approximate size for the given pointer index that
1225  * occurred between this event and the previous motion event.
1226  * This represents some approximation of the area of the screen being
1227  * pressed; the actual value in pixels corresponding to the
1228  * touch is normalized with the device specific range of values
1229  * and scaled to a value between 0 and 1.  The value of size can be used to
1230  * determine fat touch events.
1231  */
1232 float AMotionEvent_getHistoricalSize(const AInputEvent* motion_event, size_t pointer_index,
1233         size_t history_index);
1234
1235 /**
1236  * Get the historical length of the major axis of an ellipse that describes the touch area
1237  * at the point of contact for the given pointer index that
1238  * occurred between this event and the previous motion event.
1239  */
1240 float AMotionEvent_getHistoricalTouchMajor(const AInputEvent* motion_event, size_t pointer_index,
1241         size_t history_index);
1242
1243 /**
1244  * Get the historical length of the minor axis of an ellipse that describes the touch area
1245  * at the point of contact for the given pointer index that
1246  * occurred between this event and the previous motion event.
1247  */
1248 float AMotionEvent_getHistoricalTouchMinor(const AInputEvent* motion_event, size_t pointer_index,
1249         size_t history_index);
1250
1251 /**
1252  * Get the historical length of the major axis of an ellipse that describes the size
1253  * of the approaching tool for the given pointer index that
1254  * occurred between this event and the previous motion event.
1255  * The tool area represents the estimated size of the finger or pen that is
1256  * touching the device independent of its actual touch area at the point of contact.
1257  */
1258 float AMotionEvent_getHistoricalToolMajor(const AInputEvent* motion_event, size_t pointer_index,
1259         size_t history_index);
1260
1261 /**
1262  * Get the historical length of the minor axis of an ellipse that describes the size
1263  * of the approaching tool for the given pointer index that
1264  * occurred between this event and the previous motion event.
1265  * The tool area represents the estimated size of the finger or pen that is
1266  * touching the device independent of its actual touch area at the point of contact.
1267  */
1268 float AMotionEvent_getHistoricalToolMinor(const AInputEvent* motion_event, size_t pointer_index,
1269         size_t history_index);
1270
1271 /**
1272  * Get the historical orientation of the touch area and tool area in radians clockwise from
1273  * vertical for the given pointer index that
1274  * occurred between this event and the previous motion event.
1275  * An angle of 0 degrees indicates that the major axis of contact is oriented
1276  * upwards, is perfectly circular or is of unknown orientation.  A positive angle
1277  * indicates that the major axis of contact is oriented to the right.  A negative angle
1278  * indicates that the major axis of contact is oriented to the left.
1279  * The full range is from -PI/2 radians (finger pointing fully left) to PI/2 radians
1280  * (finger pointing fully right).
1281  */
1282 float AMotionEvent_getHistoricalOrientation(const AInputEvent* motion_event, size_t pointer_index,
1283         size_t history_index);
1284
1285 #if __ANDROID_API__ >= 13
1286 /**
1287  * Get the historical value of the request axis for the given pointer index
1288  * that occurred between this event and the previous motion event.
1289  */
1290 float AMotionEvent_getHistoricalAxisValue(const AInputEvent* motion_event,
1291         int32_t axis, size_t pointer_index, size_t history_index);
1292 #endif
1293
1294
1295 struct AInputQueue;
1296 /**
1297  * Input queue
1298  *
1299  * An input queue is the facility through which you retrieve input
1300  * events.
1301  */
1302 typedef struct AInputQueue AInputQueue;
1303
1304 /**
1305  * Add this input queue to a looper for processing.  See
1306  * ALooper_addFd() for information on the ident, callback, and data params.
1307  */
1308 void AInputQueue_attachLooper(AInputQueue* queue, ALooper* looper,
1309         int ident, ALooper_callbackFunc callback, void* data);
1310
1311 /**
1312  * Remove the input queue from the looper it is currently attached to.
1313  */
1314 void AInputQueue_detachLooper(AInputQueue* queue);
1315
1316 /**
1317  * Returns true if there are one or more events available in the
1318  * input queue.  Returns 1 if the queue has events; 0 if
1319  * it does not have events; and a negative value if there is an error.
1320  */
1321 int32_t AInputQueue_hasEvents(AInputQueue* queue);
1322
1323 /**
1324  * Returns the next available event from the queue.  Returns a negative
1325  * value if no events are available or an error has occurred.
1326  */
1327 int32_t AInputQueue_getEvent(AInputQueue* queue, AInputEvent** outEvent);
1328
1329 /**
1330  * Sends the key for standard pre-dispatching -- that is, possibly deliver
1331  * it to the current IME to be consumed before the app.  Returns 0 if it
1332  * was not pre-dispatched, meaning you can process it right now.  If non-zero
1333  * is returned, you must abandon the current event processing and allow the
1334  * event to appear again in the event queue (if it does not get consumed during
1335  * pre-dispatching).
1336  */
1337 int32_t AInputQueue_preDispatchEvent(AInputQueue* queue, AInputEvent* event);
1338
1339 /**
1340  * Report that dispatching has finished with the given event.
1341  * This must be called after receiving an event with AInputQueue_get_event().
1342  */
1343 void AInputQueue_finishEvent(AInputQueue* queue, AInputEvent* event, int handled);
1344
1345 #ifdef __cplusplus
1346 }
1347 #endif
1348
1349 #endif // _ANDROID_INPUT_H
1350
1351 /** @} */