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