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