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