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