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