KeyEvent.java revision 9066cfe9886ac131c34d59ed0e2d287b0e3c0087
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_PLAYPAUSE = 85; 115 public static final int KEYCODE_STOP = 86; 116 public static final int KEYCODE_NEXTSONG = 87; 117 public static final int KEYCODE_PREVIOUSSONG = 88; 118 public static final int KEYCODE_REWIND = 89; 119 public static final int KEYCODE_FORWARD = 90; 120 public static final int KEYCODE_MUTE = 91; 121 private static final int LAST_KEYCODE = KEYCODE_MUTE; 122 123 // NOTE: If you add a new keycode here you must also add it to: 124 // isSystem() 125 // frameworks/base/include/ui/KeycodeLabels.h 126 // tools/puppet_master/PuppetMaster/nav_keys.py 127 // frameworks/base/core/res/res/values/attrs.xml 128 // commands/monkey/Monkey.java 129 // emulator? 130 131 /** 132 * @deprecated There are now more than MAX_KEYCODE keycodes. 133 * Use {@link #getMaxKeyCode()} instead. 134 */ 135 @Deprecated 136 public static final int MAX_KEYCODE = 84; 137 138 /** 139 * {@link #getAction} value: the key has been pressed down. 140 */ 141 public static final int ACTION_DOWN = 0; 142 /** 143 * {@link #getAction} value: the key has been released. 144 */ 145 public static final int ACTION_UP = 1; 146 /** 147 * {@link #getAction} value: multiple duplicate key events have 148 * occurred in a row, or a complex string is being delivered. If the 149 * key code is not {#link {@link #KEYCODE_UNKNOWN} then the 150 * {#link {@link #getRepeatCount()} method returns the number of times 151 * the given key code should be executed. 152 * Otherwise, if the key code {@link #KEYCODE_UNKNOWN}, then 153 * this is a sequence of characters as returned by {@link #getCharacters}. 154 */ 155 public static final int ACTION_MULTIPLE = 2; 156 157 /** 158 * <p>This mask is used to check whether one of the ALT meta keys is pressed.</p> 159 * 160 * @see #isAltPressed() 161 * @see #getMetaState() 162 * @see #KEYCODE_ALT_LEFT 163 * @see #KEYCODE_ALT_RIGHT 164 */ 165 public static final int META_ALT_ON = 0x02; 166 167 /** 168 * <p>This mask is used to check whether the left ALT meta key is pressed.</p> 169 * 170 * @see #isAltPressed() 171 * @see #getMetaState() 172 * @see #KEYCODE_ALT_LEFT 173 */ 174 public static final int META_ALT_LEFT_ON = 0x10; 175 176 /** 177 * <p>This mask is used to check whether the right the ALT meta key is pressed.</p> 178 * 179 * @see #isAltPressed() 180 * @see #getMetaState() 181 * @see #KEYCODE_ALT_RIGHT 182 */ 183 public static final int META_ALT_RIGHT_ON = 0x20; 184 185 /** 186 * <p>This mask is used to check whether one of the SHIFT meta keys is pressed.</p> 187 * 188 * @see #isShiftPressed() 189 * @see #getMetaState() 190 * @see #KEYCODE_SHIFT_LEFT 191 * @see #KEYCODE_SHIFT_RIGHT 192 */ 193 public static final int META_SHIFT_ON = 0x1; 194 195 /** 196 * <p>This mask is used to check whether the left SHIFT meta key is pressed.</p> 197 * 198 * @see #isShiftPressed() 199 * @see #getMetaState() 200 * @see #KEYCODE_SHIFT_LEFT 201 */ 202 public static final int META_SHIFT_LEFT_ON = 0x40; 203 204 /** 205 * <p>This mask is used to check whether the right SHIFT meta key is pressed.</p> 206 * 207 * @see #isShiftPressed() 208 * @see #getMetaState() 209 * @see #KEYCODE_SHIFT_RIGHT 210 */ 211 public static final int META_SHIFT_RIGHT_ON = 0x80; 212 213 /** 214 * <p>This mask is used to check whether the SYM meta key is pressed.</p> 215 * 216 * @see #isSymPressed() 217 * @see #getMetaState() 218 */ 219 public static final int META_SYM_ON = 0x4; 220 221 /** 222 * This mask is set if the device woke because of this key event. 223 */ 224 public static final int FLAG_WOKE_HERE = 0x1; 225 226 /** 227 * This mask is set if the key event was generated by a software keyboard. 228 */ 229 public static final int FLAG_SOFT_KEYBOARD = 0x2; 230 231 /** 232 * This mask is set if we don't want the key event to cause us to leave 233 * touch mode. 234 */ 235 public static final int FLAG_KEEP_TOUCH_MODE = 0x4; 236 237 /** 238 * Returns the maximum keycode. 239 */ 240 public static int getMaxKeyCode() { 241 return LAST_KEYCODE; 242 } 243 244 /** 245 * Get the character that is produced by putting accent on the character 246 * c. 247 * For example, getDeadChar('`', 'e') returns è. 248 */ 249 public static int getDeadChar(int accent, int c) { 250 return KeyCharacterMap.getDeadChar(accent, c); 251 } 252 253 private int mMetaState; 254 private int mAction; 255 private int mKeyCode; 256 private int mScancode; 257 private int mRepeatCount; 258 private int mDeviceId; 259 private int mFlags; 260 private long mDownTime; 261 private long mEventTime; 262 private String mCharacters; 263 264 public interface Callback { 265 /** 266 * Called when a key down event has occurred. 267 * 268 * @param keyCode The value in event.getKeyCode(). 269 * @param event Description of the key event. 270 * 271 * @return If you handled the event, return true. If you want to allow 272 * the event to be handled by the next receiver, return false. 273 */ 274 boolean onKeyDown(int keyCode, KeyEvent event); 275 276 /** 277 * Called when a key up event has occurred. 278 * 279 * @param keyCode The value in event.getKeyCode(). 280 * @param event Description of the key event. 281 * 282 * @return If you handled the event, return true. If you want to allow 283 * the event to be handled by the next receiver, return false. 284 */ 285 boolean onKeyUp(int keyCode, KeyEvent event); 286 287 /** 288 * Called when multiple down/up pairs of the same key have occurred 289 * in a row. 290 * 291 * @param keyCode The value in event.getKeyCode(). 292 * @param count Number of pairs as returned by event.getRepeatCount(). 293 * @param event Description of the key event. 294 * 295 * @return If you handled the event, return true. If you want to allow 296 * the event to be handled by the next receiver, return false. 297 */ 298 boolean onKeyMultiple(int keyCode, int count, KeyEvent event); 299 } 300 301 /** 302 * Create a new key event. 303 * 304 * @param action Action code: either {@link #ACTION_DOWN}, 305 * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}. 306 * @param code The key code. 307 */ 308 public KeyEvent(int action, int code) { 309 mAction = action; 310 mKeyCode = code; 311 mRepeatCount = 0; 312 } 313 314 /** 315 * Create a new key event. 316 * 317 * @param downTime The time (in {@link android.os.SystemClock#uptimeMillis}) 318 * at which this key code originally went down. 319 * @param eventTime The time (in {@link android.os.SystemClock#uptimeMillis}) 320 * at which this event happened. 321 * @param action Action code: either {@link #ACTION_DOWN}, 322 * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}. 323 * @param code The key code. 324 * @param repeat A repeat count for down events (> 0 if this is after the 325 * initial down) or event count for multiple events. 326 */ 327 public KeyEvent(long downTime, long eventTime, int action, 328 int code, int repeat) { 329 mDownTime = downTime; 330 mEventTime = eventTime; 331 mAction = action; 332 mKeyCode = code; 333 mRepeatCount = repeat; 334 } 335 336 /** 337 * Create a new key event. 338 * 339 * @param downTime The time (in {@link android.os.SystemClock#uptimeMillis}) 340 * at which this key code originally went down. 341 * @param eventTime The time (in {@link android.os.SystemClock#uptimeMillis}) 342 * at which this event happened. 343 * @param action Action code: either {@link #ACTION_DOWN}, 344 * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}. 345 * @param code The key code. 346 * @param repeat A repeat count for down events (> 0 if this is after the 347 * initial down) or event count for multiple events. 348 * @param metaState Flags indicating which meta keys are currently pressed. 349 */ 350 public KeyEvent(long downTime, long eventTime, int action, 351 int code, int repeat, int metaState) { 352 mDownTime = downTime; 353 mEventTime = eventTime; 354 mAction = action; 355 mKeyCode = code; 356 mRepeatCount = repeat; 357 mMetaState = metaState; 358 } 359 360 /** 361 * Create a new key event. 362 * 363 * @param downTime The time (in {@link android.os.SystemClock#uptimeMillis}) 364 * at which this key code originally went down. 365 * @param eventTime The time (in {@link android.os.SystemClock#uptimeMillis}) 366 * at which this event happened. 367 * @param action Action code: either {@link #ACTION_DOWN}, 368 * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}. 369 * @param code The key code. 370 * @param repeat A repeat count for down events (> 0 if this is after the 371 * initial down) or event count for multiple events. 372 * @param metaState Flags indicating which meta keys are currently pressed. 373 * @param device The device ID that generated the key event. 374 * @param scancode Raw device scan code of the event. 375 */ 376 public KeyEvent(long downTime, long eventTime, int action, 377 int code, int repeat, int metaState, 378 int device, int scancode) { 379 mDownTime = downTime; 380 mEventTime = eventTime; 381 mAction = action; 382 mKeyCode = code; 383 mRepeatCount = repeat; 384 mMetaState = metaState; 385 mDeviceId = device; 386 mScancode = scancode; 387 } 388 389 /** 390 * Create a new key event. 391 * 392 * @param downTime The time (in {@link android.os.SystemClock#uptimeMillis}) 393 * at which this key code originally went down. 394 * @param eventTime The time (in {@link android.os.SystemClock#uptimeMillis}) 395 * at which this event happened. 396 * @param action Action code: either {@link #ACTION_DOWN}, 397 * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}. 398 * @param code The key code. 399 * @param repeat A repeat count for down events (> 0 if this is after the 400 * initial down) or event count for multiple events. 401 * @param metaState Flags indicating which meta keys are currently pressed. 402 * @param device The device ID that generated the key event. 403 * @param scancode Raw device scan code of the event. 404 * @param flags The flags for this key event 405 */ 406 public KeyEvent(long downTime, long eventTime, int action, 407 int code, int repeat, int metaState, 408 int device, int scancode, int flags) { 409 mDownTime = downTime; 410 mEventTime = eventTime; 411 mAction = action; 412 mKeyCode = code; 413 mRepeatCount = repeat; 414 mMetaState = metaState; 415 mDeviceId = device; 416 mScancode = scancode; 417 mFlags = flags; 418 } 419 420 /** 421 * Create a new key event for a string of characters. The key code, 422 * action, and repeat could will automatically be set to 423 * {@link #KEYCODE_UNKNOWN}, {@link #ACTION_MULTIPLE}, and 0 for you. 424 * 425 * @param time The time (in {@link android.os.SystemClock#uptimeMillis}) 426 * at which this event occured. 427 * @param characters The string of characters. 428 * @param device The device ID that generated the key event. 429 * @param flags The flags for this key event 430 */ 431 public KeyEvent(long time, String characters, int device, int flags) { 432 mDownTime = time; 433 mEventTime = time; 434 mCharacters = characters; 435 mAction = ACTION_MULTIPLE; 436 mKeyCode = KEYCODE_UNKNOWN; 437 mRepeatCount = 0; 438 mDeviceId = device; 439 mFlags = flags; 440 } 441 442 /** 443 * Copy an existing key event, modifying its time and repeat count. 444 * 445 * @param origEvent The existing event to be copied. 446 * @param eventTime The new event time 447 * (in {@link android.os.SystemClock#uptimeMillis}) of the event. 448 * @param newRepeat The new repeat count of the event. 449 */ 450 public KeyEvent(KeyEvent origEvent, long eventTime, int newRepeat) { 451 mDownTime = origEvent.mDownTime; 452 mEventTime = eventTime; 453 mAction = origEvent.mAction; 454 mKeyCode = origEvent.mKeyCode; 455 mRepeatCount = newRepeat; 456 mMetaState = origEvent.mMetaState; 457 mDeviceId = origEvent.mDeviceId; 458 mScancode = origEvent.mScancode; 459 mFlags = origEvent.mFlags; 460 mCharacters = origEvent.mCharacters; 461 } 462 463 /** 464 * Copy an existing key event, modifying its action. 465 * 466 * @param origEvent The existing event to be copied. 467 * @param action The new action code of the event. 468 */ 469 public KeyEvent(KeyEvent origEvent, int action) { 470 mDownTime = origEvent.mDownTime; 471 mEventTime = origEvent.mEventTime; 472 mAction = action; 473 mKeyCode = origEvent.mKeyCode; 474 mRepeatCount = origEvent.mRepeatCount; 475 mMetaState = origEvent.mMetaState; 476 mDeviceId = origEvent.mDeviceId; 477 mScancode = origEvent.mScancode; 478 mFlags = origEvent.mFlags; 479 // Don't copy mCharacters, since one way or the other we'll lose it 480 // when changing the action. 481 } 482 483 /** 484 * Don't use in new code, instead explicitly check 485 * {@link #getAction()}. 486 * 487 * @return If the action is ACTION_DOWN, returns true; else false. 488 * 489 * @deprecated 490 * @hide 491 */ 492 @Deprecated public final boolean isDown() { 493 return mAction == ACTION_DOWN; 494 } 495 496 /** 497 * Is this a system key? System keys can not be used for menu shortcuts. 498 * 499 * TODO: this information should come from a table somewhere. 500 * TODO: should the dpad keys be here? arguably, because they also shouldn't be menu shortcuts 501 */ 502 public final boolean isSystem() { 503 switch (mKeyCode) { 504 case KEYCODE_MENU: 505 case KEYCODE_SOFT_RIGHT: 506 case KEYCODE_HOME: 507 case KEYCODE_BACK: 508 case KEYCODE_CALL: 509 case KEYCODE_ENDCALL: 510 case KEYCODE_VOLUME_UP: 511 case KEYCODE_VOLUME_DOWN: 512 case KEYCODE_MUTE: 513 case KEYCODE_POWER: 514 case KEYCODE_HEADSETHOOK: 515 case KEYCODE_PLAYPAUSE: 516 case KEYCODE_STOP: 517 case KEYCODE_NEXTSONG: 518 case KEYCODE_PREVIOUSSONG: 519 case KEYCODE_REWIND: 520 case KEYCODE_FORWARD: 521 case KEYCODE_CAMERA: 522 case KEYCODE_FOCUS: 523 case KEYCODE_SEARCH: 524 return true; 525 default: 526 return false; 527 } 528 } 529 530 531 /** 532 * <p>Returns the state of the meta keys.</p> 533 * 534 * @return an integer in which each bit set to 1 represents a pressed 535 * meta key 536 * 537 * @see #isAltPressed() 538 * @see #isShiftPressed() 539 * @see #isSymPressed() 540 * @see #META_ALT_ON 541 * @see #META_SHIFT_ON 542 * @see #META_SYM_ON 543 */ 544 public final int getMetaState() { 545 return mMetaState; 546 } 547 548 /** 549 * Returns the flags for this key event. 550 * 551 * @see #FLAG_WOKE_HERE 552 */ 553 public final int getFlags() { 554 return mFlags; 555 } 556 557 /** 558 * Returns true if this key code is a modifier key. 559 * 560 * @return whether the provided keyCode is one of 561 * {@link #KEYCODE_SHIFT_LEFT} {@link #KEYCODE_SHIFT_RIGHT}, 562 * {@link #KEYCODE_ALT_LEFT}, {@link #KEYCODE_ALT_RIGHT} 563 * or {@link #KEYCODE_SYM}. 564 */ 565 public static boolean isModifierKey(int keyCode) { 566 return keyCode == KEYCODE_SHIFT_LEFT || keyCode == KEYCODE_SHIFT_RIGHT 567 || keyCode == KEYCODE_ALT_LEFT || keyCode == KEYCODE_ALT_RIGHT 568 || keyCode == KEYCODE_SYM; 569 } 570 571 /** 572 * <p>Returns the pressed state of the ALT meta key.</p> 573 * 574 * @return true if the ALT key is pressed, false otherwise 575 * 576 * @see #KEYCODE_ALT_LEFT 577 * @see #KEYCODE_ALT_RIGHT 578 * @see #META_ALT_ON 579 */ 580 public final boolean isAltPressed() { 581 return (mMetaState & META_ALT_ON) != 0; 582 } 583 584 /** 585 * <p>Returns the pressed state of the SHIFT meta key.</p> 586 * 587 * @return true if the SHIFT key is pressed, false otherwise 588 * 589 * @see #KEYCODE_SHIFT_LEFT 590 * @see #KEYCODE_SHIFT_RIGHT 591 * @see #META_SHIFT_ON 592 */ 593 public final boolean isShiftPressed() { 594 return (mMetaState & META_SHIFT_ON) != 0; 595 } 596 597 /** 598 * <p>Returns the pressed state of the SYM meta key.</p> 599 * 600 * @return true if the SYM key is pressed, false otherwise 601 * 602 * @see #KEYCODE_SYM 603 * @see #META_SYM_ON 604 */ 605 public final boolean isSymPressed() { 606 return (mMetaState & META_SYM_ON) != 0; 607 } 608 609 /** 610 * Retrieve the action of this key event. May be either 611 * {@link #ACTION_DOWN}, {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}. 612 * 613 * @return The event action: ACTION_DOWN, ACTION_UP, or ACTION_MULTIPLE. 614 */ 615 public final int getAction() { 616 return mAction; 617 } 618 619 /** 620 * Retrieve the key code of the key event. This is the physical key that 621 * was pressed, <em>not</em> the Unicode character. 622 * 623 * @return The key code of the event. 624 */ 625 public final int getKeyCode() { 626 return mKeyCode; 627 } 628 629 /** 630 * For the special case of a {@link #ACTION_MULTIPLE} event with key 631 * code of {@link #KEYCODE_UNKNOWN}, this is a raw string of characters 632 * associated with the event. In all other cases it is null. 633 * 634 * @return Returns a String of 1 or more characters associated with 635 * the event. 636 */ 637 public final String getCharacters() { 638 return mCharacters; 639 } 640 641 /** 642 * Retrieve the hardware key id of this key event. These values are not 643 * reliable and vary from device to device. 644 * 645 * {@more} 646 * Mostly this is here for debugging purposes. 647 */ 648 public final int getScanCode() { 649 return mScancode; 650 } 651 652 /** 653 * Retrieve the repeat count of the event. For both key up and key down 654 * events, this is the number of times the key has repeated with the first 655 * down starting at 0 and counting up from there. For multiple key 656 * events, this is the number of down/up pairs that have occurred. 657 * 658 * @return The number of times the key has repeated. 659 */ 660 public final int getRepeatCount() { 661 return mRepeatCount; 662 } 663 664 /** 665 * Retrieve the time of the most recent key down event, 666 * in the {@link android.os.SystemClock#uptimeMillis} time base. If this 667 * is a down event, this will be the same as {@link #getEventTime()}. 668 * Note that when chording keys, this value is the down time of the 669 * most recently pressed key, which may <em>not</em> be the same physical 670 * key of this event. 671 * 672 * @return Returns the most recent key down time, in the 673 * {@link android.os.SystemClock#uptimeMillis} time base 674 */ 675 public final long getDownTime() { 676 return mDownTime; 677 } 678 679 /** 680 * Retrieve the time this event occurred, 681 * in the {@link android.os.SystemClock#uptimeMillis} time base. 682 * 683 * @return Returns the time this event occurred, 684 * in the {@link android.os.SystemClock#uptimeMillis} time base. 685 */ 686 public final long getEventTime() { 687 return mEventTime; 688 } 689 690 /** 691 * Return the id for the keyboard that this event came from. A device 692 * id of 0 indicates the event didn't come from a physical device and 693 * maps to the default keymap. The other numbers are arbitrary and 694 * you shouldn't depend on the values. 695 * 696 * @see KeyCharacterMap#load 697 */ 698 public final int getDeviceId() { 699 return mDeviceId; 700 } 701 702 /** 703 * Renamed to {@link #getDeviceId}. 704 * 705 * @hide 706 * @deprecated 707 */ 708 public final int getKeyboardDevice() { 709 return mDeviceId; 710 } 711 712 /** 713 * Get the primary character for this key. In other words, the label 714 * that is physically printed on it. 715 */ 716 public char getDisplayLabel() { 717 return KeyCharacterMap.load(mDeviceId).getDisplayLabel(mKeyCode); 718 } 719 720 /** 721 * <p> 722 * Returns the Unicode character that the key would produce. 723 * </p><p> 724 * Returns 0 if the key is not one that is used to type Unicode 725 * characters. 726 * </p><p> 727 * If the return value has bit 728 * {@link KeyCharacterMap#COMBINING_ACCENT} 729 * set, the key is a "dead key" that should be combined with another to 730 * actually produce a character -- see {@link #getDeadChar} -- 731 * after masking with 732 * {@link KeyCharacterMap#COMBINING_ACCENT_MASK}. 733 * </p> 734 */ 735 public int getUnicodeChar() { 736 return getUnicodeChar(mMetaState); 737 } 738 739 /** 740 * <p> 741 * Returns the Unicode character that the key would produce. 742 * </p><p> 743 * Returns 0 if the key is not one that is used to type Unicode 744 * characters. 745 * </p><p> 746 * If the return value has bit 747 * {@link KeyCharacterMap#COMBINING_ACCENT} 748 * set, the key is a "dead key" that should be combined with another to 749 * actually produce a character -- see {@link #getDeadChar} -- after masking 750 * with {@link KeyCharacterMap#COMBINING_ACCENT_MASK}. 751 * </p> 752 */ 753 public int getUnicodeChar(int meta) { 754 return KeyCharacterMap.load(mDeviceId).get(mKeyCode, meta); 755 } 756 757 /** 758 * Get the characters conversion data for the key event.. 759 * 760 * @param results a {@link KeyData} that will be filled with the results. 761 * 762 * @return whether the key was mapped or not. If the key was not mapped, 763 * results is not modified. 764 */ 765 public boolean getKeyData(KeyData results) { 766 return KeyCharacterMap.load(mDeviceId).getKeyData(mKeyCode, results); 767 } 768 769 /** 770 * The same as {@link #getMatch(char[],int) getMatch(chars, 0)}. 771 */ 772 public char getMatch(char[] chars) { 773 return getMatch(chars, 0); 774 } 775 776 /** 777 * If one of the chars in the array can be generated by the keyCode of this 778 * key event, return the char; otherwise return '\0'. 779 * @param chars the characters to try to find 780 * @param modifiers the modifier bits to prefer. If any of these bits 781 * are set, if there are multiple choices, that could 782 * work, the one for this modifier will be set. 783 */ 784 public char getMatch(char[] chars, int modifiers) { 785 return KeyCharacterMap.load(mDeviceId).getMatch(mKeyCode, chars, modifiers); 786 } 787 788 /** 789 * Gets the number or symbol associated with the key. The character value 790 * is returned, not the numeric value. If the key is not a number, but is 791 * a symbol, the symbol is retuned. 792 */ 793 public char getNumber() { 794 return KeyCharacterMap.load(mDeviceId).getNumber(mKeyCode); 795 } 796 797 /** 798 * Does the key code of this key produce a glyph? 799 */ 800 public boolean isPrintingKey() { 801 return KeyCharacterMap.load(mDeviceId).isPrintingKey(mKeyCode); 802 } 803 804 /** 805 * Deliver this key event to a {@link Callback} interface. If this is 806 * an ACTION_MULTIPLE event and it is not handled, then an attempt will 807 * be made to deliver a single normal event. 808 * 809 * @param receiver The Callback that will be given the event. 810 * 811 * @return The return value from the Callback method that was called. 812 */ 813 public final boolean dispatch(Callback receiver) { 814 switch (mAction) { 815 case ACTION_DOWN: 816 return receiver.onKeyDown(mKeyCode, this); 817 case ACTION_UP: 818 return receiver.onKeyUp(mKeyCode, this); 819 case ACTION_MULTIPLE: 820 final int count = mRepeatCount; 821 final int code = mKeyCode; 822 if (receiver.onKeyMultiple(code, count, this)) { 823 return true; 824 } 825 if (code != KeyEvent.KEYCODE_UNKNOWN) { 826 mAction = ACTION_DOWN; 827 mRepeatCount = 0; 828 boolean handled = receiver.onKeyDown(code, this); 829 if (handled) { 830 mAction = ACTION_UP; 831 receiver.onKeyUp(code, this); 832 } 833 mAction = ACTION_MULTIPLE; 834 mRepeatCount = count; 835 return handled; 836 } 837 } 838 return false; 839 } 840 841 public String toString() { 842 return "KeyEvent{action=" + mAction + " code=" + mKeyCode 843 + " repeat=" + mRepeatCount 844 + " meta=" + mMetaState + " scancode=" + mScancode 845 + " mFlags=" + mFlags + "}"; 846 } 847 848 public static final Parcelable.Creator<KeyEvent> CREATOR 849 = new Parcelable.Creator<KeyEvent>() { 850 public KeyEvent createFromParcel(Parcel in) { 851 return new KeyEvent(in); 852 } 853 854 public KeyEvent[] newArray(int size) { 855 return new KeyEvent[size]; 856 } 857 }; 858 859 public int describeContents() { 860 return 0; 861 } 862 863 public void writeToParcel(Parcel out, int flags) { 864 out.writeInt(mAction); 865 out.writeInt(mKeyCode); 866 out.writeInt(mRepeatCount); 867 out.writeInt(mMetaState); 868 out.writeInt(mDeviceId); 869 out.writeInt(mScancode); 870 out.writeInt(mFlags); 871 out.writeLong(mDownTime); 872 out.writeLong(mEventTime); 873 } 874 875 private KeyEvent(Parcel in) { 876 mAction = in.readInt(); 877 mKeyCode = in.readInt(); 878 mRepeatCount = in.readInt(); 879 mMetaState = in.readInt(); 880 mDeviceId = in.readInt(); 881 mScancode = in.readInt(); 882 mFlags = in.readInt(); 883 mDownTime = in.readLong(); 884 mEventTime = in.readLong(); 885 } 886} 887