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 17 package android.view; 18 19 import android.os.Parcel; 20 import android.os.Parcelable; 21 import android.util.Log; 22 import android.util.SparseIntArray; 23 import android.view.KeyCharacterMap; 24 import 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 */ 60 public 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 */ getMaxKeyCode()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 */ getDeadChar(int accent, int c)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 */ onKeyDown(int keyCode, KeyEvent event)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 */ onKeyLongPress(int keyCode, KeyEvent event)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 */ onKeyUp(int keyCode, KeyEvent event)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 */ onKeyMultiple(int keyCode, int count, KeyEvent event)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 */ KeyEvent(int action, int code)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 */ KeyEvent(long downTime, long eventTime, int action, int code, int repeat)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 */ KeyEvent(long downTime, long eventTime, int action, int code, int repeat, int metaState)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 */ KeyEvent(long downTime, long eventTime, int action, int code, int repeat, int metaState, int deviceId, int scancode)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 */ KeyEvent(long downTime, long eventTime, int action, int code, int repeat, int metaState, int deviceId, int scancode, int flags)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 */ KeyEvent(long downTime, long eventTime, int action, int code, int repeat, int metaState, int deviceId, int scancode, int flags, int source)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 */ KeyEvent(long time, String characters, int deviceId, int flags)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 */ KeyEvent(KeyEvent origEvent)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 KeyEvent(KeyEvent origEvent, long eventTime, int newRepeat)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 */ changeTimeRepeat(KeyEvent event, long eventTime, int newRepeat)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 */ changeTimeRepeat(KeyEvent event, long eventTime, int newRepeat, int newFlags)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 */ KeyEvent(KeyEvent origEvent, int action)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 */ changeAction(KeyEvent event, int action)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 */ changeFlags(KeyEvent event, int flags)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 */ isDown()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 */ isSystem()923 public final boolean isSystem() { 924 return native_isSystemKey(mKeyCode); 925 } 926 927 /** @hide */ hasDefaultAction()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 */ getMetaState()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 */ getFlags()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 */ isModifierKey(int keyCode)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 */ isAltPressed()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 */ isShiftPressed()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 */ isSymPressed()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 */ getAction()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 */ isCanceled()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 */ startTracking()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 */ isTracking()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 */ isLongPress()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 */ getKeyCode()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 */ getCharacters()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 */ getScanCode()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 */ getRepeatCount()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 */ getDownTime()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 */ getEventTime()1124 public final long getEventTime() { 1125 return mEventTime; 1126 } 1127 1128 /** 1129 * Renamed to {@link #getDeviceId}. 1130 * 1131 * @hide 1132 * @deprecated 1133 */ getKeyboardDevice()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 */ getDisplayLabel()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 */ getUnicodeChar()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 */ getUnicodeChar(int meta)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 */ getKeyData(KeyData results)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 */ getMatch(char[] chars)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 */ getMatch(char[] chars, int modifiers)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 */ getNumber()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 */ isPrintingKey()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 dispatch(Callback receiver)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 */ dispatch(Callback receiver, DispatcherState state, Object target)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 */ reset()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 */ reset(Object target)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 */ startTracking(KeyEvent event, Object target)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 */ isTracking(KeyEvent event)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 */ performedLongPress(KeyEvent event)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 */ handleUpEvent(KeyEvent event)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 toString()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 */ createFromParcelBody(Parcel in)1416 public static KeyEvent createFromParcelBody(Parcel in) { 1417 return new KeyEvent(in); 1418 } 1419 KeyEvent(Parcel in)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 writeToParcel(Parcel out, int flags)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 native_isSystemKey(int keyCode)1448 private native boolean native_isSystemKey(int keyCode); native_hasDefaultAction(int keyCode)1449 private native boolean native_hasDefaultAction(int keyCode); 1450 } 1451