include/input/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 #ifndef _LIBINPUT_INPUT_H
  18 #define _LIBINPUT_INPUT_H
  19
  20 /**
  21  * Native input event structures.
  22  */
  23
  24 #include <android/input.h>
  25 #include <utils/Vector.h>
  26 #include <utils/KeyedVector.h>
  27 #include <utils/Timers.h>
  28 #include <utils/RefBase.h>
  29 #include <utils/String8.h>
  30
  31 /*
  32  * Additional private constants not defined in ndk/ui/input.h.
  33  */
  34 enum {
  35     /* Signifies that the key is being predispatched */
  36     AKEY_EVENT_FLAG_PREDISPATCH = 0x20000000,
  37
  38     /* Private control to determine when an app is tracking a key sequence. */
  39     AKEY_EVENT_FLAG_START_TRACKING = 0x40000000,
  40
  41     /* Key event is inconsistent with previously sent key events. */
  42     AKEY_EVENT_FLAG_TAINTED = 0x80000000,
  43 };
  44
  45 enum {
  46     /* Motion event is inconsistent with previously sent motion events. */
  47     AMOTION_EVENT_FLAG_TAINTED = 0x80000000,
  48 };
  49
  50 enum {
  51     /* Used when a motion event is not associated with any display.
  52      * Typically used for non-pointer events. */
  53     ADISPLAY_ID_NONE = -1,
  54
  55     /* The default display id. */
  56     ADISPLAY_ID_DEFAULT = 0,
  57 };
  58
  59 enum {
  60     /*
  61      * Indicates that an input device has switches.
  62      * This input source flag is hidden from the API because switches are only used by the system
  63      * and applications have no way to interact with them.
  64      */
  65     AINPUT_SOURCE_SWITCH = 0x80000000,
  66 };
  67
  68 enum {
  69     /**
  70      * Constants for LEDs. Hidden from the API since we don't actually expose a way to interact
  71      * with LEDs to developers
  72      *
  73      * NOTE: If you add LEDs here, you must also add them to KeycodeLabels.h
  74      */
  75
  76     ALED_NUM_LOCK = 0x00,
  77     ALED_CAPS_LOCK = 0x01,
  78     ALED_SCROLL_LOCK = 0x02,
  79     ALED_COMPOSE = 0x03,
  80     ALED_KANA = 0x04,
  81     ALED_SLEEP = 0x05,
  82     ALED_SUSPEND = 0x06,
  83     ALED_MUTE = 0x07,
  84     ALED_MISC = 0x08,
  85     ALED_MAIL = 0x09,
  86     ALED_CHARGING = 0x0a,
  87     ALED_CONTROLLER_1 = 0x10,
  88     ALED_CONTROLLER_2 = 0x11,
  89     ALED_CONTROLLER_3 = 0x12,
  90     ALED_CONTROLLER_4 = 0x13,
  91 };
  92
  93 /*
  94  * SystemUiVisibility constants from View.
  95  */
  96 enum {
  97     ASYSTEM_UI_VISIBILITY_STATUS_BAR_VISIBLE = 0,
  98     ASYSTEM_UI_VISIBILITY_STATUS_BAR_HIDDEN = 0x00000001,
  99 };
 100
 101 /*
 102  * Maximum number of pointers supported per motion event.
 103  * Smallest number of pointers is 1.
 104  * (We want at least 10 but some touch controllers obstensibly configured for 10 pointers
 105  * will occasionally emit 11.  There is not much harm making this constant bigger.)
 106  */
 107 #define MAX_POINTERS 16
 108
 109 /*
 110  * Maximum pointer id value supported in a motion event.
 111  * Smallest pointer id is 0.
 112  * (This is limited by our use of BitSet32 to track pointer assignments.)
 113  */
 114 #define MAX_POINTER_ID 31
 115
 116 /*
 117  * Declare a concrete type for the NDK's input event forward declaration.
 118  */
 119 struct AInputEvent {
 120     virtual ~AInputEvent() { }
 121 };
 122
 123 /*
 124  * Declare a concrete type for the NDK's input device forward declaration.
 125  */
 126 struct AInputDevice {
 127     virtual ~AInputDevice() { }
 128 };
 129
 130
 131 namespace android {
 132
 133 #ifdef HAVE_ANDROID_OS
 134 class Parcel;
 135 #endif
 136
 137 /*
 138  * Flags that flow alongside events in the input dispatch system to help with certain
 139  * policy decisions such as waking from device sleep.
 140  *
 141  * These flags are also defined in frameworks/base/core/java/android/view/WindowManagerPolicy.java.
 142  */
 143 enum {
 144     /* These flags originate in RawEvents and are generally set in the key map.
 145      * NOTE: If you edit these flags, also edit labels in KeycodeLabels.h. */
 146
 147     POLICY_FLAG_WAKE = 0x00000001,
 148     POLICY_FLAG_WAKE_DROPPED = 0x00000002,
 149     POLICY_FLAG_SHIFT = 0x00000004,
 150     POLICY_FLAG_CAPS_LOCK = 0x00000008,
 151     POLICY_FLAG_ALT = 0x00000010,
 152     POLICY_FLAG_ALT_GR = 0x00000020,
 153     POLICY_FLAG_MENU = 0x00000040,
 154     POLICY_FLAG_LAUNCHER = 0x00000080,
 155     POLICY_FLAG_VIRTUAL = 0x00000100,
 156     POLICY_FLAG_FUNCTION = 0x00000200,
 157
 158     POLICY_FLAG_RAW_MASK = 0x0000ffff,
 159
 160     /* These flags are set by the input dispatcher. */
 161
 162     // Indicates that the input event was injected.
 163     POLICY_FLAG_INJECTED = 0x01000000,
 164
 165     // Indicates that the input event is from a trusted source such as a directly attached
 166     // input device or an application with system-wide event injection permission.
 167     POLICY_FLAG_TRUSTED = 0x02000000,
 168
 169     // Indicates that the input event has passed through an input filter.
 170     POLICY_FLAG_FILTERED = 0x04000000,
 171
 172     // Disables automatic key repeating behavior.
 173     POLICY_FLAG_DISABLE_KEY_REPEAT = 0x08000000,
 174
 175     /* These flags are set by the input reader policy as it intercepts each event. */
 176
 177     // Indicates that the screen was off when the event was received and the event
 178     // should wake the device.
 179     POLICY_FLAG_WOKE_HERE = 0x10000000,
 180
 181     // Indicates that the screen was dim when the event was received and the event
 182     // should brighten the device.
 183     POLICY_FLAG_BRIGHT_HERE = 0x20000000,
 184
 185     // Indicates that the event should be dispatched to applications.
 186     // The input event should still be sent to the InputDispatcher so that it can see all
 187     // input events received include those that it will not deliver.
 188     POLICY_FLAG_PASS_TO_USER = 0x40000000,
 189 };
 190
 191 /*
 192  * Pointer coordinate data.
 193  */
 194 struct PointerCoords {
 195     enum { MAX_AXES = 14 }; // 14 so that sizeof(PointerCoords) == 64
 196
 197     // Bitfield of axes that are present in this structure.
 198     uint64_t bits;
 199
 200     // Values of axes that are stored in this structure packed in order by axis id
 201     // for each axis that is present in the structure according to 'bits'.
 202     float values[MAX_AXES];
 203
 204     inline void clear() {
 205         bits = 0;
 206     }
 207
 208     float getAxisValue(int32_t axis) const;
 209     status_t setAxisValue(int32_t axis, float value);
 210
 211     void scale(float scale);
 212     void applyOffset(float xOffset, float yOffset);
 213
 214     inline float getX() const {
 215         return getAxisValue(AMOTION_EVENT_AXIS_X);
 216     }
 217
 218     inline float getY() const {
 219         return getAxisValue(AMOTION_EVENT_AXIS_Y);
 220     }
 221
 222 #ifdef HAVE_ANDROID_OS
 223     status_t readFromParcel(Parcel* parcel);
 224     status_t writeToParcel(Parcel* parcel) const;
 225 #endif
 226
 227     bool operator==(const PointerCoords& other) const;
 228     inline bool operator!=(const PointerCoords& other) const {
 229         return !(*this == other);
 230     }
 231
 232     void copyFrom(const PointerCoords& other);
 233
 234 private:
 235     void tooManyAxes(int axis);
 236 };
 237
 238 /*
 239  * Pointer property data.
 240  */
 241 struct PointerProperties {
 242     // The id of the pointer.
 243     int32_t id;
 244
 245     // The pointer tool type.
 246     int32_t toolType;
 247
 248     inline void clear() {
 249         id = -1;
 250         toolType = 0;
 251     }
 252
 253     bool operator==(const PointerProperties& other) const;
 254     inline bool operator!=(const PointerProperties& other) const {
 255         return !(*this == other);
 256     }
 257
 258     void copyFrom(const PointerProperties& other);
 259 };
 260
 261 /*
 262  * Input events.
 263  */
 264 class InputEvent : public AInputEvent {
 265 public:
 266     virtual ~InputEvent() { }
 267
 268     virtual int32_t getType() const = 0;
 269
 270     inline int32_t getDeviceId() const { return mDeviceId; }
 271
 272     inline int32_t getSource() const { return mSource; }
 273
 274     inline void setSource(int32_t source) { mSource = source; }
 275
 276 protected:
 277     void initialize(int32_t deviceId, int32_t source);
 278     void initialize(const InputEvent& from);
 279
 280     int32_t mDeviceId;
 281     int32_t mSource;
 282 };
 283
 284 /*
 285  * Key events.
 286  */
 287 class KeyEvent : public InputEvent {
 288 public:
 289     virtual ~KeyEvent() { }
 290
 291     virtual int32_t getType() const { return AINPUT_EVENT_TYPE_KEY; }
 292
 293     inline int32_t getAction() const { return mAction; }
 294
 295     inline int32_t getFlags() const { return mFlags; }
 296
 297     inline void setFlags(int32_t flags) { mFlags = flags; }
 298
 299     inline int32_t getKeyCode() const { return mKeyCode; }
 300
 301     inline int32_t getScanCode() const { return mScanCode; }
 302
 303     inline int32_t getMetaState() const { return mMetaState; }
 304
 305     inline int32_t getRepeatCount() const { return mRepeatCount; }
 306
 307     inline nsecs_t getDownTime() const { return mDownTime; }
 308
 309     inline nsecs_t getEventTime() const { return mEventTime; }
 310
 311     // Return true if this event may have a default action implementation.
 312     static bool hasDefaultAction(int32_t keyCode);
 313     bool hasDefaultAction() const;
 314
 315     // Return true if this event represents a system key.
 316     static bool isSystemKey(int32_t keyCode);
 317     bool isSystemKey() const;
 318
 319     void initialize(
 320             int32_t deviceId,
 321             int32_t source,
 322             int32_t action,
 323             int32_t flags,
 324             int32_t keyCode,
 325             int32_t scanCode,
 326             int32_t metaState,
 327             int32_t repeatCount,
 328             nsecs_t downTime,
 329             nsecs_t eventTime);
 330     void initialize(const KeyEvent& from);
 331
 332 protected:
 333     int32_t mAction;
 334     int32_t mFlags;
 335     int32_t mKeyCode;
 336     int32_t mScanCode;
 337     int32_t mMetaState;
 338     int32_t mRepeatCount;
 339     nsecs_t mDownTime;
 340     nsecs_t mEventTime;
 341 };
 342
 343 /*
 344  * Motion events.
 345  */
 346 class MotionEvent : public InputEvent {
 347 public:
 348     virtual ~MotionEvent() { }
 349
 350     virtual int32_t getType() const { return AINPUT_EVENT_TYPE_MOTION; }
 351
 352     inline int32_t getAction() const { return mAction; }
 353
 354     inline int32_t getActionMasked() const { return mAction & AMOTION_EVENT_ACTION_MASK; }
 355
 356     inline int32_t getActionIndex() const {
 357         return (mAction & AMOTION_EVENT_ACTION_POINTER_INDEX_MASK)
 358                 >> AMOTION_EVENT_ACTION_POINTER_INDEX_SHIFT;
 359     }
 360
 361     inline void setAction(int32_t action) { mAction = action; }
 362
 363     inline int32_t getFlags() const { return mFlags; }
 364
 365     inline void setFlags(int32_t flags) { mFlags = flags; }
 366
 367     inline int32_t getEdgeFlags() const { return mEdgeFlags; }
 368
 369     inline void setEdgeFlags(int32_t edgeFlags) { mEdgeFlags = edgeFlags; }
 370
 371     inline int32_t getMetaState() const { return mMetaState; }
 372
 373     inline void setMetaState(int32_t metaState) { mMetaState = metaState; }
 374
 375     inline int32_t getButtonState() const { return mButtonState; }
 376
 377     inline float getXOffset() const { return mXOffset; }
 378
 379     inline float getYOffset() const { return mYOffset; }
 380
 381     inline float getXPrecision() const { return mXPrecision; }
 382
 383     inline float getYPrecision() const { return mYPrecision; }
 384
 385     inline nsecs_t getDownTime() const { return mDownTime; }
 386
 387     inline void setDownTime(nsecs_t downTime) { mDownTime = downTime; }
 388
 389     inline size_t getPointerCount() const { return mPointerProperties.size(); }
 390
 391     inline const PointerProperties* getPointerProperties(size_t pointerIndex) const {
 392         return &mPointerProperties[pointerIndex];
 393     }
 394
 395     inline int32_t getPointerId(size_t pointerIndex) const {
 396         return mPointerProperties[pointerIndex].id;
 397     }
 398
 399     inline int32_t getToolType(size_t pointerIndex) const {
 400         return mPointerProperties[pointerIndex].toolType;
 401     }
 402
 403     inline nsecs_t getEventTime() const { return mSampleEventTimes[getHistorySize()]; }
 404
 405     const PointerCoords* getRawPointerCoords(size_t pointerIndex) const;
 406
 407     float getRawAxisValue(int32_t axis, size_t pointerIndex) const;
 408
 409     inline float getRawX(size_t pointerIndex) const {
 410         return getRawAxisValue(AMOTION_EVENT_AXIS_X, pointerIndex);
 411     }
 412
 413     inline float getRawY(size_t pointerIndex) const {
 414         return getRawAxisValue(AMOTION_EVENT_AXIS_Y, pointerIndex);
 415     }
 416
 417     float getAxisValue(int32_t axis, size_t pointerIndex) const;
 418
 419     inline float getX(size_t pointerIndex) const {
 420         return getAxisValue(AMOTION_EVENT_AXIS_X, pointerIndex);
 421     }
 422
 423     inline float getY(size_t pointerIndex) const {
 424         return getAxisValue(AMOTION_EVENT_AXIS_Y, pointerIndex);
 425     }
 426
 427     inline float getPressure(size_t pointerIndex) const {
 428         return getAxisValue(AMOTION_EVENT_AXIS_PRESSURE, pointerIndex);
 429     }
 430
 431     inline float getSize(size_t pointerIndex) const {
 432         return getAxisValue(AMOTION_EVENT_AXIS_SIZE, pointerIndex);
 433     }
 434
 435     inline float getTouchMajor(size_t pointerIndex) const {
 436         return getAxisValue(AMOTION_EVENT_AXIS_TOUCH_MAJOR, pointerIndex);
 437     }
 438
 439     inline float getTouchMinor(size_t pointerIndex) const {
 440         return getAxisValue(AMOTION_EVENT_AXIS_TOUCH_MINOR, pointerIndex);
 441     }
 442
 443     inline float getToolMajor(size_t pointerIndex) const {
 444         return getAxisValue(AMOTION_EVENT_AXIS_TOOL_MAJOR, pointerIndex);
 445     }
 446
 447     inline float getToolMinor(size_t pointerIndex) const {
 448         return getAxisValue(AMOTION_EVENT_AXIS_TOOL_MINOR, pointerIndex);
 449     }
 450
 451     inline float getOrientation(size_t pointerIndex) const {
 452         return getAxisValue(AMOTION_EVENT_AXIS_ORIENTATION, pointerIndex);
 453     }
 454
 455     inline size_t getHistorySize() const { return mSampleEventTimes.size() - 1; }
 456
 457     inline nsecs_t getHistoricalEventTime(size_t historicalIndex) const {
 458         return mSampleEventTimes[historicalIndex];
 459     }
 460
 461     const PointerCoords* getHistoricalRawPointerCoords(
 462             size_t pointerIndex, size_t historicalIndex) const;
 463
 464     float getHistoricalRawAxisValue(int32_t axis, size_t pointerIndex,
 465             size_t historicalIndex) const;
 466
 467     inline float getHistoricalRawX(size_t pointerIndex, size_t historicalIndex) const {
 468         return getHistoricalRawAxisValue(
 469                 AMOTION_EVENT_AXIS_X, pointerIndex, historicalIndex);
 470     }
 471
 472     inline float getHistoricalRawY(size_t pointerIndex, size_t historicalIndex) const {
 473         return getHistoricalRawAxisValue(
 474                 AMOTION_EVENT_AXIS_Y, pointerIndex, historicalIndex);
 475     }
 476
 477     float getHistoricalAxisValue(int32_t axis, size_t pointerIndex, size_t historicalIndex) const;
 478
 479     inline float getHistoricalX(size_t pointerIndex, size_t historicalIndex) const {
 480         return getHistoricalAxisValue(
 481                 AMOTION_EVENT_AXIS_X, pointerIndex, historicalIndex);
 482     }
 483
 484     inline float getHistoricalY(size_t pointerIndex, size_t historicalIndex) const {
 485         return getHistoricalAxisValue(
 486                 AMOTION_EVENT_AXIS_Y, pointerIndex, historicalIndex);
 487     }
 488
 489     inline float getHistoricalPressure(size_t pointerIndex, size_t historicalIndex) const {
 490         return getHistoricalAxisValue(
 491                 AMOTION_EVENT_AXIS_PRESSURE, pointerIndex, historicalIndex);
 492     }
 493
 494     inline float getHistoricalSize(size_t pointerIndex, size_t historicalIndex) const {
 495         return getHistoricalAxisValue(
 496                 AMOTION_EVENT_AXIS_SIZE, pointerIndex, historicalIndex);
 497     }
 498
 499     inline float getHistoricalTouchMajor(size_t pointerIndex, size_t historicalIndex) const {
 500         return getHistoricalAxisValue(
 501                 AMOTION_EVENT_AXIS_TOUCH_MAJOR, pointerIndex, historicalIndex);
 502     }
 503
 504     inline float getHistoricalTouchMinor(size_t pointerIndex, size_t historicalIndex) const {
 505         return getHistoricalAxisValue(
 506                 AMOTION_EVENT_AXIS_TOUCH_MINOR, pointerIndex, historicalIndex);
 507     }
 508
 509     inline float getHistoricalToolMajor(size_t pointerIndex, size_t historicalIndex) const {
 510         return getHistoricalAxisValue(
 511                 AMOTION_EVENT_AXIS_TOOL_MAJOR, pointerIndex, historicalIndex);
 512     }
 513
 514     inline float getHistoricalToolMinor(size_t pointerIndex, size_t historicalIndex) const {
 515         return getHistoricalAxisValue(
 516                 AMOTION_EVENT_AXIS_TOOL_MINOR, pointerIndex, historicalIndex);
 517     }
 518
 519     inline float getHistoricalOrientation(size_t pointerIndex, size_t historicalIndex) const {
 520         return getHistoricalAxisValue(
 521                 AMOTION_EVENT_AXIS_ORIENTATION, pointerIndex, historicalIndex);
 522     }
 523
 524     ssize_t findPointerIndex(int32_t pointerId) const;
 525
 526     void initialize(
 527             int32_t deviceId,
 528             int32_t source,
 529             int32_t action,
 530             int32_t flags,
 531             int32_t edgeFlags,
 532             int32_t metaState,
 533             int32_t buttonState,
 534             float xOffset,
 535             float yOffset,
 536             float xPrecision,
 537             float yPrecision,
 538             nsecs_t downTime,
 539             nsecs_t eventTime,
 540             size_t pointerCount,
 541             const PointerProperties* pointerProperties,
 542             const PointerCoords* pointerCoords);
 543
 544     void copyFrom(const MotionEvent* other, bool keepHistory);
 545
 546     void addSample(
 547             nsecs_t eventTime,
 548             const PointerCoords* pointerCoords);
 549
 550     void offsetLocation(float xOffset, float yOffset);
 551
 552     void scale(float scaleFactor);
 553
 554     // Apply 3x3 perspective matrix transformation.
 555     // Matrix is in row-major form and compatible with SkMatrix.
 556     void transform(const float matrix[9]);
 557
 558 #ifdef HAVE_ANDROID_OS
 559     status_t readFromParcel(Parcel* parcel);
 560     status_t writeToParcel(Parcel* parcel) const;
 561 #endif
 562
 563     static bool isTouchEvent(int32_t source, int32_t action);
 564     inline bool isTouchEvent() const {
 565         return isTouchEvent(mSource, mAction);
 566     }
 567
 568     // Low-level accessors.
 569     inline const PointerProperties* getPointerProperties() const {
 570         return mPointerProperties.array();
 571     }
 572     inline const nsecs_t* getSampleEventTimes() const { return mSampleEventTimes.array(); }
 573     inline const PointerCoords* getSamplePointerCoords() const {
 574             return mSamplePointerCoords.array();
 575     }
 576
 577 protected:
 578     int32_t mAction;
 579     int32_t mFlags;
 580     int32_t mEdgeFlags;
 581     int32_t mMetaState;
 582     int32_t mButtonState;
 583     float mXOffset;
 584     float mYOffset;
 585     float mXPrecision;
 586     float mYPrecision;
 587     nsecs_t mDownTime;
 588     Vector<PointerProperties> mPointerProperties;
 589     Vector<nsecs_t> mSampleEventTimes;
 590     Vector<PointerCoords> mSamplePointerCoords;
 591 };
 592
 593 /*
 594  * Input event factory.
 595  */
 596 class InputEventFactoryInterface {
 597 protected:
 598     virtual ~InputEventFactoryInterface() { }
 599
 600 public:
 601     InputEventFactoryInterface() { }
 602
 603     virtual KeyEvent* createKeyEvent() = 0;
 604     virtual MotionEvent* createMotionEvent() = 0;
 605 };
 606
 607 /*
 608  * A simple input event factory implementation that uses a single preallocated instance
 609  * of each type of input event that are reused for each request.
 610  */
 611 class PreallocatedInputEventFactory : public InputEventFactoryInterface {
 612 public:
 613     PreallocatedInputEventFactory() { }
 614     virtual ~PreallocatedInputEventFactory() { }
 615
 616     virtual KeyEvent* createKeyEvent() { return & mKeyEvent; }
 617     virtual MotionEvent* createMotionEvent() { return & mMotionEvent; }
 618
 619 private:
 620     KeyEvent mKeyEvent;
 621     MotionEvent mMotionEvent;
 622 };
 623
 624 /*
 625  * An input event factory implementation that maintains a pool of input events.
 626  */
 627 class PooledInputEventFactory : public InputEventFactoryInterface {
 628 public:
 629     PooledInputEventFactory(size_t maxPoolSize = 20);
 630     virtual ~PooledInputEventFactory();
 631
 632     virtual KeyEvent* createKeyEvent();
 633     virtual MotionEvent* createMotionEvent();
 634
 635     void recycle(InputEvent* event);
 636
 637 private:
 638     const size_t mMaxPoolSize;
 639
 640     Vector<KeyEvent*> mKeyEventPool;
 641     Vector<MotionEvent*> mMotionEventPool;
 642 };
 643
 644 } // namespace android
 645
 646 #endif // _LIBINPUT_INPUT_H