core/java/android/view/KeyEvent.java

   1 /*
   2  * Copyright (C) 2006 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 package android.view;
  18
  19 import android.os.Parcel;
  20 import android.os.Parcelable;
  21 import android.text.method.MetaKeyKeyListener;
  22 import android.util.Log;
  23 import android.util.SparseIntArray;
  24 import android.view.KeyCharacterMap;
  25 import android.view.KeyCharacterMap.KeyData;
  26
  27 /**
  28  * Object used to report key and button events.
  29  * <p>
  30  * Each key press is described by a sequence of key events.  A key press
  31  * starts with a key event with {@link #ACTION_DOWN}.  If the key is held
  32  * sufficiently long that it repeats, then the initial down is followed
  33  * additional key events with {@link #ACTION_DOWN} and a non-zero value for
  34  * {@link #getRepeatCount()}.  The last key event is a {@link #ACTION_UP}
  35  * for the key up.  If the key press is canceled, the key up event will have the
  36  * {@link #FLAG_CANCELED} flag set.
  37  * </p><p>
  38  * Key events are generally accompanied by a key code ({@link #getKeyCode()}),
  39  * scan code ({@link #getScanCode()}) and meta state ({@link #getMetaState()}).
  40  * Key code constants are defined in this class.  Scan code constants are raw
  41  * device-specific codes obtained from the OS and so are not generally meaningful
  42  * to applications unless interpreted using the {@link KeyCharacterMap}.
  43  * Meta states describe the pressed state of key modifiers
  44  * such as {@link #META_SHIFT_ON} or {@link #META_ALT_ON}.
  45  * </p><p>
  46  * Key codes typically correspond one-to-one with individual keys on an input device.
  47  * Many keys and key combinations serve quite different functions on different
  48  * input devices so care must be taken when interpreting them.  Always use the
  49  * {@link KeyCharacterMap} associated with the input device when mapping keys
  50  * to characters.  Be aware that there may be multiple key input devices active
  51  * at the same time and each will have its own key character map.
  52  * </p><p>
  53  * As soft input methods can use multiple and inventive ways of inputting text,
  54  * there is no guarantee that any key press on a soft keyboard will generate a key
  55  * event: this is left to the IME's discretion, and in fact sending such events is
  56  * discouraged.  You should never rely on receiving KeyEvents for any key on a soft
  57  * input method.  In particular, the default software keyboard will never send any
  58  * key event to any application targetting Jelly Bean or later, and will only send
  59  * events for some presses of the delete and return keys to applications targetting
  60  * Ice Cream Sandwich or earlier.  Be aware that other software input methods may
  61  * never send key events regardless of the version.  Consider using editor actions
  62  * like {@link android.view.inputmethod.EditorInfo#IME_ACTION_DONE} if you need
  63  * specific interaction with the software keyboard, as it gives more visibility to
  64  * the user as to how your application will react to key presses.
  65  * </p><p>
  66  * When interacting with an IME, the framework may deliver key events
  67  * with the special action {@link #ACTION_MULTIPLE} that either specifies
  68  * that single repeated key code or a sequence of characters to insert.
  69  * </p><p>
  70  * In general, the framework cannot guarantee that the key events it delivers
  71  * to a view always constitute complete key sequences since some events may be dropped
  72  * or modified by containing views before they are delivered.  The view implementation
  73  * should be prepared to handle {@link #FLAG_CANCELED} and should tolerate anomalous
  74  * situations such as receiving a new {@link #ACTION_DOWN} without first having
  75  * received an {@link #ACTION_UP} for the prior key press.
  76  * </p><p>
  77  * Refer to {@link InputDevice} for more information about how different kinds of
  78  * input devices and sources represent keys and buttons.
  79  * </p>
  80  */
  81 public class KeyEvent extends InputEvent implements Parcelable {
  82     /** Key code constant: Unknown key code. */
  83     public static final int KEYCODE_UNKNOWN         = 0;
  84     /** Key code constant: Soft Left key.
  85      * Usually situated below the display on phones and used as a multi-function
  86      * feature key for selecting a software defined function shown on the bottom left
  87      * of the display. */
  88     public static final int KEYCODE_SOFT_LEFT       = 1;
  89     /** Key code constant: Soft Right key.
  90      * Usually situated below the display on phones and used as a multi-function
  91      * feature key for selecting a software defined function shown on the bottom right
  92      * of the display. */
  93     public static final int KEYCODE_SOFT_RIGHT      = 2;
  94     /** Key code constant: Home key.
  95      * This key is handled by the framework and is never delivered to applications. */
  96     public static final int KEYCODE_HOME            = 3;
  97     /** Key code constant: Back key. */
  98     public static final int KEYCODE_BACK            = 4;
  99     /** Key code constant: Call key. */
 100     public static final int KEYCODE_CALL            = 5;
 101     /** Key code constant: End Call key. */
 102     public static final int KEYCODE_ENDCALL         = 6;
 103     /** Key code constant: '0' key. */
 104     public static final int KEYCODE_0               = 7;
 105     /** Key code constant: '1' key. */
 106     public static final int KEYCODE_1               = 8;
 107     /** Key code constant: '2' key. */
 108     public static final int KEYCODE_2               = 9;
 109     /** Key code constant: '3' key. */
 110     public static final int KEYCODE_3               = 10;
 111     /** Key code constant: '4' key. */
 112     public static final int KEYCODE_4               = 11;
 113     /** Key code constant: '5' key. */
 114     public static final int KEYCODE_5               = 12;
 115     /** Key code constant: '6' key. */
 116     public static final int KEYCODE_6               = 13;
 117     /** Key code constant: '7' key. */
 118     public static final int KEYCODE_7               = 14;
 119     /** Key code constant: '8' key. */
 120     public static final int KEYCODE_8               = 15;
 121     /** Key code constant: '9' key. */
 122     public static final int KEYCODE_9               = 16;
 123     /** Key code constant: '*' key. */
 124     public static final int KEYCODE_STAR            = 17;
 125     /** Key code constant: '#' key. */
 126     public static final int KEYCODE_POUND           = 18;
 127     /** Key code constant: Directional Pad Up key.
 128      * May also be synthesized from trackball motions. */
 129     public static final int KEYCODE_DPAD_UP         = 19;
 130     /** Key code constant: Directional Pad Down key.
 131      * May also be synthesized from trackball motions. */
 132     public static final int KEYCODE_DPAD_DOWN       = 20;
 133     /** Key code constant: Directional Pad Left key.
 134      * May also be synthesized from trackball motions. */
 135     public static final int KEYCODE_DPAD_LEFT       = 21;
 136     /** Key code constant: Directional Pad Right key.
 137      * May also be synthesized from trackball motions. */
 138     public static final int KEYCODE_DPAD_RIGHT      = 22;
 139     /** Key code constant: Directional Pad Center key.
 140      * May also be synthesized from trackball motions. */
 141     public static final int KEYCODE_DPAD_CENTER     = 23;
 142     /** Key code constant: Volume Up key.
 143      * Adjusts the speaker volume up. */
 144     public static final int KEYCODE_VOLUME_UP       = 24;
 145     /** Key code constant: Volume Down key.
 146      * Adjusts the speaker volume down. */
 147     public static final int KEYCODE_VOLUME_DOWN     = 25;
 148     /** Key code constant: Power key. */
 149     public static final int KEYCODE_POWER           = 26;
 150     /** Key code constant: Camera key.
 151      * Used to launch a camera application or take pictures. */
 152     public static final int KEYCODE_CAMERA          = 27;
 153     /** Key code constant: Clear key. */
 154     public static final int KEYCODE_CLEAR           = 28;
 155     /** Key code constant: 'A' key. */
 156     public static final int KEYCODE_A               = 29;
 157     /** Key code constant: 'B' key. */
 158     public static final int KEYCODE_B               = 30;
 159     /** Key code constant: 'C' key. */
 160     public static final int KEYCODE_C               = 31;
 161     /** Key code constant: 'D' key. */
 162     public static final int KEYCODE_D               = 32;
 163     /** Key code constant: 'E' key. */
 164     public static final int KEYCODE_E               = 33;
 165     /** Key code constant: 'F' key. */
 166     public static final int KEYCODE_F               = 34;
 167     /** Key code constant: 'G' key. */
 168     public static final int KEYCODE_G               = 35;
 169     /** Key code constant: 'H' key. */
 170     public static final int KEYCODE_H               = 36;
 171     /** Key code constant: 'I' key. */
 172     public static final int KEYCODE_I               = 37;
 173     /** Key code constant: 'J' key. */
 174     public static final int KEYCODE_J               = 38;
 175     /** Key code constant: 'K' key. */
 176     public static final int KEYCODE_K               = 39;
 177     /** Key code constant: 'L' key. */
 178     public static final int KEYCODE_L               = 40;
 179     /** Key code constant: 'M' key. */
 180     public static final int KEYCODE_M               = 41;
 181     /** Key code constant: 'N' key. */
 182     public static final int KEYCODE_N               = 42;
 183     /** Key code constant: 'O' key. */
 184     public static final int KEYCODE_O               = 43;
 185     /** Key code constant: 'P' key. */
 186     public static final int KEYCODE_P               = 44;
 187     /** Key code constant: 'Q' key. */
 188     public static final int KEYCODE_Q               = 45;
 189     /** Key code constant: 'R' key. */
 190     public static final int KEYCODE_R               = 46;
 191     /** Key code constant: 'S' key. */
 192     public static final int KEYCODE_S               = 47;
 193     /** Key code constant: 'T' key. */
 194     public static final int KEYCODE_T               = 48;
 195     /** Key code constant: 'U' key. */
 196     public static final int KEYCODE_U               = 49;
 197     /** Key code constant: 'V' key. */
 198     public static final int KEYCODE_V               = 50;
 199     /** Key code constant: 'W' key. */
 200     public static final int KEYCODE_W               = 51;
 201     /** Key code constant: 'X' key. */
 202     public static final int KEYCODE_X               = 52;
 203     /** Key code constant: 'Y' key. */
 204     public static final int KEYCODE_Y               = 53;
 205     /** Key code constant: 'Z' key. */
 206     public static final int KEYCODE_Z               = 54;
 207     /** Key code constant: ',' key. */
 208     public static final int KEYCODE_COMMA           = 55;
 209     /** Key code constant: '.' key. */
 210     public static final int KEYCODE_PERIOD          = 56;
 211     /** Key code constant: Left Alt modifier key. */
 212     public static final int KEYCODE_ALT_LEFT        = 57;
 213     /** Key code constant: Right Alt modifier key. */
 214     public static final int KEYCODE_ALT_RIGHT       = 58;
 215     /** Key code constant: Left Shift modifier key. */
 216     public static final int KEYCODE_SHIFT_LEFT      = 59;
 217     /** Key code constant: Right Shift modifier key. */
 218     public static final int KEYCODE_SHIFT_RIGHT     = 60;
 219     /** Key code constant: Tab key. */
 220     public static final int KEYCODE_TAB             = 61;
 221     /** Key code constant: Space key. */
 222     public static final int KEYCODE_SPACE           = 62;
 223     /** Key code constant: Symbol modifier key.
 224      * Used to enter alternate symbols. */
 225     public static final int KEYCODE_SYM             = 63;
 226     /** Key code constant: Explorer special function key.
 227      * Used to launch a browser application. */
 228     public static final int KEYCODE_EXPLORER        = 64;
 229     /** Key code constant: Envelope special function key.
 230      * Used to launch a mail application. */
 231     public static final int KEYCODE_ENVELOPE        = 65;
 232     /** Key code constant: Enter key. */
 233     public static final int KEYCODE_ENTER           = 66;
 234     /** Key code constant: Backspace key.
 235      * Deletes characters before the insertion point, unlike {@link #KEYCODE_FORWARD_DEL}. */
 236     public static final int KEYCODE_DEL             = 67;
 237     /** Key code constant: '`' (backtick) key. */
 238     public static final int KEYCODE_GRAVE           = 68;
 239     /** Key code constant: '-'. */
 240     public static final int KEYCODE_MINUS           = 69;
 241     /** Key code constant: '=' key. */
 242     public static final int KEYCODE_EQUALS          = 70;
 243     /** Key code constant: '[' key. */
 244     public static final int KEYCODE_LEFT_BRACKET    = 71;
 245     /** Key code constant: ']' key. */
 246     public static final int KEYCODE_RIGHT_BRACKET   = 72;
 247     /** Key code constant: '\' key. */
 248     public static final int KEYCODE_BACKSLASH       = 73;
 249     /** Key code constant: ';' key. */
 250     public static final int KEYCODE_SEMICOLON       = 74;
 251     /** Key code constant: ''' (apostrophe) key. */
 252     public static final int KEYCODE_APOSTROPHE      = 75;
 253     /** Key code constant: '/' key. */
 254     public static final int KEYCODE_SLASH           = 76;
 255     /** Key code constant: '@' key. */
 256     public static final int KEYCODE_AT              = 77;
 257     /** Key code constant: Number modifier key.
 258      * Used to enter numeric symbols.
 259      * This key is not Num Lock; it is more like {@link #KEYCODE_ALT_LEFT} and is
 260      * interpreted as an ALT key by {@link android.text.method.MetaKeyKeyListener}. */
 261     public static final int KEYCODE_NUM             = 78;
 262     /** Key code constant: Headset Hook key.
 263      * Used to hang up calls and stop media. */
 264     public static final int KEYCODE_HEADSETHOOK     = 79;
 265     /** Key code constant: Camera Focus key.
 266      * Used to focus the camera. */
 267     public static final int KEYCODE_FOCUS           = 80;   // *Camera* focus
 268     /** Key code constant: '+' key. */
 269     public static final int KEYCODE_PLUS            = 81;
 270     /** Key code constant: Menu key. */
 271     public static final int KEYCODE_MENU            = 82;
 272     /** Key code constant: Notification key. */
 273     public static final int KEYCODE_NOTIFICATION    = 83;
 274     /** Key code constant: Search key. */
 275     public static final int KEYCODE_SEARCH          = 84;
 276     /** Key code constant: Play/Pause media key. */
 277     public static final int KEYCODE_MEDIA_PLAY_PAUSE= 85;
 278     /** Key code constant: Stop media key. */
 279     public static final int KEYCODE_MEDIA_STOP      = 86;
 280     /** Key code constant: Play Next media key. */
 281     public static final int KEYCODE_MEDIA_NEXT      = 87;
 282     /** Key code constant: Play Previous media key. */
 283     public static final int KEYCODE_MEDIA_PREVIOUS  = 88;
 284     /** Key code constant: Rewind media key. */
 285     public static final int KEYCODE_MEDIA_REWIND    = 89;
 286     /** Key code constant: Fast Forward media key. */
 287     public static final int KEYCODE_MEDIA_FAST_FORWARD = 90;
 288     /** Key code constant: Mute key.
 289      * Mutes the microphone, unlike {@link #KEYCODE_VOLUME_MUTE}. */
 290     public static final int KEYCODE_MUTE            = 91;
 291     /** Key code constant: Page Up key. */
 292     public static final int KEYCODE_PAGE_UP         = 92;
 293     /** Key code constant: Page Down key. */
 294     public static final int KEYCODE_PAGE_DOWN       = 93;
 295     /** Key code constant: Picture Symbols modifier key.
 296      * Used to switch symbol sets (Emoji, Kao-moji). */
 297     public static final int KEYCODE_PICTSYMBOLS     = 94;   // switch symbol-sets (Emoji,Kao-moji)
 298     /** Key code constant: Switch Charset modifier key.
 299      * Used to switch character sets (Kanji, Katakana). */
 300     public static final int KEYCODE_SWITCH_CHARSET  = 95;   // switch char-sets (Kanji,Katakana)
 301     /** Key code constant: A Button key.
 302      * On a game controller, the A button should be either the button labeled A
 303      * or the first button on the bottom row of controller buttons. */
 304     public static final int KEYCODE_BUTTON_A        = 96;
 305     /** Key code constant: B Button key.
 306      * On a game controller, the B button should be either the button labeled B
 307      * or the second button on the bottom row of controller buttons. */
 308     public static final int KEYCODE_BUTTON_B        = 97;
 309     /** Key code constant: C Button key.
 310      * On a game controller, the C button should be either the button labeled C
 311      * or the third button on the bottom row of controller buttons. */
 312     public static final int KEYCODE_BUTTON_C        = 98;
 313     /** Key code constant: X Button key.
 314      * On a game controller, the X button should be either the button labeled X
 315      * or the first button on the upper row of controller buttons. */
 316     public static final int KEYCODE_BUTTON_X        = 99;
 317     /** Key code constant: Y Button key.
 318      * On a game controller, the Y button should be either the button labeled Y
 319      * or the second button on the upper row of controller buttons. */
 320     public static final int KEYCODE_BUTTON_Y        = 100;
 321     /** Key code constant: Z Button key.
 322      * On a game controller, the Z button should be either the button labeled Z
 323      * or the third button on the upper row of controller buttons. */
 324     public static final int KEYCODE_BUTTON_Z        = 101;
 325     /** Key code constant: L1 Button key.
 326      * On a game controller, the L1 button should be either the button labeled L1 (or L)
 327      * or the top left trigger button. */
 328     public static final int KEYCODE_BUTTON_L1       = 102;
 329     /** Key code constant: R1 Button key.
 330      * On a game controller, the R1 button should be either the button labeled R1 (or R)
 331      * or the top right trigger button. */
 332     public static final int KEYCODE_BUTTON_R1       = 103;
 333     /** Key code constant: L2 Button key.
 334      * On a game controller, the L2 button should be either the button labeled L2
 335      * or the bottom left trigger button. */
 336     public static final int KEYCODE_BUTTON_L2       = 104;
 337     /** Key code constant: R2 Button key.
 338      * On a game controller, the R2 button should be either the button labeled R2
 339      * or the bottom right trigger button. */
 340     public static final int KEYCODE_BUTTON_R2       = 105;
 341     /** Key code constant: Left Thumb Button key.
 342      * On a game controller, the left thumb button indicates that the left (or only)
 343      * joystick is pressed. */
 344     public static final int KEYCODE_BUTTON_THUMBL   = 106;
 345     /** Key code constant: Right Thumb Button key.
 346      * On a game controller, the right thumb button indicates that the right
 347      * joystick is pressed. */
 348     public static final int KEYCODE_BUTTON_THUMBR   = 107;
 349     /** Key code constant: Start Button key.
 350      * On a game controller, the button labeled Start. */
 351     public static final int KEYCODE_BUTTON_START    = 108;
 352     /** Key code constant: Select Button key.
 353      * On a game controller, the button labeled Select. */
 354     public static final int KEYCODE_BUTTON_SELECT   = 109;
 355     /** Key code constant: Mode Button key.
 356      * On a game controller, the button labeled Mode. */
 357     public static final int KEYCODE_BUTTON_MODE     = 110;
 358     /** Key code constant: Escape key. */
 359     public static final int KEYCODE_ESCAPE          = 111;
 360     /** Key code constant: Forward Delete key.
 361      * Deletes characters ahead of the insertion point, unlike {@link #KEYCODE_DEL}. */
 362     public static final int KEYCODE_FORWARD_DEL     = 112;
 363     /** Key code constant: Left Control modifier key. */
 364     public static final int KEYCODE_CTRL_LEFT       = 113;
 365     /** Key code constant: Right Control modifier key. */
 366     public static final int KEYCODE_CTRL_RIGHT      = 114;
 367     /** Key code constant: Caps Lock key. */
 368     public static final int KEYCODE_CAPS_LOCK       = 115;
 369     /** Key code constant: Scroll Lock key. */
 370     public static final int KEYCODE_SCROLL_LOCK     = 116;
 371     /** Key code constant: Left Meta modifier key. */
 372     public static final int KEYCODE_META_LEFT       = 117;
 373     /** Key code constant: Right Meta modifier key. */
 374     public static final int KEYCODE_META_RIGHT      = 118;
 375     /** Key code constant: Function modifier key. */
 376     public static final int KEYCODE_FUNCTION        = 119;
 377     /** Key code constant: System Request / Print Screen key. */
 378     public static final int KEYCODE_SYSRQ           = 120;
 379     /** Key code constant: Break / Pause key. */
 380     public static final int KEYCODE_BREAK           = 121;
 381     /** Key code constant: Home Movement key.
 382      * Used for scrolling or moving the cursor around to the start of a line
 383      * or to the top of a list. */
 384     public static final int KEYCODE_MOVE_HOME       = 122;
 385     /** Key code constant: End Movement key.
 386      * Used for scrolling or moving the cursor around to the end of a line
 387      * or to the bottom of a list. */
 388     public static final int KEYCODE_MOVE_END        = 123;
 389     /** Key code constant: Insert key.
 390      * Toggles insert / overwrite edit mode. */
 391     public static final int KEYCODE_INSERT          = 124;
 392     /** Key code constant: Forward key.
 393      * Navigates forward in the history stack.  Complement of {@link #KEYCODE_BACK}. */
 394     public static final int KEYCODE_FORWARD         = 125;
 395     /** Key code constant: Play media key. */
 396     public static final int KEYCODE_MEDIA_PLAY      = 126;
 397     /** Key code constant: Pause media key. */
 398     public static final int KEYCODE_MEDIA_PAUSE     = 127;
 399     /** Key code constant: Close media key.
 400      * May be used to close a CD tray, for example. */
 401     public static final int KEYCODE_MEDIA_CLOSE     = 128;
 402     /** Key code constant: Eject media key.
 403      * May be used to eject a CD tray, for example. */
 404     public static final int KEYCODE_MEDIA_EJECT     = 129;
 405     /** Key code constant: Record media key. */
 406     public static final int KEYCODE_MEDIA_RECORD    = 130;
 407     /** Key code constant: F1 key. */
 408     public static final int KEYCODE_F1              = 131;
 409     /** Key code constant: F2 key. */
 410     public static final int KEYCODE_F2              = 132;
 411     /** Key code constant: F3 key. */
 412     public static final int KEYCODE_F3              = 133;
 413     /** Key code constant: F4 key. */
 414     public static final int KEYCODE_F4              = 134;
 415     /** Key code constant: F5 key. */
 416     public static final int KEYCODE_F5              = 135;
 417     /** Key code constant: F6 key. */
 418     public static final int KEYCODE_F6              = 136;
 419     /** Key code constant: F7 key. */
 420     public static final int KEYCODE_F7              = 137;
 421     /** Key code constant: F8 key. */
 422     public static final int KEYCODE_F8              = 138;
 423     /** Key code constant: F9 key. */
 424     public static final int KEYCODE_F9              = 139;
 425     /** Key code constant: F10 key. */
 426     public static final int KEYCODE_F10             = 140;
 427     /** Key code constant: F11 key. */
 428     public static final int KEYCODE_F11             = 141;
 429     /** Key code constant: F12 key. */
 430     public static final int KEYCODE_F12             = 142;
 431     /** Key code constant: Num Lock key.
 432      * This is the Num Lock key; it is different from {@link #KEYCODE_NUM}.
 433      * This key alters the behavior of other keys on the numeric keypad. */
 434     public static final int KEYCODE_NUM_LOCK        = 143;
 435     /** Key code constant: Numeric keypad '0' key. */
 436     public static final int KEYCODE_NUMPAD_0        = 144;
 437     /** Key code constant: Numeric keypad '1' key. */
 438     public static final int KEYCODE_NUMPAD_1        = 145;
 439     /** Key code constant: Numeric keypad '2' key. */
 440     public static final int KEYCODE_NUMPAD_2        = 146;
 441     /** Key code constant: Numeric keypad '3' key. */
 442     public static final int KEYCODE_NUMPAD_3        = 147;
 443     /** Key code constant: Numeric keypad '4' key. */
 444     public static final int KEYCODE_NUMPAD_4        = 148;
 445     /** Key code constant: Numeric keypad '5' key. */
 446     public static final int KEYCODE_NUMPAD_5        = 149;
 447     /** Key code constant: Numeric keypad '6' key. */
 448     public static final int KEYCODE_NUMPAD_6        = 150;
 449     /** Key code constant: Numeric keypad '7' key. */
 450     public static final int KEYCODE_NUMPAD_7        = 151;
 451     /** Key code constant: Numeric keypad '8' key. */
 452     public static final int KEYCODE_NUMPAD_8        = 152;
 453     /** Key code constant: Numeric keypad '9' key. */
 454     public static final int KEYCODE_NUMPAD_9        = 153;
 455     /** Key code constant: Numeric keypad '/' key (for division). */
 456     public static final int KEYCODE_NUMPAD_DIVIDE   = 154;
 457     /** Key code constant: Numeric keypad '*' key (for multiplication). */
 458     public static final int KEYCODE_NUMPAD_MULTIPLY = 155;
 459     /** Key code constant: Numeric keypad '-' key (for subtraction). */
 460     public static final int KEYCODE_NUMPAD_SUBTRACT = 156;
 461     /** Key code constant: Numeric keypad '+' key (for addition). */
 462     public static final int KEYCODE_NUMPAD_ADD      = 157;
 463     /** Key code constant: Numeric keypad '.' key (for decimals or digit grouping). */
 464     public static final int KEYCODE_NUMPAD_DOT      = 158;
 465     /** Key code constant: Numeric keypad ',' key (for decimals or digit grouping). */
 466     public static final int KEYCODE_NUMPAD_COMMA    = 159;
 467     /** Key code constant: Numeric keypad Enter key. */
 468     public static final int KEYCODE_NUMPAD_ENTER    = 160;
 469     /** Key code constant: Numeric keypad '=' key. */
 470     public static final int KEYCODE_NUMPAD_EQUALS   = 161;
 471     /** Key code constant: Numeric keypad '(' key. */
 472     public static final int KEYCODE_NUMPAD_LEFT_PAREN = 162;
 473     /** Key code constant: Numeric keypad ')' key. */
 474     public static final int KEYCODE_NUMPAD_RIGHT_PAREN = 163;
 475     /** Key code constant: Volume Mute key.
 476      * Mutes the speaker, unlike {@link #KEYCODE_MUTE}.
 477      * This key should normally be implemented as a toggle such that the first press
 478      * mutes the speaker and the second press restores the original volume. */
 479     public static final int KEYCODE_VOLUME_MUTE     = 164;
 480     /** Key code constant: Info key.
 481      * Common on TV remotes to show additional information related to what is
 482      * currently being viewed. */
 483     public static final int KEYCODE_INFO            = 165;
 484     /** Key code constant: Channel up key.
 485      * On TV remotes, increments the television channel. */
 486     public static final int KEYCODE_CHANNEL_UP      = 166;
 487     /** Key code constant: Channel down key.
 488      * On TV remotes, decrements the television channel. */
 489     public static final int KEYCODE_CHANNEL_DOWN    = 167;
 490     /** Key code constant: Zoom in key. */
 491     public static final int KEYCODE_ZOOM_IN         = 168;
 492     /** Key code constant: Zoom out key. */
 493     public static final int KEYCODE_ZOOM_OUT        = 169;
 494     /** Key code constant: TV key.
 495      * On TV remotes, switches to viewing live TV. */
 496     public static final int KEYCODE_TV              = 170;
 497     /** Key code constant: Window key.
 498      * On TV remotes, toggles picture-in-picture mode or other windowing functions. */
 499     public static final int KEYCODE_WINDOW          = 171;
 500     /** Key code constant: Guide key.
 501      * On TV remotes, shows a programming guide. */
 502     public static final int KEYCODE_GUIDE           = 172;
 503     /** Key code constant: DVR key.
 504      * On some TV remotes, switches to a DVR mode for recorded shows. */
 505     public static final int KEYCODE_DVR             = 173;
 506     /** Key code constant: Bookmark key.
 507      * On some TV remotes, bookmarks content or web pages. */
 508     public static final int KEYCODE_BOOKMARK        = 174;
 509     /** Key code constant: Toggle captions key.
 510      * Switches the mode for closed-captioning text, for example during television shows. */
 511     public static final int KEYCODE_CAPTIONS        = 175;
 512     /** Key code constant: Settings key.
 513      * Starts the system settings activity. */
 514     public static final int KEYCODE_SETTINGS        = 176;
 515     /** Key code constant: TV power key.
 516      * On TV remotes, toggles the power on a television screen. */
 517     public static final int KEYCODE_TV_POWER        = 177;
 518     /** Key code constant: TV input key.
 519      * On TV remotes, switches the input on a television screen. */
 520     public static final int KEYCODE_TV_INPUT        = 178;
 521     /** Key code constant: Set-top-box power key.
 522      * On TV remotes, toggles the power on an external Set-top-box. */
 523     public static final int KEYCODE_STB_POWER       = 179;
 524     /** Key code constant: Set-top-box input key.
 525      * On TV remotes, switches the input mode on an external Set-top-box. */
 526     public static final int KEYCODE_STB_INPUT       = 180;
 527     /** Key code constant: A/V Receiver power key.
 528      * On TV remotes, toggles the power on an external A/V Receiver. */
 529     public static final int KEYCODE_AVR_POWER       = 181;
 530     /** Key code constant: A/V Receiver input key.
 531      * On TV remotes, switches the input mode on an external A/V Receiver. */
 532     public static final int KEYCODE_AVR_INPUT       = 182;
 533     /** Key code constant: Red "programmable" key.
 534      * On TV remotes, acts as a contextual/programmable key. */
 535     public static final int KEYCODE_PROG_RED        = 183;
 536     /** Key code constant: Green "programmable" key.
 537      * On TV remotes, actsas a contextual/programmable key. */
 538     public static final int KEYCODE_PROG_GREEN      = 184;
 539     /** Key code constant: Yellow "programmable" key.
 540      * On TV remotes, acts as a contextual/programmable key. */
 541     public static final int KEYCODE_PROG_YELLOW     = 185;
 542     /** Key code constant: Blue "programmable" key.
 543      * On TV remotes, acts as a contextual/programmable key. */
 544     public static final int KEYCODE_PROG_BLUE       = 186;
 545     /** Key code constant: App switch key.
 546      * Should bring up the application switcher dialog. */
 547     public static final int KEYCODE_APP_SWITCH      = 187;
 548     /** Key code constant: Generic Game Pad Button #1.*/
 549     public static final int KEYCODE_BUTTON_1        = 188;
 550     /** Key code constant: Generic Game Pad Button #2.*/
 551     public static final int KEYCODE_BUTTON_2        = 189;
 552     /** Key code constant: Generic Game Pad Button #3.*/
 553     public static final int KEYCODE_BUTTON_3        = 190;
 554     /** Key code constant: Generic Game Pad Button #4.*/
 555     public static final int KEYCODE_BUTTON_4        = 191;
 556     /** Key code constant: Generic Game Pad Button #5.*/
 557     public static final int KEYCODE_BUTTON_5        = 192;
 558     /** Key code constant: Generic Game Pad Button #6.*/
 559     public static final int KEYCODE_BUTTON_6        = 193;
 560     /** Key code constant: Generic Game Pad Button #7.*/
 561     public static final int KEYCODE_BUTTON_7        = 194;
 562     /** Key code constant: Generic Game Pad Button #8.*/
 563     public static final int KEYCODE_BUTTON_8        = 195;
 564     /** Key code constant: Generic Game Pad Button #9.*/
 565     public static final int KEYCODE_BUTTON_9        = 196;
 566     /** Key code constant: Generic Game Pad Button #10.*/
 567     public static final int KEYCODE_BUTTON_10       = 197;
 568     /** Key code constant: Generic Game Pad Button #11.*/
 569     public static final int KEYCODE_BUTTON_11       = 198;
 570     /** Key code constant: Generic Game Pad Button #12.*/
 571     public static final int KEYCODE_BUTTON_12       = 199;
 572     /** Key code constant: Generic Game Pad Button #13.*/
 573     public static final int KEYCODE_BUTTON_13       = 200;
 574     /** Key code constant: Generic Game Pad Button #14.*/
 575     public static final int KEYCODE_BUTTON_14       = 201;
 576     /** Key code constant: Generic Game Pad Button #15.*/
 577     public static final int KEYCODE_BUTTON_15       = 202;
 578     /** Key code constant: Generic Game Pad Button #16.*/
 579     public static final int KEYCODE_BUTTON_16       = 203;
 580     /** Key code constant: Language Switch key.
 581      * Toggles the current input language such as switching between English and Japanese on
 582      * a QWERTY keyboard.  On some devices, the same function may be performed by
 583      * pressing Shift+Spacebar. */
 584     public static final int KEYCODE_LANGUAGE_SWITCH = 204;
 585     /** Key code constant: Manner Mode key.
 586      * Toggles silent or vibrate mode on and off to make the device behave more politely
 587      * in certain settings such as on a crowded train.  On some devices, the key may only
 588      * operate when long-pressed. */
 589     public static final int KEYCODE_MANNER_MODE     = 205;
 590     /** Key code constant: 3D Mode key.
 591      * Toggles the display between 2D and 3D mode. */
 592     public static final int KEYCODE_3D_MODE         = 206;
 593     /** Key code constant: Contacts special function key.
 594      * Used to launch an address book application. */
 595     public static final int KEYCODE_CONTACTS        = 207;
 596     /** Key code constant: Calendar special function key.
 597      * Used to launch a calendar application. */
 598     public static final int KEYCODE_CALENDAR        = 208;
 599     /** Key code constant: Music special function key.
 600      * Used to launch a music player application. */
 601     public static final int KEYCODE_MUSIC           = 209;
 602     /** Key code constant: Calculator special function key.
 603      * Used to launch a calculator application. */
 604     public static final int KEYCODE_CALCULATOR      = 210;
 605     /** Key code constant: Japanese full-width / half-width key. */
 606     public static final int KEYCODE_ZENKAKU_HANKAKU = 211;
 607     /** Key code constant: Japanese alphanumeric key. */
 608     public static final int KEYCODE_EISU            = 212;
 609     /** Key code constant: Japanese non-conversion key. */
 610     public static final int KEYCODE_MUHENKAN        = 213;
 611     /** Key code constant: Japanese conversion key. */
 612     public static final int KEYCODE_HENKAN          = 214;
 613     /** Key code constant: Japanese katakana / hiragana key. */
 614     public static final int KEYCODE_KATAKANA_HIRAGANA = 215;
 615     /** Key code constant: Japanese Yen key. */
 616     public static final int KEYCODE_YEN             = 216;
 617     /** Key code constant: Japanese Ro key. */
 618     public static final int KEYCODE_RO              = 217;
 619     /** Key code constant: Japanese kana key. */
 620     public static final int KEYCODE_KANA            = 218;
 621     /** Key code constant: Assist key.
 622      * Launches the global assist activity.  Not delivered to applications. */
 623     public static final int KEYCODE_ASSIST          = 219;
 624     /** Key code constant: Brightness Down key.
 625      * Adjusts the screen brightness down. */
 626     public static final int KEYCODE_BRIGHTNESS_DOWN = 220;
 627     /** Key code constant: Brightness Up key.
 628      * Adjusts the screen brightness up. */
 629     public static final int KEYCODE_BRIGHTNESS_UP   = 221;
 630     /** Key code constant: Audio Track key.
 631      * Switches the audio tracks. */
 632     public static final int KEYCODE_MEDIA_AUDIO_TRACK = 222;
 633     /** Key code constant: Sleep key.
 634      * Puts the device to sleep.  Behaves somewhat like {@link #KEYCODE_POWER} but it
 635      * has no effect if the device is already asleep. */
 636     public static final int KEYCODE_SLEEP           = 223;
 637     /** Key code constant: Wakeup key.
 638      * Wakes up the device.  Behaves somewhat like {@link #KEYCODE_POWER} but it
 639      * has no effect if the device is already awake. */
 640     public static final int KEYCODE_WAKEUP          = 224;
 641     /** Key code constant: Pairing key.
 642      * Initiates peripheral pairing mode. Useful for pairing remote control
 643      * devices or game controllers, especially if no other input mode is
 644      * available. */
 645     public static final int KEYCODE_PAIRING         = 225;
 646     /** Key code constant: Media Top Menu key.
 647      * Goes to the top of media menu. */
 648     public static final int KEYCODE_MEDIA_TOP_MENU  = 226;
 649     /** Key code constant: '11' key. */
 650     public static final int KEYCODE_11              = 227;
 651     /** Key code constant: '12' key. */
 652     public static final int KEYCODE_12              = 228;
 653     /** Key code constant: Last Channel key.
 654      * Goes to the last viewed channel. */
 655     public static final int KEYCODE_LAST_CHANNEL    = 229;
 656     /** Key code constant: TV data service key.
 657      * Displays data services like weather, sports. */
 658     public static final int KEYCODE_TV_DATA_SERVICE = 230;
 659     /** Key code constant: Voice Assist key.
 660      * Launches the global voice assist activity. Not delivered to applications. */
 661     public static final int KEYCODE_VOICE_ASSIST = 231;
 662     /** Key code constant: Radio key.
 663      * Toggles TV service / Radio service. */
 664     public static final int KEYCODE_TV_RADIO_SERVICE = 232;
 665     /** Key code constant: Teletext key.
 666      * Displays Teletext service. */
 667     public static final int KEYCODE_TV_TELETEXT = 233;
 668     /** Key code constant: Number entry key.
 669      * Initiates to enter multi-digit channel nubmber when each digit key is assigned
 670      * for selecting separate channel. Corresponds to Number Entry Mode (0x1D) of CEC
 671      * User Control Code. */
 672     public static final int KEYCODE_TV_NUMBER_ENTRY = 234;
 673     /** Key code constant: Analog Terrestrial key.
 674      * Switches to analog terrestrial broadcast service. */
 675     public static final int KEYCODE_TV_TERRESTRIAL_ANALOG = 235;
 676     /** Key code constant: Digital Terrestrial key.
 677      * Switches to digital terrestrial broadcast service. */
 678     public static final int KEYCODE_TV_TERRESTRIAL_DIGITAL = 236;
 679     /** Key code constant: Satellite key.
 680      * Switches to digital satellite broadcast service. */
 681     public static final int KEYCODE_TV_SATELLITE = 237;
 682     /** Key code constant: BS key.
 683      * Switches to BS digital satellite broadcasting service available in Japan. */
 684     public static final int KEYCODE_TV_SATELLITE_BS = 238;
 685     /** Key code constant: CS key.
 686      * Switches to CS digital satellite broadcasting service available in Japan. */
 687     public static final int KEYCODE_TV_SATELLITE_CS = 239;
 688     /** Key code constant: BS/CS key.
 689      * Toggles between BS and CS digital satellite services. */
 690     public static final int KEYCODE_TV_SATELLITE_SERVICE = 240;
 691     /** Key code constant: Toggle Network key.
 692      * Toggles selecting broacast services. */
 693     public static final int KEYCODE_TV_NETWORK = 241;
 694     /** Key code constant: Antenna/Cable key.
 695      * Toggles broadcast input source between antenna and cable. */
 696     public static final int KEYCODE_TV_ANTENNA_CABLE = 242;
 697     /** Key code constant: HDMI #1 key.
 698      * Switches to HDMI input #1. */
 699     public static final int KEYCODE_TV_INPUT_HDMI_1 = 243;
 700     /** Key code constant: HDMI #2 key.
 701      * Switches to HDMI input #2. */
 702     public static final int KEYCODE_TV_INPUT_HDMI_2 = 244;
 703     /** Key code constant: HDMI #3 key.
 704      * Switches to HDMI input #3. */
 705     public static final int KEYCODE_TV_INPUT_HDMI_3 = 245;
 706     /** Key code constant: HDMI #4 key.
 707      * Switches to HDMI input #4. */
 708     public static final int KEYCODE_TV_INPUT_HDMI_4 = 246;
 709     /** Key code constant: Composite #1 key.
 710      * Switches to composite video input #1. */
 711     public static final int KEYCODE_TV_INPUT_COMPOSITE_1 = 247;
 712     /** Key code constant: Composite #2 key.
 713      * Switches to composite video input #2. */
 714     public static final int KEYCODE_TV_INPUT_COMPOSITE_2 = 248;
 715     /** Key code constant: Component #1 key.
 716      * Switches to component video input #1. */
 717     public static final int KEYCODE_TV_INPUT_COMPONENT_1 = 249;
 718     /** Key code constant: Component #2 key.
 719      * Switches to component video input #2. */
 720     public static final int KEYCODE_TV_INPUT_COMPONENT_2 = 250;
 721     /** Key code constant: VGA #1 key.
 722      * Switches to VGA (analog RGB) input #1. */
 723     public static final int KEYCODE_TV_INPUT_VGA_1 = 251;
 724     /** Key code constant: Audio description key.
 725      * Toggles audio description off / on. */
 726     public static final int KEYCODE_TV_AUDIO_DESCRIPTION = 252;
 727     /** Key code constant: Audio description mixing volume up key.
 728      * Louden audio description volume as compared with normal audio volume. */
 729     public static final int KEYCODE_TV_AUDIO_DESCRIPTION_MIX_UP = 253;
 730     /** Key code constant: Audio description mixing volume down key.
 731      * Lessen audio description volume as compared with normal audio volume. */
 732     public static final int KEYCODE_TV_AUDIO_DESCRIPTION_MIX_DOWN = 254;
 733     /** Key code constant: Zoom mode key.
 734      * Changes Zoom mode (Normal, Full, Zoom, Wide-zoom, etc.) */
 735     public static final int KEYCODE_TV_ZOOM_MODE = 255;
 736     /** Key code constant: Contents menu key.
 737      * Goes to the title list. Corresponds to Contents Menu (0x0B) of CEC User Control
 738      * Code */
 739     public static final int KEYCODE_TV_CONTENTS_MENU = 256;
 740     /** Key code constant: Media context menu key.
 741      * Goes to the context menu of media contents. Corresponds to Media Context-sensitive
 742      * Menu (0x11) of CEC User Control Code. */
 743     public static final int KEYCODE_TV_MEDIA_CONTEXT_MENU = 257;
 744     /** Key code constant: Timer programming key.
 745      * Goes to the timer recording menu. Corresponds to Timer Programming (0x54) of
 746      * CEC User Control Code. */
 747     public static final int KEYCODE_TV_TIMER_PROGRAMMING = 258;
 748     /** Key code constant: Help key. */
 749     public static final int KEYCODE_HELP = 259;
 750     /** Key code constant: Navigate to previous key.
 751      * Goes backward by one item in an ordered collection of items. */
 752     public static final int KEYCODE_NAVIGATE_PREVIOUS = 260;
 753     /** Key code constant: Navigate to next key.
 754      * Advances to the next item in an ordered collection of items. */
 755     public static final int KEYCODE_NAVIGATE_NEXT   = 261;
 756     /** Key code constant: Navigate in key.
 757      * Activates the item that currently has focus or expands to the next level of a navigation
 758      * hierarchy. */
 759     public static final int KEYCODE_NAVIGATE_IN     = 262;
 760     /** Key code constant: Navigate out key.
 761      * Backs out one level of a navigation hierarchy or collapses the item that currently has
 762      * focus. */
 763     public static final int KEYCODE_NAVIGATE_OUT    = 263;
 764     /** Key code constant: Skip forward media key. */
 765     public static final int KEYCODE_MEDIA_SKIP_FORWARD = 272;
 766     /** Key code constant: Skip backward media key. */
 767     public static final int KEYCODE_MEDIA_SKIP_BACKWARD = 273;
 768     /** Key code constant: Step forward media key.
 769      * Steps media forward, one frame at a time. */
 770     public static final int KEYCODE_MEDIA_STEP_FORWARD = 274;
 771     /** Key code constant: Step backward media key.
 772      * Steps media backward, one frame at a time. */
 773     public static final int KEYCODE_MEDIA_STEP_BACKWARD = 275;
 774
 775     private static final int LAST_KEYCODE = KEYCODE_MEDIA_STEP_BACKWARD;
 776
 777     // NOTE: If you add a new keycode here you must also add it to:
 778     //  isSystem()
 779     //  isWakeKey()
 780     //  frameworks/native/include/android/keycodes.h
 781     //  frameworks/native/include/input/InputEventLabels.h
 782     //  frameworks/base/core/res/res/values/attrs.xml
 783     //  emulator?
 784     //  LAST_KEYCODE
 785     //
 786     //  Also Android currently does not reserve code ranges for vendor-
 787     //  specific key codes.  If you have new key codes to have, you
 788     //  MUST contribute a patch to the open source project to define
 789     //  those new codes.  This is intended to maintain a consistent
 790     //  set of key code definitions across all Android devices.
 791
 792     // Symbolic names of all metakeys in bit order from least significant to most significant.
 793     // Accordingly there are exactly 32 values in this table.
 794     private static final String[] META_SYMBOLIC_NAMES = new String[] {
 795         "META_SHIFT_ON",
 796         "META_ALT_ON",
 797         "META_SYM_ON",
 798         "META_FUNCTION_ON",
 799         "META_ALT_LEFT_ON",
 800         "META_ALT_RIGHT_ON",
 801         "META_SHIFT_LEFT_ON",
 802         "META_SHIFT_RIGHT_ON",
 803         "META_CAP_LOCKED",
 804         "META_ALT_LOCKED",
 805         "META_SYM_LOCKED",
 806         "0x00000800",
 807         "META_CTRL_ON",
 808         "META_CTRL_LEFT_ON",
 809         "META_CTRL_RIGHT_ON",
 810         "0x00008000",
 811         "META_META_ON",
 812         "META_META_LEFT_ON",
 813         "META_META_RIGHT_ON",
 814         "0x00080000",
 815         "META_CAPS_LOCK_ON",
 816         "META_NUM_LOCK_ON",
 817         "META_SCROLL_LOCK_ON",
 818         "0x00800000",
 819         "0x01000000",
 820         "0x02000000",
 821         "0x04000000",
 822         "0x08000000",
 823         "0x10000000",
 824         "0x20000000",
 825         "0x40000000",
 826         "0x80000000",
 827     };
 828
 829     private static final String LABEL_PREFIX = "KEYCODE_";
 830
 831     /**
 832      * @deprecated There are now more than MAX_KEYCODE keycodes.
 833      * Use {@link #getMaxKeyCode()} instead.
 834      */
 835     @Deprecated
 836     public static final int MAX_KEYCODE             = 84;
 837
 838     /**
 839      * {@link #getAction} value: the key has been pressed down.
 840      */
 841     public static final int ACTION_DOWN             = 0;
 842     /**
 843      * {@link #getAction} value: the key has been released.
 844      */
 845     public static final int ACTION_UP               = 1;
 846     /**
 847      * {@link #getAction} value: multiple duplicate key events have
 848      * occurred in a row, or a complex string is being delivered.  If the
 849      * key code is not {#link {@link #KEYCODE_UNKNOWN} then the
 850      * {#link {@link #getRepeatCount()} method returns the number of times
 851      * the given key code should be executed.
 852      * Otherwise, if the key code is {@link #KEYCODE_UNKNOWN}, then
 853      * this is a sequence of characters as returned by {@link #getCharacters}.
 854      */
 855     public static final int ACTION_MULTIPLE         = 2;
 856
 857     /**
 858      * SHIFT key locked in CAPS mode.
 859      * Reserved for use by {@link MetaKeyKeyListener} for a published constant in its API.
 860      * @hide
 861      */
 862     public static final int META_CAP_LOCKED = 0x100;
 863
 864     /**
 865      * ALT key locked.
 866      * Reserved for use by {@link MetaKeyKeyListener} for a published constant in its API.
 867      * @hide
 868      */
 869     public static final int META_ALT_LOCKED = 0x200;
 870
 871     /**
 872      * SYM key locked.
 873      * Reserved for use by {@link MetaKeyKeyListener} for a published constant in its API.
 874      * @hide
 875      */
 876     public static final int META_SYM_LOCKED = 0x400;
 877
 878     /**
 879      * Text is in selection mode.
 880      * Reserved for use by {@link MetaKeyKeyListener} for a private unpublished constant
 881      * in its API that is currently being retained for legacy reasons.
 882      * @hide
 883      */
 884     public static final int META_SELECTING = 0x800;
 885
 886     /**
 887      * <p>This mask is used to check whether one of the ALT meta keys is pressed.</p>
 888      *
 889      * @see #isAltPressed()
 890      * @see #getMetaState()
 891      * @see #KEYCODE_ALT_LEFT
 892      * @see #KEYCODE_ALT_RIGHT
 893      */
 894     public static final int META_ALT_ON = 0x02;
 895
 896     /**
 897      * <p>This mask is used to check whether the left ALT meta key is pressed.</p>
 898      *
 899      * @see #isAltPressed()
 900      * @see #getMetaState()
 901      * @see #KEYCODE_ALT_LEFT
 902      */
 903     public static final int META_ALT_LEFT_ON = 0x10;
 904
 905     /**
 906      * <p>This mask is used to check whether the right the ALT meta key is pressed.</p>
 907      *
 908      * @see #isAltPressed()
 909      * @see #getMetaState()
 910      * @see #KEYCODE_ALT_RIGHT
 911      */
 912     public static final int META_ALT_RIGHT_ON = 0x20;
 913
 914     /**
 915      * <p>This mask is used to check whether one of the SHIFT meta keys is pressed.</p>
 916      *
 917      * @see #isShiftPressed()
 918      * @see #getMetaState()
 919      * @see #KEYCODE_SHIFT_LEFT
 920      * @see #KEYCODE_SHIFT_RIGHT
 921      */
 922     public static final int META_SHIFT_ON = 0x1;
 923
 924     /**
 925      * <p>This mask is used to check whether the left SHIFT meta key is pressed.</p>
 926      *
 927      * @see #isShiftPressed()
 928      * @see #getMetaState()
 929      * @see #KEYCODE_SHIFT_LEFT
 930      */
 931     public static final int META_SHIFT_LEFT_ON = 0x40;
 932
 933     /**
 934      * <p>This mask is used to check whether the right SHIFT meta key is pressed.</p>
 935      *
 936      * @see #isShiftPressed()
 937      * @see #getMetaState()
 938      * @see #KEYCODE_SHIFT_RIGHT
 939      */
 940     public static final int META_SHIFT_RIGHT_ON = 0x80;
 941
 942     /**
 943      * <p>This mask is used to check whether the SYM meta key is pressed.</p>
 944      *
 945      * @see #isSymPressed()
 946      * @see #getMetaState()
 947      */
 948     public static final int META_SYM_ON = 0x4;
 949
 950     /**
 951      * <p>This mask is used to check whether the FUNCTION meta key is pressed.</p>
 952      *
 953      * @see #isFunctionPressed()
 954      * @see #getMetaState()
 955      */
 956     public static final int META_FUNCTION_ON = 0x8;
 957
 958     /**
 959      * <p>This mask is used to check whether one of the CTRL meta keys is pressed.</p>
 960      *
 961      * @see #isCtrlPressed()
 962      * @see #getMetaState()
 963      * @see #KEYCODE_CTRL_LEFT
 964      * @see #KEYCODE_CTRL_RIGHT
 965      */
 966     public static final int META_CTRL_ON = 0x1000;
 967
 968     /**
 969      * <p>This mask is used to check whether the left CTRL meta key is pressed.</p>
 970      *
 971      * @see #isCtrlPressed()
 972      * @see #getMetaState()
 973      * @see #KEYCODE_CTRL_LEFT
 974      */
 975     public static final int META_CTRL_LEFT_ON = 0x2000;
 976
 977     /**
 978      * <p>This mask is used to check whether the right CTRL meta key is pressed.</p>
 979      *
 980      * @see #isCtrlPressed()
 981      * @see #getMetaState()
 982      * @see #KEYCODE_CTRL_RIGHT
 983      */
 984     public static final int META_CTRL_RIGHT_ON = 0x4000;
 985
 986     /**
 987      * <p>This mask is used to check whether one of the META meta keys is pressed.</p>
 988      *
 989      * @see #isMetaPressed()
 990      * @see #getMetaState()
 991      * @see #KEYCODE_META_LEFT
 992      * @see #KEYCODE_META_RIGHT
 993      */
 994     public static final int META_META_ON = 0x10000;
 995
 996     /**
 997      * <p>This mask is used to check whether the left META meta key is pressed.</p>
 998      *
 999      * @see #isMetaPressed()
1000      * @see #getMetaState()
1001      * @see #KEYCODE_META_LEFT
1002      */
1003     public static final int META_META_LEFT_ON = 0x20000;
1004
1005     /**
1006      * <p>This mask is used to check whether the right META meta key is pressed.</p>
1007      *
1008      * @see #isMetaPressed()
1009      * @see #getMetaState()
1010      * @see #KEYCODE_META_RIGHT
1011      */
1012     public static final int META_META_RIGHT_ON = 0x40000;
1013
1014     /**
1015      * <p>This mask is used to check whether the CAPS LOCK meta key is on.</p>
1016      *
1017      * @see #isCapsLockOn()
1018      * @see #getMetaState()
1019      * @see #KEYCODE_CAPS_LOCK
1020      */
1021     public static final int META_CAPS_LOCK_ON = 0x100000;
1022
1023     /**
1024      * <p>This mask is used to check whether the NUM LOCK meta key is on.</p>
1025      *
1026      * @see #isNumLockOn()
1027      * @see #getMetaState()
1028      * @see #KEYCODE_NUM_LOCK
1029      */
1030     public static final int META_NUM_LOCK_ON = 0x200000;
1031
1032     /**
1033      * <p>This mask is used to check whether the SCROLL LOCK meta key is on.</p>
1034      *
1035      * @see #isScrollLockOn()
1036      * @see #getMetaState()
1037      * @see #KEYCODE_SCROLL_LOCK
1038      */
1039     public static final int META_SCROLL_LOCK_ON = 0x400000;
1040
1041     /**
1042      * This mask is a combination of {@link #META_SHIFT_ON}, {@link #META_SHIFT_LEFT_ON}
1043      * and {@link #META_SHIFT_RIGHT_ON}.
1044      */
1045     public static final int META_SHIFT_MASK = META_SHIFT_ON
1046             | META_SHIFT_LEFT_ON | META_SHIFT_RIGHT_ON;
1047
1048     /**
1049      * This mask is a combination of {@link #META_ALT_ON}, {@link #META_ALT_LEFT_ON}
1050      * and {@link #META_ALT_RIGHT_ON}.
1051      */
1052     public static final int META_ALT_MASK = META_ALT_ON
1053             | META_ALT_LEFT_ON | META_ALT_RIGHT_ON;
1054
1055     /**
1056      * This mask is a combination of {@link #META_CTRL_ON}, {@link #META_CTRL_LEFT_ON}
1057      * and {@link #META_CTRL_RIGHT_ON}.
1058      */
1059     public static final int META_CTRL_MASK = META_CTRL_ON
1060             | META_CTRL_LEFT_ON | META_CTRL_RIGHT_ON;
1061
1062     /**
1063      * This mask is a combination of {@link #META_META_ON}, {@link #META_META_LEFT_ON}
1064      * and {@link #META_META_RIGHT_ON}.
1065      */
1066     public static final int META_META_MASK = META_META_ON
1067             | META_META_LEFT_ON | META_META_RIGHT_ON;
1068
1069     /**
1070      * This mask is set if the device woke because of this key event.
1071      *
1072      * @deprecated This flag will never be set by the system since the system
1073      * consumes all wake keys itself.
1074      */
1075     @Deprecated
1076     public static final int FLAG_WOKE_HERE = 0x1;
1077
1078     /**
1079      * This mask is set if the key event was generated by a software keyboard.
1080      */
1081     public static final int FLAG_SOFT_KEYBOARD = 0x2;
1082
1083     /**
1084      * This mask is set if we don't want the key event to cause us to leave
1085      * touch mode.
1086      */
1087     public static final int FLAG_KEEP_TOUCH_MODE = 0x4;
1088
1089     /**
1090      * This mask is set if an event was known to come from a trusted part
1091      * of the system.  That is, the event is known to come from the user,
1092      * and could not have been spoofed by a third party component.
1093      */
1094     public static final int FLAG_FROM_SYSTEM = 0x8;
1095
1096     /**
1097      * This mask is used for compatibility, to identify enter keys that are
1098      * coming from an IME whose enter key has been auto-labelled "next" or
1099      * "done".  This allows TextView to dispatch these as normal enter keys
1100      * for old applications, but still do the appropriate action when
1101      * receiving them.
1102      */
1103     public static final int FLAG_EDITOR_ACTION = 0x10;
1104
1105     /**
1106      * When associated with up key events, this indicates that the key press
1107      * has been canceled.  Typically this is used with virtual touch screen
1108      * keys, where the user can slide from the virtual key area on to the
1109      * display: in that case, the application will receive a canceled up
1110      * event and should not perform the action normally associated with the
1111      * key.  Note that for this to work, the application can not perform an
1112      * action for a key until it receives an up or the long press timeout has
1113      * expired.
1114      */
1115     public static final int FLAG_CANCELED = 0x20;
1116
1117     /**
1118      * This key event was generated by a virtual (on-screen) hard key area.
1119      * Typically this is an area of the touchscreen, outside of the regular
1120      * display, dedicated to "hardware" buttons.
1121      */
1122     public static final int FLAG_VIRTUAL_HARD_KEY = 0x40;
1123
1124     /**
1125      * This flag is set for the first key repeat that occurs after the
1126      * long press timeout.
1127      */
1128     public static final int FLAG_LONG_PRESS = 0x80;
1129
1130     /**
1131      * Set when a key event has {@link #FLAG_CANCELED} set because a long
1132      * press action was executed while it was down.
1133      */
1134     public static final int FLAG_CANCELED_LONG_PRESS = 0x100;
1135
1136     /**
1137      * Set for {@link #ACTION_UP} when this event's key code is still being
1138      * tracked from its initial down.  That is, somebody requested that tracking
1139      * started on the key down and a long press has not caused
1140      * the tracking to be canceled.
1141      */
1142     public static final int FLAG_TRACKING = 0x200;
1143
1144     /**
1145      * Set when a key event has been synthesized to implement default behavior
1146      * for an event that the application did not handle.
1147      * Fallback key events are generated by unhandled trackball motions
1148      * (to emulate a directional keypad) and by certain unhandled key presses
1149      * that are declared in the key map (such as special function numeric keypad
1150      * keys when numlock is off).
1151      */
1152     public static final int FLAG_FALLBACK = 0x400;
1153
1154     /**
1155      * Signifies that the key is being predispatched.
1156      * @hide
1157      */
1158     public static final int FLAG_PREDISPATCH = 0x20000000;
1159
1160     /**
1161      * Private control to determine when an app is tracking a key sequence.
1162      * @hide
1163      */
1164     public static final int FLAG_START_TRACKING = 0x40000000;
1165
1166     /**
1167      * Private flag that indicates when the system has detected that this key event
1168      * may be inconsistent with respect to the sequence of previously delivered key events,
1169      * such as when a key up event is sent but the key was not down.
1170      *
1171      * @hide
1172      * @see #isTainted
1173      * @see #setTainted
1174      */
1175     public static final int FLAG_TAINTED = 0x80000000;
1176
1177     /**
1178      * Returns the maximum keycode.
1179      */
1180     public static int getMaxKeyCode() {
1181         return LAST_KEYCODE;
1182     }
1183
1184     /**
1185      * Get the character that is produced by putting accent on the character
1186      * c.
1187      * For example, getDeadChar('`', 'e') returns &egrave;.
1188      */
1189     public static int getDeadChar(int accent, int c) {
1190         return KeyCharacterMap.getDeadChar(accent, c);
1191     }
1192
1193     static final boolean DEBUG = false;
1194     static final String TAG = "KeyEvent";
1195
1196     private static final int MAX_RECYCLED = 10;
1197     private static final Object gRecyclerLock = new Object();
1198     private static int gRecyclerUsed;
1199     private static KeyEvent gRecyclerTop;
1200
1201     private KeyEvent mNext;
1202
1203     private int mDeviceId;
1204     private int mSource;
1205     private int mMetaState;
1206     private int mAction;
1207     private int mKeyCode;
1208     private int mScanCode;
1209     private int mRepeatCount;
1210     private int mFlags;
1211     private long mDownTime;
1212     private long mEventTime;
1213     private String mCharacters;
1214
1215     public interface Callback {
1216         /**
1217          * Called when a key down event has occurred.  If you return true,
1218          * you can first call {@link KeyEvent#startTracking()
1219          * KeyEvent.startTracking()} to have the framework track the event
1220          * through its {@link #onKeyUp(int, KeyEvent)} and also call your
1221          * {@link #onKeyLongPress(int, KeyEvent)} if it occurs.
1222          *
1223          * @param keyCode The value in event.getKeyCode().
1224          * @param event Description of the key event.
1225          *
1226          * @return If you handled the event, return true.  If you want to allow
1227          *         the event to be handled by the next receiver, return false.
1228          */
1229         boolean onKeyDown(int keyCode, KeyEvent event);
1230
1231         /**
1232          * Called when a long press has occurred.  If you return true,
1233          * the final key up will have {@link KeyEvent#FLAG_CANCELED} and
1234          * {@link KeyEvent#FLAG_CANCELED_LONG_PRESS} set.  Note that in
1235          * order to receive this callback, someone in the event change
1236          * <em>must</em> return true from {@link #onKeyDown} <em>and</em>
1237          * call {@link KeyEvent#startTracking()} on the event.
1238          *
1239          * @param keyCode The value in event.getKeyCode().
1240          * @param event Description of the key event.
1241          *
1242          * @return If you handled the event, return true.  If you want to allow
1243          *         the event to be handled by the next receiver, return false.
1244          */
1245         boolean onKeyLongPress(int keyCode, KeyEvent event);
1246
1247         /**
1248          * Called when a key up event has occurred.
1249          *
1250          * @param keyCode The value in event.getKeyCode().
1251          * @param event Description of the key event.
1252          *
1253          * @return If you handled the event, return true.  If you want to allow
1254          *         the event to be handled by the next receiver, return false.
1255          */
1256         boolean onKeyUp(int keyCode, KeyEvent event);
1257
1258         /**
1259          * Called when multiple down/up pairs of the same key have occurred
1260          * in a row.
1261          *
1262          * @param keyCode The value in event.getKeyCode().
1263          * @param count Number of pairs as returned by event.getRepeatCount().
1264          * @param event Description of the key event.
1265          *
1266          * @return If you handled the event, return true.  If you want to allow
1267          *         the event to be handled by the next receiver, return false.
1268          */
1269         boolean onKeyMultiple(int keyCode, int count, KeyEvent event);
1270     }
1271
1272     private static native String nativeKeyCodeToString(int keyCode);
1273     private static native int nativeKeyCodeFromString(String keyCode);
1274
1275     private KeyEvent() {
1276     }
1277
1278     /**
1279      * Create a new key event.
1280      *
1281      * @param action Action code: either {@link #ACTION_DOWN},
1282      * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}.
1283      * @param code The key code.
1284      */
1285     public KeyEvent(int action, int code) {
1286         mAction = action;
1287         mKeyCode = code;
1288         mRepeatCount = 0;
1289         mDeviceId = KeyCharacterMap.VIRTUAL_KEYBOARD;
1290     }
1291
1292     /**
1293      * Create a new key event.
1294      *
1295      * @param downTime The time (in {@link android.os.SystemClock#uptimeMillis})
1296      * at which this key code originally went down.
1297      * @param eventTime The time (in {@link android.os.SystemClock#uptimeMillis})
1298      * at which this event happened.
1299      * @param action Action code: either {@link #ACTION_DOWN},
1300      * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}.
1301      * @param code The key code.
1302      * @param repeat A repeat count for down events (> 0 if this is after the
1303      * initial down) or event count for multiple events.
1304      */
1305     public KeyEvent(long downTime, long eventTime, int action,
1306                     int code, int repeat) {
1307         mDownTime = downTime;
1308         mEventTime = eventTime;
1309         mAction = action;
1310         mKeyCode = code;
1311         mRepeatCount = repeat;
1312         mDeviceId = KeyCharacterMap.VIRTUAL_KEYBOARD;
1313     }
1314
1315     /**
1316      * Create a new key event.
1317      *
1318      * @param downTime The time (in {@link android.os.SystemClock#uptimeMillis})
1319      * at which this key code originally went down.
1320      * @param eventTime The time (in {@link android.os.SystemClock#uptimeMillis})
1321      * at which this event happened.
1322      * @param action Action code: either {@link #ACTION_DOWN},
1323      * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}.
1324      * @param code The key code.
1325      * @param repeat A repeat count for down events (> 0 if this is after the
1326      * initial down) or event count for multiple events.
1327      * @param metaState Flags indicating which meta keys are currently pressed.
1328      */
1329     public KeyEvent(long downTime, long eventTime, int action,
1330                     int code, int repeat, int metaState) {
1331         mDownTime = downTime;
1332         mEventTime = eventTime;
1333         mAction = action;
1334         mKeyCode = code;
1335         mRepeatCount = repeat;
1336         mMetaState = metaState;
1337         mDeviceId = KeyCharacterMap.VIRTUAL_KEYBOARD;
1338     }
1339
1340     /**
1341      * Create a new key event.
1342      *
1343      * @param downTime The time (in {@link android.os.SystemClock#uptimeMillis})
1344      * at which this key code originally went down.
1345      * @param eventTime The time (in {@link android.os.SystemClock#uptimeMillis})
1346      * at which this event happened.
1347      * @param action Action code: either {@link #ACTION_DOWN},
1348      * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}.
1349      * @param code The key code.
1350      * @param repeat A repeat count for down events (> 0 if this is after the
1351      * initial down) or event count for multiple events.
1352      * @param metaState Flags indicating which meta keys are currently pressed.
1353      * @param deviceId The device ID that generated the key event.
1354      * @param scancode Raw device scan code of the event.
1355      */
1356     public KeyEvent(long downTime, long eventTime, int action,
1357                     int code, int repeat, int metaState,
1358                     int deviceId, int scancode) {
1359         mDownTime = downTime;
1360         mEventTime = eventTime;
1361         mAction = action;
1362         mKeyCode = code;
1363         mRepeatCount = repeat;
1364         mMetaState = metaState;
1365         mDeviceId = deviceId;
1366         mScanCode = scancode;
1367     }
1368
1369     /**
1370      * Create a new key event.
1371      *
1372      * @param downTime The time (in {@link android.os.SystemClock#uptimeMillis})
1373      * at which this key code originally went down.
1374      * @param eventTime The time (in {@link android.os.SystemClock#uptimeMillis})
1375      * at which this event happened.
1376      * @param action Action code: either {@link #ACTION_DOWN},
1377      * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}.
1378      * @param code The key code.
1379      * @param repeat A repeat count for down events (> 0 if this is after the
1380      * initial down) or event count for multiple events.
1381      * @param metaState Flags indicating which meta keys are currently pressed.
1382      * @param deviceId The device ID that generated the key event.
1383      * @param scancode Raw device scan code of the event.
1384      * @param flags The flags for this key event
1385      */
1386     public KeyEvent(long downTime, long eventTime, int action,
1387                     int code, int repeat, int metaState,
1388                     int deviceId, int scancode, int flags) {
1389         mDownTime = downTime;
1390         mEventTime = eventTime;
1391         mAction = action;
1392         mKeyCode = code;
1393         mRepeatCount = repeat;
1394         mMetaState = metaState;
1395         mDeviceId = deviceId;
1396         mScanCode = scancode;
1397         mFlags = flags;
1398     }
1399
1400     /**
1401      * Create a new key event.
1402      *
1403      * @param downTime The time (in {@link android.os.SystemClock#uptimeMillis})
1404      * at which this key code originally went down.
1405      * @param eventTime The time (in {@link android.os.SystemClock#uptimeMillis})
1406      * at which this event happened.
1407      * @param action Action code: either {@link #ACTION_DOWN},
1408      * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}.
1409      * @param code The key code.
1410      * @param repeat A repeat count for down events (> 0 if this is after the
1411      * initial down) or event count for multiple events.
1412      * @param metaState Flags indicating which meta keys are currently pressed.
1413      * @param deviceId The device ID that generated the key event.
1414      * @param scancode Raw device scan code of the event.
1415      * @param flags The flags for this key event
1416      * @param source The input source such as {@link InputDevice#SOURCE_KEYBOARD}.
1417      */
1418     public KeyEvent(long downTime, long eventTime, int action,
1419                     int code, int repeat, int metaState,
1420                     int deviceId, int scancode, int flags, int source) {
1421         mDownTime = downTime;
1422         mEventTime = eventTime;
1423         mAction = action;
1424         mKeyCode = code;
1425         mRepeatCount = repeat;
1426         mMetaState = metaState;
1427         mDeviceId = deviceId;
1428         mScanCode = scancode;
1429         mFlags = flags;
1430         mSource = source;
1431     }
1432
1433     /**
1434      * Create a new key event for a string of characters.  The key code,
1435      * action, repeat count and source will automatically be set to
1436      * {@link #KEYCODE_UNKNOWN}, {@link #ACTION_MULTIPLE}, 0, and
1437      * {@link InputDevice#SOURCE_KEYBOARD} for you.
1438      *
1439      * @param time The time (in {@link android.os.SystemClock#uptimeMillis})
1440      * at which this event occured.
1441      * @param characters The string of characters.
1442      * @param deviceId The device ID that generated the key event.
1443      * @param flags The flags for this key event
1444      */
1445     public KeyEvent(long time, String characters, int deviceId, int flags) {
1446         mDownTime = time;
1447         mEventTime = time;
1448         mCharacters = characters;
1449         mAction = ACTION_MULTIPLE;
1450         mKeyCode = KEYCODE_UNKNOWN;
1451         mRepeatCount = 0;
1452         mDeviceId = deviceId;
1453         mFlags = flags;
1454         mSource = InputDevice.SOURCE_KEYBOARD;
1455     }
1456
1457     /**
1458      * Make an exact copy of an existing key event.
1459      */
1460     public KeyEvent(KeyEvent origEvent) {
1461         mDownTime = origEvent.mDownTime;
1462         mEventTime = origEvent.mEventTime;
1463         mAction = origEvent.mAction;
1464         mKeyCode = origEvent.mKeyCode;
1465         mRepeatCount = origEvent.mRepeatCount;
1466         mMetaState = origEvent.mMetaState;
1467         mDeviceId = origEvent.mDeviceId;
1468         mSource = origEvent.mSource;
1469         mScanCode = origEvent.mScanCode;
1470         mFlags = origEvent.mFlags;
1471         mCharacters = origEvent.mCharacters;
1472     }
1473
1474     /**
1475      * Copy an existing key event, modifying its time and repeat count.
1476      *
1477      * @deprecated Use {@link #changeTimeRepeat(KeyEvent, long, int)}
1478      * instead.
1479      *
1480      * @param origEvent The existing event to be copied.
1481      * @param eventTime The new event time
1482      * (in {@link android.os.SystemClock#uptimeMillis}) of the event.
1483      * @param newRepeat The new repeat count of the event.
1484      */
1485     @Deprecated
1486     public KeyEvent(KeyEvent origEvent, long eventTime, int newRepeat) {
1487         mDownTime = origEvent.mDownTime;
1488         mEventTime = eventTime;
1489         mAction = origEvent.mAction;
1490         mKeyCode = origEvent.mKeyCode;
1491         mRepeatCount = newRepeat;
1492         mMetaState = origEvent.mMetaState;
1493         mDeviceId = origEvent.mDeviceId;
1494         mSource = origEvent.mSource;
1495         mScanCode = origEvent.mScanCode;
1496         mFlags = origEvent.mFlags;
1497         mCharacters = origEvent.mCharacters;
1498     }
1499
1500     private static KeyEvent obtain() {
1501         final KeyEvent ev;
1502         synchronized (gRecyclerLock) {
1503             ev = gRecyclerTop;
1504             if (ev == null) {
1505                 return new KeyEvent();
1506             }
1507             gRecyclerTop = ev.mNext;
1508             gRecyclerUsed -= 1;
1509         }
1510         ev.mNext = null;
1511         ev.prepareForReuse();
1512         return ev;
1513     }
1514
1515     /**
1516      * Obtains a (potentially recycled) key event.
1517      *
1518      * @hide
1519      */
1520     public static KeyEvent obtain(long downTime, long eventTime, int action,
1521                     int code, int repeat, int metaState,
1522                     int deviceId, int scancode, int flags, int source, String characters) {
1523         KeyEvent ev = obtain();
1524         ev.mDownTime = downTime;
1525         ev.mEventTime = eventTime;
1526         ev.mAction = action;
1527         ev.mKeyCode = code;
1528         ev.mRepeatCount = repeat;
1529         ev.mMetaState = metaState;
1530         ev.mDeviceId = deviceId;
1531         ev.mScanCode = scancode;
1532         ev.mFlags = flags;
1533         ev.mSource = source;
1534         ev.mCharacters = characters;
1535         return ev;
1536     }
1537
1538     /**
1539      * Obtains a (potentially recycled) copy of another key event.
1540      *
1541      * @hide
1542      */
1543     public static KeyEvent obtain(KeyEvent other) {
1544         KeyEvent ev = obtain();
1545         ev.mDownTime = other.mDownTime;
1546         ev.mEventTime = other.mEventTime;
1547         ev.mAction = other.mAction;
1548         ev.mKeyCode = other.mKeyCode;
1549         ev.mRepeatCount = other.mRepeatCount;
1550         ev.mMetaState = other.mMetaState;
1551         ev.mDeviceId = other.mDeviceId;
1552         ev.mScanCode = other.mScanCode;
1553         ev.mFlags = other.mFlags;
1554         ev.mSource = other.mSource;
1555         ev.mCharacters = other.mCharacters;
1556         return ev;
1557     }
1558
1559     /** @hide */
1560     @Override
1561     public KeyEvent copy() {
1562         return obtain(this);
1563     }
1564
1565     /**
1566      * Recycles a key event.
1567      * Key events should only be recycled if they are owned by the system since user
1568      * code expects them to be essentially immutable, "tracking" notwithstanding.
1569      *
1570      * @hide
1571      */
1572     @Override
1573     public final void recycle() {
1574         super.recycle();
1575         mCharacters = null;
1576
1577         synchronized (gRecyclerLock) {
1578             if (gRecyclerUsed < MAX_RECYCLED) {
1579                 gRecyclerUsed++;
1580                 mNext = gRecyclerTop;
1581                 gRecyclerTop = this;
1582             }
1583         }
1584     }
1585
1586     /** @hide */
1587     @Override
1588     public final void recycleIfNeededAfterDispatch() {
1589         // Do nothing.
1590     }
1591
1592     /**
1593      * Create a new key event that is the same as the given one, but whose
1594      * event time and repeat count are replaced with the given value.
1595      *
1596      * @param event The existing event to be copied.  This is not modified.
1597      * @param eventTime The new event time
1598      * (in {@link android.os.SystemClock#uptimeMillis}) of the event.
1599      * @param newRepeat The new repeat count of the event.
1600      */
1601     public static KeyEvent changeTimeRepeat(KeyEvent event, long eventTime,
1602             int newRepeat) {
1603         return new KeyEvent(event, eventTime, newRepeat);
1604     }
1605
1606     /**
1607      * Create a new key event that is the same as the given one, but whose
1608      * event time and repeat count are replaced with the given value.
1609      *
1610      * @param event The existing event to be copied.  This is not modified.
1611      * @param eventTime The new event time
1612      * (in {@link android.os.SystemClock#uptimeMillis}) of the event.
1613      * @param newRepeat The new repeat count of the event.
1614      * @param newFlags New flags for the event, replacing the entire value
1615      * in the original event.
1616      */
1617     public static KeyEvent changeTimeRepeat(KeyEvent event, long eventTime,
1618             int newRepeat, int newFlags) {
1619         KeyEvent ret = new KeyEvent(event);
1620         ret.mEventTime = eventTime;
1621         ret.mRepeatCount = newRepeat;
1622         ret.mFlags = newFlags;
1623         return ret;
1624     }
1625
1626     /**
1627      * Copy an existing key event, modifying its action.
1628      *
1629      * @param origEvent The existing event to be copied.
1630      * @param action The new action code of the event.
1631      */
1632     private KeyEvent(KeyEvent origEvent, int action) {
1633         mDownTime = origEvent.mDownTime;
1634         mEventTime = origEvent.mEventTime;
1635         mAction = action;
1636         mKeyCode = origEvent.mKeyCode;
1637         mRepeatCount = origEvent.mRepeatCount;
1638         mMetaState = origEvent.mMetaState;
1639         mDeviceId = origEvent.mDeviceId;
1640         mSource = origEvent.mSource;
1641         mScanCode = origEvent.mScanCode;
1642         mFlags = origEvent.mFlags;
1643         // Don't copy mCharacters, since one way or the other we'll lose it
1644         // when changing the action.
1645     }
1646
1647     /**
1648      * Create a new key event that is the same as the given one, but whose
1649      * action is replaced with the given value.
1650      *
1651      * @param event The existing event to be copied.  This is not modified.
1652      * @param action The new action code of the event.
1653      */
1654     public static KeyEvent changeAction(KeyEvent event, int action) {
1655         return new KeyEvent(event, action);
1656     }
1657
1658     /**
1659      * Create a new key event that is the same as the given one, but whose
1660      * flags are replaced with the given value.
1661      *
1662      * @param event The existing event to be copied.  This is not modified.
1663      * @param flags The new flags constant.
1664      */
1665     public static KeyEvent changeFlags(KeyEvent event, int flags) {
1666         event = new KeyEvent(event);
1667         event.mFlags = flags;
1668         return event;
1669     }
1670
1671     /** @hide */
1672     @Override
1673     public final boolean isTainted() {
1674         return (mFlags & FLAG_TAINTED) != 0;
1675     }
1676
1677     /** @hide */
1678     @Override
1679     public final void setTainted(boolean tainted) {
1680         mFlags = tainted ? mFlags | FLAG_TAINTED : mFlags & ~FLAG_TAINTED;
1681     }
1682
1683     /**
1684      * Don't use in new code, instead explicitly check
1685      * {@link #getAction()}.
1686      *
1687      * @return If the action is ACTION_DOWN, returns true; else false.
1688      *
1689      * @deprecated
1690      * @hide
1691      */
1692     @Deprecated public final boolean isDown() {
1693         return mAction == ACTION_DOWN;
1694     }
1695
1696     /** Is this a system key?  System keys can not be used for menu shortcuts.
1697      */
1698     public final boolean isSystem() {
1699         return isSystemKey(mKeyCode);
1700     }
1701
1702     /** @hide */
1703     public final boolean isWakeKey() {
1704         return isWakeKey(mKeyCode);
1705     }
1706
1707     /**
1708      * Returns true if the specified keycode is a gamepad button.
1709      * @return True if the keycode is a gamepad button, such as {@link #KEYCODE_BUTTON_A}.
1710      */
1711     public static final boolean isGamepadButton(int keyCode) {
1712         switch (keyCode) {
1713             case KeyEvent.KEYCODE_BUTTON_A:
1714             case KeyEvent.KEYCODE_BUTTON_B:
1715             case KeyEvent.KEYCODE_BUTTON_C:
1716             case KeyEvent.KEYCODE_BUTTON_X:
1717             case KeyEvent.KEYCODE_BUTTON_Y:
1718             case KeyEvent.KEYCODE_BUTTON_Z:
1719             case KeyEvent.KEYCODE_BUTTON_L1:
1720             case KeyEvent.KEYCODE_BUTTON_R1:
1721             case KeyEvent.KEYCODE_BUTTON_L2:
1722             case KeyEvent.KEYCODE_BUTTON_R2:
1723             case KeyEvent.KEYCODE_BUTTON_THUMBL:
1724             case KeyEvent.KEYCODE_BUTTON_THUMBR:
1725             case KeyEvent.KEYCODE_BUTTON_START:
1726             case KeyEvent.KEYCODE_BUTTON_SELECT:
1727             case KeyEvent.KEYCODE_BUTTON_MODE:
1728             case KeyEvent.KEYCODE_BUTTON_1:
1729             case KeyEvent.KEYCODE_BUTTON_2:
1730             case KeyEvent.KEYCODE_BUTTON_3:
1731             case KeyEvent.KEYCODE_BUTTON_4:
1732             case KeyEvent.KEYCODE_BUTTON_5:
1733             case KeyEvent.KEYCODE_BUTTON_6:
1734             case KeyEvent.KEYCODE_BUTTON_7:
1735             case KeyEvent.KEYCODE_BUTTON_8:
1736             case KeyEvent.KEYCODE_BUTTON_9:
1737             case KeyEvent.KEYCODE_BUTTON_10:
1738             case KeyEvent.KEYCODE_BUTTON_11:
1739             case KeyEvent.KEYCODE_BUTTON_12:
1740             case KeyEvent.KEYCODE_BUTTON_13:
1741             case KeyEvent.KEYCODE_BUTTON_14:
1742             case KeyEvent.KEYCODE_BUTTON_15:
1743             case KeyEvent.KEYCODE_BUTTON_16:
1744                 return true;
1745             default:
1746                 return false;
1747         }
1748     }
1749
1750     /** Whether key will, by default, trigger a click on the focused view.
1751      * @hide
1752      */
1753     public static final boolean isConfirmKey(int keyCode) {
1754         switch (keyCode) {
1755             case KeyEvent.KEYCODE_DPAD_CENTER:
1756             case KeyEvent.KEYCODE_ENTER:
1757                 return true;
1758             default:
1759                 return false;
1760         }
1761     }
1762
1763     /**
1764      * Whether this key is a media key, which can be send to apps that are
1765      * interested in media key events.
1766      *
1767      * @hide
1768      */
1769     public static final boolean isMediaKey(int keyCode) {
1770         switch (keyCode) {
1771             case KeyEvent.KEYCODE_MEDIA_PLAY:
1772             case KeyEvent.KEYCODE_MEDIA_PAUSE:
1773             case KeyEvent.KEYCODE_MEDIA_PLAY_PAUSE:
1774             case KeyEvent.KEYCODE_MUTE:
1775             case KeyEvent.KEYCODE_HEADSETHOOK:
1776             case KeyEvent.KEYCODE_MEDIA_STOP:
1777             case KeyEvent.KEYCODE_MEDIA_NEXT:
1778             case KeyEvent.KEYCODE_MEDIA_PREVIOUS:
1779             case KeyEvent.KEYCODE_MEDIA_REWIND:
1780             case KeyEvent.KEYCODE_MEDIA_RECORD:
1781             case KeyEvent.KEYCODE_MEDIA_FAST_FORWARD:
1782                 return true;
1783         }
1784         return false;
1785     }
1786
1787
1788     /** Is this a system key? System keys can not be used for menu shortcuts.
1789      * @hide
1790      */
1791     public static final boolean isSystemKey(int keyCode) {
1792         switch (keyCode) {
1793             case KeyEvent.KEYCODE_MENU:
1794             case KeyEvent.KEYCODE_SOFT_RIGHT:
1795             case KeyEvent.KEYCODE_HOME:
1796             case KeyEvent.KEYCODE_BACK:
1797             case KeyEvent.KEYCODE_CALL:
1798             case KeyEvent.KEYCODE_ENDCALL:
1799             case KeyEvent.KEYCODE_VOLUME_UP:
1800             case KeyEvent.KEYCODE_VOLUME_DOWN:
1801             case KeyEvent.KEYCODE_VOLUME_MUTE:
1802             case KeyEvent.KEYCODE_MUTE:
1803             case KeyEvent.KEYCODE_POWER:
1804             case KeyEvent.KEYCODE_HEADSETHOOK:
1805             case KeyEvent.KEYCODE_MEDIA_PLAY:
1806             case KeyEvent.KEYCODE_MEDIA_PAUSE:
1807             case KeyEvent.KEYCODE_MEDIA_PLAY_PAUSE:
1808             case KeyEvent.KEYCODE_MEDIA_STOP:
1809             case KeyEvent.KEYCODE_MEDIA_NEXT:
1810             case KeyEvent.KEYCODE_MEDIA_PREVIOUS:
1811             case KeyEvent.KEYCODE_MEDIA_REWIND:
1812             case KeyEvent.KEYCODE_MEDIA_RECORD:
1813             case KeyEvent.KEYCODE_MEDIA_FAST_FORWARD:
1814             case KeyEvent.KEYCODE_CAMERA:
1815             case KeyEvent.KEYCODE_FOCUS:
1816             case KeyEvent.KEYCODE_SEARCH:
1817             case KeyEvent.KEYCODE_BRIGHTNESS_DOWN:
1818             case KeyEvent.KEYCODE_BRIGHTNESS_UP:
1819             case KeyEvent.KEYCODE_MEDIA_AUDIO_TRACK:
1820                 return true;
1821         }
1822
1823         return false;
1824     }
1825
1826     /** @hide */
1827     public static final boolean isWakeKey(int keyCode) {
1828         switch (keyCode) {
1829             case KeyEvent.KEYCODE_BACK:
1830             case KeyEvent.KEYCODE_MENU:
1831             case KeyEvent.KEYCODE_WAKEUP:
1832             case KeyEvent.KEYCODE_PAIRING:
1833                 return true;
1834         }
1835         return false;
1836     }
1837
1838     /** @hide */
1839     public static final boolean isMetaKey(int keyCode) {
1840         return keyCode == KeyEvent.KEYCODE_META_LEFT || keyCode == KeyEvent.KEYCODE_META_RIGHT;
1841     }
1842
1843     /** {@inheritDoc} */
1844     @Override
1845     public final int getDeviceId() {
1846         return mDeviceId;
1847     }
1848
1849     /** {@inheritDoc} */
1850     @Override
1851     public final int getSource() {
1852         return mSource;
1853     }
1854
1855     /** {@inheritDoc} */
1856     @Override
1857     public final void setSource(int source) {
1858         mSource = source;
1859     }
1860
1861     /**
1862      * <p>Returns the state of the meta keys.</p>
1863      *
1864      * @return an integer in which each bit set to 1 represents a pressed
1865      *         meta key
1866      *
1867      * @see #isAltPressed()
1868      * @see #isShiftPressed()
1869      * @see #isSymPressed()
1870      * @see #isCtrlPressed()
1871      * @see #isMetaPressed()
1872      * @see #isFunctionPressed()
1873      * @see #isCapsLockOn()
1874      * @see #isNumLockOn()
1875      * @see #isScrollLockOn()
1876      * @see #META_ALT_ON
1877      * @see #META_ALT_LEFT_ON
1878      * @see #META_ALT_RIGHT_ON
1879      * @see #META_SHIFT_ON
1880      * @see #META_SHIFT_LEFT_ON
1881      * @see #META_SHIFT_RIGHT_ON
1882      * @see #META_SYM_ON
1883      * @see #META_FUNCTION_ON
1884      * @see #META_CTRL_ON
1885      * @see #META_CTRL_LEFT_ON
1886      * @see #META_CTRL_RIGHT_ON
1887      * @see #META_META_ON
1888      * @see #META_META_LEFT_ON
1889      * @see #META_META_RIGHT_ON
1890      * @see #META_CAPS_LOCK_ON
1891      * @see #META_NUM_LOCK_ON
1892      * @see #META_SCROLL_LOCK_ON
1893      * @see #getModifiers
1894      */
1895     public final int getMetaState() {
1896         return mMetaState;
1897     }
1898
1899     /**
1900      * Returns the state of the modifier keys.
1901      * <p>
1902      * For the purposes of this function, {@link #KEYCODE_CAPS_LOCK},
1903      * {@link #KEYCODE_SCROLL_LOCK}, and {@link #KEYCODE_NUM_LOCK} are
1904      * not considered modifier keys.  Consequently, this function specifically masks out
1905      * {@link #META_CAPS_LOCK_ON}, {@link #META_SCROLL_LOCK_ON} and {@link #META_NUM_LOCK_ON}.
1906      * </p><p>
1907      * The value returned consists of the meta state (from {@link #getMetaState})
1908      * normalized using {@link #normalizeMetaState(int)} and then masked with
1909      * {@link #getModifierMetaStateMask} so that only valid modifier bits are retained.
1910      * </p>
1911      *
1912      * @return An integer in which each bit set to 1 represents a pressed modifier key.
1913      * @see #getMetaState
1914      */
1915     public final int getModifiers() {
1916         return normalizeMetaState(mMetaState) & META_MODIFIER_MASK;
1917     }
1918
1919     /**
1920      * Returns the flags for this key event.
1921      *
1922      * @see #FLAG_WOKE_HERE
1923      */
1924     public final int getFlags() {
1925         return mFlags;
1926     }
1927
1928     // Mask of all modifier key meta states.  Specifically excludes locked keys like caps lock.
1929     private static final int META_MODIFIER_MASK =
1930             META_SHIFT_ON | META_SHIFT_LEFT_ON | META_SHIFT_RIGHT_ON
1931             | META_ALT_ON | META_ALT_LEFT_ON | META_ALT_RIGHT_ON
1932             | META_CTRL_ON | META_CTRL_LEFT_ON | META_CTRL_RIGHT_ON
1933             | META_META_ON | META_META_LEFT_ON | META_META_RIGHT_ON
1934             | META_SYM_ON | META_FUNCTION_ON;
1935
1936     // Mask of all lock key meta states.
1937     private static final int META_LOCK_MASK =
1938             META_CAPS_LOCK_ON | META_NUM_LOCK_ON | META_SCROLL_LOCK_ON;
1939
1940     // Mask of all valid meta states.
1941     private static final int META_ALL_MASK = META_MODIFIER_MASK | META_LOCK_MASK;
1942
1943     // Mask of all synthetic meta states that are reserved for API compatibility with
1944     // historical uses in MetaKeyKeyListener.
1945     private static final int META_SYNTHETIC_MASK =
1946             META_CAP_LOCKED | META_ALT_LOCKED | META_SYM_LOCKED | META_SELECTING;
1947
1948     // Mask of all meta states that are not valid use in specifying a modifier key.
1949     // These bits are known to be used for purposes other than specifying modifiers.
1950     private static final int META_INVALID_MODIFIER_MASK =
1951             META_LOCK_MASK | META_SYNTHETIC_MASK;
1952
1953     /**
1954      * Gets a mask that includes all valid modifier key meta state bits.
1955      * <p>
1956      * For the purposes of this function, {@link #KEYCODE_CAPS_LOCK},
1957      * {@link #KEYCODE_SCROLL_LOCK}, and {@link #KEYCODE_NUM_LOCK} are
1958      * not considered modifier keys.  Consequently, the mask specifically excludes
1959      * {@link #META_CAPS_LOCK_ON}, {@link #META_SCROLL_LOCK_ON} and {@link #META_NUM_LOCK_ON}.
1960      * </p>
1961      *
1962      * @return The modifier meta state mask which is a combination of
1963      * {@link #META_SHIFT_ON}, {@link #META_SHIFT_LEFT_ON}, {@link #META_SHIFT_RIGHT_ON},
1964      * {@link #META_ALT_ON}, {@link #META_ALT_LEFT_ON}, {@link #META_ALT_RIGHT_ON},
1965      * {@link #META_CTRL_ON}, {@link #META_CTRL_LEFT_ON}, {@link #META_CTRL_RIGHT_ON},
1966      * {@link #META_META_ON}, {@link #META_META_LEFT_ON}, {@link #META_META_RIGHT_ON},
1967      * {@link #META_SYM_ON}, {@link #META_FUNCTION_ON}.
1968      */
1969     public static int getModifierMetaStateMask() {
1970         return META_MODIFIER_MASK;
1971     }
1972
1973     /**
1974      * Returns true if this key code is a modifier key.
1975      * <p>
1976      * For the purposes of this function, {@link #KEYCODE_CAPS_LOCK},
1977      * {@link #KEYCODE_SCROLL_LOCK}, and {@link #KEYCODE_NUM_LOCK} are
1978      * not considered modifier keys.  Consequently, this function return false
1979      * for those keys.
1980      * </p>
1981      *
1982      * @return True if the key code is one of
1983      * {@link #KEYCODE_SHIFT_LEFT} {@link #KEYCODE_SHIFT_RIGHT},
1984      * {@link #KEYCODE_ALT_LEFT}, {@link #KEYCODE_ALT_RIGHT},
1985      * {@link #KEYCODE_CTRL_LEFT}, {@link #KEYCODE_CTRL_RIGHT},
1986      * {@link #KEYCODE_META_LEFT}, or {@link #KEYCODE_META_RIGHT},
1987      * {@link #KEYCODE_SYM}, {@link #KEYCODE_NUM}, {@link #KEYCODE_FUNCTION}.
1988      */
1989     public static boolean isModifierKey(int keyCode) {
1990         switch (keyCode) {
1991             case KEYCODE_SHIFT_LEFT:
1992             case KEYCODE_SHIFT_RIGHT:
1993             case KEYCODE_ALT_LEFT:
1994             case KEYCODE_ALT_RIGHT:
1995             case KEYCODE_CTRL_LEFT:
1996             case KEYCODE_CTRL_RIGHT:
1997             case KEYCODE_META_LEFT:
1998             case KEYCODE_META_RIGHT:
1999             case KEYCODE_SYM:
2000             case KEYCODE_NUM:
2001             case KEYCODE_FUNCTION:
2002                 return true;
2003             default:
2004                 return false;
2005         }
2006     }
2007
2008     /**
2009      * Normalizes the specified meta state.
2010      * <p>
2011      * The meta state is normalized such that if either the left or right modifier meta state
2012      * bits are set then the result will also include the universal bit for that modifier.
2013      * </p><p>
2014      * If the specified meta state contains {@link #META_ALT_LEFT_ON} then
2015      * the result will also contain {@link #META_ALT_ON} in addition to {@link #META_ALT_LEFT_ON}
2016      * and the other bits that were specified in the input.  The same is process is
2017      * performed for shift, control and meta.
2018      * </p><p>
2019      * If the specified meta state contains synthetic meta states defined by
2020      * {@link MetaKeyKeyListener}, then those states are translated here and the original
2021      * synthetic meta states are removed from the result.
2022      * {@link MetaKeyKeyListener#META_CAP_LOCKED} is translated to {@link #META_CAPS_LOCK_ON}.
2023      * {@link MetaKeyKeyListener#META_ALT_LOCKED} is translated to {@link #META_ALT_ON}.
2024      * {@link MetaKeyKeyListener#META_SYM_LOCKED} is translated to {@link #META_SYM_ON}.
2025      * </p><p>
2026      * Undefined meta state bits are removed.
2027      * </p>
2028      *
2029      * @param metaState The meta state.
2030      * @return The normalized meta state.
2031      */
2032     public static int normalizeMetaState(int metaState) {
2033         if ((metaState & (META_SHIFT_LEFT_ON | META_SHIFT_RIGHT_ON)) != 0) {
2034             metaState |= META_SHIFT_ON;
2035         }
2036         if ((metaState & (META_ALT_LEFT_ON | META_ALT_RIGHT_ON)) != 0) {
2037             metaState |= META_ALT_ON;
2038         }
2039         if ((metaState & (META_CTRL_LEFT_ON | META_CTRL_RIGHT_ON)) != 0) {
2040             metaState |= META_CTRL_ON;
2041         }
2042         if ((metaState & (META_META_LEFT_ON | META_META_RIGHT_ON)) != 0) {
2043             metaState |= META_META_ON;
2044         }
2045         if ((metaState & MetaKeyKeyListener.META_CAP_LOCKED) != 0) {
2046             metaState |= META_CAPS_LOCK_ON;
2047         }
2048         if ((metaState & MetaKeyKeyListener.META_ALT_LOCKED) != 0) {
2049             metaState |= META_ALT_ON;
2050         }
2051         if ((metaState & MetaKeyKeyListener.META_SYM_LOCKED) != 0) {
2052             metaState |= META_SYM_ON;
2053         }
2054         return metaState & META_ALL_MASK;
2055     }
2056
2057     /**
2058      * Returns true if no modifiers keys are pressed according to the specified meta state.
2059      * <p>
2060      * For the purposes of this function, {@link #KEYCODE_CAPS_LOCK},
2061      * {@link #KEYCODE_SCROLL_LOCK}, and {@link #KEYCODE_NUM_LOCK} are
2062      * not considered modifier keys.  Consequently, this function ignores
2063      * {@link #META_CAPS_LOCK_ON}, {@link #META_SCROLL_LOCK_ON} and {@link #META_NUM_LOCK_ON}.
2064      * </p><p>
2065      * The meta state is normalized prior to comparison using {@link #normalizeMetaState(int)}.
2066      * </p>
2067      *
2068      * @param metaState The meta state to consider.
2069      * @return True if no modifier keys are pressed.
2070      * @see #hasNoModifiers()
2071      */
2072     public static boolean metaStateHasNoModifiers(int metaState) {
2073         return (normalizeMetaState(metaState) & META_MODIFIER_MASK) == 0;
2074     }
2075
2076     /**
2077      * Returns true if only the specified modifier keys are pressed according to
2078      * the specified meta state.  Returns false if a different combination of modifier
2079      * keys are pressed.
2080      * <p>
2081      * For the purposes of this function, {@link #KEYCODE_CAPS_LOCK},
2082      * {@link #KEYCODE_SCROLL_LOCK}, and {@link #KEYCODE_NUM_LOCK} are
2083      * not considered modifier keys.  Consequently, this function ignores
2084      * {@link #META_CAPS_LOCK_ON}, {@link #META_SCROLL_LOCK_ON} and {@link #META_NUM_LOCK_ON}.
2085      * </p><p>
2086      * If the specified modifier mask includes directional modifiers, such as
2087      * {@link #META_SHIFT_LEFT_ON}, then this method ensures that the
2088      * modifier is pressed on that side.
2089      * If the specified modifier mask includes non-directional modifiers, such as
2090      * {@link #META_SHIFT_ON}, then this method ensures that the modifier
2091      * is pressed on either side.
2092      * If the specified modifier mask includes both directional and non-directional modifiers
2093      * for the same type of key, such as {@link #META_SHIFT_ON} and {@link #META_SHIFT_LEFT_ON},
2094      * then this method throws an illegal argument exception.
2095      * </p>
2096      *
2097      * @param metaState The meta state to consider.
2098      * @param modifiers The meta state of the modifier keys to check.  May be a combination
2099      * of modifier meta states as defined by {@link #getModifierMetaStateMask()}.  May be 0 to
2100      * ensure that no modifier keys are pressed.
2101      * @return True if only the specified modifier keys are pressed.
2102      * @throws IllegalArgumentException if the modifiers parameter contains invalid modifiers
2103      * @see #hasModifiers
2104      */
2105     public static boolean metaStateHasModifiers(int metaState, int modifiers) {
2106         // Note: For forward compatibility, we allow the parameter to contain meta states
2107         //       that we do not recognize but we explicitly disallow meta states that
2108         //       are not valid modifiers.
2109         if ((modifiers & META_INVALID_MODIFIER_MASK) != 0) {
2110             throw new IllegalArgumentException("modifiers must not contain "
2111                     + "META_CAPS_LOCK_ON, META_NUM_LOCK_ON, META_SCROLL_LOCK_ON, "
2112                     + "META_CAP_LOCKED, META_ALT_LOCKED, META_SYM_LOCKED, "
2113                     + "or META_SELECTING");
2114         }
2115
2116         metaState = normalizeMetaState(metaState) & META_MODIFIER_MASK;
2117         metaState = metaStateFilterDirectionalModifiers(metaState, modifiers,
2118                 META_SHIFT_ON, META_SHIFT_LEFT_ON, META_SHIFT_RIGHT_ON);
2119         metaState = metaStateFilterDirectionalModifiers(metaState, modifiers,
2120                 META_ALT_ON, META_ALT_LEFT_ON, META_ALT_RIGHT_ON);
2121         metaState = metaStateFilterDirectionalModifiers(metaState, modifiers,
2122                 META_CTRL_ON, META_CTRL_LEFT_ON, META_CTRL_RIGHT_ON);
2123         metaState = metaStateFilterDirectionalModifiers(metaState, modifiers,
2124                 META_META_ON, META_META_LEFT_ON, META_META_RIGHT_ON);
2125         return metaState == modifiers;
2126     }
2127
2128     private static int metaStateFilterDirectionalModifiers(int metaState,
2129             int modifiers, int basic, int left, int right) {
2130         final boolean wantBasic = (modifiers & basic) != 0;
2131         final int directional = left | right;
2132         final boolean wantLeftOrRight = (modifiers & directional) != 0;
2133
2134         if (wantBasic) {
2135             if (wantLeftOrRight) {
2136                 throw new IllegalArgumentException("modifiers must not contain "
2137                         + metaStateToString(basic) + " combined with "
2138                         + metaStateToString(left) + " or " + metaStateToString(right));
2139             }
2140             return metaState & ~directional;
2141         } else if (wantLeftOrRight) {
2142             return metaState & ~basic;
2143         } else {
2144             return metaState;
2145         }
2146     }
2147
2148     /**
2149      * Returns true if no modifier keys are pressed.
2150      * <p>
2151      * For the purposes of this function, {@link #KEYCODE_CAPS_LOCK},
2152      * {@link #KEYCODE_SCROLL_LOCK}, and {@link #KEYCODE_NUM_LOCK} are
2153      * not considered modifier keys.  Consequently, this function ignores
2154      * {@link #META_CAPS_LOCK_ON}, {@link #META_SCROLL_LOCK_ON} and {@link #META_NUM_LOCK_ON}.
2155      * </p><p>
2156      * The meta state is normalized prior to comparison using {@link #normalizeMetaState(int)}.
2157      * </p>
2158      *
2159      * @return True if no modifier keys are pressed.
2160      * @see #metaStateHasNoModifiers
2161      */
2162     public final boolean hasNoModifiers() {
2163         return metaStateHasNoModifiers(mMetaState);
2164     }
2165
2166     /**
2167      * Returns true if only the specified modifiers keys are pressed.
2168      * Returns false if a different combination of modifier keys are pressed.
2169      * <p>
2170      * For the purposes of this function, {@link #KEYCODE_CAPS_LOCK},
2171      * {@link #KEYCODE_SCROLL_LOCK}, and {@link #KEYCODE_NUM_LOCK} are
2172      * not considered modifier keys.  Consequently, this function ignores
2173      * {@link #META_CAPS_LOCK_ON}, {@link #META_SCROLL_LOCK_ON} and {@link #META_NUM_LOCK_ON}.
2174      * </p><p>
2175      * If the specified modifier mask includes directional modifiers, such as
2176      * {@link #META_SHIFT_LEFT_ON}, then this method ensures that the
2177      * modifier is pressed on that side.
2178      * If the specified modifier mask includes non-directional modifiers, such as
2179      * {@link #META_SHIFT_ON}, then this method ensures that the modifier
2180      * is pressed on either side.
2181      * If the specified modifier mask includes both directional and non-directional modifiers
2182      * for the same type of key, such as {@link #META_SHIFT_ON} and {@link #META_SHIFT_LEFT_ON},
2183      * then this method throws an illegal argument exception.
2184      * </p>
2185      *
2186      * @param modifiers The meta state of the modifier keys to check.  May be a combination
2187      * of modifier meta states as defined by {@link #getModifierMetaStateMask()}.  May be 0 to
2188      * ensure that no modifier keys are pressed.
2189      * @return True if only the specified modifier keys are pressed.
2190      * @throws IllegalArgumentException if the modifiers parameter contains invalid modifiers
2191      * @see #metaStateHasModifiers
2192      */
2193     public final boolean hasModifiers(int modifiers) {
2194         return metaStateHasModifiers(mMetaState, modifiers);
2195     }
2196
2197     /**
2198      * <p>Returns the pressed state of the ALT meta key.</p>
2199      *
2200      * @return true if the ALT key is pressed, false otherwise
2201      *
2202      * @see #KEYCODE_ALT_LEFT
2203      * @see #KEYCODE_ALT_RIGHT
2204      * @see #META_ALT_ON
2205      */
2206     public final boolean isAltPressed() {
2207         return (mMetaState & META_ALT_ON) != 0;
2208     }
2209
2210     /**
2211      * <p>Returns the pressed state of the SHIFT meta key.</p>
2212      *
2213      * @return true if the SHIFT key is pressed, false otherwise
2214      *
2215      * @see #KEYCODE_SHIFT_LEFT
2216      * @see #KEYCODE_SHIFT_RIGHT
2217      * @see #META_SHIFT_ON
2218      */
2219     public final boolean isShiftPressed() {
2220         return (mMetaState & META_SHIFT_ON) != 0;
2221     }
2222
2223     /**
2224      * <p>Returns the pressed state of the SYM meta key.</p>
2225      *
2226      * @return true if the SYM key is pressed, false otherwise
2227      *
2228      * @see #KEYCODE_SYM
2229      * @see #META_SYM_ON
2230      */
2231     public final boolean isSymPressed() {
2232         return (mMetaState & META_SYM_ON) != 0;
2233     }
2234
2235     /**
2236      * <p>Returns the pressed state of the CTRL meta key.</p>
2237      *
2238      * @return true if the CTRL key is pressed, false otherwise
2239      *
2240      * @see #KEYCODE_CTRL_LEFT
2241      * @see #KEYCODE_CTRL_RIGHT
2242      * @see #META_CTRL_ON
2243      */
2244     public final boolean isCtrlPressed() {
2245         return (mMetaState & META_CTRL_ON) != 0;
2246     }
2247
2248     /**
2249      * <p>Returns the pressed state of the META meta key.</p>
2250      *
2251      * @return true if the META key is pressed, false otherwise
2252      *
2253      * @see #KEYCODE_META_LEFT
2254      * @see #KEYCODE_META_RIGHT
2255      * @see #META_META_ON
2256      */
2257     public final boolean isMetaPressed() {
2258         return (mMetaState & META_META_ON) != 0;
2259     }
2260
2261     /**
2262      * <p>Returns the pressed state of the FUNCTION meta key.</p>
2263      *
2264      * @return true if the FUNCTION key is pressed, false otherwise
2265      *
2266      * @see #KEYCODE_FUNCTION
2267      * @see #META_FUNCTION_ON
2268      */
2269     public final boolean isFunctionPressed() {
2270         return (mMetaState & META_FUNCTION_ON) != 0;
2271     }
2272
2273     /**
2274      * <p>Returns the locked state of the CAPS LOCK meta key.</p>
2275      *
2276      * @return true if the CAPS LOCK key is on, false otherwise
2277      *
2278      * @see #KEYCODE_CAPS_LOCK
2279      * @see #META_CAPS_LOCK_ON
2280      */
2281     public final boolean isCapsLockOn() {
2282         return (mMetaState & META_CAPS_LOCK_ON) != 0;
2283     }
2284
2285     /**
2286      * <p>Returns the locked state of the NUM LOCK meta key.</p>
2287      *
2288      * @return true if the NUM LOCK key is on, false otherwise
2289      *
2290      * @see #KEYCODE_NUM_LOCK
2291      * @see #META_NUM_LOCK_ON
2292      */
2293     public final boolean isNumLockOn() {
2294         return (mMetaState & META_NUM_LOCK_ON) != 0;
2295     }
2296
2297     /**
2298      * <p>Returns the locked state of the SCROLL LOCK meta key.</p>
2299      *
2300      * @return true if the SCROLL LOCK key is on, false otherwise
2301      *
2302      * @see #KEYCODE_SCROLL_LOCK
2303      * @see #META_SCROLL_LOCK_ON
2304      */
2305     public final boolean isScrollLockOn() {
2306         return (mMetaState & META_SCROLL_LOCK_ON) != 0;
2307     }
2308
2309     /**
2310      * Retrieve the action of this key event.  May be either
2311      * {@link #ACTION_DOWN}, {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}.
2312      *
2313      * @return The event action: ACTION_DOWN, ACTION_UP, or ACTION_MULTIPLE.
2314      */
2315     public final int getAction() {
2316         return mAction;
2317     }
2318
2319     /**
2320      * For {@link #ACTION_UP} events, indicates that the event has been
2321      * canceled as per {@link #FLAG_CANCELED}.
2322      */
2323     public final boolean isCanceled() {
2324         return (mFlags&FLAG_CANCELED) != 0;
2325     }
2326
2327     /**
2328      * Set {@link #FLAG_CANCELED} flag for the key event.
2329      *
2330      * @hide
2331      */
2332     @Override
2333     public final void cancel() {
2334         mFlags |= FLAG_CANCELED;
2335     }
2336
2337     /**
2338      * Call this during {@link Callback#onKeyDown} to have the system track
2339      * the key through its final up (possibly including a long press).  Note
2340      * that only one key can be tracked at a time -- if another key down
2341      * event is received while a previous one is being tracked, tracking is
2342      * stopped on the previous event.
2343      */
2344     public final void startTracking() {
2345         mFlags |= FLAG_START_TRACKING;
2346     }
2347
2348     /**
2349      * For {@link #ACTION_UP} events, indicates that the event is still being
2350      * tracked from its initial down event as per
2351      * {@link #FLAG_TRACKING}.
2352      */
2353     public final boolean isTracking() {
2354         return (mFlags&FLAG_TRACKING) != 0;
2355     }
2356
2357     /**
2358      * For {@link #ACTION_DOWN} events, indicates that the event has been
2359      * canceled as per {@link #FLAG_LONG_PRESS}.
2360      */
2361     public final boolean isLongPress() {
2362         return (mFlags&FLAG_LONG_PRESS) != 0;
2363     }
2364
2365     /**
2366      * Retrieve the key code of the key event.  This is the physical key that
2367      * was pressed, <em>not</em> the Unicode character.
2368      *
2369      * @return The key code of the event.
2370      */
2371     public final int getKeyCode() {
2372         return mKeyCode;
2373     }
2374
2375     /**
2376      * For the special case of a {@link #ACTION_MULTIPLE} event with key
2377      * code of {@link #KEYCODE_UNKNOWN}, this is a raw string of characters
2378      * associated with the event.  In all other cases it is null.
2379      *
2380      * @return Returns a String of 1 or more characters associated with
2381      * the event.
2382      */
2383     public final String getCharacters() {
2384         return mCharacters;
2385     }
2386
2387     /**
2388      * Retrieve the hardware key id of this key event.  These values are not
2389      * reliable and vary from device to device.
2390      *
2391      * {@more}
2392      * Mostly this is here for debugging purposes.
2393      */
2394     public final int getScanCode() {
2395         return mScanCode;
2396     }
2397
2398     /**
2399      * Retrieve the repeat count of the event.  For both key up and key down
2400      * events, this is the number of times the key has repeated with the first
2401      * down starting at 0 and counting up from there.  For multiple key
2402      * events, this is the number of down/up pairs that have occurred.
2403      *
2404      * @return The number of times the key has repeated.
2405      */
2406     public final int getRepeatCount() {
2407         return mRepeatCount;
2408     }
2409
2410     /**
2411      * Retrieve the time of the most recent key down event,
2412      * in the {@link android.os.SystemClock#uptimeMillis} time base.  If this
2413      * is a down event, this will be the same as {@link #getEventTime()}.
2414      * Note that when chording keys, this value is the down time of the
2415      * most recently pressed key, which may <em>not</em> be the same physical
2416      * key of this event.
2417      *
2418      * @return Returns the most recent key down time, in the
2419      * {@link android.os.SystemClock#uptimeMillis} time base
2420      */
2421     public final long getDownTime() {
2422         return mDownTime;
2423     }
2424
2425     /**
2426      * Retrieve the time this event occurred,
2427      * in the {@link android.os.SystemClock#uptimeMillis} time base.
2428      *
2429      * @return Returns the time this event occurred,
2430      * in the {@link android.os.SystemClock#uptimeMillis} time base.
2431      */
2432     @Override
2433     public final long getEventTime() {
2434         return mEventTime;
2435     }
2436
2437     /**
2438      * Retrieve the time this event occurred,
2439      * in the {@link android.os.SystemClock#uptimeMillis} time base but with
2440      * nanosecond (instead of millisecond) precision.
2441      * <p>
2442      * The value is in nanosecond precision but it may not have nanosecond accuracy.
2443      * </p>
2444      *
2445      * @return Returns the time this event occurred,
2446      * in the {@link android.os.SystemClock#uptimeMillis} time base but with
2447      * nanosecond (instead of millisecond) precision.
2448      *
2449      * @hide
2450      */
2451     @Override
2452     public final long getEventTimeNano() {
2453         return mEventTime * 1000000L;
2454     }
2455
2456     /**
2457      * Renamed to {@link #getDeviceId}.
2458      *
2459      * @hide
2460      * @deprecated use {@link #getDeviceId()} instead.
2461      */
2462     @Deprecated
2463     public final int getKeyboardDevice() {
2464         return mDeviceId;
2465     }
2466
2467     /**
2468      * Gets the {@link KeyCharacterMap} associated with the keyboard device.
2469      *
2470      * @return The associated key character map.
2471      * @throws {@link KeyCharacterMap.UnavailableException} if the key character map
2472      * could not be loaded because it was malformed or the default key character map
2473      * is missing from the system.
2474      *
2475      * @see KeyCharacterMap#load
2476      */
2477     public final KeyCharacterMap getKeyCharacterMap() {
2478         return KeyCharacterMap.load(mDeviceId);
2479     }
2480
2481     /**
2482      * Gets the primary character for this key.
2483      * In other words, the label that is physically printed on it.
2484      *
2485      * @return The display label character, or 0 if none (eg. for non-printing keys).
2486      */
2487     public char getDisplayLabel() {
2488         return getKeyCharacterMap().getDisplayLabel(mKeyCode);
2489     }
2490
2491     /**
2492      * Gets the Unicode character generated by the specified key and meta
2493      * key state combination.
2494      * <p>
2495      * Returns the Unicode character that the specified key would produce
2496      * when the specified meta bits (see {@link MetaKeyKeyListener})
2497      * were active.
2498      * </p><p>
2499      * Returns 0 if the key is not one that is used to type Unicode
2500      * characters.
2501      * </p><p>
2502      * If the return value has bit {@link KeyCharacterMap#COMBINING_ACCENT} set, the
2503      * key is a "dead key" that should be combined with another to
2504      * actually produce a character -- see {@link KeyCharacterMap#getDeadChar} --
2505      * after masking with {@link KeyCharacterMap#COMBINING_ACCENT_MASK}.
2506      * </p>
2507      *
2508      * @return The associated character or combining accent, or 0 if none.
2509      */
2510     public int getUnicodeChar() {
2511         return getUnicodeChar(mMetaState);
2512     }
2513
2514     /**
2515      * Gets the Unicode character generated by the specified key and meta
2516      * key state combination.
2517      * <p>
2518      * Returns the Unicode character that the specified key would produce
2519      * when the specified meta bits (see {@link MetaKeyKeyListener})
2520      * were active.
2521      * </p><p>
2522      * Returns 0 if the key is not one that is used to type Unicode
2523      * characters.
2524      * </p><p>
2525      * If the return value has bit {@link KeyCharacterMap#COMBINING_ACCENT} set, the
2526      * key is a "dead key" that should be combined with another to
2527      * actually produce a character -- see {@link KeyCharacterMap#getDeadChar} --
2528      * after masking with {@link KeyCharacterMap#COMBINING_ACCENT_MASK}.
2529      * </p>
2530      *
2531      * @param metaState The meta key modifier state.
2532      * @return The associated character or combining accent, or 0 if none.
2533      */
2534     public int getUnicodeChar(int metaState) {
2535         return getKeyCharacterMap().get(mKeyCode, metaState);
2536     }
2537
2538     /**
2539      * Get the character conversion data for a given key code.
2540      *
2541      * @param results A {@link KeyCharacterMap.KeyData} instance that will be
2542      * filled with the results.
2543      * @return True if the key was mapped.  If the key was not mapped, results is not modified.
2544      *
2545      * @deprecated instead use {@link #getDisplayLabel()},
2546      * {@link #getNumber()} or {@link #getUnicodeChar(int)}.
2547      */
2548     @Deprecated
2549     public boolean getKeyData(KeyData results) {
2550         return getKeyCharacterMap().getKeyData(mKeyCode, results);
2551     }
2552
2553     /**
2554      * Gets the first character in the character array that can be generated
2555      * by the specified key code.
2556      * <p>
2557      * This is a convenience function that returns the same value as
2558      * {@link #getMatch(char[],int) getMatch(chars, 0)}.
2559      * </p>
2560      *
2561      * @param chars The array of matching characters to consider.
2562      * @return The matching associated character, or 0 if none.
2563      */
2564     public char getMatch(char[] chars) {
2565         return getMatch(chars, 0);
2566     }
2567
2568     /**
2569      * Gets the first character in the character array that can be generated
2570      * by the specified key code.  If there are multiple choices, prefers
2571      * the one that would be generated with the specified meta key modifier state.
2572      *
2573      * @param chars The array of matching characters to consider.
2574      * @param metaState The preferred meta key modifier state.
2575      * @return The matching associated character, or 0 if none.
2576      */
2577     public char getMatch(char[] chars, int metaState) {
2578         return getKeyCharacterMap().getMatch(mKeyCode, chars, metaState);
2579     }
2580
2581     /**
2582      * Gets the number or symbol associated with the key.
2583      * <p>
2584      * The character value is returned, not the numeric value.
2585      * If the key is not a number, but is a symbol, the symbol is retuned.
2586      * </p><p>
2587      * This method is intended to to support dial pads and other numeric or
2588      * symbolic entry on keyboards where certain keys serve dual function
2589      * as alphabetic and symbolic keys.  This method returns the number
2590      * or symbol associated with the key independent of whether the user
2591      * has pressed the required modifier.
2592      * </p><p>
2593      * For example, on one particular keyboard the keys on the top QWERTY row generate
2594      * numbers when ALT is pressed such that ALT-Q maps to '1'.  So for that keyboard
2595      * when {@link #getNumber} is called with {@link KeyEvent#KEYCODE_Q} it returns '1'
2596      * so that the user can type numbers without pressing ALT when it makes sense.
2597      * </p>
2598      *
2599      * @return The associated numeric or symbolic character, or 0 if none.
2600      */
2601     public char getNumber() {
2602         return getKeyCharacterMap().getNumber(mKeyCode);
2603     }
2604
2605     /**
2606      * Returns true if this key produces a glyph.
2607      *
2608      * @return True if the key is a printing key.
2609      */
2610     public boolean isPrintingKey() {
2611         return getKeyCharacterMap().isPrintingKey(mKeyCode);
2612     }
2613
2614     /**
2615      * @deprecated Use {@link #dispatch(Callback, DispatcherState, Object)} instead.
2616      */
2617     @Deprecated
2618     public final boolean dispatch(Callback receiver) {
2619         return dispatch(receiver, null, null);
2620     }
2621
2622     /**
2623      * Deliver this key event to a {@link Callback} interface.  If this is
2624      * an ACTION_MULTIPLE event and it is not handled, then an attempt will
2625      * be made to deliver a single normal event.
2626      *
2627      * @param receiver The Callback that will be given the event.
2628      * @param state State information retained across events.
2629      * @param target The target of the dispatch, for use in tracking.
2630      *
2631      * @return The return value from the Callback method that was called.
2632      */
2633     public final boolean dispatch(Callback receiver, DispatcherState state,
2634             Object target) {
2635         switch (mAction) {
2636             case ACTION_DOWN: {
2637                 mFlags &= ~FLAG_START_TRACKING;
2638                 if (DEBUG) Log.v(TAG, "Key down to " + target + " in " + state
2639                         + ": " + this);
2640                 boolean res = receiver.onKeyDown(mKeyCode, this);
2641                 if (state != null) {
2642                     if (res && mRepeatCount == 0 && (mFlags&FLAG_START_TRACKING) != 0) {
2643                         if (DEBUG) Log.v(TAG, "  Start tracking!");
2644                         state.startTracking(this, target);
2645                     } else if (isLongPress() && state.isTracking(this)) {
2646                         try {
2647                             if (receiver.onKeyLongPress(mKeyCode, this)) {
2648                                 if (DEBUG) Log.v(TAG, "  Clear from long press!");
2649                                 state.performedLongPress(this);
2650                                 res = true;
2651                             }
2652                         } catch (AbstractMethodError e) {
2653                         }
2654                     }
2655                 }
2656                 return res;
2657             }
2658             case ACTION_UP:
2659                 if (DEBUG) Log.v(TAG, "Key up to " + target + " in " + state
2660                         + ": " + this);
2661                 if (state != null) {
2662                     state.handleUpEvent(this);
2663                 }
2664                 return receiver.onKeyUp(mKeyCode, this);
2665             case ACTION_MULTIPLE:
2666                 final int count = mRepeatCount;
2667                 final int code = mKeyCode;
2668                 if (receiver.onKeyMultiple(code, count, this)) {
2669                     return true;
2670                 }
2671                 if (code != KeyEvent.KEYCODE_UNKNOWN) {
2672                     mAction = ACTION_DOWN;
2673                     mRepeatCount = 0;
2674                     boolean handled = receiver.onKeyDown(code, this);
2675                     if (handled) {
2676                         mAction = ACTION_UP;
2677                         receiver.onKeyUp(code, this);
2678                     }
2679                     mAction = ACTION_MULTIPLE;
2680                     mRepeatCount = count;
2681                     return handled;
2682                 }
2683                 return false;
2684         }
2685         return false;
2686     }
2687
2688     /**
2689      * Use with {@link KeyEvent#dispatch(Callback, DispatcherState, Object)}
2690      * for more advanced key dispatching, such as long presses.
2691      */
2692     public static class DispatcherState {
2693         int mDownKeyCode;
2694         Object mDownTarget;
2695         SparseIntArray mActiveLongPresses = new SparseIntArray();
2696
2697         /**
2698          * Reset back to initial state.
2699          */
2700         public void reset() {
2701             if (DEBUG) Log.v(TAG, "Reset: " + this);
2702             mDownKeyCode = 0;
2703             mDownTarget = null;
2704             mActiveLongPresses.clear();
2705         }
2706
2707         /**
2708          * Stop any tracking associated with this target.
2709          */
2710         public void reset(Object target) {
2711             if (mDownTarget == target) {
2712                 if (DEBUG) Log.v(TAG, "Reset in " + target + ": " + this);
2713                 mDownKeyCode = 0;
2714                 mDownTarget = null;
2715             }
2716         }
2717
2718         /**
2719          * Start tracking the key code associated with the given event.  This
2720          * can only be called on a key down.  It will allow you to see any
2721          * long press associated with the key, and will result in
2722          * {@link KeyEvent#isTracking} return true on the long press and up
2723          * events.
2724          *
2725          * <p>This is only needed if you are directly dispatching events, rather
2726          * than handling them in {@link Callback#onKeyDown}.
2727          */
2728         public void startTracking(KeyEvent event, Object target) {
2729             if (event.getAction() != ACTION_DOWN) {
2730                 throw new IllegalArgumentException(
2731                         "Can only start tracking on a down event");
2732             }
2733             if (DEBUG) Log.v(TAG, "Start trackingt in " + target + ": " + this);
2734             mDownKeyCode = event.getKeyCode();
2735             mDownTarget = target;
2736         }
2737
2738         /**
2739          * Return true if the key event is for a key code that is currently
2740          * being tracked by the dispatcher.
2741          */
2742         public boolean isTracking(KeyEvent event) {
2743             return mDownKeyCode == event.getKeyCode();
2744         }
2745
2746         /**
2747          * Keep track of the given event's key code as having performed an
2748          * action with a long press, so no action should occur on the up.
2749          * <p>This is only needed if you are directly dispatching events, rather
2750          * than handling them in {@link Callback#onKeyLongPress}.
2751          */
2752         public void performedLongPress(KeyEvent event) {
2753             mActiveLongPresses.put(event.getKeyCode(), 1);
2754         }
2755
2756         /**
2757          * Handle key up event to stop tracking.  This resets the dispatcher state,
2758          * and updates the key event state based on it.
2759          * <p>This is only needed if you are directly dispatching events, rather
2760          * than handling them in {@link Callback#onKeyUp}.
2761          */
2762         public void handleUpEvent(KeyEvent event) {
2763             final int keyCode = event.getKeyCode();
2764             if (DEBUG) Log.v(TAG, "Handle key up " + event + ": " + this);
2765             int index = mActiveLongPresses.indexOfKey(keyCode);
2766             if (index >= 0) {
2767                 if (DEBUG) Log.v(TAG, "  Index: " + index);
2768                 event.mFlags |= FLAG_CANCELED | FLAG_CANCELED_LONG_PRESS;
2769                 mActiveLongPresses.removeAt(index);
2770             }
2771             if (mDownKeyCode == keyCode) {
2772                 if (DEBUG) Log.v(TAG, "  Tracking!");
2773                 event.mFlags |= FLAG_TRACKING;
2774                 mDownKeyCode = 0;
2775                 mDownTarget = null;
2776             }
2777         }
2778     }
2779
2780     @Override
2781     public String toString() {
2782         StringBuilder msg = new StringBuilder();
2783         msg.append("KeyEvent { action=").append(actionToString(mAction));
2784         msg.append(", keyCode=").append(keyCodeToString(mKeyCode));
2785         msg.append(", scanCode=").append(mScanCode);
2786         if (mCharacters != null) {
2787             msg.append(", characters=\"").append(mCharacters).append("\"");
2788         }
2789         msg.append(", metaState=").append(metaStateToString(mMetaState));
2790         msg.append(", flags=0x").append(Integer.toHexString(mFlags));
2791         msg.append(", repeatCount=").append(mRepeatCount);
2792         msg.append(", eventTime=").append(mEventTime);
2793         msg.append(", downTime=").append(mDownTime);
2794         msg.append(", deviceId=").append(mDeviceId);
2795         msg.append(", source=0x").append(Integer.toHexString(mSource));
2796         msg.append(" }");
2797         return msg.toString();
2798     }
2799
2800     /**
2801      * Returns a string that represents the symbolic name of the specified action
2802      * such as "ACTION_DOWN", or an equivalent numeric constant such as "35" if unknown.
2803      *
2804      * @param action The action.
2805      * @return The symbolic name of the specified action.
2806      * @hide
2807      */
2808     public static String actionToString(int action) {
2809         switch (action) {
2810             case ACTION_DOWN:
2811                 return "ACTION_DOWN";
2812             case ACTION_UP:
2813                 return "ACTION_UP";
2814             case ACTION_MULTIPLE:
2815                 return "ACTION_MULTIPLE";
2816             default:
2817                 return Integer.toString(action);
2818         }
2819     }
2820
2821     /**
2822      * Returns a string that represents the symbolic name of the specified keycode
2823      * such as "KEYCODE_A", "KEYCODE_DPAD_UP", or an equivalent numeric constant
2824      * such as "1001" if unknown.
2825      *
2826      * @param keyCode The key code.
2827      * @return The symbolic name of the specified keycode.
2828      *
2829      * @see KeyCharacterMap#getDisplayLabel
2830      */
2831     public static String keyCodeToString(int keyCode) {
2832         String symbolicName = nativeKeyCodeToString(keyCode);
2833         return symbolicName != null ? LABEL_PREFIX + symbolicName : Integer.toString(keyCode);
2834     }
2835
2836     /**
2837      * Gets a keycode by its symbolic name such as "KEYCODE_A" or an equivalent
2838      * numeric constant such as "1001".
2839      *
2840      * @param symbolicName The symbolic name of the keycode.
2841      * @return The keycode or {@link #KEYCODE_UNKNOWN} if not found.
2842      * @see #keycodeToString(int)
2843      */
2844     public static int keyCodeFromString(String symbolicName) {
2845         if (symbolicName.startsWith(LABEL_PREFIX)) {
2846             symbolicName = symbolicName.substring(LABEL_PREFIX.length());
2847             int keyCode = nativeKeyCodeFromString(symbolicName);
2848             if (keyCode > 0) {
2849                 return keyCode;
2850             }
2851         }
2852         try {
2853             return Integer.parseInt(symbolicName, 10);
2854         } catch (NumberFormatException ex) {
2855             return KEYCODE_UNKNOWN;
2856         }
2857     }
2858
2859     /**
2860      * Returns a string that represents the symbolic name of the specified combined meta
2861      * key modifier state flags such as "0", "META_SHIFT_ON",
2862      * "META_ALT_ON|META_SHIFT_ON" or an equivalent numeric constant such as "0x10000000"
2863      * if unknown.
2864      *
2865      * @param metaState The meta state.
2866      * @return The symbolic name of the specified combined meta state flags.
2867      * @hide
2868      */
2869     public static String metaStateToString(int metaState) {
2870         if (metaState == 0) {
2871             return "0";
2872         }
2873         StringBuilder result = null;
2874         int i = 0;
2875         while (metaState != 0) {
2876             final boolean isSet = (metaState & 1) != 0;
2877             metaState >>>= 1; // unsigned shift!
2878             if (isSet) {
2879                 final String name = META_SYMBOLIC_NAMES[i];
2880                 if (result == null) {
2881                     if (metaState == 0) {
2882                         return name;
2883                     }
2884                     result = new StringBuilder(name);
2885                 } else {
2886                     result.append('|');
2887                     result.append(name);
2888                 }
2889             }
2890             i += 1;
2891         }
2892         return result.toString();
2893     }
2894
2895     public static final Parcelable.Creator<KeyEvent> CREATOR
2896             = new Parcelable.Creator<KeyEvent>() {
2897         public KeyEvent createFromParcel(Parcel in) {
2898             in.readInt(); // skip token, we already know this is a KeyEvent
2899             return KeyEvent.createFromParcelBody(in);
2900         }
2901
2902         public KeyEvent[] newArray(int size) {
2903             return new KeyEvent[size];
2904         }
2905     };
2906
2907     /** @hide */
2908     public static KeyEvent createFromParcelBody(Parcel in) {
2909         return new KeyEvent(in);
2910     }
2911
2912     private KeyEvent(Parcel in) {
2913         mDeviceId = in.readInt();
2914         mSource = in.readInt();
2915         mAction = in.readInt();
2916         mKeyCode = in.readInt();
2917         mRepeatCount = in.readInt();
2918         mMetaState = in.readInt();
2919         mScanCode = in.readInt();
2920         mFlags = in.readInt();
2921         mDownTime = in.readLong();
2922         mEventTime = in.readLong();
2923     }
2924
2925     public void writeToParcel(Parcel out, int flags) {
2926         out.writeInt(PARCEL_TOKEN_KEY_EVENT);
2927
2928         out.writeInt(mDeviceId);
2929         out.writeInt(mSource);
2930         out.writeInt(mAction);
2931         out.writeInt(mKeyCode);
2932         out.writeInt(mRepeatCount);
2933         out.writeInt(mMetaState);
2934         out.writeInt(mScanCode);
2935         out.writeInt(mFlags);
2936         out.writeLong(mDownTime);
2937         out.writeLong(mEventTime);
2938     }
2939 }