KeyEvent.java revision ddca3ee3e86fbaa05c1528bd72afd955f0fb4ee6
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 17package android.view; 18 19import android.os.Parcel; 20import android.os.Parcelable; 21import android.view.KeyCharacterMap; 22import android.view.KeyCharacterMap.KeyData; 23 24/** 25 * Contains constants for key events. 26 */ 27public class KeyEvent implements Parcelable { 28 // key codes 29 public static final int KEYCODE_UNKNOWN = 0; 30 public static final int KEYCODE_SOFT_LEFT = 1; 31 public static final int KEYCODE_SOFT_RIGHT = 2; 32 public static final int KEYCODE_HOME = 3; 33 public static final int KEYCODE_BACK = 4; 34 public static final int KEYCODE_CALL = 5; 35 public static final int KEYCODE_ENDCALL = 6; 36 public static final int KEYCODE_0 = 7; 37 public static final int KEYCODE_1 = 8; 38 public static final int KEYCODE_2 = 9; 39 public static final int KEYCODE_3 = 10; 40 public static final int KEYCODE_4 = 11; 41 public static final int KEYCODE_5 = 12; 42 public static final int KEYCODE_6 = 13; 43 public static final int KEYCODE_7 = 14; 44 public static final int KEYCODE_8 = 15; 45 public static final int KEYCODE_9 = 16; 46 public static final int KEYCODE_STAR = 17; 47 public static final int KEYCODE_POUND = 18; 48 public static final int KEYCODE_DPAD_UP = 19; 49 public static final int KEYCODE_DPAD_DOWN = 20; 50 public static final int KEYCODE_DPAD_LEFT = 21; 51 public static final int KEYCODE_DPAD_RIGHT = 22; 52 public static final int KEYCODE_DPAD_CENTER = 23; 53 public static final int KEYCODE_VOLUME_UP = 24; 54 public static final int KEYCODE_VOLUME_DOWN = 25; 55 public static final int KEYCODE_POWER = 26; 56 public static final int KEYCODE_CAMERA = 27; 57 public static final int KEYCODE_CLEAR = 28; 58 public static final int KEYCODE_A = 29; 59 public static final int KEYCODE_B = 30; 60 public static final int KEYCODE_C = 31; 61 public static final int KEYCODE_D = 32; 62 public static final int KEYCODE_E = 33; 63 public static final int KEYCODE_F = 34; 64 public static final int KEYCODE_G = 35; 65 public static final int KEYCODE_H = 36; 66 public static final int KEYCODE_I = 37; 67 public static final int KEYCODE_J = 38; 68 public static final int KEYCODE_K = 39; 69 public static final int KEYCODE_L = 40; 70 public static final int KEYCODE_M = 41; 71 public static final int KEYCODE_N = 42; 72 public static final int KEYCODE_O = 43; 73 public static final int KEYCODE_P = 44; 74 public static final int KEYCODE_Q = 45; 75 public static final int KEYCODE_R = 46; 76 public static final int KEYCODE_S = 47; 77 public static final int KEYCODE_T = 48; 78 public static final int KEYCODE_U = 49; 79 public static final int KEYCODE_V = 50; 80 public static final int KEYCODE_W = 51; 81 public static final int KEYCODE_X = 52; 82 public static final int KEYCODE_Y = 53; 83 public static final int KEYCODE_Z = 54; 84 public static final int KEYCODE_COMMA = 55; 85 public static final int KEYCODE_PERIOD = 56; 86 public static final int KEYCODE_ALT_LEFT = 57; 87 public static final int KEYCODE_ALT_RIGHT = 58; 88 public static final int KEYCODE_SHIFT_LEFT = 59; 89 public static final int KEYCODE_SHIFT_RIGHT = 60; 90 public static final int KEYCODE_TAB = 61; 91 public static final int KEYCODE_SPACE = 62; 92 public static final int KEYCODE_SYM = 63; 93 public static final int KEYCODE_EXPLORER = 64; 94 public static final int KEYCODE_ENVELOPE = 65; 95 public static final int KEYCODE_ENTER = 66; 96 public static final int KEYCODE_DEL = 67; 97 public static final int KEYCODE_GRAVE = 68; 98 public static final int KEYCODE_MINUS = 69; 99 public static final int KEYCODE_EQUALS = 70; 100 public static final int KEYCODE_LEFT_BRACKET = 71; 101 public static final int KEYCODE_RIGHT_BRACKET = 72; 102 public static final int KEYCODE_BACKSLASH = 73; 103 public static final int KEYCODE_SEMICOLON = 74; 104 public static final int KEYCODE_APOSTROPHE = 75; 105 public static final int KEYCODE_SLASH = 76; 106 public static final int KEYCODE_AT = 77; 107 public static final int KEYCODE_NUM = 78; 108 public static final int KEYCODE_HEADSETHOOK = 79; 109 public static final int KEYCODE_FOCUS = 80; // *Camera* focus 110 public static final int KEYCODE_PLUS = 81; 111 public static final int KEYCODE_MENU = 82; 112 public static final int KEYCODE_NOTIFICATION = 83; 113 public static final int KEYCODE_SEARCH = 84; 114 public static final int KEYCODE_MEDIA_PLAY_PAUSE= 85; 115 public static final int KEYCODE_MEDIA_STOP = 86; 116 public static final int KEYCODE_MEDIA_NEXT = 87; 117 public static final int KEYCODE_MEDIA_PREVIOUS = 88; 118 public static final int KEYCODE_MEDIA_REWIND = 89; 119 public static final int KEYCODE_MEDIA_FAST_FORWARD = 90; 120 public static final int KEYCODE_MUTE = 91; 121 122 // NOTE: If you add a new keycode here you must also add it to: 123 // isSystem() 124 // frameworks/base/include/ui/KeycodeLabels.h 125 // tools/puppet_master/PuppetMaster/nav_keys.py 126 // frameworks/base/core/res/res/values/attrs.xml 127 // commands/monkey/Monkey.java 128 // emulator? 129 // 130 // Also Android currently does not reserve code ranges for vendor- 131 // specific key codes. If you have new key codes to have, you 132 // MUST contribute a patch to the open source project to define 133 // those new codes. This is intended to maintain a consistent 134 // set of key code definitions across all Android devices. 135 136 private static final int LAST_KEYCODE = KEYCODE_MUTE; 137 138 /** 139 * @deprecated There are now more than MAX_KEYCODE keycodes. 140 * Use {@link #getMaxKeyCode()} instead. 141 */ 142 @Deprecated 143 public static final int MAX_KEYCODE = 84; 144 145 /** 146 * {@link #getAction} value: the key has been pressed down. 147 */ 148 public static final int ACTION_DOWN = 0; 149 /** 150 * {@link #getAction} value: the key has been released. 151 */ 152 public static final int ACTION_UP = 1; 153 /** 154 * {@link #getAction} value: multiple duplicate key events have 155 * occurred in a row, or a complex string is being delivered. If the 156 * key code is not {#link {@link #KEYCODE_UNKNOWN} then the 157 * {#link {@link #getRepeatCount()} method returns the number of times 158 * the given key code should be executed. 159 * Otherwise, if the key code {@link #KEYCODE_UNKNOWN}, then 160 * this is a sequence of characters as returned by {@link #getCharacters}. 161 */ 162 public static final int ACTION_MULTIPLE = 2; 163 164 /** 165 * <p>This mask is used to check whether one of the ALT meta keys is pressed.</p> 166 * 167 * @see #isAltPressed() 168 * @see #getMetaState() 169 * @see #KEYCODE_ALT_LEFT 170 * @see #KEYCODE_ALT_RIGHT 171 */ 172 public static final int META_ALT_ON = 0x02; 173 174 /** 175 * <p>This mask is used to check whether the left ALT meta key is pressed.</p> 176 * 177 * @see #isAltPressed() 178 * @see #getMetaState() 179 * @see #KEYCODE_ALT_LEFT 180 */ 181 public static final int META_ALT_LEFT_ON = 0x10; 182 183 /** 184 * <p>This mask is used to check whether the right the ALT meta key is pressed.</p> 185 * 186 * @see #isAltPressed() 187 * @see #getMetaState() 188 * @see #KEYCODE_ALT_RIGHT 189 */ 190 public static final int META_ALT_RIGHT_ON = 0x20; 191 192 /** 193 * <p>This mask is used to check whether one of the SHIFT meta keys is pressed.</p> 194 * 195 * @see #isShiftPressed() 196 * @see #getMetaState() 197 * @see #KEYCODE_SHIFT_LEFT 198 * @see #KEYCODE_SHIFT_RIGHT 199 */ 200 public static final int META_SHIFT_ON = 0x1; 201 202 /** 203 * <p>This mask is used to check whether the left SHIFT meta key is pressed.</p> 204 * 205 * @see #isShiftPressed() 206 * @see #getMetaState() 207 * @see #KEYCODE_SHIFT_LEFT 208 */ 209 public static final int META_SHIFT_LEFT_ON = 0x40; 210 211 /** 212 * <p>This mask is used to check whether the right SHIFT meta key is pressed.</p> 213 * 214 * @see #isShiftPressed() 215 * @see #getMetaState() 216 * @see #KEYCODE_SHIFT_RIGHT 217 */ 218 public static final int META_SHIFT_RIGHT_ON = 0x80; 219 220 /** 221 * <p>This mask is used to check whether the SYM meta key is pressed.</p> 222 * 223 * @see #isSymPressed() 224 * @see #getMetaState() 225 */ 226 public static final int META_SYM_ON = 0x4; 227 228 /** 229 * This mask is set if the device woke because of this key event. 230 */ 231 public static final int FLAG_WOKE_HERE = 0x1; 232 233 /** 234 * This mask is set if the key event was generated by a software keyboard. 235 */ 236 public static final int FLAG_SOFT_KEYBOARD = 0x2; 237 238 /** 239 * This mask is set if we don't want the key event to cause us to leave 240 * touch mode. 241 */ 242 public static final int FLAG_KEEP_TOUCH_MODE = 0x4; 243 244 /** 245 * This mask is set if an event was known to come from a trusted part 246 * of the system. That is, the event is known to come from the user, 247 * and could not have been spoofed by a third party component. 248 */ 249 public static final int FLAG_FROM_SYSTEM = 0x8; 250 251 /** 252 * This mask is used for compatibility, to identify enter keys that are 253 * coming from an IME whose enter key has been auto-labelled "next" or 254 * "done". This allows TextView to dispatch these as normal enter keys 255 * for old applications, but still do the appropriate action when 256 * receiving them. 257 */ 258 public static final int FLAG_EDITOR_ACTION = 0x10; 259 260 /** 261 * When associated with up key events, this indicates that the key press 262 * has been canceled. Typically this is used with virtual touch screen 263 * keys, where the user can slide from the virtual key area on to the 264 * display: in that case, the application will receive a canceled up 265 * event and should not perform the action normally associated with the 266 * key. Note that for this to work, the application can not perform an 267 * action for a key until it receives an up or the long press timeout has 268 * expired. 269 */ 270 public static final int FLAG_CANCELED = 0x20; 271 272 /** 273 * This key event was generated by a virtual (on-screen) hard key area. 274 * Typically this is an area of the touchscreen, outside of the regular 275 * display, dedicated to "hardware" buttons. 276 */ 277 public static final int FLAG_VIRTUAL_HARD_KEY = 0x40; 278 279 /** 280 * Returns the maximum keycode. 281 */ 282 public static int getMaxKeyCode() { 283 return LAST_KEYCODE; 284 } 285 286 /** 287 * Get the character that is produced by putting accent on the character 288 * c. 289 * For example, getDeadChar('`', 'e') returns è. 290 */ 291 public static int getDeadChar(int accent, int c) { 292 return KeyCharacterMap.getDeadChar(accent, c); 293 } 294 295 private int mMetaState; 296 private int mAction; 297 private int mKeyCode; 298 private int mScancode; 299 private int mRepeatCount; 300 private int mDeviceId; 301 private int mFlags; 302 private long mDownTime; 303 private long mEventTime; 304 private String mCharacters; 305 306 public interface Callback { 307 /** 308 * Called when a key down event has occurred. 309 * 310 * @param keyCode The value in event.getKeyCode(). 311 * @param event Description of the key event. 312 * 313 * @return If you handled the event, return true. If you want to allow 314 * the event to be handled by the next receiver, return false. 315 */ 316 boolean onKeyDown(int keyCode, KeyEvent event); 317 318 /** 319 * Called when a key up event has occurred. 320 * 321 * @param keyCode The value in event.getKeyCode(). 322 * @param event Description of the key event. 323 * 324 * @return If you handled the event, return true. If you want to allow 325 * the event to be handled by the next receiver, return false. 326 */ 327 boolean onKeyUp(int keyCode, KeyEvent event); 328 329 /** 330 * Called when multiple down/up pairs of the same key have occurred 331 * in a row. 332 * 333 * @param keyCode The value in event.getKeyCode(). 334 * @param count Number of pairs as returned by event.getRepeatCount(). 335 * @param event Description of the key event. 336 * 337 * @return If you handled the event, return true. If you want to allow 338 * the event to be handled by the next receiver, return false. 339 */ 340 boolean onKeyMultiple(int keyCode, int count, KeyEvent event); 341 } 342 343 /** 344 * Create a new key event. 345 * 346 * @param action Action code: either {@link #ACTION_DOWN}, 347 * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}. 348 * @param code The key code. 349 */ 350 public KeyEvent(int action, int code) { 351 mAction = action; 352 mKeyCode = code; 353 mRepeatCount = 0; 354 } 355 356 /** 357 * Create a new key event. 358 * 359 * @param downTime The time (in {@link android.os.SystemClock#uptimeMillis}) 360 * at which this key code originally went down. 361 * @param eventTime The time (in {@link android.os.SystemClock#uptimeMillis}) 362 * at which this event happened. 363 * @param action Action code: either {@link #ACTION_DOWN}, 364 * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}. 365 * @param code The key code. 366 * @param repeat A repeat count for down events (> 0 if this is after the 367 * initial down) or event count for multiple events. 368 */ 369 public KeyEvent(long downTime, long eventTime, int action, 370 int code, int repeat) { 371 mDownTime = downTime; 372 mEventTime = eventTime; 373 mAction = action; 374 mKeyCode = code; 375 mRepeatCount = repeat; 376 } 377 378 /** 379 * Create a new key event. 380 * 381 * @param downTime The time (in {@link android.os.SystemClock#uptimeMillis}) 382 * at which this key code originally went down. 383 * @param eventTime The time (in {@link android.os.SystemClock#uptimeMillis}) 384 * at which this event happened. 385 * @param action Action code: either {@link #ACTION_DOWN}, 386 * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}. 387 * @param code The key code. 388 * @param repeat A repeat count for down events (> 0 if this is after the 389 * initial down) or event count for multiple events. 390 * @param metaState Flags indicating which meta keys are currently pressed. 391 */ 392 public KeyEvent(long downTime, long eventTime, int action, 393 int code, int repeat, int metaState) { 394 mDownTime = downTime; 395 mEventTime = eventTime; 396 mAction = action; 397 mKeyCode = code; 398 mRepeatCount = repeat; 399 mMetaState = metaState; 400 } 401 402 /** 403 * Create a new key event. 404 * 405 * @param downTime The time (in {@link android.os.SystemClock#uptimeMillis}) 406 * at which this key code originally went down. 407 * @param eventTime The time (in {@link android.os.SystemClock#uptimeMillis}) 408 * at which this event happened. 409 * @param action Action code: either {@link #ACTION_DOWN}, 410 * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}. 411 * @param code The key code. 412 * @param repeat A repeat count for down events (> 0 if this is after the 413 * initial down) or event count for multiple events. 414 * @param metaState Flags indicating which meta keys are currently pressed. 415 * @param device The device ID that generated the key event. 416 * @param scancode Raw device scan code of the event. 417 */ 418 public KeyEvent(long downTime, long eventTime, int action, 419 int code, int repeat, int metaState, 420 int device, int scancode) { 421 mDownTime = downTime; 422 mEventTime = eventTime; 423 mAction = action; 424 mKeyCode = code; 425 mRepeatCount = repeat; 426 mMetaState = metaState; 427 mDeviceId = device; 428 mScancode = scancode; 429 } 430 431 /** 432 * Create a new key event. 433 * 434 * @param downTime The time (in {@link android.os.SystemClock#uptimeMillis}) 435 * at which this key code originally went down. 436 * @param eventTime The time (in {@link android.os.SystemClock#uptimeMillis}) 437 * at which this event happened. 438 * @param action Action code: either {@link #ACTION_DOWN}, 439 * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}. 440 * @param code The key code. 441 * @param repeat A repeat count for down events (> 0 if this is after the 442 * initial down) or event count for multiple events. 443 * @param metaState Flags indicating which meta keys are currently pressed. 444 * @param device The device ID that generated the key event. 445 * @param scancode Raw device scan code of the event. 446 * @param flags The flags for this key event 447 */ 448 public KeyEvent(long downTime, long eventTime, int action, 449 int code, int repeat, int metaState, 450 int device, int scancode, int flags) { 451 mDownTime = downTime; 452 mEventTime = eventTime; 453 mAction = action; 454 mKeyCode = code; 455 mRepeatCount = repeat; 456 mMetaState = metaState; 457 mDeviceId = device; 458 mScancode = scancode; 459 mFlags = flags; 460 } 461 462 /** 463 * Create a new key event for a string of characters. The key code, 464 * action, and repeat could will automatically be set to 465 * {@link #KEYCODE_UNKNOWN}, {@link #ACTION_MULTIPLE}, and 0 for you. 466 * 467 * @param time The time (in {@link android.os.SystemClock#uptimeMillis}) 468 * at which this event occured. 469 * @param characters The string of characters. 470 * @param device The device ID that generated the key event. 471 * @param flags The flags for this key event 472 */ 473 public KeyEvent(long time, String characters, int device, int flags) { 474 mDownTime = time; 475 mEventTime = time; 476 mCharacters = characters; 477 mAction = ACTION_MULTIPLE; 478 mKeyCode = KEYCODE_UNKNOWN; 479 mRepeatCount = 0; 480 mDeviceId = device; 481 mFlags = flags; 482 } 483 484 /** 485 * Make an exact copy of an existing key event. 486 */ 487 public KeyEvent(KeyEvent origEvent) { 488 mDownTime = origEvent.mDownTime; 489 mEventTime = origEvent.mEventTime; 490 mAction = origEvent.mAction; 491 mKeyCode = origEvent.mKeyCode; 492 mRepeatCount = origEvent.mRepeatCount; 493 mMetaState = origEvent.mMetaState; 494 mDeviceId = origEvent.mDeviceId; 495 mScancode = origEvent.mScancode; 496 mFlags = origEvent.mFlags; 497 mCharacters = origEvent.mCharacters; 498 } 499 500 /** 501 * Copy an existing key event, modifying its time and repeat count. 502 * 503 * @param origEvent The existing event to be copied. 504 * @param eventTime The new event time 505 * (in {@link android.os.SystemClock#uptimeMillis}) of the event. 506 * @param newRepeat The new repeat count of the event. 507 */ 508 public KeyEvent(KeyEvent origEvent, long eventTime, int newRepeat) { 509 mDownTime = origEvent.mDownTime; 510 mEventTime = eventTime; 511 mAction = origEvent.mAction; 512 mKeyCode = origEvent.mKeyCode; 513 mRepeatCount = newRepeat; 514 mMetaState = origEvent.mMetaState; 515 mDeviceId = origEvent.mDeviceId; 516 mScancode = origEvent.mScancode; 517 mFlags = origEvent.mFlags; 518 mCharacters = origEvent.mCharacters; 519 } 520 521 /** 522 * Create a new key event that is the same as the given one, but whose 523 * event time and repeat count are replaced with the given value. 524 * 525 * @param event The existing event to be copied. This is not modified. 526 * @param eventTime The new event time 527 * (in {@link android.os.SystemClock#uptimeMillis}) of the event. 528 * @param newRepeat The new repeat count of the event. 529 */ 530 public static KeyEvent changeTimeRepeat(KeyEvent event, long eventTime, 531 int newRepeat) { 532 return new KeyEvent(event, eventTime, newRepeat); 533 } 534 535 /** 536 * Copy an existing key event, modifying its action. 537 * 538 * @param origEvent The existing event to be copied. 539 * @param action The new action code of the event. 540 */ 541 private KeyEvent(KeyEvent origEvent, int action) { 542 mDownTime = origEvent.mDownTime; 543 mEventTime = origEvent.mEventTime; 544 mAction = action; 545 mKeyCode = origEvent.mKeyCode; 546 mRepeatCount = origEvent.mRepeatCount; 547 mMetaState = origEvent.mMetaState; 548 mDeviceId = origEvent.mDeviceId; 549 mScancode = origEvent.mScancode; 550 mFlags = origEvent.mFlags; 551 // Don't copy mCharacters, since one way or the other we'll lose it 552 // when changing the action. 553 } 554 555 /** 556 * Create a new key event that is the same as the given one, but whose 557 * action is replaced with the given value. 558 * 559 * @param event The existing event to be copied. This is not modified. 560 * @param action The new action code of the event. 561 */ 562 public static KeyEvent changeAction(KeyEvent event, int action) { 563 return new KeyEvent(event, action); 564 } 565 566 /** 567 * Create a new key event that is the same as the given one, but whose 568 * flags are replaced with the given value. 569 * 570 * @param event The existing event to be copied. This is not modified. 571 * @param flags The new flags constant. 572 */ 573 public static KeyEvent changeFlags(KeyEvent event, int flags) { 574 event = new KeyEvent(event); 575 event.mFlags = flags; 576 return event; 577 } 578 579 /** 580 * Don't use in new code, instead explicitly check 581 * {@link #getAction()}. 582 * 583 * @return If the action is ACTION_DOWN, returns true; else false. 584 * 585 * @deprecated 586 * @hide 587 */ 588 @Deprecated public final boolean isDown() { 589 return mAction == ACTION_DOWN; 590 } 591 592 /** 593 * Is this a system key? System keys can not be used for menu shortcuts. 594 * 595 * TODO: this information should come from a table somewhere. 596 * TODO: should the dpad keys be here? arguably, because they also shouldn't be menu shortcuts 597 */ 598 public final boolean isSystem() { 599 switch (mKeyCode) { 600 case KEYCODE_MENU: 601 case KEYCODE_SOFT_RIGHT: 602 case KEYCODE_HOME: 603 case KEYCODE_BACK: 604 case KEYCODE_CALL: 605 case KEYCODE_ENDCALL: 606 case KEYCODE_VOLUME_UP: 607 case KEYCODE_VOLUME_DOWN: 608 case KEYCODE_MUTE: 609 case KEYCODE_POWER: 610 case KEYCODE_HEADSETHOOK: 611 case KEYCODE_MEDIA_PLAY_PAUSE: 612 case KEYCODE_MEDIA_STOP: 613 case KEYCODE_MEDIA_NEXT: 614 case KEYCODE_MEDIA_PREVIOUS: 615 case KEYCODE_MEDIA_REWIND: 616 case KEYCODE_MEDIA_FAST_FORWARD: 617 case KEYCODE_CAMERA: 618 case KEYCODE_FOCUS: 619 case KEYCODE_SEARCH: 620 return true; 621 default: 622 return false; 623 } 624 } 625 626 627 /** 628 * <p>Returns the state of the meta keys.</p> 629 * 630 * @return an integer in which each bit set to 1 represents a pressed 631 * meta key 632 * 633 * @see #isAltPressed() 634 * @see #isShiftPressed() 635 * @see #isSymPressed() 636 * @see #META_ALT_ON 637 * @see #META_SHIFT_ON 638 * @see #META_SYM_ON 639 */ 640 public final int getMetaState() { 641 return mMetaState; 642 } 643 644 /** 645 * Returns the flags for this key event. 646 * 647 * @see #FLAG_WOKE_HERE 648 */ 649 public final int getFlags() { 650 return mFlags; 651 } 652 653 /** 654 * Returns true if this key code is a modifier key. 655 * 656 * @return whether the provided keyCode is one of 657 * {@link #KEYCODE_SHIFT_LEFT} {@link #KEYCODE_SHIFT_RIGHT}, 658 * {@link #KEYCODE_ALT_LEFT}, {@link #KEYCODE_ALT_RIGHT} 659 * or {@link #KEYCODE_SYM}. 660 */ 661 public static boolean isModifierKey(int keyCode) { 662 return keyCode == KEYCODE_SHIFT_LEFT || keyCode == KEYCODE_SHIFT_RIGHT 663 || keyCode == KEYCODE_ALT_LEFT || keyCode == KEYCODE_ALT_RIGHT 664 || keyCode == KEYCODE_SYM; 665 } 666 667 /** 668 * <p>Returns the pressed state of the ALT meta key.</p> 669 * 670 * @return true if the ALT key is pressed, false otherwise 671 * 672 * @see #KEYCODE_ALT_LEFT 673 * @see #KEYCODE_ALT_RIGHT 674 * @see #META_ALT_ON 675 */ 676 public final boolean isAltPressed() { 677 return (mMetaState & META_ALT_ON) != 0; 678 } 679 680 /** 681 * <p>Returns the pressed state of the SHIFT meta key.</p> 682 * 683 * @return true if the SHIFT key is pressed, false otherwise 684 * 685 * @see #KEYCODE_SHIFT_LEFT 686 * @see #KEYCODE_SHIFT_RIGHT 687 * @see #META_SHIFT_ON 688 */ 689 public final boolean isShiftPressed() { 690 return (mMetaState & META_SHIFT_ON) != 0; 691 } 692 693 /** 694 * <p>Returns the pressed state of the SYM meta key.</p> 695 * 696 * @return true if the SYM key is pressed, false otherwise 697 * 698 * @see #KEYCODE_SYM 699 * @see #META_SYM_ON 700 */ 701 public final boolean isSymPressed() { 702 return (mMetaState & META_SYM_ON) != 0; 703 } 704 705 /** 706 * Retrieve the action of this key event. May be either 707 * {@link #ACTION_DOWN}, {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}. 708 * 709 * @return The event action: ACTION_DOWN, ACTION_UP, or ACTION_MULTIPLE. 710 */ 711 public final int getAction() { 712 return mAction; 713 } 714 715 /** 716 * For {@link #ACTION_UP} events, indicates that the event has been 717 * canceled as per {@link #FLAG_CANCELED}. 718 */ 719 public final boolean isCanceled() { 720 return (mFlags&FLAG_CANCELED) != 0; 721 } 722 723 /** 724 * Retrieve the key code of the key event. This is the physical key that 725 * was pressed, <em>not</em> the Unicode character. 726 * 727 * @return The key code of the event. 728 */ 729 public final int getKeyCode() { 730 return mKeyCode; 731 } 732 733 /** 734 * For the special case of a {@link #ACTION_MULTIPLE} event with key 735 * code of {@link #KEYCODE_UNKNOWN}, this is a raw string of characters 736 * associated with the event. In all other cases it is null. 737 * 738 * @return Returns a String of 1 or more characters associated with 739 * the event. 740 */ 741 public final String getCharacters() { 742 return mCharacters; 743 } 744 745 /** 746 * Retrieve the hardware key id of this key event. These values are not 747 * reliable and vary from device to device. 748 * 749 * {@more} 750 * Mostly this is here for debugging purposes. 751 */ 752 public final int getScanCode() { 753 return mScancode; 754 } 755 756 /** 757 * Retrieve the repeat count of the event. For both key up and key down 758 * events, this is the number of times the key has repeated with the first 759 * down starting at 0 and counting up from there. For multiple key 760 * events, this is the number of down/up pairs that have occurred. 761 * 762 * @return The number of times the key has repeated. 763 */ 764 public final int getRepeatCount() { 765 return mRepeatCount; 766 } 767 768 /** 769 * Retrieve the time of the most recent key down event, 770 * in the {@link android.os.SystemClock#uptimeMillis} time base. If this 771 * is a down event, this will be the same as {@link #getEventTime()}. 772 * Note that when chording keys, this value is the down time of the 773 * most recently pressed key, which may <em>not</em> be the same physical 774 * key of this event. 775 * 776 * @return Returns the most recent key down time, in the 777 * {@link android.os.SystemClock#uptimeMillis} time base 778 */ 779 public final long getDownTime() { 780 return mDownTime; 781 } 782 783 /** 784 * Retrieve the time this event occurred, 785 * in the {@link android.os.SystemClock#uptimeMillis} time base. 786 * 787 * @return Returns the time this event occurred, 788 * in the {@link android.os.SystemClock#uptimeMillis} time base. 789 */ 790 public final long getEventTime() { 791 return mEventTime; 792 } 793 794 /** 795 * Return the id for the keyboard that this event came from. A device 796 * id of 0 indicates the event didn't come from a physical device and 797 * maps to the default keymap. The other numbers are arbitrary and 798 * you shouldn't depend on the values. 799 * 800 * @see KeyCharacterMap#load 801 */ 802 public final int getDeviceId() { 803 return mDeviceId; 804 } 805 806 /** 807 * Renamed to {@link #getDeviceId}. 808 * 809 * @hide 810 * @deprecated 811 */ 812 public final int getKeyboardDevice() { 813 return mDeviceId; 814 } 815 816 /** 817 * Get the primary character for this key. In other words, the label 818 * that is physically printed on it. 819 */ 820 public char getDisplayLabel() { 821 return KeyCharacterMap.load(mDeviceId).getDisplayLabel(mKeyCode); 822 } 823 824 /** 825 * <p> 826 * Returns the Unicode character that the key would produce. 827 * </p><p> 828 * Returns 0 if the key is not one that is used to type Unicode 829 * characters. 830 * </p><p> 831 * If the return value has bit 832 * {@link KeyCharacterMap#COMBINING_ACCENT} 833 * set, the key is a "dead key" that should be combined with another to 834 * actually produce a character -- see {@link #getDeadChar} -- 835 * after masking with 836 * {@link KeyCharacterMap#COMBINING_ACCENT_MASK}. 837 * </p> 838 */ 839 public int getUnicodeChar() { 840 return getUnicodeChar(mMetaState); 841 } 842 843 /** 844 * <p> 845 * Returns the Unicode character that the key would produce. 846 * </p><p> 847 * Returns 0 if the key is not one that is used to type Unicode 848 * characters. 849 * </p><p> 850 * If the return value has bit 851 * {@link KeyCharacterMap#COMBINING_ACCENT} 852 * set, the key is a "dead key" that should be combined with another to 853 * actually produce a character -- see {@link #getDeadChar} -- after masking 854 * with {@link KeyCharacterMap#COMBINING_ACCENT_MASK}. 855 * </p> 856 */ 857 public int getUnicodeChar(int meta) { 858 return KeyCharacterMap.load(mDeviceId).get(mKeyCode, meta); 859 } 860 861 /** 862 * Get the characters conversion data for the key event.. 863 * 864 * @param results a {@link KeyData} that will be filled with the results. 865 * 866 * @return whether the key was mapped or not. If the key was not mapped, 867 * results is not modified. 868 */ 869 public boolean getKeyData(KeyData results) { 870 return KeyCharacterMap.load(mDeviceId).getKeyData(mKeyCode, results); 871 } 872 873 /** 874 * The same as {@link #getMatch(char[],int) getMatch(chars, 0)}. 875 */ 876 public char getMatch(char[] chars) { 877 return getMatch(chars, 0); 878 } 879 880 /** 881 * If one of the chars in the array can be generated by the keyCode of this 882 * key event, return the char; otherwise return '\0'. 883 * @param chars the characters to try to find 884 * @param modifiers the modifier bits to prefer. If any of these bits 885 * are set, if there are multiple choices, that could 886 * work, the one for this modifier will be set. 887 */ 888 public char getMatch(char[] chars, int modifiers) { 889 return KeyCharacterMap.load(mDeviceId).getMatch(mKeyCode, chars, modifiers); 890 } 891 892 /** 893 * Gets the number or symbol associated with the key. The character value 894 * is returned, not the numeric value. If the key is not a number, but is 895 * a symbol, the symbol is retuned. 896 */ 897 public char getNumber() { 898 return KeyCharacterMap.load(mDeviceId).getNumber(mKeyCode); 899 } 900 901 /** 902 * Does the key code of this key produce a glyph? 903 */ 904 public boolean isPrintingKey() { 905 return KeyCharacterMap.load(mDeviceId).isPrintingKey(mKeyCode); 906 } 907 908 /** 909 * Deliver this key event to a {@link Callback} interface. If this is 910 * an ACTION_MULTIPLE event and it is not handled, then an attempt will 911 * be made to deliver a single normal event. 912 * 913 * @param receiver The Callback that will be given the event. 914 * 915 * @return The return value from the Callback method that was called. 916 */ 917 public final boolean dispatch(Callback receiver) { 918 switch (mAction) { 919 case ACTION_DOWN: 920 return receiver.onKeyDown(mKeyCode, this); 921 case ACTION_UP: 922 return receiver.onKeyUp(mKeyCode, this); 923 case ACTION_MULTIPLE: 924 final int count = mRepeatCount; 925 final int code = mKeyCode; 926 if (receiver.onKeyMultiple(code, count, this)) { 927 return true; 928 } 929 if (code != KeyEvent.KEYCODE_UNKNOWN) { 930 mAction = ACTION_DOWN; 931 mRepeatCount = 0; 932 boolean handled = receiver.onKeyDown(code, this); 933 if (handled) { 934 mAction = ACTION_UP; 935 receiver.onKeyUp(code, this); 936 } 937 mAction = ACTION_MULTIPLE; 938 mRepeatCount = count; 939 return handled; 940 } 941 } 942 return false; 943 } 944 945 public String toString() { 946 return "KeyEvent{action=" + mAction + " code=" + mKeyCode 947 + " repeat=" + mRepeatCount 948 + " meta=" + mMetaState + " scancode=" + mScancode 949 + " mFlags=" + mFlags + "}"; 950 } 951 952 public static final Parcelable.Creator<KeyEvent> CREATOR 953 = new Parcelable.Creator<KeyEvent>() { 954 public KeyEvent createFromParcel(Parcel in) { 955 return new KeyEvent(in); 956 } 957 958 public KeyEvent[] newArray(int size) { 959 return new KeyEvent[size]; 960 } 961 }; 962 963 public int describeContents() { 964 return 0; 965 } 966 967 public void writeToParcel(Parcel out, int flags) { 968 out.writeInt(mAction); 969 out.writeInt(mKeyCode); 970 out.writeInt(mRepeatCount); 971 out.writeInt(mMetaState); 972 out.writeInt(mDeviceId); 973 out.writeInt(mScancode); 974 out.writeInt(mFlags); 975 out.writeLong(mDownTime); 976 out.writeLong(mEventTime); 977 } 978 979 private KeyEvent(Parcel in) { 980 mAction = in.readInt(); 981 mKeyCode = in.readInt(); 982 mRepeatCount = in.readInt(); 983 mMetaState = in.readInt(); 984 mDeviceId = in.readInt(); 985 mScancode = in.readInt(); 986 mFlags = in.readInt(); 987 mDownTime = in.readLong(); 988 mEventTime = in.readLong(); 989 } 990} 991