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