KeyEvent.java revision dc1ab4b5cc274b7d744c11a939bb5910becec5e0
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.util.Log; 22import android.util.SparseIntArray; 23import android.view.KeyCharacterMap; 24import android.view.KeyCharacterMap.KeyData; 25 26/** 27 * Object used to report key and button events. 28 * <p> 29 * Each key press is described by a sequence of key events. A key press 30 * starts with a key event with {@link #ACTION_DOWN}. If the key is held 31 * sufficiently long that it repeats, then the initial down is followed 32 * additional key events with {@link #ACTION_DOWN} and a non-zero value for 33 * {@link #getRepeatCount()}. The last key event is a {@link #ACTION_UP} 34 * for the key up. If the key press is canceled, the key up event will have the 35 * {@link #FLAG_CANCELED} flag set. 36 * </p><p> 37 * Key events are generally accompanied by a key code ({@link #getKeyCode()}), 38 * scan code ({@link #getScanCode()}) and meta state ({@link #getMetaState()}). 39 * Key code constants are defined in this class. Scan code constants are raw 40 * device-specific codes obtained from the OS and so are not generally meaningful 41 * to applications unless interpreted using the {@link KeyCharacterMap}. 42 * Meta states describe the pressed state of key modifiers 43 * such as {@link #META_SHIFT_ON} or {@link #META_ALT_ON}. 44 * </p><p> 45 * When interacting with an IME, the framework may deliver key events 46 * with the special action {@link #ACTION_MULTIPLE} that either specifies 47 * that single repeated key code or a sequence of characters to insert. 48 * </p><p> 49 * In general, the framework makes no guarantees that the key events delivered 50 * to a view constitute a complete key press. In particular, there is no 51 * guarantee that a view will always receive a key event with {@link #ACTION_UP} 52 * for each {@link #ACTION_DOWN} that was delivered. 53 * </p><p> 54 * Refer to {@link InputDevice} for more information about how different kinds of 55 * input devices and sources represent keys and buttons. 56 * </p> 57 */ 58public class KeyEvent extends InputEvent implements Parcelable { 59 /** Key code constant: Unknown key code. */ 60 public static final int KEYCODE_UNKNOWN = 0; 61 /** Key code constant: Soft Left key. 62 * Usually situated below the display on phones and used as a multi-function 63 * feature key for selecting a software defined function shown on the bottom left 64 * of the display. */ 65 public static final int KEYCODE_SOFT_LEFT = 1; 66 /** Key code constant: Soft Right key. 67 * Usually situated below the display on phones and used as a multi-function 68 * feature key for selecting a software defined function shown on the bottom right 69 * of the display. */ 70 public static final int KEYCODE_SOFT_RIGHT = 2; 71 /** Key code constant: Home key. 72 * This key is handled by the framework and is never delivered to applications. */ 73 public static final int KEYCODE_HOME = 3; 74 /** Key code constant: Back key. */ 75 public static final int KEYCODE_BACK = 4; 76 /** Key code constant: Call key. */ 77 public static final int KEYCODE_CALL = 5; 78 /** Key code constant: End Call key. */ 79 public static final int KEYCODE_ENDCALL = 6; 80 /** Key code constant: '0' key. */ 81 public static final int KEYCODE_0 = 7; 82 /** Key code constant: '1' key. */ 83 public static final int KEYCODE_1 = 8; 84 /** Key code constant: '2' key. */ 85 public static final int KEYCODE_2 = 9; 86 /** Key code constant: '3' key. */ 87 public static final int KEYCODE_3 = 10; 88 /** Key code constant: '4' key. */ 89 public static final int KEYCODE_4 = 11; 90 /** Key code constant: '5' key. */ 91 public static final int KEYCODE_5 = 12; 92 /** Key code constant: '6' key. */ 93 public static final int KEYCODE_6 = 13; 94 /** Key code constant: '7' key. */ 95 public static final int KEYCODE_7 = 14; 96 /** Key code constant: '8' key. */ 97 public static final int KEYCODE_8 = 15; 98 /** Key code constant: '9' key. */ 99 public static final int KEYCODE_9 = 16; 100 /** Key code constant: '*' key. */ 101 public static final int KEYCODE_STAR = 17; 102 /** Key code constant: '#' key. */ 103 public static final int KEYCODE_POUND = 18; 104 /** Key code constant: Directional Pad Up key. 105 * May also be synthesized from trackball motions. */ 106 public static final int KEYCODE_DPAD_UP = 19; 107 /** Key code constant: Directional Pad Down key. 108 * May also be synthesized from trackball motions. */ 109 public static final int KEYCODE_DPAD_DOWN = 20; 110 /** Key code constant: Directional Pad Left key. 111 * May also be synthesized from trackball motions. */ 112 public static final int KEYCODE_DPAD_LEFT = 21; 113 /** Key code constant: Directional Pad Right key. 114 * May also be synthesized from trackball motions. */ 115 public static final int KEYCODE_DPAD_RIGHT = 22; 116 /** Key code constant: Directional Pad Center key. 117 * May also be synthesized from trackball motions. */ 118 public static final int KEYCODE_DPAD_CENTER = 23; 119 /** Key code constant: Volume Up key. */ 120 public static final int KEYCODE_VOLUME_UP = 24; 121 /** Key code constant: Volume Down key. */ 122 public static final int KEYCODE_VOLUME_DOWN = 25; 123 /** Key code constant: Power key. */ 124 public static final int KEYCODE_POWER = 26; 125 /** Key code constant: Camera key. 126 * Used to launch a camera application or take pictures. */ 127 public static final int KEYCODE_CAMERA = 27; 128 /** Key code constant: Clear key. */ 129 public static final int KEYCODE_CLEAR = 28; 130 /** Key code constant: 'A' key. */ 131 public static final int KEYCODE_A = 29; 132 /** Key code constant: 'B' key. */ 133 public static final int KEYCODE_B = 30; 134 /** Key code constant: 'C' key. */ 135 public static final int KEYCODE_C = 31; 136 /** Key code constant: 'D' key. */ 137 public static final int KEYCODE_D = 32; 138 /** Key code constant: 'E' key. */ 139 public static final int KEYCODE_E = 33; 140 /** Key code constant: 'F' key. */ 141 public static final int KEYCODE_F = 34; 142 /** Key code constant: 'G' key. */ 143 public static final int KEYCODE_G = 35; 144 /** Key code constant: 'H' key. */ 145 public static final int KEYCODE_H = 36; 146 /** Key code constant: 'I' key. */ 147 public static final int KEYCODE_I = 37; 148 /** Key code constant: 'J' key. */ 149 public static final int KEYCODE_J = 38; 150 /** Key code constant: 'K' key. */ 151 public static final int KEYCODE_K = 39; 152 /** Key code constant: 'L' key. */ 153 public static final int KEYCODE_L = 40; 154 /** Key code constant: 'M' key. */ 155 public static final int KEYCODE_M = 41; 156 /** Key code constant: 'N' key. */ 157 public static final int KEYCODE_N = 42; 158 /** Key code constant: 'O' key. */ 159 public static final int KEYCODE_O = 43; 160 /** Key code constant: 'P' key. */ 161 public static final int KEYCODE_P = 44; 162 /** Key code constant: 'Q' key. */ 163 public static final int KEYCODE_Q = 45; 164 /** Key code constant: 'R' key. */ 165 public static final int KEYCODE_R = 46; 166 /** Key code constant: 'S' key. */ 167 public static final int KEYCODE_S = 47; 168 /** Key code constant: 'T' key. */ 169 public static final int KEYCODE_T = 48; 170 /** Key code constant: 'U' key. */ 171 public static final int KEYCODE_U = 49; 172 /** Key code constant: 'V' key. */ 173 public static final int KEYCODE_V = 50; 174 /** Key code constant: 'W' key. */ 175 public static final int KEYCODE_W = 51; 176 /** Key code constant: 'X' key. */ 177 public static final int KEYCODE_X = 52; 178 /** Key code constant: 'Y' key. */ 179 public static final int KEYCODE_Y = 53; 180 /** Key code constant: 'Z' key. */ 181 public static final int KEYCODE_Z = 54; 182 /** Key code constant: ',' key. */ 183 public static final int KEYCODE_COMMA = 55; 184 /** Key code constant: '.' key. */ 185 public static final int KEYCODE_PERIOD = 56; 186 /** Key code constant: Left Alt modifier key. */ 187 public static final int KEYCODE_ALT_LEFT = 57; 188 /** Key code constant: Right Alt modifier key. */ 189 public static final int KEYCODE_ALT_RIGHT = 58; 190 /** Key code constant: Left Shift modifier key. */ 191 public static final int KEYCODE_SHIFT_LEFT = 59; 192 /** Key code constant: Right Shift modifier key. */ 193 public static final int KEYCODE_SHIFT_RIGHT = 60; 194 /** Key code constant: Tab key. */ 195 public static final int KEYCODE_TAB = 61; 196 /** Key code constant: Space key. */ 197 public static final int KEYCODE_SPACE = 62; 198 /** Key code constant: Symbol modifier key. */ 199 public static final int KEYCODE_SYM = 63; 200 /** Key code constant: Explorer special function key. 201 * Used to launch a browser application. */ 202 public static final int KEYCODE_EXPLORER = 64; 203 /** Key code constant: Envelope special function key. 204 * Used to launch a mail application. */ 205 public static final int KEYCODE_ENVELOPE = 65; 206 /** Key code constant: Enter key. */ 207 public static final int KEYCODE_ENTER = 66; 208 /** Key code constant: Delete key. */ 209 public static final int KEYCODE_DEL = 67; 210 /** Key code constant: '`' (backtick) key. */ 211 public static final int KEYCODE_GRAVE = 68; 212 /** Key code constant: '-'. */ 213 public static final int KEYCODE_MINUS = 69; 214 /** Key code constant: '=' key. */ 215 public static final int KEYCODE_EQUALS = 70; 216 /** Key code constant: '[' key. */ 217 public static final int KEYCODE_LEFT_BRACKET = 71; 218 /** Key code constant: ']' key. */ 219 public static final int KEYCODE_RIGHT_BRACKET = 72; 220 /** Key code constant: '\' key. */ 221 public static final int KEYCODE_BACKSLASH = 73; 222 /** Key code constant: ';' key. */ 223 public static final int KEYCODE_SEMICOLON = 74; 224 /** Key code constant: ''' (apostrophe) key. */ 225 public static final int KEYCODE_APOSTROPHE = 75; 226 /** Key code constant: '/' key. */ 227 public static final int KEYCODE_SLASH = 76; 228 /** Key code constant: '@' key. */ 229 public static final int KEYCODE_AT = 77; 230 /** Key code constant: Number Lock modifier key. */ 231 public static final int KEYCODE_NUM = 78; 232 /** Key code constant: Headset Hook key. 233 * Used to hang up calls and stop media. */ 234 public static final int KEYCODE_HEADSETHOOK = 79; 235 /** Key code constant: Camera Focus key. 236 * Used to focus the camera. */ 237 public static final int KEYCODE_FOCUS = 80; // *Camera* focus 238 /** Key code constant: '+' key. */ 239 public static final int KEYCODE_PLUS = 81; 240 /** Key code constant: Menu key. */ 241 public static final int KEYCODE_MENU = 82; 242 /** Key code constant: Notification key. */ 243 public static final int KEYCODE_NOTIFICATION = 83; 244 /** Key code constant: Search key. */ 245 public static final int KEYCODE_SEARCH = 84; 246 /** Key code constant: Play/Pause media key. */ 247 public static final int KEYCODE_MEDIA_PLAY_PAUSE= 85; 248 /** Key code constant: Stop media key. */ 249 public static final int KEYCODE_MEDIA_STOP = 86; 250 /** Key code constant: Play Next media key. */ 251 public static final int KEYCODE_MEDIA_NEXT = 87; 252 /** Key code constant: Play Previous media key. */ 253 public static final int KEYCODE_MEDIA_PREVIOUS = 88; 254 /** Key code constant: Rewind media key. */ 255 public static final int KEYCODE_MEDIA_REWIND = 89; 256 /** Key code constant: Fast Forward media key. */ 257 public static final int KEYCODE_MEDIA_FAST_FORWARD = 90; 258 /** Key code constant: Mute key. */ 259 public static final int KEYCODE_MUTE = 91; 260 /** Key code constant: Page Up key. */ 261 public static final int KEYCODE_PAGE_UP = 92; 262 /** Key code constant: Page Down key. */ 263 public static final int KEYCODE_PAGE_DOWN = 93; 264 /** Key code constant: Picture Symbols modifier key. 265 * Used to switch symbol sets (Emoji, Kao-moji). */ 266 public static final int KEYCODE_PICTSYMBOLS = 94; // switch symbol-sets (Emoji,Kao-moji) 267 /** Key code constant: Switch Charset modifier key. 268 * Used to switch character sets (Kanji, Katakana). */ 269 public static final int KEYCODE_SWITCH_CHARSET = 95; // switch char-sets (Kanji,Katakana) 270 /** Key code constant: A Button key. 271 * On a game controller, the A button should be either the button labeled A 272 * or the first button on the upper row of controller buttons. */ 273 public static final int KEYCODE_BUTTON_A = 96; 274 /** Key code constant: B Button key. 275 * On a game controller, the B button should be either the button labeled B 276 * or the second button on the upper row of controller buttons. */ 277 public static final int KEYCODE_BUTTON_B = 97; 278 /** Key code constant: C Button key. 279 * On a game controller, the C button should be either the button labeled C 280 * or the third button on the upper row of controller buttons. */ 281 public static final int KEYCODE_BUTTON_C = 98; 282 /** Key code constant: X Button key. 283 * On a game controller, the X button should be either the button labeled X 284 * or the first button on the lower row of controller buttons. */ 285 public static final int KEYCODE_BUTTON_X = 99; 286 /** Key code constant: Y Button key. 287 * On a game controller, the Y button should be either the button labeled Y 288 * or the second button on the lower row of controller buttons. */ 289 public static final int KEYCODE_BUTTON_Y = 100; 290 /** Key code constant: Z Button key. 291 * On a game controller, the Z button should be either the button labeled Z 292 * or the third button on the lower row of controller buttons. */ 293 public static final int KEYCODE_BUTTON_Z = 101; 294 /** Key code constant: L1 Button key. 295 * On a game controller, the L1 button should be either the button labeled L1 (or L) 296 * or the top left trigger button. */ 297 public static final int KEYCODE_BUTTON_L1 = 102; 298 /** Key code constant: R1 Button key. 299 * On a game controller, the R1 button should be either the button labeled R1 (or R) 300 * or the top right trigger button. */ 301 public static final int KEYCODE_BUTTON_R1 = 103; 302 /** Key code constant: L2 Button key. 303 * On a game controller, the L2 button should be either the button labeled L2 304 * or the bottom left trigger button. */ 305 public static final int KEYCODE_BUTTON_L2 = 104; 306 /** Key code constant: R2 Button key. 307 * On a game controller, the R2 button should be either the button labeled R2 308 * or the bottom right trigger button. */ 309 public static final int KEYCODE_BUTTON_R2 = 105; 310 /** Key code constant: Left Thumb Button key. 311 * On a game controller, the left thumb button indicates that the left (or only) 312 * joystick is pressed. */ 313 public static final int KEYCODE_BUTTON_THUMBL = 106; 314 /** Key code constant: Right Thumb Button key. 315 * On a game controller, the right thumb button indicates that the right 316 * joystick is pressed. */ 317 public static final int KEYCODE_BUTTON_THUMBR = 107; 318 /** Key code constant: Start Button key. 319 * On a game controller, the button labeled Start. */ 320 public static final int KEYCODE_BUTTON_START = 108; 321 /** Key code constant: Select Button key. 322 * On a game controller, the button labeled Select. */ 323 public static final int KEYCODE_BUTTON_SELECT = 109; 324 /** Key code constant: Mode Button key. 325 * On a game controller, the button labeled Mode. */ 326 public static final int KEYCODE_BUTTON_MODE = 110; 327 328 // NOTE: If you add a new keycode here you must also add it to: 329 // isSystem() 330 // native/include/android/keycodes.h 331 // frameworks/base/include/ui/KeycodeLabels.h 332 // external/webkit/WebKit/android/plugins/ANPKeyCodes.h 333 // tools/puppet_master/PuppetMaster/nav_keys.py 334 // frameworks/base/core/res/res/values/attrs.xml 335 // commands/monkey/Monkey.java 336 // emulator? 337 // 338 // Also Android currently does not reserve code ranges for vendor- 339 // specific key codes. If you have new key codes to have, you 340 // MUST contribute a patch to the open source project to define 341 // those new codes. This is intended to maintain a consistent 342 // set of key code definitions across all Android devices. 343 344 private static final int LAST_KEYCODE = KEYCODE_BUTTON_MODE; 345 346 /** 347 * @deprecated There are now more than MAX_KEYCODE keycodes. 348 * Use {@link #getMaxKeyCode()} instead. 349 */ 350 @Deprecated 351 public static final int MAX_KEYCODE = 84; 352 353 /** 354 * {@link #getAction} value: the key has been pressed down. 355 */ 356 public static final int ACTION_DOWN = 0; 357 /** 358 * {@link #getAction} value: the key has been released. 359 */ 360 public static final int ACTION_UP = 1; 361 /** 362 * {@link #getAction} value: multiple duplicate key events have 363 * occurred in a row, or a complex string is being delivered. If the 364 * key code is not {#link {@link #KEYCODE_UNKNOWN} then the 365 * {#link {@link #getRepeatCount()} method returns the number of times 366 * the given key code should be executed. 367 * Otherwise, if the key code is {@link #KEYCODE_UNKNOWN}, then 368 * this is a sequence of characters as returned by {@link #getCharacters}. 369 */ 370 public static final int ACTION_MULTIPLE = 2; 371 372 /** 373 * <p>This mask is used to check whether one of the ALT meta keys is pressed.</p> 374 * 375 * @see #isAltPressed() 376 * @see #getMetaState() 377 * @see #KEYCODE_ALT_LEFT 378 * @see #KEYCODE_ALT_RIGHT 379 */ 380 public static final int META_ALT_ON = 0x02; 381 382 /** 383 * <p>This mask is used to check whether the left ALT meta key is pressed.</p> 384 * 385 * @see #isAltPressed() 386 * @see #getMetaState() 387 * @see #KEYCODE_ALT_LEFT 388 */ 389 public static final int META_ALT_LEFT_ON = 0x10; 390 391 /** 392 * <p>This mask is used to check whether the right the ALT meta key is pressed.</p> 393 * 394 * @see #isAltPressed() 395 * @see #getMetaState() 396 * @see #KEYCODE_ALT_RIGHT 397 */ 398 public static final int META_ALT_RIGHT_ON = 0x20; 399 400 /** 401 * <p>This mask is used to check whether one of the SHIFT meta keys is pressed.</p> 402 * 403 * @see #isShiftPressed() 404 * @see #getMetaState() 405 * @see #KEYCODE_SHIFT_LEFT 406 * @see #KEYCODE_SHIFT_RIGHT 407 */ 408 public static final int META_SHIFT_ON = 0x1; 409 410 /** 411 * <p>This mask is used to check whether the left SHIFT meta key is pressed.</p> 412 * 413 * @see #isShiftPressed() 414 * @see #getMetaState() 415 * @see #KEYCODE_SHIFT_LEFT 416 */ 417 public static final int META_SHIFT_LEFT_ON = 0x40; 418 419 /** 420 * <p>This mask is used to check whether the right SHIFT meta key is pressed.</p> 421 * 422 * @see #isShiftPressed() 423 * @see #getMetaState() 424 * @see #KEYCODE_SHIFT_RIGHT 425 */ 426 public static final int META_SHIFT_RIGHT_ON = 0x80; 427 428 /** 429 * <p>This mask is used to check whether the SYM meta key is pressed.</p> 430 * 431 * @see #isSymPressed() 432 * @see #getMetaState() 433 */ 434 public static final int META_SYM_ON = 0x4; 435 436 /** 437 * This mask is set if the device woke because of this key event. 438 */ 439 public static final int FLAG_WOKE_HERE = 0x1; 440 441 /** 442 * This mask is set if the key event was generated by a software keyboard. 443 */ 444 public static final int FLAG_SOFT_KEYBOARD = 0x2; 445 446 /** 447 * This mask is set if we don't want the key event to cause us to leave 448 * touch mode. 449 */ 450 public static final int FLAG_KEEP_TOUCH_MODE = 0x4; 451 452 /** 453 * This mask is set if an event was known to come from a trusted part 454 * of the system. That is, the event is known to come from the user, 455 * and could not have been spoofed by a third party component. 456 */ 457 public static final int FLAG_FROM_SYSTEM = 0x8; 458 459 /** 460 * This mask is used for compatibility, to identify enter keys that are 461 * coming from an IME whose enter key has been auto-labelled "next" or 462 * "done". This allows TextView to dispatch these as normal enter keys 463 * for old applications, but still do the appropriate action when 464 * receiving them. 465 */ 466 public static final int FLAG_EDITOR_ACTION = 0x10; 467 468 /** 469 * When associated with up key events, this indicates that the key press 470 * has been canceled. Typically this is used with virtual touch screen 471 * keys, where the user can slide from the virtual key area on to the 472 * display: in that case, the application will receive a canceled up 473 * event and should not perform the action normally associated with the 474 * key. Note that for this to work, the application can not perform an 475 * action for a key until it receives an up or the long press timeout has 476 * expired. 477 */ 478 public static final int FLAG_CANCELED = 0x20; 479 480 /** 481 * This key event was generated by a virtual (on-screen) hard key area. 482 * Typically this is an area of the touchscreen, outside of the regular 483 * display, dedicated to "hardware" buttons. 484 */ 485 public static final int FLAG_VIRTUAL_HARD_KEY = 0x40; 486 487 /** 488 * This flag is set for the first key repeat that occurs after the 489 * long press timeout. 490 */ 491 public static final int FLAG_LONG_PRESS = 0x80; 492 493 /** 494 * Set when a key event has {@link #FLAG_CANCELED} set because a long 495 * press action was executed while it was down. 496 */ 497 public static final int FLAG_CANCELED_LONG_PRESS = 0x100; 498 499 /** 500 * Set for {@link #ACTION_UP} when this event's key code is still being 501 * tracked from its initial down. That is, somebody requested that tracking 502 * started on the key down and a long press has not caused 503 * the tracking to be canceled. 504 */ 505 public static final int FLAG_TRACKING = 0x200; 506 507 /** 508 * Private control to determine when an app is tracking a key sequence. 509 * @hide 510 */ 511 public static final int FLAG_START_TRACKING = 0x40000000; 512 513 /** 514 * Returns the maximum keycode. 515 */ 516 public static int getMaxKeyCode() { 517 return LAST_KEYCODE; 518 } 519 520 /** 521 * Get the character that is produced by putting accent on the character 522 * c. 523 * For example, getDeadChar('`', 'e') returns è. 524 */ 525 public static int getDeadChar(int accent, int c) { 526 return KeyCharacterMap.getDeadChar(accent, c); 527 } 528 529 static final boolean DEBUG = false; 530 static final String TAG = "KeyEvent"; 531 532 private int mMetaState; 533 private int mAction; 534 private int mKeyCode; 535 private int mScanCode; 536 private int mRepeatCount; 537 private int mFlags; 538 private long mDownTime; 539 private long mEventTime; 540 private String mCharacters; 541 542 public interface Callback { 543 /** 544 * Called when a key down event has occurred. If you return true, 545 * you can first call {@link KeyEvent#startTracking() 546 * KeyEvent.startTracking()} to have the framework track the event 547 * through its {@link #onKeyUp(int, KeyEvent)} and also call your 548 * {@link #onKeyLongPress(int, KeyEvent)} if it occurs. 549 * 550 * @param keyCode The value in event.getKeyCode(). 551 * @param event Description of the key event. 552 * 553 * @return If you handled the event, return true. If you want to allow 554 * the event to be handled by the next receiver, return false. 555 */ 556 boolean onKeyDown(int keyCode, KeyEvent event); 557 558 /** 559 * Called when a long press has occurred. If you return true, 560 * the final key up will have {@link KeyEvent#FLAG_CANCELED} and 561 * {@link KeyEvent#FLAG_CANCELED_LONG_PRESS} set. Note that in 562 * order to receive this callback, someone in the event change 563 * <em>must</em> return true from {@link #onKeyDown} <em>and</em> 564 * call {@link KeyEvent#startTracking()} on the event. 565 * 566 * @param keyCode The value in event.getKeyCode(). 567 * @param event Description of the key event. 568 * 569 * @return If you handled the event, return true. If you want to allow 570 * the event to be handled by the next receiver, return false. 571 */ 572 boolean onKeyLongPress(int keyCode, KeyEvent event); 573 574 /** 575 * Called when a key up event has occurred. 576 * 577 * @param keyCode The value in event.getKeyCode(). 578 * @param event Description of the key event. 579 * 580 * @return If you handled the event, return true. If you want to allow 581 * the event to be handled by the next receiver, return false. 582 */ 583 boolean onKeyUp(int keyCode, KeyEvent event); 584 585 /** 586 * Called when multiple down/up pairs of the same key have occurred 587 * in a row. 588 * 589 * @param keyCode The value in event.getKeyCode(). 590 * @param count Number of pairs as returned by event.getRepeatCount(). 591 * @param event Description of the key event. 592 * 593 * @return If you handled the event, return true. If you want to allow 594 * the event to be handled by the next receiver, return false. 595 */ 596 boolean onKeyMultiple(int keyCode, int count, KeyEvent event); 597 } 598 599 /** 600 * Create a new key event. 601 * 602 * @param action Action code: either {@link #ACTION_DOWN}, 603 * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}. 604 * @param code The key code. 605 */ 606 public KeyEvent(int action, int code) { 607 mAction = action; 608 mKeyCode = code; 609 mRepeatCount = 0; 610 } 611 612 /** 613 * Create a new key event. 614 * 615 * @param downTime The time (in {@link android.os.SystemClock#uptimeMillis}) 616 * at which this key code originally went down. 617 * @param eventTime The time (in {@link android.os.SystemClock#uptimeMillis}) 618 * at which this event happened. 619 * @param action Action code: either {@link #ACTION_DOWN}, 620 * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}. 621 * @param code The key code. 622 * @param repeat A repeat count for down events (> 0 if this is after the 623 * initial down) or event count for multiple events. 624 */ 625 public KeyEvent(long downTime, long eventTime, int action, 626 int code, int repeat) { 627 mDownTime = downTime; 628 mEventTime = eventTime; 629 mAction = action; 630 mKeyCode = code; 631 mRepeatCount = repeat; 632 } 633 634 /** 635 * Create a new key event. 636 * 637 * @param downTime The time (in {@link android.os.SystemClock#uptimeMillis}) 638 * at which this key code originally went down. 639 * @param eventTime The time (in {@link android.os.SystemClock#uptimeMillis}) 640 * at which this event happened. 641 * @param action Action code: either {@link #ACTION_DOWN}, 642 * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}. 643 * @param code The key code. 644 * @param repeat A repeat count for down events (> 0 if this is after the 645 * initial down) or event count for multiple events. 646 * @param metaState Flags indicating which meta keys are currently pressed. 647 */ 648 public KeyEvent(long downTime, long eventTime, int action, 649 int code, int repeat, int metaState) { 650 mDownTime = downTime; 651 mEventTime = eventTime; 652 mAction = action; 653 mKeyCode = code; 654 mRepeatCount = repeat; 655 mMetaState = metaState; 656 } 657 658 /** 659 * Create a new key event. 660 * 661 * @param downTime The time (in {@link android.os.SystemClock#uptimeMillis}) 662 * at which this key code originally went down. 663 * @param eventTime The time (in {@link android.os.SystemClock#uptimeMillis}) 664 * at which this event happened. 665 * @param action Action code: either {@link #ACTION_DOWN}, 666 * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}. 667 * @param code The key code. 668 * @param repeat A repeat count for down events (> 0 if this is after the 669 * initial down) or event count for multiple events. 670 * @param metaState Flags indicating which meta keys are currently pressed. 671 * @param deviceId The device ID that generated the key event. 672 * @param scancode Raw device scan code of the event. 673 */ 674 public KeyEvent(long downTime, long eventTime, int action, 675 int code, int repeat, int metaState, 676 int deviceId, int scancode) { 677 mDownTime = downTime; 678 mEventTime = eventTime; 679 mAction = action; 680 mKeyCode = code; 681 mRepeatCount = repeat; 682 mMetaState = metaState; 683 mDeviceId = deviceId; 684 mScanCode = scancode; 685 } 686 687 /** 688 * Create a new key event. 689 * 690 * @param downTime The time (in {@link android.os.SystemClock#uptimeMillis}) 691 * at which this key code originally went down. 692 * @param eventTime The time (in {@link android.os.SystemClock#uptimeMillis}) 693 * at which this event happened. 694 * @param action Action code: either {@link #ACTION_DOWN}, 695 * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}. 696 * @param code The key code. 697 * @param repeat A repeat count for down events (> 0 if this is after the 698 * initial down) or event count for multiple events. 699 * @param metaState Flags indicating which meta keys are currently pressed. 700 * @param deviceId The device ID that generated the key event. 701 * @param scancode Raw device scan code of the event. 702 * @param flags The flags for this key event 703 */ 704 public KeyEvent(long downTime, long eventTime, int action, 705 int code, int repeat, int metaState, 706 int deviceId, int scancode, int flags) { 707 mDownTime = downTime; 708 mEventTime = eventTime; 709 mAction = action; 710 mKeyCode = code; 711 mRepeatCount = repeat; 712 mMetaState = metaState; 713 mDeviceId = deviceId; 714 mScanCode = scancode; 715 mFlags = flags; 716 } 717 718 /** 719 * Create a new key event. 720 * 721 * @param downTime The time (in {@link android.os.SystemClock#uptimeMillis}) 722 * at which this key code originally went down. 723 * @param eventTime The time (in {@link android.os.SystemClock#uptimeMillis}) 724 * at which this event happened. 725 * @param action Action code: either {@link #ACTION_DOWN}, 726 * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}. 727 * @param code The key code. 728 * @param repeat A repeat count for down events (> 0 if this is after the 729 * initial down) or event count for multiple events. 730 * @param metaState Flags indicating which meta keys are currently pressed. 731 * @param deviceId The device ID that generated the key event. 732 * @param scancode Raw device scan code of the event. 733 * @param flags The flags for this key event 734 * @param source The input source such as {@link InputDevice#SOURCE_KEYBOARD}. 735 */ 736 public KeyEvent(long downTime, long eventTime, int action, 737 int code, int repeat, int metaState, 738 int deviceId, int scancode, int flags, int source) { 739 mDownTime = downTime; 740 mEventTime = eventTime; 741 mAction = action; 742 mKeyCode = code; 743 mRepeatCount = repeat; 744 mMetaState = metaState; 745 mDeviceId = deviceId; 746 mScanCode = scancode; 747 mFlags = flags; 748 mSource = source; 749 } 750 751 /** 752 * Create a new key event for a string of characters. The key code, 753 * action, repeat count and source will automatically be set to 754 * {@link #KEYCODE_UNKNOWN}, {@link #ACTION_MULTIPLE}, 0, and 755 * {@link InputDevice#SOURCE_KEYBOARD} for you. 756 * 757 * @param time The time (in {@link android.os.SystemClock#uptimeMillis}) 758 * at which this event occured. 759 * @param characters The string of characters. 760 * @param deviceId The device ID that generated the key event. 761 * @param flags The flags for this key event 762 */ 763 public KeyEvent(long time, String characters, int deviceId, int flags) { 764 mDownTime = time; 765 mEventTime = time; 766 mCharacters = characters; 767 mAction = ACTION_MULTIPLE; 768 mKeyCode = KEYCODE_UNKNOWN; 769 mRepeatCount = 0; 770 mDeviceId = deviceId; 771 mFlags = flags; 772 mSource = InputDevice.SOURCE_KEYBOARD; 773 } 774 775 /** 776 * Make an exact copy of an existing key event. 777 */ 778 public KeyEvent(KeyEvent origEvent) { 779 mDownTime = origEvent.mDownTime; 780 mEventTime = origEvent.mEventTime; 781 mAction = origEvent.mAction; 782 mKeyCode = origEvent.mKeyCode; 783 mRepeatCount = origEvent.mRepeatCount; 784 mMetaState = origEvent.mMetaState; 785 mDeviceId = origEvent.mDeviceId; 786 mSource = origEvent.mSource; 787 mScanCode = origEvent.mScanCode; 788 mFlags = origEvent.mFlags; 789 mCharacters = origEvent.mCharacters; 790 } 791 792 /** 793 * Copy an existing key event, modifying its time and repeat count. 794 * 795 * @deprecated Use {@link #changeTimeRepeat(KeyEvent, long, int)} 796 * instead. 797 * 798 * @param origEvent The existing event to be copied. 799 * @param eventTime The new event time 800 * (in {@link android.os.SystemClock#uptimeMillis}) of the event. 801 * @param newRepeat The new repeat count of the event. 802 */ 803 @Deprecated 804 public KeyEvent(KeyEvent origEvent, long eventTime, int newRepeat) { 805 mDownTime = origEvent.mDownTime; 806 mEventTime = eventTime; 807 mAction = origEvent.mAction; 808 mKeyCode = origEvent.mKeyCode; 809 mRepeatCount = newRepeat; 810 mMetaState = origEvent.mMetaState; 811 mDeviceId = origEvent.mDeviceId; 812 mSource = origEvent.mSource; 813 mScanCode = origEvent.mScanCode; 814 mFlags = origEvent.mFlags; 815 mCharacters = origEvent.mCharacters; 816 } 817 818 /** 819 * Create a new key event that is the same as the given one, but whose 820 * event time and repeat count are replaced with the given value. 821 * 822 * @param event The existing event to be copied. This is not modified. 823 * @param eventTime The new event time 824 * (in {@link android.os.SystemClock#uptimeMillis}) of the event. 825 * @param newRepeat The new repeat count of the event. 826 */ 827 public static KeyEvent changeTimeRepeat(KeyEvent event, long eventTime, 828 int newRepeat) { 829 return new KeyEvent(event, eventTime, newRepeat); 830 } 831 832 /** 833 * Create a new key event that is the same as the given one, but whose 834 * event time and repeat count are replaced with the given value. 835 * 836 * @param event The existing event to be copied. This is not modified. 837 * @param eventTime The new event time 838 * (in {@link android.os.SystemClock#uptimeMillis}) of the event. 839 * @param newRepeat The new repeat count of the event. 840 * @param newFlags New flags for the event, replacing the entire value 841 * in the original event. 842 */ 843 public static KeyEvent changeTimeRepeat(KeyEvent event, long eventTime, 844 int newRepeat, int newFlags) { 845 KeyEvent ret = new KeyEvent(event); 846 ret.mEventTime = eventTime; 847 ret.mRepeatCount = newRepeat; 848 ret.mFlags = newFlags; 849 return ret; 850 } 851 852 /** 853 * Copy an existing key event, modifying its action. 854 * 855 * @param origEvent The existing event to be copied. 856 * @param action The new action code of the event. 857 */ 858 private KeyEvent(KeyEvent origEvent, int action) { 859 mDownTime = origEvent.mDownTime; 860 mEventTime = origEvent.mEventTime; 861 mAction = action; 862 mKeyCode = origEvent.mKeyCode; 863 mRepeatCount = origEvent.mRepeatCount; 864 mMetaState = origEvent.mMetaState; 865 mDeviceId = origEvent.mDeviceId; 866 mSource = origEvent.mSource; 867 mScanCode = origEvent.mScanCode; 868 mFlags = origEvent.mFlags; 869 // Don't copy mCharacters, since one way or the other we'll lose it 870 // when changing the action. 871 } 872 873 /** 874 * Create a new key event that is the same as the given one, but whose 875 * action is replaced with the given value. 876 * 877 * @param event The existing event to be copied. This is not modified. 878 * @param action The new action code of the event. 879 */ 880 public static KeyEvent changeAction(KeyEvent event, int action) { 881 return new KeyEvent(event, action); 882 } 883 884 /** 885 * Create a new key event that is the same as the given one, but whose 886 * flags are replaced with the given value. 887 * 888 * @param event The existing event to be copied. This is not modified. 889 * @param flags The new flags constant. 890 */ 891 public static KeyEvent changeFlags(KeyEvent event, int flags) { 892 event = new KeyEvent(event); 893 event.mFlags = flags; 894 return event; 895 } 896 897 /** 898 * Don't use in new code, instead explicitly check 899 * {@link #getAction()}. 900 * 901 * @return If the action is ACTION_DOWN, returns true; else false. 902 * 903 * @deprecated 904 * @hide 905 */ 906 @Deprecated public final boolean isDown() { 907 return mAction == ACTION_DOWN; 908 } 909 910 /** 911 * Is this a system key? System keys can not be used for menu shortcuts. 912 * 913 * TODO: this information should come from a table somewhere. 914 * TODO: should the dpad keys be here? arguably, because they also shouldn't be menu shortcuts 915 */ 916 public final boolean isSystem() { 917 return native_isSystemKey(mKeyCode); 918 } 919 920 /** @hide */ 921 public final boolean hasDefaultAction() { 922 return native_hasDefaultAction(mKeyCode); 923 } 924 925 926 /** 927 * <p>Returns the state of the meta keys.</p> 928 * 929 * @return an integer in which each bit set to 1 represents a pressed 930 * meta key 931 * 932 * @see #isAltPressed() 933 * @see #isShiftPressed() 934 * @see #isSymPressed() 935 * @see #META_ALT_ON 936 * @see #META_SHIFT_ON 937 * @see #META_SYM_ON 938 */ 939 public final int getMetaState() { 940 return mMetaState; 941 } 942 943 /** 944 * Returns the flags for this key event. 945 * 946 * @see #FLAG_WOKE_HERE 947 */ 948 public final int getFlags() { 949 return mFlags; 950 } 951 952 /** 953 * Returns true if this key code is a modifier key. 954 * 955 * @return whether the provided keyCode is one of 956 * {@link #KEYCODE_SHIFT_LEFT} {@link #KEYCODE_SHIFT_RIGHT}, 957 * {@link #KEYCODE_ALT_LEFT}, {@link #KEYCODE_ALT_RIGHT} 958 * or {@link #KEYCODE_SYM}. 959 */ 960 public static boolean isModifierKey(int keyCode) { 961 return keyCode == KEYCODE_SHIFT_LEFT || keyCode == KEYCODE_SHIFT_RIGHT 962 || keyCode == KEYCODE_ALT_LEFT || keyCode == KEYCODE_ALT_RIGHT 963 || keyCode == KEYCODE_SYM; 964 } 965 966 /** 967 * <p>Returns the pressed state of the ALT meta key.</p> 968 * 969 * @return true if the ALT key is pressed, false otherwise 970 * 971 * @see #KEYCODE_ALT_LEFT 972 * @see #KEYCODE_ALT_RIGHT 973 * @see #META_ALT_ON 974 */ 975 public final boolean isAltPressed() { 976 return (mMetaState & META_ALT_ON) != 0; 977 } 978 979 /** 980 * <p>Returns the pressed state of the SHIFT meta key.</p> 981 * 982 * @return true if the SHIFT key is pressed, false otherwise 983 * 984 * @see #KEYCODE_SHIFT_LEFT 985 * @see #KEYCODE_SHIFT_RIGHT 986 * @see #META_SHIFT_ON 987 */ 988 public final boolean isShiftPressed() { 989 return (mMetaState & META_SHIFT_ON) != 0; 990 } 991 992 /** 993 * <p>Returns the pressed state of the SYM meta key.</p> 994 * 995 * @return true if the SYM key is pressed, false otherwise 996 * 997 * @see #KEYCODE_SYM 998 * @see #META_SYM_ON 999 */ 1000 public final boolean isSymPressed() { 1001 return (mMetaState & META_SYM_ON) != 0; 1002 } 1003 1004 /** 1005 * Retrieve the action of this key event. May be either 1006 * {@link #ACTION_DOWN}, {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}. 1007 * 1008 * @return The event action: ACTION_DOWN, ACTION_UP, or ACTION_MULTIPLE. 1009 */ 1010 public final int getAction() { 1011 return mAction; 1012 } 1013 1014 /** 1015 * For {@link #ACTION_UP} events, indicates that the event has been 1016 * canceled as per {@link #FLAG_CANCELED}. 1017 */ 1018 public final boolean isCanceled() { 1019 return (mFlags&FLAG_CANCELED) != 0; 1020 } 1021 1022 /** 1023 * Call this during {@link Callback#onKeyDown} to have the system track 1024 * the key through its final up (possibly including a long press). Note 1025 * that only one key can be tracked at a time -- if another key down 1026 * event is received while a previous one is being tracked, tracking is 1027 * stopped on the previous event. 1028 */ 1029 public final void startTracking() { 1030 mFlags |= FLAG_START_TRACKING; 1031 } 1032 1033 /** 1034 * For {@link #ACTION_UP} events, indicates that the event is still being 1035 * tracked from its initial down event as per 1036 * {@link #FLAG_TRACKING}. 1037 */ 1038 public final boolean isTracking() { 1039 return (mFlags&FLAG_TRACKING) != 0; 1040 } 1041 1042 /** 1043 * For {@link #ACTION_DOWN} events, indicates that the event has been 1044 * canceled as per {@link #FLAG_LONG_PRESS}. 1045 */ 1046 public final boolean isLongPress() { 1047 return (mFlags&FLAG_LONG_PRESS) != 0; 1048 } 1049 1050 /** 1051 * Retrieve the key code of the key event. This is the physical key that 1052 * was pressed, <em>not</em> the Unicode character. 1053 * 1054 * @return The key code of the event. 1055 */ 1056 public final int getKeyCode() { 1057 return mKeyCode; 1058 } 1059 1060 /** 1061 * For the special case of a {@link #ACTION_MULTIPLE} event with key 1062 * code of {@link #KEYCODE_UNKNOWN}, this is a raw string of characters 1063 * associated with the event. In all other cases it is null. 1064 * 1065 * @return Returns a String of 1 or more characters associated with 1066 * the event. 1067 */ 1068 public final String getCharacters() { 1069 return mCharacters; 1070 } 1071 1072 /** 1073 * Retrieve the hardware key id of this key event. These values are not 1074 * reliable and vary from device to device. 1075 * 1076 * {@more} 1077 * Mostly this is here for debugging purposes. 1078 */ 1079 public final int getScanCode() { 1080 return mScanCode; 1081 } 1082 1083 /** 1084 * Retrieve the repeat count of the event. For both key up and key down 1085 * events, this is the number of times the key has repeated with the first 1086 * down starting at 0 and counting up from there. For multiple key 1087 * events, this is the number of down/up pairs that have occurred. 1088 * 1089 * @return The number of times the key has repeated. 1090 */ 1091 public final int getRepeatCount() { 1092 return mRepeatCount; 1093 } 1094 1095 /** 1096 * Retrieve the time of the most recent key down event, 1097 * in the {@link android.os.SystemClock#uptimeMillis} time base. If this 1098 * is a down event, this will be the same as {@link #getEventTime()}. 1099 * Note that when chording keys, this value is the down time of the 1100 * most recently pressed key, which may <em>not</em> be the same physical 1101 * key of this event. 1102 * 1103 * @return Returns the most recent key down time, in the 1104 * {@link android.os.SystemClock#uptimeMillis} time base 1105 */ 1106 public final long getDownTime() { 1107 return mDownTime; 1108 } 1109 1110 /** 1111 * Retrieve the time this event occurred, 1112 * in the {@link android.os.SystemClock#uptimeMillis} time base. 1113 * 1114 * @return Returns the time this event occurred, 1115 * in the {@link android.os.SystemClock#uptimeMillis} time base. 1116 */ 1117 public final long getEventTime() { 1118 return mEventTime; 1119 } 1120 1121 /** 1122 * Renamed to {@link #getDeviceId}. 1123 * 1124 * @hide 1125 * @deprecated 1126 */ 1127 public final int getKeyboardDevice() { 1128 return mDeviceId; 1129 } 1130 1131 /** 1132 * Get the primary character for this key. In other words, the label 1133 * that is physically printed on it. 1134 */ 1135 public char getDisplayLabel() { 1136 return KeyCharacterMap.load(mDeviceId).getDisplayLabel(mKeyCode); 1137 } 1138 1139 /** 1140 * <p> 1141 * Returns the Unicode character that the key would produce. 1142 * </p><p> 1143 * Returns 0 if the key is not one that is used to type Unicode 1144 * characters. 1145 * </p><p> 1146 * If the return value has bit 1147 * {@link KeyCharacterMap#COMBINING_ACCENT} 1148 * set, the key is a "dead key" that should be combined with another to 1149 * actually produce a character -- see {@link #getDeadChar} -- 1150 * after masking with 1151 * {@link KeyCharacterMap#COMBINING_ACCENT_MASK}. 1152 * </p> 1153 */ 1154 public int getUnicodeChar() { 1155 return getUnicodeChar(mMetaState); 1156 } 1157 1158 /** 1159 * <p> 1160 * Returns the Unicode character that the key would produce. 1161 * </p><p> 1162 * Returns 0 if the key is not one that is used to type Unicode 1163 * characters. 1164 * </p><p> 1165 * If the return value has bit 1166 * {@link KeyCharacterMap#COMBINING_ACCENT} 1167 * set, the key is a "dead key" that should be combined with another to 1168 * actually produce a character -- see {@link #getDeadChar} -- after masking 1169 * with {@link KeyCharacterMap#COMBINING_ACCENT_MASK}. 1170 * </p> 1171 */ 1172 public int getUnicodeChar(int meta) { 1173 return KeyCharacterMap.load(mDeviceId).get(mKeyCode, meta); 1174 } 1175 1176 /** 1177 * Get the characters conversion data for the key event.. 1178 * 1179 * @param results a {@link KeyData} that will be filled with the results. 1180 * 1181 * @return whether the key was mapped or not. If the key was not mapped, 1182 * results is not modified. 1183 */ 1184 public boolean getKeyData(KeyData results) { 1185 return KeyCharacterMap.load(mDeviceId).getKeyData(mKeyCode, results); 1186 } 1187 1188 /** 1189 * The same as {@link #getMatch(char[],int) getMatch(chars, 0)}. 1190 */ 1191 public char getMatch(char[] chars) { 1192 return getMatch(chars, 0); 1193 } 1194 1195 /** 1196 * If one of the chars in the array can be generated by the keyCode of this 1197 * key event, return the char; otherwise return '\0'. 1198 * @param chars the characters to try to find 1199 * @param modifiers the modifier bits to prefer. If any of these bits 1200 * are set, if there are multiple choices, that could 1201 * work, the one for this modifier will be set. 1202 */ 1203 public char getMatch(char[] chars, int modifiers) { 1204 return KeyCharacterMap.load(mDeviceId).getMatch(mKeyCode, chars, modifiers); 1205 } 1206 1207 /** 1208 * Gets the number or symbol associated with the key. The character value 1209 * is returned, not the numeric value. If the key is not a number, but is 1210 * a symbol, the symbol is retuned. 1211 */ 1212 public char getNumber() { 1213 return KeyCharacterMap.load(mDeviceId).getNumber(mKeyCode); 1214 } 1215 1216 /** 1217 * Does the key code of this key produce a glyph? 1218 */ 1219 public boolean isPrintingKey() { 1220 return KeyCharacterMap.load(mDeviceId).isPrintingKey(mKeyCode); 1221 } 1222 1223 /** 1224 * @deprecated Use {@link #dispatch(Callback, DispatcherState, Object)} instead. 1225 */ 1226 @Deprecated 1227 public final boolean dispatch(Callback receiver) { 1228 return dispatch(receiver, null, null); 1229 } 1230 1231 /** 1232 * Deliver this key event to a {@link Callback} interface. If this is 1233 * an ACTION_MULTIPLE event and it is not handled, then an attempt will 1234 * be made to deliver a single normal event. 1235 * 1236 * @param receiver The Callback that will be given the event. 1237 * @param state State information retained across events. 1238 * @param target The target of the dispatch, for use in tracking. 1239 * 1240 * @return The return value from the Callback method that was called. 1241 */ 1242 public final boolean dispatch(Callback receiver, DispatcherState state, 1243 Object target) { 1244 switch (mAction) { 1245 case ACTION_DOWN: { 1246 mFlags &= ~FLAG_START_TRACKING; 1247 if (DEBUG) Log.v(TAG, "Key down to " + target + " in " + state 1248 + ": " + this); 1249 boolean res = receiver.onKeyDown(mKeyCode, this); 1250 if (state != null) { 1251 if (res && mRepeatCount == 0 && (mFlags&FLAG_START_TRACKING) != 0) { 1252 if (DEBUG) Log.v(TAG, " Start tracking!"); 1253 state.startTracking(this, target); 1254 } else if (isLongPress() && state.isTracking(this)) { 1255 try { 1256 if (receiver.onKeyLongPress(mKeyCode, this)) { 1257 if (DEBUG) Log.v(TAG, " Clear from long press!"); 1258 state.performedLongPress(this); 1259 res = true; 1260 } 1261 } catch (AbstractMethodError e) { 1262 } 1263 } 1264 } 1265 return res; 1266 } 1267 case ACTION_UP: 1268 if (DEBUG) Log.v(TAG, "Key up to " + target + " in " + state 1269 + ": " + this); 1270 if (state != null) { 1271 state.handleUpEvent(this); 1272 } 1273 return receiver.onKeyUp(mKeyCode, this); 1274 case ACTION_MULTIPLE: 1275 final int count = mRepeatCount; 1276 final int code = mKeyCode; 1277 if (receiver.onKeyMultiple(code, count, this)) { 1278 return true; 1279 } 1280 if (code != KeyEvent.KEYCODE_UNKNOWN) { 1281 mAction = ACTION_DOWN; 1282 mRepeatCount = 0; 1283 boolean handled = receiver.onKeyDown(code, this); 1284 if (handled) { 1285 mAction = ACTION_UP; 1286 receiver.onKeyUp(code, this); 1287 } 1288 mAction = ACTION_MULTIPLE; 1289 mRepeatCount = count; 1290 return handled; 1291 } 1292 return false; 1293 } 1294 return false; 1295 } 1296 1297 /** 1298 * Use with {@link KeyEvent#dispatch(Callback, DispatcherState, Object)} 1299 * for more advanced key dispatching, such as long presses. 1300 */ 1301 public static class DispatcherState { 1302 int mDownKeyCode; 1303 Object mDownTarget; 1304 SparseIntArray mActiveLongPresses = new SparseIntArray(); 1305 1306 /** 1307 * Reset back to initial state. 1308 */ 1309 public void reset() { 1310 if (DEBUG) Log.v(TAG, "Reset: " + this); 1311 mDownKeyCode = 0; 1312 mDownTarget = null; 1313 mActiveLongPresses.clear(); 1314 } 1315 1316 /** 1317 * Stop any tracking associated with this target. 1318 */ 1319 public void reset(Object target) { 1320 if (mDownTarget == target) { 1321 if (DEBUG) Log.v(TAG, "Reset in " + target + ": " + this); 1322 mDownKeyCode = 0; 1323 mDownTarget = null; 1324 } 1325 } 1326 1327 /** 1328 * Start tracking the key code associated with the given event. This 1329 * can only be called on a key down. It will allow you to see any 1330 * long press associated with the key, and will result in 1331 * {@link KeyEvent#isTracking} return true on the long press and up 1332 * events. 1333 * 1334 * <p>This is only needed if you are directly dispatching events, rather 1335 * than handling them in {@link Callback#onKeyDown}. 1336 */ 1337 public void startTracking(KeyEvent event, Object target) { 1338 if (event.getAction() != ACTION_DOWN) { 1339 throw new IllegalArgumentException( 1340 "Can only start tracking on a down event"); 1341 } 1342 if (DEBUG) Log.v(TAG, "Start trackingt in " + target + ": " + this); 1343 mDownKeyCode = event.getKeyCode(); 1344 mDownTarget = target; 1345 } 1346 1347 /** 1348 * Return true if the key event is for a key code that is currently 1349 * being tracked by the dispatcher. 1350 */ 1351 public boolean isTracking(KeyEvent event) { 1352 return mDownKeyCode == event.getKeyCode(); 1353 } 1354 1355 /** 1356 * Keep track of the given event's key code as having performed an 1357 * action with a long press, so no action should occur on the up. 1358 * <p>This is only needed if you are directly dispatching events, rather 1359 * than handling them in {@link Callback#onKeyLongPress}. 1360 */ 1361 public void performedLongPress(KeyEvent event) { 1362 mActiveLongPresses.put(event.getKeyCode(), 1); 1363 } 1364 1365 /** 1366 * Handle key up event to stop tracking. This resets the dispatcher state, 1367 * and updates the key event state based on it. 1368 * <p>This is only needed if you are directly dispatching events, rather 1369 * than handling them in {@link Callback#onKeyUp}. 1370 */ 1371 public void handleUpEvent(KeyEvent event) { 1372 final int keyCode = event.getKeyCode(); 1373 if (DEBUG) Log.v(TAG, "Handle key up " + event + ": " + this); 1374 int index = mActiveLongPresses.indexOfKey(keyCode); 1375 if (index >= 0) { 1376 if (DEBUG) Log.v(TAG, " Index: " + index); 1377 event.mFlags |= FLAG_CANCELED | FLAG_CANCELED_LONG_PRESS; 1378 mActiveLongPresses.removeAt(index); 1379 } 1380 if (mDownKeyCode == keyCode) { 1381 if (DEBUG) Log.v(TAG, " Tracking!"); 1382 event.mFlags |= FLAG_TRACKING; 1383 mDownKeyCode = 0; 1384 mDownTarget = null; 1385 } 1386 } 1387 } 1388 1389 public String toString() { 1390 return "KeyEvent{action=" + mAction + " code=" + mKeyCode 1391 + " repeat=" + mRepeatCount 1392 + " meta=" + mMetaState + " scancode=" + mScanCode 1393 + " mFlags=" + mFlags + "}"; 1394 } 1395 1396 public static final Parcelable.Creator<KeyEvent> CREATOR 1397 = new Parcelable.Creator<KeyEvent>() { 1398 public KeyEvent createFromParcel(Parcel in) { 1399 in.readInt(); // skip token, we already know this is a KeyEvent 1400 return KeyEvent.createFromParcelBody(in); 1401 } 1402 1403 public KeyEvent[] newArray(int size) { 1404 return new KeyEvent[size]; 1405 } 1406 }; 1407 1408 /** @hide */ 1409 public static KeyEvent createFromParcelBody(Parcel in) { 1410 return new KeyEvent(in); 1411 } 1412 1413 private KeyEvent(Parcel in) { 1414 readBaseFromParcel(in); 1415 1416 mAction = in.readInt(); 1417 mKeyCode = in.readInt(); 1418 mRepeatCount = in.readInt(); 1419 mMetaState = in.readInt(); 1420 mScanCode = in.readInt(); 1421 mFlags = in.readInt(); 1422 mDownTime = in.readLong(); 1423 mEventTime = in.readLong(); 1424 } 1425 1426 public void writeToParcel(Parcel out, int flags) { 1427 out.writeInt(PARCEL_TOKEN_KEY_EVENT); 1428 1429 writeBaseToParcel(out); 1430 1431 out.writeInt(mAction); 1432 out.writeInt(mKeyCode); 1433 out.writeInt(mRepeatCount); 1434 out.writeInt(mMetaState); 1435 out.writeInt(mScanCode); 1436 out.writeInt(mFlags); 1437 out.writeLong(mDownTime); 1438 out.writeLong(mEventTime); 1439 } 1440 1441 private native boolean native_isSystemKey(int keyCode); 1442 private native boolean native_hasDefaultAction(int keyCode); 1443} 1444