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 static android.view.Display.INVALID_DISPLAY; 20 21 import android.annotation.NonNull; 22 import android.annotation.TestApi; 23 import android.compat.annotation.UnsupportedAppUsage; 24 import android.os.Build; 25 import android.os.Parcel; 26 import android.os.Parcelable; 27 import android.text.method.MetaKeyKeyListener; 28 import android.util.Log; 29 import android.util.SparseIntArray; 30 import android.view.KeyCharacterMap.KeyData; 31 32 /** 33 * Object used to report key and button events. 34 * <p> 35 * Each key press is described by a sequence of key events. A key press 36 * starts with a key event with {@link #ACTION_DOWN}. If the key is held 37 * sufficiently long that it repeats, then the initial down is followed 38 * additional key events with {@link #ACTION_DOWN} and a non-zero value for 39 * {@link #getRepeatCount()}. The last key event is a {@link #ACTION_UP} 40 * for the key up. If the key press is canceled, the key up event will have the 41 * {@link #FLAG_CANCELED} flag set. 42 * </p><p> 43 * Key events are generally accompanied by a key code ({@link #getKeyCode()}), 44 * scan code ({@link #getScanCode()}) and meta state ({@link #getMetaState()}). 45 * Key code constants are defined in this class. Scan code constants are raw 46 * device-specific codes obtained from the OS and so are not generally meaningful 47 * to applications unless interpreted using the {@link KeyCharacterMap}. 48 * Meta states describe the pressed state of key modifiers 49 * such as {@link #META_SHIFT_ON} or {@link #META_ALT_ON}. 50 * </p><p> 51 * Key codes typically correspond one-to-one with individual keys on an input device. 52 * Many keys and key combinations serve quite different functions on different 53 * input devices so care must be taken when interpreting them. Always use the 54 * {@link KeyCharacterMap} associated with the input device when mapping keys 55 * to characters. Be aware that there may be multiple key input devices active 56 * at the same time and each will have its own key character map. 57 * </p><p> 58 * As soft input methods can use multiple and inventive ways of inputting text, 59 * there is no guarantee that any key press on a soft keyboard will generate a key 60 * event: this is left to the IME's discretion, and in fact sending such events is 61 * discouraged. You should never rely on receiving KeyEvents for any key on a soft 62 * input method. In particular, the default software keyboard will never send any 63 * key event to any application targetting Jelly Bean or later, and will only send 64 * events for some presses of the delete and return keys to applications targetting 65 * Ice Cream Sandwich or earlier. Be aware that other software input methods may 66 * never send key events regardless of the version. Consider using editor actions 67 * like {@link android.view.inputmethod.EditorInfo#IME_ACTION_DONE} if you need 68 * specific interaction with the software keyboard, as it gives more visibility to 69 * the user as to how your application will react to key presses. 70 * </p><p> 71 * When interacting with an IME, the framework may deliver key events 72 * with the special action {@link #ACTION_MULTIPLE} that either specifies 73 * that single repeated key code or a sequence of characters to insert. 74 * </p><p> 75 * In general, the framework cannot guarantee that the key events it delivers 76 * to a view always constitute complete key sequences since some events may be dropped 77 * or modified by containing views before they are delivered. The view implementation 78 * should be prepared to handle {@link #FLAG_CANCELED} and should tolerate anomalous 79 * situations such as receiving a new {@link #ACTION_DOWN} without first having 80 * received an {@link #ACTION_UP} for the prior key press. 81 * </p><p> 82 * Refer to {@link InputDevice} for more information about how different kinds of 83 * input devices and sources represent keys and buttons. 84 * </p> 85 */ 86 public class KeyEvent extends InputEvent implements Parcelable { 87 /** Key code constant: Unknown key code. */ 88 public static final int KEYCODE_UNKNOWN = 0; 89 /** Key code constant: Soft Left key. 90 * Usually situated below the display on phones and used as a multi-function 91 * feature key for selecting a software defined function shown on the bottom left 92 * of the display. */ 93 public static final int KEYCODE_SOFT_LEFT = 1; 94 /** Key code constant: Soft Right key. 95 * Usually situated below the display on phones and used as a multi-function 96 * feature key for selecting a software defined function shown on the bottom right 97 * of the display. */ 98 public static final int KEYCODE_SOFT_RIGHT = 2; 99 /** Key code constant: Home key. 100 * This key is handled by the framework and is never delivered to applications. */ 101 public static final int KEYCODE_HOME = 3; 102 /** Key code constant: Back key. */ 103 public static final int KEYCODE_BACK = 4; 104 /** Key code constant: Call key. */ 105 public static final int KEYCODE_CALL = 5; 106 /** Key code constant: End Call key. */ 107 public static final int KEYCODE_ENDCALL = 6; 108 /** Key code constant: '0' key. */ 109 public static final int KEYCODE_0 = 7; 110 /** Key code constant: '1' key. */ 111 public static final int KEYCODE_1 = 8; 112 /** Key code constant: '2' key. */ 113 public static final int KEYCODE_2 = 9; 114 /** Key code constant: '3' key. */ 115 public static final int KEYCODE_3 = 10; 116 /** Key code constant: '4' key. */ 117 public static final int KEYCODE_4 = 11; 118 /** Key code constant: '5' key. */ 119 public static final int KEYCODE_5 = 12; 120 /** Key code constant: '6' key. */ 121 public static final int KEYCODE_6 = 13; 122 /** Key code constant: '7' key. */ 123 public static final int KEYCODE_7 = 14; 124 /** Key code constant: '8' key. */ 125 public static final int KEYCODE_8 = 15; 126 /** Key code constant: '9' key. */ 127 public static final int KEYCODE_9 = 16; 128 /** Key code constant: '*' key. */ 129 public static final int KEYCODE_STAR = 17; 130 /** Key code constant: '#' key. */ 131 public static final int KEYCODE_POUND = 18; 132 /** Key code constant: Directional Pad Up key. 133 * May also be synthesized from trackball motions. */ 134 public static final int KEYCODE_DPAD_UP = 19; 135 /** Key code constant: Directional Pad Down key. 136 * May also be synthesized from trackball motions. */ 137 public static final int KEYCODE_DPAD_DOWN = 20; 138 /** Key code constant: Directional Pad Left key. 139 * May also be synthesized from trackball motions. */ 140 public static final int KEYCODE_DPAD_LEFT = 21; 141 /** Key code constant: Directional Pad Right key. 142 * May also be synthesized from trackball motions. */ 143 public static final int KEYCODE_DPAD_RIGHT = 22; 144 /** Key code constant: Directional Pad Center key. 145 * May also be synthesized from trackball motions. */ 146 public static final int KEYCODE_DPAD_CENTER = 23; 147 /** Key code constant: Volume Up key. 148 * Adjusts the speaker volume up. */ 149 public static final int KEYCODE_VOLUME_UP = 24; 150 /** Key code constant: Volume Down key. 151 * Adjusts the speaker volume down. */ 152 public static final int KEYCODE_VOLUME_DOWN = 25; 153 /** Key code constant: Power key. */ 154 public static final int KEYCODE_POWER = 26; 155 /** Key code constant: Camera key. 156 * Used to launch a camera application or take pictures. */ 157 public static final int KEYCODE_CAMERA = 27; 158 /** Key code constant: Clear key. */ 159 public static final int KEYCODE_CLEAR = 28; 160 /** Key code constant: 'A' key. */ 161 public static final int KEYCODE_A = 29; 162 /** Key code constant: 'B' key. */ 163 public static final int KEYCODE_B = 30; 164 /** Key code constant: 'C' key. */ 165 public static final int KEYCODE_C = 31; 166 /** Key code constant: 'D' key. */ 167 public static final int KEYCODE_D = 32; 168 /** Key code constant: 'E' key. */ 169 public static final int KEYCODE_E = 33; 170 /** Key code constant: 'F' key. */ 171 public static final int KEYCODE_F = 34; 172 /** Key code constant: 'G' key. */ 173 public static final int KEYCODE_G = 35; 174 /** Key code constant: 'H' key. */ 175 public static final int KEYCODE_H = 36; 176 /** Key code constant: 'I' key. */ 177 public static final int KEYCODE_I = 37; 178 /** Key code constant: 'J' key. */ 179 public static final int KEYCODE_J = 38; 180 /** Key code constant: 'K' key. */ 181 public static final int KEYCODE_K = 39; 182 /** Key code constant: 'L' key. */ 183 public static final int KEYCODE_L = 40; 184 /** Key code constant: 'M' key. */ 185 public static final int KEYCODE_M = 41; 186 /** Key code constant: 'N' key. */ 187 public static final int KEYCODE_N = 42; 188 /** Key code constant: 'O' key. */ 189 public static final int KEYCODE_O = 43; 190 /** Key code constant: 'P' key. */ 191 public static final int KEYCODE_P = 44; 192 /** Key code constant: 'Q' key. */ 193 public static final int KEYCODE_Q = 45; 194 /** Key code constant: 'R' key. */ 195 public static final int KEYCODE_R = 46; 196 /** Key code constant: 'S' key. */ 197 public static final int KEYCODE_S = 47; 198 /** Key code constant: 'T' key. */ 199 public static final int KEYCODE_T = 48; 200 /** Key code constant: 'U' key. */ 201 public static final int KEYCODE_U = 49; 202 /** Key code constant: 'V' key. */ 203 public static final int KEYCODE_V = 50; 204 /** Key code constant: 'W' key. */ 205 public static final int KEYCODE_W = 51; 206 /** Key code constant: 'X' key. */ 207 public static final int KEYCODE_X = 52; 208 /** Key code constant: 'Y' key. */ 209 public static final int KEYCODE_Y = 53; 210 /** Key code constant: 'Z' key. */ 211 public static final int KEYCODE_Z = 54; 212 /** Key code constant: ',' key. */ 213 public static final int KEYCODE_COMMA = 55; 214 /** Key code constant: '.' key. */ 215 public static final int KEYCODE_PERIOD = 56; 216 /** Key code constant: Left Alt modifier key. */ 217 public static final int KEYCODE_ALT_LEFT = 57; 218 /** Key code constant: Right Alt modifier key. */ 219 public static final int KEYCODE_ALT_RIGHT = 58; 220 /** Key code constant: Left Shift modifier key. */ 221 public static final int KEYCODE_SHIFT_LEFT = 59; 222 /** Key code constant: Right Shift modifier key. */ 223 public static final int KEYCODE_SHIFT_RIGHT = 60; 224 /** Key code constant: Tab key. */ 225 public static final int KEYCODE_TAB = 61; 226 /** Key code constant: Space key. */ 227 public static final int KEYCODE_SPACE = 62; 228 /** Key code constant: Symbol modifier key. 229 * Used to enter alternate symbols. */ 230 public static final int KEYCODE_SYM = 63; 231 /** Key code constant: Explorer special function key. 232 * Used to launch a browser application. */ 233 public static final int KEYCODE_EXPLORER = 64; 234 /** Key code constant: Envelope special function key. 235 * Used to launch a mail application. */ 236 public static final int KEYCODE_ENVELOPE = 65; 237 /** Key code constant: Enter key. */ 238 public static final int KEYCODE_ENTER = 66; 239 /** Key code constant: Backspace key. 240 * Deletes characters before the insertion point, unlike {@link #KEYCODE_FORWARD_DEL}. */ 241 public static final int KEYCODE_DEL = 67; 242 /** Key code constant: '`' (backtick) key. */ 243 public static final int KEYCODE_GRAVE = 68; 244 /** Key code constant: '-'. */ 245 public static final int KEYCODE_MINUS = 69; 246 /** Key code constant: '=' key. */ 247 public static final int KEYCODE_EQUALS = 70; 248 /** Key code constant: '[' key. */ 249 public static final int KEYCODE_LEFT_BRACKET = 71; 250 /** Key code constant: ']' key. */ 251 public static final int KEYCODE_RIGHT_BRACKET = 72; 252 /** Key code constant: '\' key. */ 253 public static final int KEYCODE_BACKSLASH = 73; 254 /** Key code constant: ';' key. */ 255 public static final int KEYCODE_SEMICOLON = 74; 256 /** Key code constant: ''' (apostrophe) key. */ 257 public static final int KEYCODE_APOSTROPHE = 75; 258 /** Key code constant: '/' key. */ 259 public static final int KEYCODE_SLASH = 76; 260 /** Key code constant: '@' key. */ 261 public static final int KEYCODE_AT = 77; 262 /** Key code constant: Number modifier key. 263 * Used to enter numeric symbols. 264 * This key is not Num Lock; it is more like {@link #KEYCODE_ALT_LEFT} and is 265 * interpreted as an ALT key by {@link android.text.method.MetaKeyKeyListener}. */ 266 public static final int KEYCODE_NUM = 78; 267 /** Key code constant: Headset Hook key. 268 * Used to hang up calls and stop media. */ 269 public static final int KEYCODE_HEADSETHOOK = 79; 270 /** Key code constant: Camera Focus key. 271 * Used to focus the camera. */ 272 public static final int KEYCODE_FOCUS = 80; // *Camera* focus 273 /** Key code constant: '+' key. */ 274 public static final int KEYCODE_PLUS = 81; 275 /** Key code constant: Menu key. */ 276 public static final int KEYCODE_MENU = 82; 277 /** Key code constant: Notification key. */ 278 public static final int KEYCODE_NOTIFICATION = 83; 279 /** Key code constant: Search key. */ 280 public static final int KEYCODE_SEARCH = 84; 281 /** Key code constant: Play/Pause media key. */ 282 public static final int KEYCODE_MEDIA_PLAY_PAUSE= 85; 283 /** Key code constant: Stop media key. */ 284 public static final int KEYCODE_MEDIA_STOP = 86; 285 /** Key code constant: Play Next media key. */ 286 public static final int KEYCODE_MEDIA_NEXT = 87; 287 /** Key code constant: Play Previous media key. */ 288 public static final int KEYCODE_MEDIA_PREVIOUS = 88; 289 /** Key code constant: Rewind media key. */ 290 public static final int KEYCODE_MEDIA_REWIND = 89; 291 /** Key code constant: Fast Forward media key. */ 292 public static final int KEYCODE_MEDIA_FAST_FORWARD = 90; 293 /** Key code constant: Mute key. 294 * Mutes the microphone, unlike {@link #KEYCODE_VOLUME_MUTE}. */ 295 public static final int KEYCODE_MUTE = 91; 296 /** Key code constant: Page Up key. */ 297 public static final int KEYCODE_PAGE_UP = 92; 298 /** Key code constant: Page Down key. */ 299 public static final int KEYCODE_PAGE_DOWN = 93; 300 /** Key code constant: Picture Symbols modifier key. 301 * Used to switch symbol sets (Emoji, Kao-moji). */ 302 public static final int KEYCODE_PICTSYMBOLS = 94; // switch symbol-sets (Emoji,Kao-moji) 303 /** Key code constant: Switch Charset modifier key. 304 * Used to switch character sets (Kanji, Katakana). */ 305 public static final int KEYCODE_SWITCH_CHARSET = 95; // switch char-sets (Kanji,Katakana) 306 /** Key code constant: A Button key. 307 * On a game controller, the A button should be either the button labeled A 308 * or the first button on the bottom row of controller buttons. */ 309 public static final int KEYCODE_BUTTON_A = 96; 310 /** Key code constant: B Button key. 311 * On a game controller, the B button should be either the button labeled B 312 * or the second button on the bottom row of controller buttons. */ 313 public static final int KEYCODE_BUTTON_B = 97; 314 /** Key code constant: C Button key. 315 * On a game controller, the C button should be either the button labeled C 316 * or the third button on the bottom row of controller buttons. */ 317 public static final int KEYCODE_BUTTON_C = 98; 318 /** Key code constant: X Button key. 319 * On a game controller, the X button should be either the button labeled X 320 * or the first button on the upper row of controller buttons. */ 321 public static final int KEYCODE_BUTTON_X = 99; 322 /** Key code constant: Y Button key. 323 * On a game controller, the Y button should be either the button labeled Y 324 * or the second button on the upper row of controller buttons. */ 325 public static final int KEYCODE_BUTTON_Y = 100; 326 /** Key code constant: Z Button key. 327 * On a game controller, the Z button should be either the button labeled Z 328 * or the third button on the upper row of controller buttons. */ 329 public static final int KEYCODE_BUTTON_Z = 101; 330 /** Key code constant: L1 Button key. 331 * On a game controller, the L1 button should be either the button labeled L1 (or L) 332 * or the top left trigger button. */ 333 public static final int KEYCODE_BUTTON_L1 = 102; 334 /** Key code constant: R1 Button key. 335 * On a game controller, the R1 button should be either the button labeled R1 (or R) 336 * or the top right trigger button. */ 337 public static final int KEYCODE_BUTTON_R1 = 103; 338 /** Key code constant: L2 Button key. 339 * On a game controller, the L2 button should be either the button labeled L2 340 * or the bottom left trigger button. */ 341 public static final int KEYCODE_BUTTON_L2 = 104; 342 /** Key code constant: R2 Button key. 343 * On a game controller, the R2 button should be either the button labeled R2 344 * or the bottom right trigger button. */ 345 public static final int KEYCODE_BUTTON_R2 = 105; 346 /** Key code constant: Left Thumb Button key. 347 * On a game controller, the left thumb button indicates that the left (or only) 348 * joystick is pressed. */ 349 public static final int KEYCODE_BUTTON_THUMBL = 106; 350 /** Key code constant: Right Thumb Button key. 351 * On a game controller, the right thumb button indicates that the right 352 * joystick is pressed. */ 353 public static final int KEYCODE_BUTTON_THUMBR = 107; 354 /** Key code constant: Start Button key. 355 * On a game controller, the button labeled Start. */ 356 public static final int KEYCODE_BUTTON_START = 108; 357 /** Key code constant: Select Button key. 358 * On a game controller, the button labeled Select. */ 359 public static final int KEYCODE_BUTTON_SELECT = 109; 360 /** Key code constant: Mode Button key. 361 * On a game controller, the button labeled Mode. */ 362 public static final int KEYCODE_BUTTON_MODE = 110; 363 /** Key code constant: Escape key. */ 364 public static final int KEYCODE_ESCAPE = 111; 365 /** Key code constant: Forward Delete key. 366 * Deletes characters ahead of the insertion point, unlike {@link #KEYCODE_DEL}. */ 367 public static final int KEYCODE_FORWARD_DEL = 112; 368 /** Key code constant: Left Control modifier key. */ 369 public static final int KEYCODE_CTRL_LEFT = 113; 370 /** Key code constant: Right Control modifier key. */ 371 public static final int KEYCODE_CTRL_RIGHT = 114; 372 /** Key code constant: Caps Lock key. */ 373 public static final int KEYCODE_CAPS_LOCK = 115; 374 /** Key code constant: Scroll Lock key. */ 375 public static final int KEYCODE_SCROLL_LOCK = 116; 376 /** Key code constant: Left Meta modifier key. */ 377 public static final int KEYCODE_META_LEFT = 117; 378 /** Key code constant: Right Meta modifier key. */ 379 public static final int KEYCODE_META_RIGHT = 118; 380 /** Key code constant: Function modifier key. */ 381 public static final int KEYCODE_FUNCTION = 119; 382 /** Key code constant: System Request / Print Screen key. */ 383 public static final int KEYCODE_SYSRQ = 120; 384 /** Key code constant: Break / Pause key. */ 385 public static final int KEYCODE_BREAK = 121; 386 /** Key code constant: Home Movement key. 387 * Used for scrolling or moving the cursor around to the start of a line 388 * or to the top of a list. */ 389 public static final int KEYCODE_MOVE_HOME = 122; 390 /** Key code constant: End Movement key. 391 * Used for scrolling or moving the cursor around to the end of a line 392 * or to the bottom of a list. */ 393 public static final int KEYCODE_MOVE_END = 123; 394 /** Key code constant: Insert key. 395 * Toggles insert / overwrite edit mode. */ 396 public static final int KEYCODE_INSERT = 124; 397 /** Key code constant: Forward key. 398 * Navigates forward in the history stack. Complement of {@link #KEYCODE_BACK}. */ 399 public static final int KEYCODE_FORWARD = 125; 400 /** Key code constant: Play media key. */ 401 public static final int KEYCODE_MEDIA_PLAY = 126; 402 /** Key code constant: Pause media key. */ 403 public static final int KEYCODE_MEDIA_PAUSE = 127; 404 /** Key code constant: Close media key. 405 * May be used to close a CD tray, for example. */ 406 public static final int KEYCODE_MEDIA_CLOSE = 128; 407 /** Key code constant: Eject media key. 408 * May be used to eject a CD tray, for example. */ 409 public static final int KEYCODE_MEDIA_EJECT = 129; 410 /** Key code constant: Record media key. */ 411 public static final int KEYCODE_MEDIA_RECORD = 130; 412 /** Key code constant: F1 key. */ 413 public static final int KEYCODE_F1 = 131; 414 /** Key code constant: F2 key. */ 415 public static final int KEYCODE_F2 = 132; 416 /** Key code constant: F3 key. */ 417 public static final int KEYCODE_F3 = 133; 418 /** Key code constant: F4 key. */ 419 public static final int KEYCODE_F4 = 134; 420 /** Key code constant: F5 key. */ 421 public static final int KEYCODE_F5 = 135; 422 /** Key code constant: F6 key. */ 423 public static final int KEYCODE_F6 = 136; 424 /** Key code constant: F7 key. */ 425 public static final int KEYCODE_F7 = 137; 426 /** Key code constant: F8 key. */ 427 public static final int KEYCODE_F8 = 138; 428 /** Key code constant: F9 key. */ 429 public static final int KEYCODE_F9 = 139; 430 /** Key code constant: F10 key. */ 431 public static final int KEYCODE_F10 = 140; 432 /** Key code constant: F11 key. */ 433 public static final int KEYCODE_F11 = 141; 434 /** Key code constant: F12 key. */ 435 public static final int KEYCODE_F12 = 142; 436 /** Key code constant: Num Lock key. 437 * This is the Num Lock key; it is different from {@link #KEYCODE_NUM}. 438 * This key alters the behavior of other keys on the numeric keypad. */ 439 public static final int KEYCODE_NUM_LOCK = 143; 440 /** Key code constant: Numeric keypad '0' key. */ 441 public static final int KEYCODE_NUMPAD_0 = 144; 442 /** Key code constant: Numeric keypad '1' key. */ 443 public static final int KEYCODE_NUMPAD_1 = 145; 444 /** Key code constant: Numeric keypad '2' key. */ 445 public static final int KEYCODE_NUMPAD_2 = 146; 446 /** Key code constant: Numeric keypad '3' key. */ 447 public static final int KEYCODE_NUMPAD_3 = 147; 448 /** Key code constant: Numeric keypad '4' key. */ 449 public static final int KEYCODE_NUMPAD_4 = 148; 450 /** Key code constant: Numeric keypad '5' key. */ 451 public static final int KEYCODE_NUMPAD_5 = 149; 452 /** Key code constant: Numeric keypad '6' key. */ 453 public static final int KEYCODE_NUMPAD_6 = 150; 454 /** Key code constant: Numeric keypad '7' key. */ 455 public static final int KEYCODE_NUMPAD_7 = 151; 456 /** Key code constant: Numeric keypad '8' key. */ 457 public static final int KEYCODE_NUMPAD_8 = 152; 458 /** Key code constant: Numeric keypad '9' key. */ 459 public static final int KEYCODE_NUMPAD_9 = 153; 460 /** Key code constant: Numeric keypad '/' key (for division). */ 461 public static final int KEYCODE_NUMPAD_DIVIDE = 154; 462 /** Key code constant: Numeric keypad '*' key (for multiplication). */ 463 public static final int KEYCODE_NUMPAD_MULTIPLY = 155; 464 /** Key code constant: Numeric keypad '-' key (for subtraction). */ 465 public static final int KEYCODE_NUMPAD_SUBTRACT = 156; 466 /** Key code constant: Numeric keypad '+' key (for addition). */ 467 public static final int KEYCODE_NUMPAD_ADD = 157; 468 /** Key code constant: Numeric keypad '.' key (for decimals or digit grouping). */ 469 public static final int KEYCODE_NUMPAD_DOT = 158; 470 /** Key code constant: Numeric keypad ',' key (for decimals or digit grouping). */ 471 public static final int KEYCODE_NUMPAD_COMMA = 159; 472 /** Key code constant: Numeric keypad Enter key. */ 473 public static final int KEYCODE_NUMPAD_ENTER = 160; 474 /** Key code constant: Numeric keypad '=' key. */ 475 public static final int KEYCODE_NUMPAD_EQUALS = 161; 476 /** Key code constant: Numeric keypad '(' key. */ 477 public static final int KEYCODE_NUMPAD_LEFT_PAREN = 162; 478 /** Key code constant: Numeric keypad ')' key. */ 479 public static final int KEYCODE_NUMPAD_RIGHT_PAREN = 163; 480 /** Key code constant: Volume Mute key. 481 * Mutes the speaker, unlike {@link #KEYCODE_MUTE}. 482 * This key should normally be implemented as a toggle such that the first press 483 * mutes the speaker and the second press restores the original volume. */ 484 public static final int KEYCODE_VOLUME_MUTE = 164; 485 /** Key code constant: Info key. 486 * Common on TV remotes to show additional information related to what is 487 * currently being viewed. */ 488 public static final int KEYCODE_INFO = 165; 489 /** Key code constant: Channel up key. 490 * On TV remotes, increments the television channel. */ 491 public static final int KEYCODE_CHANNEL_UP = 166; 492 /** Key code constant: Channel down key. 493 * On TV remotes, decrements the television channel. */ 494 public static final int KEYCODE_CHANNEL_DOWN = 167; 495 /** Key code constant: Zoom in key. */ 496 public static final int KEYCODE_ZOOM_IN = 168; 497 /** Key code constant: Zoom out key. */ 498 public static final int KEYCODE_ZOOM_OUT = 169; 499 /** Key code constant: TV key. 500 * On TV remotes, switches to viewing live TV. */ 501 public static final int KEYCODE_TV = 170; 502 /** Key code constant: Window key. 503 * On TV remotes, toggles picture-in-picture mode or other windowing functions. 504 * On Android Wear devices, triggers a display offset. */ 505 public static final int KEYCODE_WINDOW = 171; 506 /** Key code constant: Guide key. 507 * On TV remotes, shows a programming guide. */ 508 public static final int KEYCODE_GUIDE = 172; 509 /** Key code constant: DVR key. 510 * On some TV remotes, switches to a DVR mode for recorded shows. */ 511 public static final int KEYCODE_DVR = 173; 512 /** Key code constant: Bookmark key. 513 * On some TV remotes, bookmarks content or web pages. */ 514 public static final int KEYCODE_BOOKMARK = 174; 515 /** Key code constant: Toggle captions key. 516 * Switches the mode for closed-captioning text, for example during television shows. */ 517 public static final int KEYCODE_CAPTIONS = 175; 518 /** Key code constant: Settings key. 519 * Starts the system settings activity. */ 520 public static final int KEYCODE_SETTINGS = 176; 521 /** Key code constant: TV power key. 522 * On TV remotes, toggles the power on a television screen. */ 523 public static final int KEYCODE_TV_POWER = 177; 524 /** Key code constant: TV input key. 525 * On TV remotes, switches the input on a television screen. */ 526 public static final int KEYCODE_TV_INPUT = 178; 527 /** Key code constant: Set-top-box power key. 528 * On TV remotes, toggles the power on an external Set-top-box. */ 529 public static final int KEYCODE_STB_POWER = 179; 530 /** Key code constant: Set-top-box input key. 531 * On TV remotes, switches the input mode on an external Set-top-box. */ 532 public static final int KEYCODE_STB_INPUT = 180; 533 /** Key code constant: A/V Receiver power key. 534 * On TV remotes, toggles the power on an external A/V Receiver. */ 535 public static final int KEYCODE_AVR_POWER = 181; 536 /** Key code constant: A/V Receiver input key. 537 * On TV remotes, switches the input mode on an external A/V Receiver. */ 538 public static final int KEYCODE_AVR_INPUT = 182; 539 /** Key code constant: Red "programmable" key. 540 * On TV remotes, acts as a contextual/programmable key. */ 541 public static final int KEYCODE_PROG_RED = 183; 542 /** Key code constant: Green "programmable" key. 543 * On TV remotes, actsas a contextual/programmable key. */ 544 public static final int KEYCODE_PROG_GREEN = 184; 545 /** Key code constant: Yellow "programmable" key. 546 * On TV remotes, acts as a contextual/programmable key. */ 547 public static final int KEYCODE_PROG_YELLOW = 185; 548 /** Key code constant: Blue "programmable" key. 549 * On TV remotes, acts as a contextual/programmable key. */ 550 public static final int KEYCODE_PROG_BLUE = 186; 551 /** Key code constant: App switch key. 552 * Should bring up the application switcher dialog. */ 553 public static final int KEYCODE_APP_SWITCH = 187; 554 /** Key code constant: Generic Game Pad Button #1.*/ 555 public static final int KEYCODE_BUTTON_1 = 188; 556 /** Key code constant: Generic Game Pad Button #2.*/ 557 public static final int KEYCODE_BUTTON_2 = 189; 558 /** Key code constant: Generic Game Pad Button #3.*/ 559 public static final int KEYCODE_BUTTON_3 = 190; 560 /** Key code constant: Generic Game Pad Button #4.*/ 561 public static final int KEYCODE_BUTTON_4 = 191; 562 /** Key code constant: Generic Game Pad Button #5.*/ 563 public static final int KEYCODE_BUTTON_5 = 192; 564 /** Key code constant: Generic Game Pad Button #6.*/ 565 public static final int KEYCODE_BUTTON_6 = 193; 566 /** Key code constant: Generic Game Pad Button #7.*/ 567 public static final int KEYCODE_BUTTON_7 = 194; 568 /** Key code constant: Generic Game Pad Button #8.*/ 569 public static final int KEYCODE_BUTTON_8 = 195; 570 /** Key code constant: Generic Game Pad Button #9.*/ 571 public static final int KEYCODE_BUTTON_9 = 196; 572 /** Key code constant: Generic Game Pad Button #10.*/ 573 public static final int KEYCODE_BUTTON_10 = 197; 574 /** Key code constant: Generic Game Pad Button #11.*/ 575 public static final int KEYCODE_BUTTON_11 = 198; 576 /** Key code constant: Generic Game Pad Button #12.*/ 577 public static final int KEYCODE_BUTTON_12 = 199; 578 /** Key code constant: Generic Game Pad Button #13.*/ 579 public static final int KEYCODE_BUTTON_13 = 200; 580 /** Key code constant: Generic Game Pad Button #14.*/ 581 public static final int KEYCODE_BUTTON_14 = 201; 582 /** Key code constant: Generic Game Pad Button #15.*/ 583 public static final int KEYCODE_BUTTON_15 = 202; 584 /** Key code constant: Generic Game Pad Button #16.*/ 585 public static final int KEYCODE_BUTTON_16 = 203; 586 /** Key code constant: Language Switch key. 587 * Toggles the current input language such as switching between English and Japanese on 588 * a QWERTY keyboard. On some devices, the same function may be performed by 589 * pressing Shift+Spacebar. */ 590 public static final int KEYCODE_LANGUAGE_SWITCH = 204; 591 /** Key code constant: Manner Mode key. 592 * Toggles silent or vibrate mode on and off to make the device behave more politely 593 * in certain settings such as on a crowded train. On some devices, the key may only 594 * operate when long-pressed. */ 595 public static final int KEYCODE_MANNER_MODE = 205; 596 /** Key code constant: 3D Mode key. 597 * Toggles the display between 2D and 3D mode. */ 598 public static final int KEYCODE_3D_MODE = 206; 599 /** Key code constant: Contacts special function key. 600 * Used to launch an address book application. */ 601 public static final int KEYCODE_CONTACTS = 207; 602 /** Key code constant: Calendar special function key. 603 * Used to launch a calendar application. */ 604 public static final int KEYCODE_CALENDAR = 208; 605 /** Key code constant: Music special function key. 606 * Used to launch a music player application. */ 607 public static final int KEYCODE_MUSIC = 209; 608 /** Key code constant: Calculator special function key. 609 * Used to launch a calculator application. */ 610 public static final int KEYCODE_CALCULATOR = 210; 611 /** Key code constant: Japanese full-width / half-width key. */ 612 public static final int KEYCODE_ZENKAKU_HANKAKU = 211; 613 /** Key code constant: Japanese alphanumeric key. */ 614 public static final int KEYCODE_EISU = 212; 615 /** Key code constant: Japanese non-conversion key. */ 616 public static final int KEYCODE_MUHENKAN = 213; 617 /** Key code constant: Japanese conversion key. */ 618 public static final int KEYCODE_HENKAN = 214; 619 /** Key code constant: Japanese katakana / hiragana key. */ 620 public static final int KEYCODE_KATAKANA_HIRAGANA = 215; 621 /** Key code constant: Japanese Yen key. */ 622 public static final int KEYCODE_YEN = 216; 623 /** Key code constant: Japanese Ro key. */ 624 public static final int KEYCODE_RO = 217; 625 /** Key code constant: Japanese kana key. */ 626 public static final int KEYCODE_KANA = 218; 627 /** Key code constant: Assist key. 628 * Launches the global assist activity. Not delivered to applications. */ 629 public static final int KEYCODE_ASSIST = 219; 630 /** Key code constant: Brightness Down key. 631 * Adjusts the screen brightness down. */ 632 public static final int KEYCODE_BRIGHTNESS_DOWN = 220; 633 /** Key code constant: Brightness Up key. 634 * Adjusts the screen brightness up. */ 635 public static final int KEYCODE_BRIGHTNESS_UP = 221; 636 /** Key code constant: Audio Track key. 637 * Switches the audio tracks. */ 638 public static final int KEYCODE_MEDIA_AUDIO_TRACK = 222; 639 /** Key code constant: Sleep key. 640 * Puts the device to sleep. Behaves somewhat like {@link #KEYCODE_POWER} but it 641 * has no effect if the device is already asleep. */ 642 public static final int KEYCODE_SLEEP = 223; 643 /** Key code constant: Wakeup key. 644 * Wakes up the device. Behaves somewhat like {@link #KEYCODE_POWER} but it 645 * has no effect if the device is already awake. */ 646 public static final int KEYCODE_WAKEUP = 224; 647 /** Key code constant: Pairing key. 648 * Initiates peripheral pairing mode. Useful for pairing remote control 649 * devices or game controllers, especially if no other input mode is 650 * available. */ 651 public static final int KEYCODE_PAIRING = 225; 652 /** Key code constant: Media Top Menu key. 653 * Goes to the top of media menu. */ 654 public static final int KEYCODE_MEDIA_TOP_MENU = 226; 655 /** Key code constant: '11' key. */ 656 public static final int KEYCODE_11 = 227; 657 /** Key code constant: '12' key. */ 658 public static final int KEYCODE_12 = 228; 659 /** Key code constant: Last Channel key. 660 * Goes to the last viewed channel. */ 661 public static final int KEYCODE_LAST_CHANNEL = 229; 662 /** Key code constant: TV data service key. 663 * Displays data services like weather, sports. */ 664 public static final int KEYCODE_TV_DATA_SERVICE = 230; 665 /** Key code constant: Voice Assist key. 666 * Launches the global voice assist activity. Not delivered to applications. */ 667 public static final int KEYCODE_VOICE_ASSIST = 231; 668 /** Key code constant: Radio key. 669 * Toggles TV service / Radio service. */ 670 public static final int KEYCODE_TV_RADIO_SERVICE = 232; 671 /** Key code constant: Teletext key. 672 * Displays Teletext service. */ 673 public static final int KEYCODE_TV_TELETEXT = 233; 674 /** Key code constant: Number entry key. 675 * Initiates to enter multi-digit channel nubmber when each digit key is assigned 676 * for selecting separate channel. Corresponds to Number Entry Mode (0x1D) of CEC 677 * User Control Code. */ 678 public static final int KEYCODE_TV_NUMBER_ENTRY = 234; 679 /** Key code constant: Analog Terrestrial key. 680 * Switches to analog terrestrial broadcast service. */ 681 public static final int KEYCODE_TV_TERRESTRIAL_ANALOG = 235; 682 /** Key code constant: Digital Terrestrial key. 683 * Switches to digital terrestrial broadcast service. */ 684 public static final int KEYCODE_TV_TERRESTRIAL_DIGITAL = 236; 685 /** Key code constant: Satellite key. 686 * Switches to digital satellite broadcast service. */ 687 public static final int KEYCODE_TV_SATELLITE = 237; 688 /** Key code constant: BS key. 689 * Switches to BS digital satellite broadcasting service available in Japan. */ 690 public static final int KEYCODE_TV_SATELLITE_BS = 238; 691 /** Key code constant: CS key. 692 * Switches to CS digital satellite broadcasting service available in Japan. */ 693 public static final int KEYCODE_TV_SATELLITE_CS = 239; 694 /** Key code constant: BS/CS key. 695 * Toggles between BS and CS digital satellite services. */ 696 public static final int KEYCODE_TV_SATELLITE_SERVICE = 240; 697 /** Key code constant: Toggle Network key. 698 * Toggles selecting broacast services. */ 699 public static final int KEYCODE_TV_NETWORK = 241; 700 /** Key code constant: Antenna/Cable key. 701 * Toggles broadcast input source between antenna and cable. */ 702 public static final int KEYCODE_TV_ANTENNA_CABLE = 242; 703 /** Key code constant: HDMI #1 key. 704 * Switches to HDMI input #1. */ 705 public static final int KEYCODE_TV_INPUT_HDMI_1 = 243; 706 /** Key code constant: HDMI #2 key. 707 * Switches to HDMI input #2. */ 708 public static final int KEYCODE_TV_INPUT_HDMI_2 = 244; 709 /** Key code constant: HDMI #3 key. 710 * Switches to HDMI input #3. */ 711 public static final int KEYCODE_TV_INPUT_HDMI_3 = 245; 712 /** Key code constant: HDMI #4 key. 713 * Switches to HDMI input #4. */ 714 public static final int KEYCODE_TV_INPUT_HDMI_4 = 246; 715 /** Key code constant: Composite #1 key. 716 * Switches to composite video input #1. */ 717 public static final int KEYCODE_TV_INPUT_COMPOSITE_1 = 247; 718 /** Key code constant: Composite #2 key. 719 * Switches to composite video input #2. */ 720 public static final int KEYCODE_TV_INPUT_COMPOSITE_2 = 248; 721 /** Key code constant: Component #1 key. 722 * Switches to component video input #1. */ 723 public static final int KEYCODE_TV_INPUT_COMPONENT_1 = 249; 724 /** Key code constant: Component #2 key. 725 * Switches to component video input #2. */ 726 public static final int KEYCODE_TV_INPUT_COMPONENT_2 = 250; 727 /** Key code constant: VGA #1 key. 728 * Switches to VGA (analog RGB) input #1. */ 729 public static final int KEYCODE_TV_INPUT_VGA_1 = 251; 730 /** Key code constant: Audio description key. 731 * Toggles audio description off / on. */ 732 public static final int KEYCODE_TV_AUDIO_DESCRIPTION = 252; 733 /** Key code constant: Audio description mixing volume up key. 734 * Louden audio description volume as compared with normal audio volume. */ 735 public static final int KEYCODE_TV_AUDIO_DESCRIPTION_MIX_UP = 253; 736 /** Key code constant: Audio description mixing volume down key. 737 * Lessen audio description volume as compared with normal audio volume. */ 738 public static final int KEYCODE_TV_AUDIO_DESCRIPTION_MIX_DOWN = 254; 739 /** Key code constant: Zoom mode key. 740 * Changes Zoom mode (Normal, Full, Zoom, Wide-zoom, etc.) */ 741 public static final int KEYCODE_TV_ZOOM_MODE = 255; 742 /** Key code constant: Contents menu key. 743 * Goes to the title list. Corresponds to Contents Menu (0x0B) of CEC User Control 744 * Code */ 745 public static final int KEYCODE_TV_CONTENTS_MENU = 256; 746 /** Key code constant: Media context menu key. 747 * Goes to the context menu of media contents. Corresponds to Media Context-sensitive 748 * Menu (0x11) of CEC User Control Code. */ 749 public static final int KEYCODE_TV_MEDIA_CONTEXT_MENU = 257; 750 /** Key code constant: Timer programming key. 751 * Goes to the timer recording menu. Corresponds to Timer Programming (0x54) of 752 * CEC User Control Code. */ 753 public static final int KEYCODE_TV_TIMER_PROGRAMMING = 258; 754 /** Key code constant: Help key. */ 755 public static final int KEYCODE_HELP = 259; 756 /** Key code constant: Navigate to previous key. 757 * Goes backward by one item in an ordered collection of items. */ 758 public static final int KEYCODE_NAVIGATE_PREVIOUS = 260; 759 /** Key code constant: Navigate to next key. 760 * Advances to the next item in an ordered collection of items. */ 761 public static final int KEYCODE_NAVIGATE_NEXT = 261; 762 /** Key code constant: Navigate in key. 763 * Activates the item that currently has focus or expands to the next level of a navigation 764 * hierarchy. */ 765 public static final int KEYCODE_NAVIGATE_IN = 262; 766 /** Key code constant: Navigate out key. 767 * Backs out one level of a navigation hierarchy or collapses the item that currently has 768 * focus. */ 769 public static final int KEYCODE_NAVIGATE_OUT = 263; 770 /** Key code constant: Primary stem key for Wear 771 * Main power/reset button on watch. */ 772 public static final int KEYCODE_STEM_PRIMARY = 264; 773 /** Key code constant: Generic stem key 1 for Wear */ 774 public static final int KEYCODE_STEM_1 = 265; 775 /** Key code constant: Generic stem key 2 for Wear */ 776 public static final int KEYCODE_STEM_2 = 266; 777 /** Key code constant: Generic stem key 3 for Wear */ 778 public static final int KEYCODE_STEM_3 = 267; 779 /** Key code constant: Directional Pad Up-Left */ 780 public static final int KEYCODE_DPAD_UP_LEFT = 268; 781 /** Key code constant: Directional Pad Down-Left */ 782 public static final int KEYCODE_DPAD_DOWN_LEFT = 269; 783 /** Key code constant: Directional Pad Up-Right */ 784 public static final int KEYCODE_DPAD_UP_RIGHT = 270; 785 /** Key code constant: Directional Pad Down-Right */ 786 public static final int KEYCODE_DPAD_DOWN_RIGHT = 271; 787 /** Key code constant: Skip forward media key. */ 788 public static final int KEYCODE_MEDIA_SKIP_FORWARD = 272; 789 /** Key code constant: Skip backward media key. */ 790 public static final int KEYCODE_MEDIA_SKIP_BACKWARD = 273; 791 /** Key code constant: Step forward media key. 792 * Steps media forward, one frame at a time. */ 793 public static final int KEYCODE_MEDIA_STEP_FORWARD = 274; 794 /** Key code constant: Step backward media key. 795 * Steps media backward, one frame at a time. */ 796 public static final int KEYCODE_MEDIA_STEP_BACKWARD = 275; 797 /** Key code constant: put device to sleep unless a wakelock is held. */ 798 public static final int KEYCODE_SOFT_SLEEP = 276; 799 /** Key code constant: Cut key. */ 800 public static final int KEYCODE_CUT = 277; 801 /** Key code constant: Copy key. */ 802 public static final int KEYCODE_COPY = 278; 803 /** Key code constant: Paste key. */ 804 public static final int KEYCODE_PASTE = 279; 805 /** Key code constant: Consumed by the system for navigation up */ 806 public static final int KEYCODE_SYSTEM_NAVIGATION_UP = 280; 807 /** Key code constant: Consumed by the system for navigation down */ 808 public static final int KEYCODE_SYSTEM_NAVIGATION_DOWN = 281; 809 /** Key code constant: Consumed by the system for navigation left*/ 810 public static final int KEYCODE_SYSTEM_NAVIGATION_LEFT = 282; 811 /** Key code constant: Consumed by the system for navigation right */ 812 public static final int KEYCODE_SYSTEM_NAVIGATION_RIGHT = 283; 813 /** Key code constant: Show all apps */ 814 public static final int KEYCODE_ALL_APPS = 284; 815 /** Key code constant: Refresh key. */ 816 public static final int KEYCODE_REFRESH = 285; 817 /** Key code constant: Thumbs up key. Apps can use this to let user upvote content. */ 818 public static final int KEYCODE_THUMBS_UP = 286; 819 /** Key code constant: Thumbs down key. Apps can use this to let user downvote content. */ 820 public static final int KEYCODE_THUMBS_DOWN = 287; 821 /** 822 * Key code constant: Used to switch current {@link android.accounts.Account} that is 823 * consuming content. May be consumed by system to set account globally. 824 */ 825 public static final int KEYCODE_PROFILE_SWITCH = 288; 826 827 /** 828 * Integer value of the last KEYCODE. Increases as new keycodes are added to KeyEvent. 829 * @hide 830 */ 831 @TestApi 832 public static final int LAST_KEYCODE = KEYCODE_PROFILE_SWITCH; 833 834 // NOTE: If you add a new keycode here you must also add it to: 835 // isSystem() 836 // isWakeKey() 837 // frameworks/native/include/android/keycodes.h 838 // frameworks/native/include/input/InputEventLabels.h 839 // frameworks/base/core/res/res/values/attrs.xml 840 // emulator? 841 // LAST_KEYCODE 842 // 843 // Also Android currently does not reserve code ranges for vendor- 844 // specific key codes. If you have new key codes to have, you 845 // MUST contribute a patch to the open source project to define 846 // those new codes. This is intended to maintain a consistent 847 // set of key code definitions across all Android devices. 848 849 // Symbolic names of all metakeys in bit order from least significant to most significant. 850 // Accordingly there are exactly 32 values in this table. 851 @UnsupportedAppUsage 852 private static final String[] META_SYMBOLIC_NAMES = new String[] { 853 "META_SHIFT_ON", 854 "META_ALT_ON", 855 "META_SYM_ON", 856 "META_FUNCTION_ON", 857 "META_ALT_LEFT_ON", 858 "META_ALT_RIGHT_ON", 859 "META_SHIFT_LEFT_ON", 860 "META_SHIFT_RIGHT_ON", 861 "META_CAP_LOCKED", 862 "META_ALT_LOCKED", 863 "META_SYM_LOCKED", 864 "0x00000800", 865 "META_CTRL_ON", 866 "META_CTRL_LEFT_ON", 867 "META_CTRL_RIGHT_ON", 868 "0x00008000", 869 "META_META_ON", 870 "META_META_LEFT_ON", 871 "META_META_RIGHT_ON", 872 "0x00080000", 873 "META_CAPS_LOCK_ON", 874 "META_NUM_LOCK_ON", 875 "META_SCROLL_LOCK_ON", 876 "0x00800000", 877 "0x01000000", 878 "0x02000000", 879 "0x04000000", 880 "0x08000000", 881 "0x10000000", 882 "0x20000000", 883 "0x40000000", 884 "0x80000000", 885 }; 886 887 private static final String LABEL_PREFIX = "KEYCODE_"; 888 889 /** 890 * @deprecated There are now more than MAX_KEYCODE keycodes. 891 * Use {@link #getMaxKeyCode()} instead. 892 */ 893 @Deprecated 894 public static final int MAX_KEYCODE = 84; 895 896 /** 897 * {@link #getAction} value: the key has been pressed down. 898 */ 899 public static final int ACTION_DOWN = 0; 900 /** 901 * {@link #getAction} value: the key has been released. 902 */ 903 public static final int ACTION_UP = 1; 904 /** 905 * @deprecated No longer used by the input system. 906 * {@link #getAction} value: multiple duplicate key events have 907 * occurred in a row, or a complex string is being delivered. If the 908 * key code is not {@link #KEYCODE_UNKNOWN} then the 909 * {@link #getRepeatCount()} method returns the number of times 910 * the given key code should be executed. 911 * Otherwise, if the key code is {@link #KEYCODE_UNKNOWN}, then 912 * this is a sequence of characters as returned by {@link #getCharacters}. 913 */ 914 @Deprecated 915 public static final int ACTION_MULTIPLE = 2; 916 917 /** 918 * SHIFT key locked in CAPS mode. 919 * Reserved for use by {@link MetaKeyKeyListener} for a published constant in its API. 920 * @hide 921 */ 922 @UnsupportedAppUsage 923 public static final int META_CAP_LOCKED = 0x100; 924 925 /** 926 * ALT key locked. 927 * Reserved for use by {@link MetaKeyKeyListener} for a published constant in its API. 928 * @hide 929 */ 930 @UnsupportedAppUsage 931 public static final int META_ALT_LOCKED = 0x200; 932 933 /** 934 * SYM key locked. 935 * Reserved for use by {@link MetaKeyKeyListener} for a published constant in its API. 936 * @hide 937 */ 938 @UnsupportedAppUsage 939 public static final int META_SYM_LOCKED = 0x400; 940 941 /** 942 * Text is in selection mode. 943 * Reserved for use by {@link MetaKeyKeyListener} for a private unpublished constant 944 * in its API that is currently being retained for legacy reasons. 945 * @hide 946 */ 947 @UnsupportedAppUsage 948 public static final int META_SELECTING = 0x800; 949 950 /** 951 * <p>This mask is used to check whether one of the ALT meta keys is pressed.</p> 952 * 953 * @see #isAltPressed() 954 * @see #getMetaState() 955 * @see #KEYCODE_ALT_LEFT 956 * @see #KEYCODE_ALT_RIGHT 957 */ 958 public static final int META_ALT_ON = 0x02; 959 960 /** 961 * <p>This mask is used to check whether the left ALT meta key is pressed.</p> 962 * 963 * @see #isAltPressed() 964 * @see #getMetaState() 965 * @see #KEYCODE_ALT_LEFT 966 */ 967 public static final int META_ALT_LEFT_ON = 0x10; 968 969 /** 970 * <p>This mask is used to check whether the right the ALT meta key is pressed.</p> 971 * 972 * @see #isAltPressed() 973 * @see #getMetaState() 974 * @see #KEYCODE_ALT_RIGHT 975 */ 976 public static final int META_ALT_RIGHT_ON = 0x20; 977 978 /** 979 * <p>This mask is used to check whether one of the SHIFT meta keys is pressed.</p> 980 * 981 * @see #isShiftPressed() 982 * @see #getMetaState() 983 * @see #KEYCODE_SHIFT_LEFT 984 * @see #KEYCODE_SHIFT_RIGHT 985 */ 986 public static final int META_SHIFT_ON = 0x1; 987 988 /** 989 * <p>This mask is used to check whether the left SHIFT meta key is pressed.</p> 990 * 991 * @see #isShiftPressed() 992 * @see #getMetaState() 993 * @see #KEYCODE_SHIFT_LEFT 994 */ 995 public static final int META_SHIFT_LEFT_ON = 0x40; 996 997 /** 998 * <p>This mask is used to check whether the right SHIFT meta key is pressed.</p> 999 * 1000 * @see #isShiftPressed() 1001 * @see #getMetaState() 1002 * @see #KEYCODE_SHIFT_RIGHT 1003 */ 1004 public static final int META_SHIFT_RIGHT_ON = 0x80; 1005 1006 /** 1007 * <p>This mask is used to check whether the SYM meta key is pressed.</p> 1008 * 1009 * @see #isSymPressed() 1010 * @see #getMetaState() 1011 */ 1012 public static final int META_SYM_ON = 0x4; 1013 1014 /** 1015 * <p>This mask is used to check whether the FUNCTION meta key is pressed.</p> 1016 * 1017 * @see #isFunctionPressed() 1018 * @see #getMetaState() 1019 */ 1020 public static final int META_FUNCTION_ON = 0x8; 1021 1022 /** 1023 * <p>This mask is used to check whether one of the CTRL meta keys is pressed.</p> 1024 * 1025 * @see #isCtrlPressed() 1026 * @see #getMetaState() 1027 * @see #KEYCODE_CTRL_LEFT 1028 * @see #KEYCODE_CTRL_RIGHT 1029 */ 1030 public static final int META_CTRL_ON = 0x1000; 1031 1032 /** 1033 * <p>This mask is used to check whether the left CTRL meta key is pressed.</p> 1034 * 1035 * @see #isCtrlPressed() 1036 * @see #getMetaState() 1037 * @see #KEYCODE_CTRL_LEFT 1038 */ 1039 public static final int META_CTRL_LEFT_ON = 0x2000; 1040 1041 /** 1042 * <p>This mask is used to check whether the right CTRL meta key is pressed.</p> 1043 * 1044 * @see #isCtrlPressed() 1045 * @see #getMetaState() 1046 * @see #KEYCODE_CTRL_RIGHT 1047 */ 1048 public static final int META_CTRL_RIGHT_ON = 0x4000; 1049 1050 /** 1051 * <p>This mask is used to check whether one of the META meta keys is pressed.</p> 1052 * 1053 * @see #isMetaPressed() 1054 * @see #getMetaState() 1055 * @see #KEYCODE_META_LEFT 1056 * @see #KEYCODE_META_RIGHT 1057 */ 1058 public static final int META_META_ON = 0x10000; 1059 1060 /** 1061 * <p>This mask is used to check whether the left META meta key is pressed.</p> 1062 * 1063 * @see #isMetaPressed() 1064 * @see #getMetaState() 1065 * @see #KEYCODE_META_LEFT 1066 */ 1067 public static final int META_META_LEFT_ON = 0x20000; 1068 1069 /** 1070 * <p>This mask is used to check whether the right META meta key is pressed.</p> 1071 * 1072 * @see #isMetaPressed() 1073 * @see #getMetaState() 1074 * @see #KEYCODE_META_RIGHT 1075 */ 1076 public static final int META_META_RIGHT_ON = 0x40000; 1077 1078 /** 1079 * <p>This mask is used to check whether the CAPS LOCK meta key is on.</p> 1080 * 1081 * @see #isCapsLockOn() 1082 * @see #getMetaState() 1083 * @see #KEYCODE_CAPS_LOCK 1084 */ 1085 public static final int META_CAPS_LOCK_ON = 0x100000; 1086 1087 /** 1088 * <p>This mask is used to check whether the NUM LOCK meta key is on.</p> 1089 * 1090 * @see #isNumLockOn() 1091 * @see #getMetaState() 1092 * @see #KEYCODE_NUM_LOCK 1093 */ 1094 public static final int META_NUM_LOCK_ON = 0x200000; 1095 1096 /** 1097 * <p>This mask is used to check whether the SCROLL LOCK meta key is on.</p> 1098 * 1099 * @see #isScrollLockOn() 1100 * @see #getMetaState() 1101 * @see #KEYCODE_SCROLL_LOCK 1102 */ 1103 public static final int META_SCROLL_LOCK_ON = 0x400000; 1104 1105 /** 1106 * This mask is a combination of {@link #META_SHIFT_ON}, {@link #META_SHIFT_LEFT_ON} 1107 * and {@link #META_SHIFT_RIGHT_ON}. 1108 */ 1109 public static final int META_SHIFT_MASK = META_SHIFT_ON 1110 | META_SHIFT_LEFT_ON | META_SHIFT_RIGHT_ON; 1111 1112 /** 1113 * This mask is a combination of {@link #META_ALT_ON}, {@link #META_ALT_LEFT_ON} 1114 * and {@link #META_ALT_RIGHT_ON}. 1115 */ 1116 public static final int META_ALT_MASK = META_ALT_ON 1117 | META_ALT_LEFT_ON | META_ALT_RIGHT_ON; 1118 1119 /** 1120 * This mask is a combination of {@link #META_CTRL_ON}, {@link #META_CTRL_LEFT_ON} 1121 * and {@link #META_CTRL_RIGHT_ON}. 1122 */ 1123 public static final int META_CTRL_MASK = META_CTRL_ON 1124 | META_CTRL_LEFT_ON | META_CTRL_RIGHT_ON; 1125 1126 /** 1127 * This mask is a combination of {@link #META_META_ON}, {@link #META_META_LEFT_ON} 1128 * and {@link #META_META_RIGHT_ON}. 1129 */ 1130 public static final int META_META_MASK = META_META_ON 1131 | META_META_LEFT_ON | META_META_RIGHT_ON; 1132 1133 /** 1134 * This mask is set if the device woke because of this key event. 1135 * 1136 * @deprecated This flag will never be set by the system since the system 1137 * consumes all wake keys itself. 1138 */ 1139 @Deprecated 1140 public static final int FLAG_WOKE_HERE = 0x1; 1141 1142 /** 1143 * This mask is set if the key event was generated by a software keyboard. 1144 */ 1145 public static final int FLAG_SOFT_KEYBOARD = 0x2; 1146 1147 /** 1148 * This mask is set if we don't want the key event to cause us to leave 1149 * touch mode. 1150 */ 1151 public static final int FLAG_KEEP_TOUCH_MODE = 0x4; 1152 1153 /** 1154 * This mask is set if an event was known to come from a trusted part 1155 * of the system. That is, the event is known to come from the user, 1156 * and could not have been spoofed by a third party component. 1157 */ 1158 public static final int FLAG_FROM_SYSTEM = 0x8; 1159 1160 /** 1161 * This mask is used for compatibility, to identify enter keys that are 1162 * coming from an IME whose enter key has been auto-labelled "next" or 1163 * "done". This allows TextView to dispatch these as normal enter keys 1164 * for old applications, but still do the appropriate action when 1165 * receiving them. 1166 */ 1167 public static final int FLAG_EDITOR_ACTION = 0x10; 1168 1169 /** 1170 * When associated with up key events, this indicates that the key press 1171 * has been canceled. Typically this is used with virtual touch screen 1172 * keys, where the user can slide from the virtual key area on to the 1173 * display: in that case, the application will receive a canceled up 1174 * event and should not perform the action normally associated with the 1175 * key. Note that for this to work, the application can not perform an 1176 * action for a key until it receives an up or the long press timeout has 1177 * expired. 1178 */ 1179 public static final int FLAG_CANCELED = 0x20; 1180 1181 /** 1182 * This key event was generated by a virtual (on-screen) hard key area. 1183 * Typically this is an area of the touchscreen, outside of the regular 1184 * display, dedicated to "hardware" buttons. 1185 */ 1186 public static final int FLAG_VIRTUAL_HARD_KEY = 0x40; 1187 1188 /** 1189 * This flag is set for the first key repeat that occurs after the 1190 * long press timeout. 1191 */ 1192 public static final int FLAG_LONG_PRESS = 0x80; 1193 1194 /** 1195 * Set when a key event has {@link #FLAG_CANCELED} set because a long 1196 * press action was executed while it was down. 1197 */ 1198 public static final int FLAG_CANCELED_LONG_PRESS = 0x100; 1199 1200 /** 1201 * Set for {@link #ACTION_UP} when this event's key code is still being 1202 * tracked from its initial down. That is, somebody requested that tracking 1203 * started on the key down and a long press has not caused 1204 * the tracking to be canceled. 1205 */ 1206 public static final int FLAG_TRACKING = 0x200; 1207 1208 /** 1209 * Set when a key event has been synthesized to implement default behavior 1210 * for an event that the application did not handle. 1211 * Fallback key events are generated by unhandled trackball motions 1212 * (to emulate a directional keypad) and by certain unhandled key presses 1213 * that are declared in the key map (such as special function numeric keypad 1214 * keys when numlock is off). 1215 */ 1216 public static final int FLAG_FALLBACK = 0x400; 1217 1218 /** 1219 * Signifies that the key is being predispatched. 1220 * @hide 1221 */ 1222 public static final int FLAG_PREDISPATCH = 0x20000000; 1223 1224 /** 1225 * Private control to determine when an app is tracking a key sequence. 1226 * @hide 1227 */ 1228 public static final int FLAG_START_TRACKING = 0x40000000; 1229 1230 /** 1231 * Private flag that indicates when the system has detected that this key event 1232 * may be inconsistent with respect to the sequence of previously delivered key events, 1233 * such as when a key up event is sent but the key was not down. 1234 * 1235 * @hide 1236 * @see #isTainted 1237 * @see #setTainted 1238 */ 1239 public static final int FLAG_TAINTED = 0x80000000; 1240 1241 /** 1242 * Returns the maximum keycode. 1243 */ getMaxKeyCode()1244 public static int getMaxKeyCode() { 1245 return LAST_KEYCODE; 1246 } 1247 1248 /** 1249 * Get the character that is produced by putting accent on the character 1250 * c. 1251 * For example, getDeadChar('`', 'e') returns è. 1252 */ getDeadChar(int accent, int c)1253 public static int getDeadChar(int accent, int c) { 1254 return KeyCharacterMap.getDeadChar(accent, c); 1255 } 1256 1257 static final boolean DEBUG = false; 1258 static final String TAG = "KeyEvent"; 1259 1260 private static final int MAX_RECYCLED = 10; 1261 private static final Object gRecyclerLock = new Object(); 1262 private static int gRecyclerUsed; 1263 private static KeyEvent gRecyclerTop; 1264 1265 private KeyEvent mNext; 1266 1267 @UnsupportedAppUsage 1268 private int mDeviceId; 1269 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.P, trackingBug = 115609023) 1270 private int mSource; 1271 private int mDisplayId; 1272 @UnsupportedAppUsage 1273 private int mMetaState; 1274 @UnsupportedAppUsage 1275 private int mAction; 1276 @UnsupportedAppUsage 1277 private int mKeyCode; 1278 @UnsupportedAppUsage 1279 private int mScanCode; 1280 @UnsupportedAppUsage 1281 private int mRepeatCount; 1282 @UnsupportedAppUsage 1283 private int mFlags; 1284 @UnsupportedAppUsage 1285 private long mDownTime; 1286 @UnsupportedAppUsage 1287 private long mEventTime; 1288 @UnsupportedAppUsage 1289 private String mCharacters; 1290 1291 public interface Callback { 1292 /** 1293 * Called when a key down event has occurred. If you return true, 1294 * you can first call {@link KeyEvent#startTracking() 1295 * KeyEvent.startTracking()} to have the framework track the event 1296 * through its {@link #onKeyUp(int, KeyEvent)} and also call your 1297 * {@link #onKeyLongPress(int, KeyEvent)} if it occurs. 1298 * 1299 * @param keyCode The value in event.getKeyCode(). 1300 * @param event Description of the key event. 1301 * 1302 * @return If you handled the event, return true. If you want to allow 1303 * the event to be handled by the next receiver, return false. 1304 */ onKeyDown(int keyCode, KeyEvent event)1305 boolean onKeyDown(int keyCode, KeyEvent event); 1306 1307 /** 1308 * Called when a long press has occurred. If you return true, 1309 * the final key up will have {@link KeyEvent#FLAG_CANCELED} and 1310 * {@link KeyEvent#FLAG_CANCELED_LONG_PRESS} set. Note that in 1311 * order to receive this callback, someone in the event change 1312 * <em>must</em> return true from {@link #onKeyDown} <em>and</em> 1313 * call {@link KeyEvent#startTracking()} on the event. 1314 * 1315 * @param keyCode The value in event.getKeyCode(). 1316 * @param event Description of the key event. 1317 * 1318 * @return If you handled the event, return true. If you want to allow 1319 * the event to be handled by the next receiver, return false. 1320 */ onKeyLongPress(int keyCode, KeyEvent event)1321 boolean onKeyLongPress(int keyCode, KeyEvent event); 1322 1323 /** 1324 * Called when a key up event has occurred. 1325 * 1326 * @param keyCode The value in event.getKeyCode(). 1327 * @param event Description of the key event. 1328 * 1329 * @return If you handled the event, return true. If you want to allow 1330 * the event to be handled by the next receiver, return false. 1331 */ onKeyUp(int keyCode, KeyEvent event)1332 boolean onKeyUp(int keyCode, KeyEvent event); 1333 1334 /** 1335 * Called when a user's interaction with an analog control, such as 1336 * flinging a trackball, generates simulated down/up events for the same 1337 * key multiple times in quick succession. 1338 * 1339 * @param keyCode The value in event.getKeyCode(). 1340 * @param count Number of pairs as returned by event.getRepeatCount(). 1341 * @param event Description of the key event. 1342 * 1343 * @return If you handled the event, return true. If you want to allow 1344 * the event to be handled by the next receiver, return false. 1345 */ onKeyMultiple(int keyCode, int count, KeyEvent event)1346 boolean onKeyMultiple(int keyCode, int count, KeyEvent event); 1347 } 1348 nativeKeyCodeToString(int keyCode)1349 private static native String nativeKeyCodeToString(int keyCode); nativeKeyCodeFromString(String keyCode)1350 private static native int nativeKeyCodeFromString(String keyCode); 1351 KeyEvent()1352 private KeyEvent() { 1353 } 1354 1355 /** 1356 * Create a new key event. 1357 * 1358 * @param action Action code: either {@link #ACTION_DOWN}, 1359 * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}. 1360 * @param code The key code. 1361 */ KeyEvent(int action, int code)1362 public KeyEvent(int action, int code) { 1363 mAction = action; 1364 mKeyCode = code; 1365 mRepeatCount = 0; 1366 mDeviceId = KeyCharacterMap.VIRTUAL_KEYBOARD; 1367 } 1368 1369 /** 1370 * Create a new key event. 1371 * 1372 * @param downTime The time (in {@link android.os.SystemClock#uptimeMillis}) 1373 * at which this key code originally went down. 1374 * @param eventTime The time (in {@link android.os.SystemClock#uptimeMillis}) 1375 * at which this event happened. 1376 * @param action Action code: either {@link #ACTION_DOWN}, 1377 * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}. 1378 * @param code The key code. 1379 * @param repeat A repeat count for down events (> 0 if this is after the 1380 * initial down) or event count for multiple events. 1381 */ KeyEvent(long downTime, long eventTime, int action, int code, int repeat)1382 public KeyEvent(long downTime, long eventTime, int action, 1383 int code, int repeat) { 1384 mDownTime = downTime; 1385 mEventTime = eventTime; 1386 mAction = action; 1387 mKeyCode = code; 1388 mRepeatCount = repeat; 1389 mDeviceId = KeyCharacterMap.VIRTUAL_KEYBOARD; 1390 } 1391 1392 /** 1393 * Create a new key event. 1394 * 1395 * @param downTime The time (in {@link android.os.SystemClock#uptimeMillis}) 1396 * at which this key code originally went down. 1397 * @param eventTime The time (in {@link android.os.SystemClock#uptimeMillis}) 1398 * at which this event happened. 1399 * @param action Action code: either {@link #ACTION_DOWN}, 1400 * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}. 1401 * @param code The key code. 1402 * @param repeat A repeat count for down events (> 0 if this is after the 1403 * initial down) or event count for multiple events. 1404 * @param metaState Flags indicating which meta keys are currently pressed. 1405 */ KeyEvent(long downTime, long eventTime, int action, int code, int repeat, int metaState)1406 public KeyEvent(long downTime, long eventTime, int action, 1407 int code, int repeat, int metaState) { 1408 mDownTime = downTime; 1409 mEventTime = eventTime; 1410 mAction = action; 1411 mKeyCode = code; 1412 mRepeatCount = repeat; 1413 mMetaState = metaState; 1414 mDeviceId = KeyCharacterMap.VIRTUAL_KEYBOARD; 1415 } 1416 1417 /** 1418 * Create a new key event. 1419 * 1420 * @param downTime The time (in {@link android.os.SystemClock#uptimeMillis}) 1421 * at which this key code originally went down. 1422 * @param eventTime The time (in {@link android.os.SystemClock#uptimeMillis}) 1423 * at which this event happened. 1424 * @param action Action code: either {@link #ACTION_DOWN}, 1425 * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}. 1426 * @param code The key code. 1427 * @param repeat A repeat count for down events (> 0 if this is after the 1428 * initial down) or event count for multiple events. 1429 * @param metaState Flags indicating which meta keys are currently pressed. 1430 * @param deviceId The device ID that generated the key event. 1431 * @param scancode Raw device scan code of the event. 1432 */ KeyEvent(long downTime, long eventTime, int action, int code, int repeat, int metaState, int deviceId, int scancode)1433 public KeyEvent(long downTime, long eventTime, int action, 1434 int code, int repeat, int metaState, 1435 int deviceId, int scancode) { 1436 mDownTime = downTime; 1437 mEventTime = eventTime; 1438 mAction = action; 1439 mKeyCode = code; 1440 mRepeatCount = repeat; 1441 mMetaState = metaState; 1442 mDeviceId = deviceId; 1443 mScanCode = scancode; 1444 } 1445 1446 /** 1447 * Create a new key event. 1448 * 1449 * @param downTime The time (in {@link android.os.SystemClock#uptimeMillis}) 1450 * at which this key code originally went down. 1451 * @param eventTime The time (in {@link android.os.SystemClock#uptimeMillis}) 1452 * at which this event happened. 1453 * @param action Action code: either {@link #ACTION_DOWN}, 1454 * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}. 1455 * @param code The key code. 1456 * @param repeat A repeat count for down events (> 0 if this is after the 1457 * initial down) or event count for multiple events. 1458 * @param metaState Flags indicating which meta keys are currently pressed. 1459 * @param deviceId The device ID that generated the key event. 1460 * @param scancode Raw device scan code of the event. 1461 * @param flags The flags for this key event 1462 */ KeyEvent(long downTime, long eventTime, int action, int code, int repeat, int metaState, int deviceId, int scancode, int flags)1463 public KeyEvent(long downTime, long eventTime, int action, 1464 int code, int repeat, int metaState, 1465 int deviceId, int scancode, int flags) { 1466 mDownTime = downTime; 1467 mEventTime = eventTime; 1468 mAction = action; 1469 mKeyCode = code; 1470 mRepeatCount = repeat; 1471 mMetaState = metaState; 1472 mDeviceId = deviceId; 1473 mScanCode = scancode; 1474 mFlags = flags; 1475 } 1476 1477 /** 1478 * Create a new key event. 1479 * 1480 * @param downTime The time (in {@link android.os.SystemClock#uptimeMillis}) 1481 * at which this key code originally went down. 1482 * @param eventTime The time (in {@link android.os.SystemClock#uptimeMillis}) 1483 * at which this event happened. 1484 * @param action Action code: either {@link #ACTION_DOWN}, 1485 * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}. 1486 * @param code The key code. 1487 * @param repeat A repeat count for down events (> 0 if this is after the 1488 * initial down) or event count for multiple events. 1489 * @param metaState Flags indicating which meta keys are currently pressed. 1490 * @param deviceId The device ID that generated the key event. 1491 * @param scancode Raw device scan code of the event. 1492 * @param flags The flags for this key event 1493 * @param source The input source such as {@link InputDevice#SOURCE_KEYBOARD}. 1494 */ KeyEvent(long downTime, long eventTime, int action, int code, int repeat, int metaState, int deviceId, int scancode, int flags, int source)1495 public KeyEvent(long downTime, long eventTime, int action, 1496 int code, int repeat, int metaState, 1497 int deviceId, int scancode, int flags, int source) { 1498 mDownTime = downTime; 1499 mEventTime = eventTime; 1500 mAction = action; 1501 mKeyCode = code; 1502 mRepeatCount = repeat; 1503 mMetaState = metaState; 1504 mDeviceId = deviceId; 1505 mScanCode = scancode; 1506 mFlags = flags; 1507 mSource = source; 1508 mDisplayId = INVALID_DISPLAY; 1509 } 1510 1511 /** 1512 * Create a new key event for a string of characters. The key code, 1513 * action, repeat count and source will automatically be set to 1514 * {@link #KEYCODE_UNKNOWN}, {@link #ACTION_MULTIPLE}, 0, and 1515 * {@link InputDevice#SOURCE_KEYBOARD} for you. 1516 * 1517 * @param time The time (in {@link android.os.SystemClock#uptimeMillis}) 1518 * at which this event occured. 1519 * @param characters The string of characters. 1520 * @param deviceId The device ID that generated the key event. 1521 * @param flags The flags for this key event 1522 */ KeyEvent(long time, String characters, int deviceId, int flags)1523 public KeyEvent(long time, String characters, int deviceId, int flags) { 1524 mDownTime = time; 1525 mEventTime = time; 1526 mCharacters = characters; 1527 mAction = ACTION_MULTIPLE; 1528 mKeyCode = KEYCODE_UNKNOWN; 1529 mRepeatCount = 0; 1530 mDeviceId = deviceId; 1531 mFlags = flags; 1532 mSource = InputDevice.SOURCE_KEYBOARD; 1533 mDisplayId = INVALID_DISPLAY; 1534 } 1535 1536 /** 1537 * Make an exact copy of an existing key event. 1538 */ KeyEvent(KeyEvent origEvent)1539 public KeyEvent(KeyEvent origEvent) { 1540 mDownTime = origEvent.mDownTime; 1541 mEventTime = origEvent.mEventTime; 1542 mAction = origEvent.mAction; 1543 mKeyCode = origEvent.mKeyCode; 1544 mRepeatCount = origEvent.mRepeatCount; 1545 mMetaState = origEvent.mMetaState; 1546 mDeviceId = origEvent.mDeviceId; 1547 mSource = origEvent.mSource; 1548 mDisplayId = origEvent.mDisplayId; 1549 mScanCode = origEvent.mScanCode; 1550 mFlags = origEvent.mFlags; 1551 mCharacters = origEvent.mCharacters; 1552 } 1553 1554 /** 1555 * Copy an existing key event, modifying its time and repeat count. 1556 * 1557 * @deprecated Use {@link #changeTimeRepeat(KeyEvent, long, int)} 1558 * instead. 1559 * 1560 * @param origEvent The existing event to be copied. 1561 * @param eventTime The new event time 1562 * (in {@link android.os.SystemClock#uptimeMillis}) of the event. 1563 * @param newRepeat The new repeat count of the event. 1564 */ 1565 @Deprecated KeyEvent(KeyEvent origEvent, long eventTime, int newRepeat)1566 public KeyEvent(KeyEvent origEvent, long eventTime, int newRepeat) { 1567 mDownTime = origEvent.mDownTime; 1568 mEventTime = eventTime; 1569 mAction = origEvent.mAction; 1570 mKeyCode = origEvent.mKeyCode; 1571 mRepeatCount = newRepeat; 1572 mMetaState = origEvent.mMetaState; 1573 mDeviceId = origEvent.mDeviceId; 1574 mSource = origEvent.mSource; 1575 mDisplayId = origEvent.mDisplayId; 1576 mScanCode = origEvent.mScanCode; 1577 mFlags = origEvent.mFlags; 1578 mCharacters = origEvent.mCharacters; 1579 } 1580 obtain()1581 private static KeyEvent obtain() { 1582 final KeyEvent ev; 1583 synchronized (gRecyclerLock) { 1584 ev = gRecyclerTop; 1585 if (ev == null) { 1586 return new KeyEvent(); 1587 } 1588 gRecyclerTop = ev.mNext; 1589 gRecyclerUsed -= 1; 1590 } 1591 ev.mNext = null; 1592 ev.prepareForReuse(); 1593 return ev; 1594 } 1595 1596 /** 1597 * Obtains a (potentially recycled) key event. 1598 * 1599 * @hide 1600 */ obtain(long downTime, long eventTime, int action, int code, int repeat, int metaState, int deviceId, int scancode, int flags, int source, int displayId, String characters)1601 public static KeyEvent obtain(long downTime, long eventTime, int action, 1602 int code, int repeat, int metaState, 1603 int deviceId, int scancode, int flags, int source, int displayId, String characters) { 1604 KeyEvent ev = obtain(); 1605 ev.mDownTime = downTime; 1606 ev.mEventTime = eventTime; 1607 ev.mAction = action; 1608 ev.mKeyCode = code; 1609 ev.mRepeatCount = repeat; 1610 ev.mMetaState = metaState; 1611 ev.mDeviceId = deviceId; 1612 ev.mScanCode = scancode; 1613 ev.mFlags = flags; 1614 ev.mSource = source; 1615 ev.mDisplayId = displayId; 1616 ev.mCharacters = characters; 1617 return ev; 1618 } 1619 1620 /** 1621 * Obtains a (potentially recycled) key event. 1622 * 1623 * @hide 1624 */ 1625 @UnsupportedAppUsage obtain(long downTime, long eventTime, int action, int code, int repeat, int metaState, int deviceId, int scancode, int flags, int source, String characters)1626 public static KeyEvent obtain(long downTime, long eventTime, int action, 1627 int code, int repeat, int metaState, 1628 int deviceId, int scancode, int flags, int source, String characters) { 1629 return obtain(downTime, eventTime, action, code, repeat, metaState, deviceId, scancode, 1630 flags, source, INVALID_DISPLAY, characters); 1631 } 1632 1633 /** 1634 1635 /** 1636 * Obtains a (potentially recycled) copy of another key event. 1637 * 1638 * @hide 1639 */ obtain(KeyEvent other)1640 public static KeyEvent obtain(KeyEvent other) { 1641 KeyEvent ev = obtain(); 1642 ev.mDownTime = other.mDownTime; 1643 ev.mEventTime = other.mEventTime; 1644 ev.mAction = other.mAction; 1645 ev.mKeyCode = other.mKeyCode; 1646 ev.mRepeatCount = other.mRepeatCount; 1647 ev.mMetaState = other.mMetaState; 1648 ev.mDeviceId = other.mDeviceId; 1649 ev.mScanCode = other.mScanCode; 1650 ev.mFlags = other.mFlags; 1651 ev.mSource = other.mSource; 1652 ev.mDisplayId = other.mDisplayId; 1653 ev.mCharacters = other.mCharacters; 1654 return ev; 1655 } 1656 1657 /** @hide */ 1658 @Override copy()1659 public KeyEvent copy() { 1660 return obtain(this); 1661 } 1662 1663 /** 1664 * Recycles a key event. 1665 * Key events should only be recycled if they are owned by the system since user 1666 * code expects them to be essentially immutable, "tracking" notwithstanding. 1667 * 1668 * @hide 1669 */ 1670 @Override 1671 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.P, trackingBug = 115609023) recycle()1672 public final void recycle() { 1673 super.recycle(); 1674 mCharacters = null; 1675 1676 synchronized (gRecyclerLock) { 1677 if (gRecyclerUsed < MAX_RECYCLED) { 1678 gRecyclerUsed++; 1679 mNext = gRecyclerTop; 1680 gRecyclerTop = this; 1681 } 1682 } 1683 } 1684 1685 /** @hide */ 1686 @Override recycleIfNeededAfterDispatch()1687 public final void recycleIfNeededAfterDispatch() { 1688 // Do nothing. 1689 } 1690 1691 /** 1692 * Create a new key event that is the same as the given one, but whose 1693 * event time and repeat count are replaced with the given value. 1694 * 1695 * @param event The existing event to be copied. This is not modified. 1696 * @param eventTime The new event time 1697 * (in {@link android.os.SystemClock#uptimeMillis}) of the event. 1698 * @param newRepeat The new repeat count of the event. 1699 */ changeTimeRepeat(KeyEvent event, long eventTime, int newRepeat)1700 public static KeyEvent changeTimeRepeat(KeyEvent event, long eventTime, 1701 int newRepeat) { 1702 return new KeyEvent(event, eventTime, newRepeat); 1703 } 1704 1705 /** 1706 * Create a new key event that is the same as the given one, but whose 1707 * event time and repeat count are replaced with the given value. 1708 * 1709 * @param event The existing event to be copied. This is not modified. 1710 * @param eventTime The new event time 1711 * (in {@link android.os.SystemClock#uptimeMillis}) of the event. 1712 * @param newRepeat The new repeat count of the event. 1713 * @param newFlags New flags for the event, replacing the entire value 1714 * in the original event. 1715 */ changeTimeRepeat(KeyEvent event, long eventTime, int newRepeat, int newFlags)1716 public static KeyEvent changeTimeRepeat(KeyEvent event, long eventTime, 1717 int newRepeat, int newFlags) { 1718 KeyEvent ret = new KeyEvent(event); 1719 ret.mEventTime = eventTime; 1720 ret.mRepeatCount = newRepeat; 1721 ret.mFlags = newFlags; 1722 return ret; 1723 } 1724 1725 /** 1726 * Copy an existing key event, modifying its action. 1727 * 1728 * @param origEvent The existing event to be copied. 1729 * @param action The new action code of the event. 1730 */ KeyEvent(KeyEvent origEvent, int action)1731 private KeyEvent(KeyEvent origEvent, int action) { 1732 mDownTime = origEvent.mDownTime; 1733 mEventTime = origEvent.mEventTime; 1734 mAction = action; 1735 mKeyCode = origEvent.mKeyCode; 1736 mRepeatCount = origEvent.mRepeatCount; 1737 mMetaState = origEvent.mMetaState; 1738 mDeviceId = origEvent.mDeviceId; 1739 mSource = origEvent.mSource; 1740 mDisplayId = origEvent.mDisplayId; 1741 mScanCode = origEvent.mScanCode; 1742 mFlags = origEvent.mFlags; 1743 // Don't copy mCharacters, since one way or the other we'll lose it 1744 // when changing the action. 1745 } 1746 1747 /** 1748 * Create a new key event that is the same as the given one, but whose 1749 * action is replaced with the given value. 1750 * 1751 * @param event The existing event to be copied. This is not modified. 1752 * @param action The new action code of the event. 1753 */ changeAction(KeyEvent event, int action)1754 public static KeyEvent changeAction(KeyEvent event, int action) { 1755 return new KeyEvent(event, action); 1756 } 1757 1758 /** 1759 * Create a new key event that is the same as the given one, but whose 1760 * flags are replaced with the given value. 1761 * 1762 * @param event The existing event to be copied. This is not modified. 1763 * @param flags The new flags constant. 1764 */ changeFlags(KeyEvent event, int flags)1765 public static KeyEvent changeFlags(KeyEvent event, int flags) { 1766 event = new KeyEvent(event); 1767 event.mFlags = flags; 1768 return event; 1769 } 1770 1771 /** @hide */ 1772 @Override isTainted()1773 public final boolean isTainted() { 1774 return (mFlags & FLAG_TAINTED) != 0; 1775 } 1776 1777 /** @hide */ 1778 @Override setTainted(boolean tainted)1779 public final void setTainted(boolean tainted) { 1780 mFlags = tainted ? mFlags | FLAG_TAINTED : mFlags & ~FLAG_TAINTED; 1781 } 1782 1783 /** 1784 * Don't use in new code, instead explicitly check 1785 * {@link #getAction()}. 1786 * 1787 * @return If the action is ACTION_DOWN, returns true; else false. 1788 * 1789 * @deprecated 1790 * @hide 1791 */ 1792 @UnsupportedAppUsage isDown()1793 @Deprecated public final boolean isDown() { 1794 return mAction == ACTION_DOWN; 1795 } 1796 1797 /** Is this a system key? System keys can not be used for menu shortcuts. 1798 */ isSystem()1799 public final boolean isSystem() { 1800 return isSystemKey(mKeyCode); 1801 } 1802 1803 /** @hide */ isWakeKey()1804 public final boolean isWakeKey() { 1805 return isWakeKey(mKeyCode); 1806 } 1807 1808 /** 1809 * Returns true if the specified keycode is a gamepad button. 1810 * @return True if the keycode is a gamepad button, such as {@link #KEYCODE_BUTTON_A}. 1811 */ isGamepadButton(int keyCode)1812 public static final boolean isGamepadButton(int keyCode) { 1813 switch (keyCode) { 1814 case KeyEvent.KEYCODE_BUTTON_A: 1815 case KeyEvent.KEYCODE_BUTTON_B: 1816 case KeyEvent.KEYCODE_BUTTON_C: 1817 case KeyEvent.KEYCODE_BUTTON_X: 1818 case KeyEvent.KEYCODE_BUTTON_Y: 1819 case KeyEvent.KEYCODE_BUTTON_Z: 1820 case KeyEvent.KEYCODE_BUTTON_L1: 1821 case KeyEvent.KEYCODE_BUTTON_R1: 1822 case KeyEvent.KEYCODE_BUTTON_L2: 1823 case KeyEvent.KEYCODE_BUTTON_R2: 1824 case KeyEvent.KEYCODE_BUTTON_THUMBL: 1825 case KeyEvent.KEYCODE_BUTTON_THUMBR: 1826 case KeyEvent.KEYCODE_BUTTON_START: 1827 case KeyEvent.KEYCODE_BUTTON_SELECT: 1828 case KeyEvent.KEYCODE_BUTTON_MODE: 1829 case KeyEvent.KEYCODE_BUTTON_1: 1830 case KeyEvent.KEYCODE_BUTTON_2: 1831 case KeyEvent.KEYCODE_BUTTON_3: 1832 case KeyEvent.KEYCODE_BUTTON_4: 1833 case KeyEvent.KEYCODE_BUTTON_5: 1834 case KeyEvent.KEYCODE_BUTTON_6: 1835 case KeyEvent.KEYCODE_BUTTON_7: 1836 case KeyEvent.KEYCODE_BUTTON_8: 1837 case KeyEvent.KEYCODE_BUTTON_9: 1838 case KeyEvent.KEYCODE_BUTTON_10: 1839 case KeyEvent.KEYCODE_BUTTON_11: 1840 case KeyEvent.KEYCODE_BUTTON_12: 1841 case KeyEvent.KEYCODE_BUTTON_13: 1842 case KeyEvent.KEYCODE_BUTTON_14: 1843 case KeyEvent.KEYCODE_BUTTON_15: 1844 case KeyEvent.KEYCODE_BUTTON_16: 1845 return true; 1846 default: 1847 return false; 1848 } 1849 } 1850 1851 /** Whether key will, by default, trigger a click on the focused view. 1852 * @hide 1853 */ 1854 @UnsupportedAppUsage isConfirmKey(int keyCode)1855 public static final boolean isConfirmKey(int keyCode) { 1856 switch (keyCode) { 1857 case KeyEvent.KEYCODE_DPAD_CENTER: 1858 case KeyEvent.KEYCODE_ENTER: 1859 case KeyEvent.KEYCODE_SPACE: 1860 case KeyEvent.KEYCODE_NUMPAD_ENTER: 1861 return true; 1862 default: 1863 return false; 1864 } 1865 } 1866 1867 /** 1868 * Returns whether this key will be sent to the 1869 * {@link android.media.session.MediaSession.Callback} if not handled. 1870 * 1871 * @hide 1872 */ isMediaSessionKey(int keyCode)1873 public static final boolean isMediaSessionKey(int keyCode) { 1874 switch (keyCode) { 1875 case KeyEvent.KEYCODE_MEDIA_PLAY: 1876 case KeyEvent.KEYCODE_MEDIA_PAUSE: 1877 case KeyEvent.KEYCODE_MEDIA_PLAY_PAUSE: 1878 case KeyEvent.KEYCODE_MUTE: 1879 case KeyEvent.KEYCODE_HEADSETHOOK: 1880 case KeyEvent.KEYCODE_MEDIA_STOP: 1881 case KeyEvent.KEYCODE_MEDIA_NEXT: 1882 case KeyEvent.KEYCODE_MEDIA_PREVIOUS: 1883 case KeyEvent.KEYCODE_MEDIA_REWIND: 1884 case KeyEvent.KEYCODE_MEDIA_RECORD: 1885 case KeyEvent.KEYCODE_MEDIA_FAST_FORWARD: 1886 return true; 1887 } 1888 return false; 1889 } 1890 1891 /** Is this a system key? System keys can not be used for menu shortcuts. 1892 * @hide 1893 */ isSystemKey(int keyCode)1894 public static final boolean isSystemKey(int keyCode) { 1895 switch (keyCode) { 1896 case KeyEvent.KEYCODE_MENU: 1897 case KeyEvent.KEYCODE_SOFT_RIGHT: 1898 case KeyEvent.KEYCODE_HOME: 1899 case KeyEvent.KEYCODE_BACK: 1900 case KeyEvent.KEYCODE_CALL: 1901 case KeyEvent.KEYCODE_ENDCALL: 1902 case KeyEvent.KEYCODE_VOLUME_UP: 1903 case KeyEvent.KEYCODE_VOLUME_DOWN: 1904 case KeyEvent.KEYCODE_VOLUME_MUTE: 1905 case KeyEvent.KEYCODE_MUTE: 1906 case KeyEvent.KEYCODE_POWER: 1907 case KeyEvent.KEYCODE_HEADSETHOOK: 1908 case KeyEvent.KEYCODE_MEDIA_PLAY: 1909 case KeyEvent.KEYCODE_MEDIA_PAUSE: 1910 case KeyEvent.KEYCODE_MEDIA_PLAY_PAUSE: 1911 case KeyEvent.KEYCODE_MEDIA_STOP: 1912 case KeyEvent.KEYCODE_MEDIA_NEXT: 1913 case KeyEvent.KEYCODE_MEDIA_PREVIOUS: 1914 case KeyEvent.KEYCODE_MEDIA_REWIND: 1915 case KeyEvent.KEYCODE_MEDIA_RECORD: 1916 case KeyEvent.KEYCODE_MEDIA_FAST_FORWARD: 1917 case KeyEvent.KEYCODE_CAMERA: 1918 case KeyEvent.KEYCODE_FOCUS: 1919 case KeyEvent.KEYCODE_SEARCH: 1920 case KeyEvent.KEYCODE_BRIGHTNESS_DOWN: 1921 case KeyEvent.KEYCODE_BRIGHTNESS_UP: 1922 case KeyEvent.KEYCODE_MEDIA_AUDIO_TRACK: 1923 case KeyEvent.KEYCODE_SYSTEM_NAVIGATION_UP: 1924 case KeyEvent.KEYCODE_SYSTEM_NAVIGATION_DOWN: 1925 case KeyEvent.KEYCODE_SYSTEM_NAVIGATION_LEFT: 1926 case KeyEvent.KEYCODE_SYSTEM_NAVIGATION_RIGHT: 1927 return true; 1928 } 1929 1930 return false; 1931 } 1932 1933 /** @hide */ isWakeKey(int keyCode)1934 public static final boolean isWakeKey(int keyCode) { 1935 switch (keyCode) { 1936 case KeyEvent.KEYCODE_BACK: 1937 case KeyEvent.KEYCODE_CAMERA: 1938 case KeyEvent.KEYCODE_MENU: 1939 case KeyEvent.KEYCODE_PAIRING: 1940 case KeyEvent.KEYCODE_STEM_1: 1941 case KeyEvent.KEYCODE_STEM_2: 1942 case KeyEvent.KEYCODE_STEM_3: 1943 case KeyEvent.KEYCODE_WAKEUP: 1944 return true; 1945 } 1946 return false; 1947 } 1948 1949 /** @hide */ isMetaKey(int keyCode)1950 public static final boolean isMetaKey(int keyCode) { 1951 return keyCode == KeyEvent.KEYCODE_META_LEFT || keyCode == KeyEvent.KEYCODE_META_RIGHT; 1952 } 1953 1954 /** @hide */ isAltKey(int keyCode)1955 public static final boolean isAltKey(int keyCode) { 1956 return keyCode == KeyEvent.KEYCODE_ALT_LEFT || keyCode == KeyEvent.KEYCODE_ALT_RIGHT; 1957 } 1958 1959 /** {@inheritDoc} */ 1960 @Override getDeviceId()1961 public final int getDeviceId() { 1962 return mDeviceId; 1963 } 1964 1965 /** {@inheritDoc} */ 1966 @Override getSource()1967 public final int getSource() { 1968 return mSource; 1969 } 1970 1971 /** {@inheritDoc} */ 1972 @Override setSource(int source)1973 public final void setSource(int source) { 1974 mSource = source; 1975 } 1976 1977 /** @hide */ 1978 @Override getDisplayId()1979 public final int getDisplayId() { 1980 return mDisplayId; 1981 } 1982 1983 /** @hide */ 1984 @TestApi 1985 @Override setDisplayId(int displayId)1986 public final void setDisplayId(int displayId) { 1987 mDisplayId = displayId; 1988 } 1989 1990 /** 1991 * <p>Returns the state of the meta keys.</p> 1992 * 1993 * @return an integer in which each bit set to 1 represents a pressed 1994 * meta key 1995 * 1996 * @see #isAltPressed() 1997 * @see #isShiftPressed() 1998 * @see #isSymPressed() 1999 * @see #isCtrlPressed() 2000 * @see #isMetaPressed() 2001 * @see #isFunctionPressed() 2002 * @see #isCapsLockOn() 2003 * @see #isNumLockOn() 2004 * @see #isScrollLockOn() 2005 * @see #META_ALT_ON 2006 * @see #META_ALT_LEFT_ON 2007 * @see #META_ALT_RIGHT_ON 2008 * @see #META_SHIFT_ON 2009 * @see #META_SHIFT_LEFT_ON 2010 * @see #META_SHIFT_RIGHT_ON 2011 * @see #META_SYM_ON 2012 * @see #META_FUNCTION_ON 2013 * @see #META_CTRL_ON 2014 * @see #META_CTRL_LEFT_ON 2015 * @see #META_CTRL_RIGHT_ON 2016 * @see #META_META_ON 2017 * @see #META_META_LEFT_ON 2018 * @see #META_META_RIGHT_ON 2019 * @see #META_CAPS_LOCK_ON 2020 * @see #META_NUM_LOCK_ON 2021 * @see #META_SCROLL_LOCK_ON 2022 * @see #getModifiers 2023 */ getMetaState()2024 public final int getMetaState() { 2025 return mMetaState; 2026 } 2027 2028 /** 2029 * Returns the state of the modifier keys. 2030 * <p> 2031 * For the purposes of this function, {@link #KEYCODE_CAPS_LOCK}, 2032 * {@link #KEYCODE_SCROLL_LOCK}, and {@link #KEYCODE_NUM_LOCK} are 2033 * not considered modifier keys. Consequently, this function specifically masks out 2034 * {@link #META_CAPS_LOCK_ON}, {@link #META_SCROLL_LOCK_ON} and {@link #META_NUM_LOCK_ON}. 2035 * </p><p> 2036 * The value returned consists of the meta state (from {@link #getMetaState}) 2037 * normalized using {@link #normalizeMetaState(int)} and then masked with 2038 * {@link #getModifierMetaStateMask} so that only valid modifier bits are retained. 2039 * </p> 2040 * 2041 * @return An integer in which each bit set to 1 represents a pressed modifier key. 2042 * @see #getMetaState 2043 */ getModifiers()2044 public final int getModifiers() { 2045 return normalizeMetaState(mMetaState) & META_MODIFIER_MASK; 2046 } 2047 2048 /** 2049 * Modifies the flags of the event. 2050 * 2051 * @param newFlags New flags for the event, replacing the entire value. 2052 * @hide 2053 */ setFlags(int newFlags)2054 public final void setFlags(int newFlags) { 2055 mFlags = newFlags; 2056 } 2057 2058 /** 2059 * Returns the flags for this key event. 2060 * 2061 * @see #FLAG_WOKE_HERE 2062 */ getFlags()2063 public final int getFlags() { 2064 return mFlags; 2065 } 2066 2067 // Mask of all modifier key meta states. Specifically excludes locked keys like caps lock. 2068 @UnsupportedAppUsage 2069 private static final int META_MODIFIER_MASK = 2070 META_SHIFT_ON | META_SHIFT_LEFT_ON | META_SHIFT_RIGHT_ON 2071 | META_ALT_ON | META_ALT_LEFT_ON | META_ALT_RIGHT_ON 2072 | META_CTRL_ON | META_CTRL_LEFT_ON | META_CTRL_RIGHT_ON 2073 | META_META_ON | META_META_LEFT_ON | META_META_RIGHT_ON 2074 | META_SYM_ON | META_FUNCTION_ON; 2075 2076 // Mask of all lock key meta states. 2077 @UnsupportedAppUsage 2078 private static final int META_LOCK_MASK = 2079 META_CAPS_LOCK_ON | META_NUM_LOCK_ON | META_SCROLL_LOCK_ON; 2080 2081 // Mask of all valid meta states. 2082 @UnsupportedAppUsage 2083 private static final int META_ALL_MASK = META_MODIFIER_MASK | META_LOCK_MASK; 2084 2085 // Mask of all synthetic meta states that are reserved for API compatibility with 2086 // historical uses in MetaKeyKeyListener. 2087 @UnsupportedAppUsage 2088 private static final int META_SYNTHETIC_MASK = 2089 META_CAP_LOCKED | META_ALT_LOCKED | META_SYM_LOCKED | META_SELECTING; 2090 2091 // Mask of all meta states that are not valid use in specifying a modifier key. 2092 // These bits are known to be used for purposes other than specifying modifiers. 2093 @UnsupportedAppUsage 2094 private static final int META_INVALID_MODIFIER_MASK = 2095 META_LOCK_MASK | META_SYNTHETIC_MASK; 2096 2097 /** 2098 * Gets a mask that includes all valid modifier key meta state bits. 2099 * <p> 2100 * For the purposes of this function, {@link #KEYCODE_CAPS_LOCK}, 2101 * {@link #KEYCODE_SCROLL_LOCK}, and {@link #KEYCODE_NUM_LOCK} are 2102 * not considered modifier keys. Consequently, the mask specifically excludes 2103 * {@link #META_CAPS_LOCK_ON}, {@link #META_SCROLL_LOCK_ON} and {@link #META_NUM_LOCK_ON}. 2104 * </p> 2105 * 2106 * @return The modifier meta state mask which is a combination of 2107 * {@link #META_SHIFT_ON}, {@link #META_SHIFT_LEFT_ON}, {@link #META_SHIFT_RIGHT_ON}, 2108 * {@link #META_ALT_ON}, {@link #META_ALT_LEFT_ON}, {@link #META_ALT_RIGHT_ON}, 2109 * {@link #META_CTRL_ON}, {@link #META_CTRL_LEFT_ON}, {@link #META_CTRL_RIGHT_ON}, 2110 * {@link #META_META_ON}, {@link #META_META_LEFT_ON}, {@link #META_META_RIGHT_ON}, 2111 * {@link #META_SYM_ON}, {@link #META_FUNCTION_ON}. 2112 */ getModifierMetaStateMask()2113 public static int getModifierMetaStateMask() { 2114 return META_MODIFIER_MASK; 2115 } 2116 2117 /** 2118 * Returns true if this key code is a modifier key. 2119 * <p> 2120 * For the purposes of this function, {@link #KEYCODE_CAPS_LOCK}, 2121 * {@link #KEYCODE_SCROLL_LOCK}, and {@link #KEYCODE_NUM_LOCK} are 2122 * not considered modifier keys. Consequently, this function return false 2123 * for those keys. 2124 * </p> 2125 * 2126 * @return True if the key code is one of 2127 * {@link #KEYCODE_SHIFT_LEFT} {@link #KEYCODE_SHIFT_RIGHT}, 2128 * {@link #KEYCODE_ALT_LEFT}, {@link #KEYCODE_ALT_RIGHT}, 2129 * {@link #KEYCODE_CTRL_LEFT}, {@link #KEYCODE_CTRL_RIGHT}, 2130 * {@link #KEYCODE_META_LEFT}, or {@link #KEYCODE_META_RIGHT}, 2131 * {@link #KEYCODE_SYM}, {@link #KEYCODE_NUM}, {@link #KEYCODE_FUNCTION}. 2132 */ isModifierKey(int keyCode)2133 public static boolean isModifierKey(int keyCode) { 2134 switch (keyCode) { 2135 case KEYCODE_SHIFT_LEFT: 2136 case KEYCODE_SHIFT_RIGHT: 2137 case KEYCODE_ALT_LEFT: 2138 case KEYCODE_ALT_RIGHT: 2139 case KEYCODE_CTRL_LEFT: 2140 case KEYCODE_CTRL_RIGHT: 2141 case KEYCODE_META_LEFT: 2142 case KEYCODE_META_RIGHT: 2143 case KEYCODE_SYM: 2144 case KEYCODE_NUM: 2145 case KEYCODE_FUNCTION: 2146 return true; 2147 default: 2148 return false; 2149 } 2150 } 2151 2152 /** 2153 * Normalizes the specified meta state. 2154 * <p> 2155 * The meta state is normalized such that if either the left or right modifier meta state 2156 * bits are set then the result will also include the universal bit for that modifier. 2157 * </p><p> 2158 * If the specified meta state contains {@link #META_ALT_LEFT_ON} then 2159 * the result will also contain {@link #META_ALT_ON} in addition to {@link #META_ALT_LEFT_ON} 2160 * and the other bits that were specified in the input. The same is process is 2161 * performed for shift, control and meta. 2162 * </p><p> 2163 * If the specified meta state contains synthetic meta states defined by 2164 * {@link MetaKeyKeyListener}, then those states are translated here and the original 2165 * synthetic meta states are removed from the result. 2166 * {@link MetaKeyKeyListener#META_CAP_LOCKED} is translated to {@link #META_CAPS_LOCK_ON}. 2167 * {@link MetaKeyKeyListener#META_ALT_LOCKED} is translated to {@link #META_ALT_ON}. 2168 * {@link MetaKeyKeyListener#META_SYM_LOCKED} is translated to {@link #META_SYM_ON}. 2169 * </p><p> 2170 * Undefined meta state bits are removed. 2171 * </p> 2172 * 2173 * @param metaState The meta state. 2174 * @return The normalized meta state. 2175 */ normalizeMetaState(int metaState)2176 public static int normalizeMetaState(int metaState) { 2177 if ((metaState & (META_SHIFT_LEFT_ON | META_SHIFT_RIGHT_ON)) != 0) { 2178 metaState |= META_SHIFT_ON; 2179 } 2180 if ((metaState & (META_ALT_LEFT_ON | META_ALT_RIGHT_ON)) != 0) { 2181 metaState |= META_ALT_ON; 2182 } 2183 if ((metaState & (META_CTRL_LEFT_ON | META_CTRL_RIGHT_ON)) != 0) { 2184 metaState |= META_CTRL_ON; 2185 } 2186 if ((metaState & (META_META_LEFT_ON | META_META_RIGHT_ON)) != 0) { 2187 metaState |= META_META_ON; 2188 } 2189 if ((metaState & MetaKeyKeyListener.META_CAP_LOCKED) != 0) { 2190 metaState |= META_CAPS_LOCK_ON; 2191 } 2192 if ((metaState & MetaKeyKeyListener.META_ALT_LOCKED) != 0) { 2193 metaState |= META_ALT_ON; 2194 } 2195 if ((metaState & MetaKeyKeyListener.META_SYM_LOCKED) != 0) { 2196 metaState |= META_SYM_ON; 2197 } 2198 return metaState & META_ALL_MASK; 2199 } 2200 2201 /** 2202 * Returns true if no modifiers keys are pressed according to the specified meta state. 2203 * <p> 2204 * For the purposes of this function, {@link #KEYCODE_CAPS_LOCK}, 2205 * {@link #KEYCODE_SCROLL_LOCK}, and {@link #KEYCODE_NUM_LOCK} are 2206 * not considered modifier keys. Consequently, this function ignores 2207 * {@link #META_CAPS_LOCK_ON}, {@link #META_SCROLL_LOCK_ON} and {@link #META_NUM_LOCK_ON}. 2208 * </p><p> 2209 * The meta state is normalized prior to comparison using {@link #normalizeMetaState(int)}. 2210 * </p> 2211 * 2212 * @param metaState The meta state to consider. 2213 * @return True if no modifier keys are pressed. 2214 * @see #hasNoModifiers() 2215 */ metaStateHasNoModifiers(int metaState)2216 public static boolean metaStateHasNoModifiers(int metaState) { 2217 return (normalizeMetaState(metaState) & META_MODIFIER_MASK) == 0; 2218 } 2219 2220 /** 2221 * Returns true if only the specified modifier keys are pressed according to 2222 * the specified meta state. Returns false if a different combination of modifier 2223 * keys are pressed. 2224 * <p> 2225 * For the purposes of this function, {@link #KEYCODE_CAPS_LOCK}, 2226 * {@link #KEYCODE_SCROLL_LOCK}, and {@link #KEYCODE_NUM_LOCK} are 2227 * not considered modifier keys. Consequently, this function ignores 2228 * {@link #META_CAPS_LOCK_ON}, {@link #META_SCROLL_LOCK_ON} and {@link #META_NUM_LOCK_ON}. 2229 * </p><p> 2230 * If the specified modifier mask includes directional modifiers, such as 2231 * {@link #META_SHIFT_LEFT_ON}, then this method ensures that the 2232 * modifier is pressed on that side. 2233 * If the specified modifier mask includes non-directional modifiers, such as 2234 * {@link #META_SHIFT_ON}, then this method ensures that the modifier 2235 * is pressed on either side. 2236 * If the specified modifier mask includes both directional and non-directional modifiers 2237 * for the same type of key, such as {@link #META_SHIFT_ON} and {@link #META_SHIFT_LEFT_ON}, 2238 * then this method throws an illegal argument exception. 2239 * </p> 2240 * 2241 * @param metaState The meta state to consider. 2242 * @param modifiers The meta state of the modifier keys to check. May be a combination 2243 * of modifier meta states as defined by {@link #getModifierMetaStateMask()}. May be 0 to 2244 * ensure that no modifier keys are pressed. 2245 * @return True if only the specified modifier keys are pressed. 2246 * @throws IllegalArgumentException if the modifiers parameter contains invalid modifiers 2247 * @see #hasModifiers 2248 */ metaStateHasModifiers(int metaState, int modifiers)2249 public static boolean metaStateHasModifiers(int metaState, int modifiers) { 2250 // Note: For forward compatibility, we allow the parameter to contain meta states 2251 // that we do not recognize but we explicitly disallow meta states that 2252 // are not valid modifiers. 2253 if ((modifiers & META_INVALID_MODIFIER_MASK) != 0) { 2254 throw new IllegalArgumentException("modifiers must not contain " 2255 + "META_CAPS_LOCK_ON, META_NUM_LOCK_ON, META_SCROLL_LOCK_ON, " 2256 + "META_CAP_LOCKED, META_ALT_LOCKED, META_SYM_LOCKED, " 2257 + "or META_SELECTING"); 2258 } 2259 2260 metaState = normalizeMetaState(metaState) & META_MODIFIER_MASK; 2261 metaState = metaStateFilterDirectionalModifiers(metaState, modifiers, 2262 META_SHIFT_ON, META_SHIFT_LEFT_ON, META_SHIFT_RIGHT_ON); 2263 metaState = metaStateFilterDirectionalModifiers(metaState, modifiers, 2264 META_ALT_ON, META_ALT_LEFT_ON, META_ALT_RIGHT_ON); 2265 metaState = metaStateFilterDirectionalModifiers(metaState, modifiers, 2266 META_CTRL_ON, META_CTRL_LEFT_ON, META_CTRL_RIGHT_ON); 2267 metaState = metaStateFilterDirectionalModifiers(metaState, modifiers, 2268 META_META_ON, META_META_LEFT_ON, META_META_RIGHT_ON); 2269 return metaState == modifiers; 2270 } 2271 metaStateFilterDirectionalModifiers(int metaState, int modifiers, int basic, int left, int right)2272 private static int metaStateFilterDirectionalModifiers(int metaState, 2273 int modifiers, int basic, int left, int right) { 2274 final boolean wantBasic = (modifiers & basic) != 0; 2275 final int directional = left | right; 2276 final boolean wantLeftOrRight = (modifiers & directional) != 0; 2277 2278 if (wantBasic) { 2279 if (wantLeftOrRight) { 2280 throw new IllegalArgumentException("modifiers must not contain " 2281 + metaStateToString(basic) + " combined with " 2282 + metaStateToString(left) + " or " + metaStateToString(right)); 2283 } 2284 return metaState & ~directional; 2285 } else if (wantLeftOrRight) { 2286 return metaState & ~basic; 2287 } else { 2288 return metaState; 2289 } 2290 } 2291 2292 /** 2293 * Returns true if no modifier keys are pressed. 2294 * <p> 2295 * For the purposes of this function, {@link #KEYCODE_CAPS_LOCK}, 2296 * {@link #KEYCODE_SCROLL_LOCK}, and {@link #KEYCODE_NUM_LOCK} are 2297 * not considered modifier keys. Consequently, this function ignores 2298 * {@link #META_CAPS_LOCK_ON}, {@link #META_SCROLL_LOCK_ON} and {@link #META_NUM_LOCK_ON}. 2299 * </p><p> 2300 * The meta state is normalized prior to comparison using {@link #normalizeMetaState(int)}. 2301 * </p> 2302 * 2303 * @return True if no modifier keys are pressed. 2304 * @see #metaStateHasNoModifiers 2305 */ hasNoModifiers()2306 public final boolean hasNoModifiers() { 2307 return metaStateHasNoModifiers(mMetaState); 2308 } 2309 2310 /** 2311 * Returns true if only the specified modifiers keys are pressed. 2312 * Returns false if a different combination of modifier keys are pressed. 2313 * <p> 2314 * For the purposes of this function, {@link #KEYCODE_CAPS_LOCK}, 2315 * {@link #KEYCODE_SCROLL_LOCK}, and {@link #KEYCODE_NUM_LOCK} are 2316 * not considered modifier keys. Consequently, this function ignores 2317 * {@link #META_CAPS_LOCK_ON}, {@link #META_SCROLL_LOCK_ON} and {@link #META_NUM_LOCK_ON}. 2318 * </p><p> 2319 * If the specified modifier mask includes directional modifiers, such as 2320 * {@link #META_SHIFT_LEFT_ON}, then this method ensures that the 2321 * modifier is pressed on that side. 2322 * If the specified modifier mask includes non-directional modifiers, such as 2323 * {@link #META_SHIFT_ON}, then this method ensures that the modifier 2324 * is pressed on either side. 2325 * If the specified modifier mask includes both directional and non-directional modifiers 2326 * for the same type of key, such as {@link #META_SHIFT_ON} and {@link #META_SHIFT_LEFT_ON}, 2327 * then this method throws an illegal argument exception. 2328 * </p> 2329 * 2330 * @param modifiers The meta state of the modifier keys to check. May be a combination 2331 * of modifier meta states as defined by {@link #getModifierMetaStateMask()}. May be 0 to 2332 * ensure that no modifier keys are pressed. 2333 * @return True if only the specified modifier keys are pressed. 2334 * @throws IllegalArgumentException if the modifiers parameter contains invalid modifiers 2335 * @see #metaStateHasModifiers 2336 */ hasModifiers(int modifiers)2337 public final boolean hasModifiers(int modifiers) { 2338 return metaStateHasModifiers(mMetaState, modifiers); 2339 } 2340 2341 /** 2342 * <p>Returns the pressed state of the ALT meta key.</p> 2343 * 2344 * @return true if the ALT key is pressed, false otherwise 2345 * 2346 * @see #KEYCODE_ALT_LEFT 2347 * @see #KEYCODE_ALT_RIGHT 2348 * @see #META_ALT_ON 2349 */ isAltPressed()2350 public final boolean isAltPressed() { 2351 return (mMetaState & META_ALT_ON) != 0; 2352 } 2353 2354 /** 2355 * <p>Returns the pressed state of the SHIFT meta key.</p> 2356 * 2357 * @return true if the SHIFT key is pressed, false otherwise 2358 * 2359 * @see #KEYCODE_SHIFT_LEFT 2360 * @see #KEYCODE_SHIFT_RIGHT 2361 * @see #META_SHIFT_ON 2362 */ isShiftPressed()2363 public final boolean isShiftPressed() { 2364 return (mMetaState & META_SHIFT_ON) != 0; 2365 } 2366 2367 /** 2368 * <p>Returns the pressed state of the SYM meta key.</p> 2369 * 2370 * @return true if the SYM key is pressed, false otherwise 2371 * 2372 * @see #KEYCODE_SYM 2373 * @see #META_SYM_ON 2374 */ isSymPressed()2375 public final boolean isSymPressed() { 2376 return (mMetaState & META_SYM_ON) != 0; 2377 } 2378 2379 /** 2380 * <p>Returns the pressed state of the CTRL meta key.</p> 2381 * 2382 * @return true if the CTRL key is pressed, false otherwise 2383 * 2384 * @see #KEYCODE_CTRL_LEFT 2385 * @see #KEYCODE_CTRL_RIGHT 2386 * @see #META_CTRL_ON 2387 */ isCtrlPressed()2388 public final boolean isCtrlPressed() { 2389 return (mMetaState & META_CTRL_ON) != 0; 2390 } 2391 2392 /** 2393 * <p>Returns the pressed state of the META meta key.</p> 2394 * 2395 * @return true if the META key is pressed, false otherwise 2396 * 2397 * @see #KEYCODE_META_LEFT 2398 * @see #KEYCODE_META_RIGHT 2399 * @see #META_META_ON 2400 */ isMetaPressed()2401 public final boolean isMetaPressed() { 2402 return (mMetaState & META_META_ON) != 0; 2403 } 2404 2405 /** 2406 * <p>Returns the pressed state of the FUNCTION meta key.</p> 2407 * 2408 * @return true if the FUNCTION key is pressed, false otherwise 2409 * 2410 * @see #KEYCODE_FUNCTION 2411 * @see #META_FUNCTION_ON 2412 */ isFunctionPressed()2413 public final boolean isFunctionPressed() { 2414 return (mMetaState & META_FUNCTION_ON) != 0; 2415 } 2416 2417 /** 2418 * <p>Returns the locked state of the CAPS LOCK meta key.</p> 2419 * 2420 * @return true if the CAPS LOCK key is on, false otherwise 2421 * 2422 * @see #KEYCODE_CAPS_LOCK 2423 * @see #META_CAPS_LOCK_ON 2424 */ isCapsLockOn()2425 public final boolean isCapsLockOn() { 2426 return (mMetaState & META_CAPS_LOCK_ON) != 0; 2427 } 2428 2429 /** 2430 * <p>Returns the locked state of the NUM LOCK meta key.</p> 2431 * 2432 * @return true if the NUM LOCK key is on, false otherwise 2433 * 2434 * @see #KEYCODE_NUM_LOCK 2435 * @see #META_NUM_LOCK_ON 2436 */ isNumLockOn()2437 public final boolean isNumLockOn() { 2438 return (mMetaState & META_NUM_LOCK_ON) != 0; 2439 } 2440 2441 /** 2442 * <p>Returns the locked state of the SCROLL LOCK meta key.</p> 2443 * 2444 * @return true if the SCROLL LOCK key is on, false otherwise 2445 * 2446 * @see #KEYCODE_SCROLL_LOCK 2447 * @see #META_SCROLL_LOCK_ON 2448 */ isScrollLockOn()2449 public final boolean isScrollLockOn() { 2450 return (mMetaState & META_SCROLL_LOCK_ON) != 0; 2451 } 2452 2453 /** 2454 * Retrieve the action of this key event. May be either 2455 * {@link #ACTION_DOWN}, {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}. 2456 * 2457 * @return The event action: ACTION_DOWN, ACTION_UP, or ACTION_MULTIPLE. 2458 */ getAction()2459 public final int getAction() { 2460 return mAction; 2461 } 2462 2463 /** 2464 * For {@link #ACTION_UP} events, indicates that the event has been 2465 * canceled as per {@link #FLAG_CANCELED}. 2466 */ isCanceled()2467 public final boolean isCanceled() { 2468 return (mFlags&FLAG_CANCELED) != 0; 2469 } 2470 2471 /** 2472 * Set {@link #FLAG_CANCELED} flag for the key event. 2473 * 2474 * @hide 2475 */ 2476 @Override cancel()2477 public final void cancel() { 2478 mFlags |= FLAG_CANCELED; 2479 } 2480 2481 /** 2482 * Call this during {@link Callback#onKeyDown} to have the system track 2483 * the key through its final up (possibly including a long press). Note 2484 * that only one key can be tracked at a time -- if another key down 2485 * event is received while a previous one is being tracked, tracking is 2486 * stopped on the previous event. 2487 */ startTracking()2488 public final void startTracking() { 2489 mFlags |= FLAG_START_TRACKING; 2490 } 2491 2492 /** 2493 * For {@link #ACTION_UP} events, indicates that the event is still being 2494 * tracked from its initial down event as per 2495 * {@link #FLAG_TRACKING}. 2496 */ isTracking()2497 public final boolean isTracking() { 2498 return (mFlags&FLAG_TRACKING) != 0; 2499 } 2500 2501 /** 2502 * For {@link #ACTION_DOWN} events, indicates that the event has been 2503 * canceled as per {@link #FLAG_LONG_PRESS}. 2504 */ isLongPress()2505 public final boolean isLongPress() { 2506 return (mFlags&FLAG_LONG_PRESS) != 0; 2507 } 2508 2509 /** 2510 * Retrieve the key code of the key event. This is the physical key that 2511 * was pressed, <em>not</em> the Unicode character. 2512 * 2513 * @return The key code of the event. 2514 */ getKeyCode()2515 public final int getKeyCode() { 2516 return mKeyCode; 2517 } 2518 2519 /** 2520 * For the special case of a {@link #ACTION_MULTIPLE} event with key 2521 * code of {@link #KEYCODE_UNKNOWN}, this is a raw string of characters 2522 * associated with the event. In all other cases it is null. 2523 * 2524 * @return Returns a String of 1 or more characters associated with 2525 * the event. 2526 * 2527 * @deprecated no longer used by the input system. 2528 */ 2529 @Deprecated getCharacters()2530 public final String getCharacters() { 2531 return mCharacters; 2532 } 2533 2534 /** 2535 * Retrieve the hardware key id of this key event. These values are not 2536 * reliable and vary from device to device. 2537 * 2538 * {@more} 2539 * Mostly this is here for debugging purposes. 2540 */ getScanCode()2541 public final int getScanCode() { 2542 return mScanCode; 2543 } 2544 2545 /** 2546 * Retrieve the repeat count of the event. For key down events, 2547 * this is the number of times the key has repeated with the first 2548 * down starting at 0 and counting up from there. For key up events, 2549 * this is always equal to zero. For multiple key events, 2550 * this is the number of down/up pairs that have occurred. 2551 * 2552 * @return The number of times the key has repeated. 2553 */ getRepeatCount()2554 public final int getRepeatCount() { 2555 return mRepeatCount; 2556 } 2557 2558 /** 2559 * Modifies the down time and the event time of the event. 2560 * 2561 * @param downTime The new down time (in {@link android.os.SystemClock#uptimeMillis}) of the 2562 * event. 2563 * @param eventTime The new event time (in {@link android.os.SystemClock#uptimeMillis}) of the 2564 * event. 2565 * @hide 2566 */ setTime(long downTime, long eventTime)2567 public final void setTime(long downTime, long eventTime) { 2568 mDownTime = downTime; 2569 mEventTime = eventTime; 2570 } 2571 2572 /** 2573 * Retrieve the time of the most recent key down event, 2574 * in the {@link android.os.SystemClock#uptimeMillis} time base. If this 2575 * is a down event, this will be the same as {@link #getEventTime()}. 2576 * Note that when chording keys, this value is the down time of the 2577 * most recently pressed key, which may <em>not</em> be the same physical 2578 * key of this event. 2579 * 2580 * @return Returns the most recent key down time, in the 2581 * {@link android.os.SystemClock#uptimeMillis} time base 2582 */ getDownTime()2583 public final long getDownTime() { 2584 return mDownTime; 2585 } 2586 2587 /** 2588 * Retrieve the time this event occurred, 2589 * in the {@link android.os.SystemClock#uptimeMillis} time base. 2590 * 2591 * @return Returns the time this event occurred, 2592 * in the {@link android.os.SystemClock#uptimeMillis} time base. 2593 */ 2594 @Override getEventTime()2595 public final long getEventTime() { 2596 return mEventTime; 2597 } 2598 2599 /** 2600 * Retrieve the time this event occurred, 2601 * in the {@link android.os.SystemClock#uptimeMillis} time base but with 2602 * nanosecond (instead of millisecond) precision. 2603 * <p> 2604 * The value is in nanosecond precision but it may not have nanosecond accuracy. 2605 * </p> 2606 * 2607 * @return Returns the time this event occurred, 2608 * in the {@link android.os.SystemClock#uptimeMillis} time base but with 2609 * nanosecond (instead of millisecond) precision. 2610 * 2611 * @hide 2612 */ 2613 @Override getEventTimeNano()2614 public final long getEventTimeNano() { 2615 return mEventTime * 1000000L; 2616 } 2617 2618 /** 2619 * Renamed to {@link #getDeviceId}. 2620 * 2621 * @hide 2622 * @deprecated use {@link #getDeviceId()} instead. 2623 */ 2624 @Deprecated getKeyboardDevice()2625 public final int getKeyboardDevice() { 2626 return mDeviceId; 2627 } 2628 2629 /** 2630 * Gets the {@link KeyCharacterMap} associated with the keyboard device. 2631 * 2632 * @return The associated key character map. 2633 * @throws {@link KeyCharacterMap.UnavailableException} if the key character map 2634 * could not be loaded because it was malformed or the default key character map 2635 * is missing from the system. 2636 * 2637 * @see KeyCharacterMap#load 2638 */ getKeyCharacterMap()2639 public final KeyCharacterMap getKeyCharacterMap() { 2640 return KeyCharacterMap.load(mDeviceId); 2641 } 2642 2643 /** 2644 * Gets the primary character for this key. 2645 * In other words, the label that is physically printed on it. 2646 * 2647 * @return The display label character, or 0 if none (eg. for non-printing keys). 2648 */ getDisplayLabel()2649 public char getDisplayLabel() { 2650 return getKeyCharacterMap().getDisplayLabel(mKeyCode); 2651 } 2652 2653 /** 2654 * Gets the Unicode character generated by the specified key and meta 2655 * key state combination. 2656 * <p> 2657 * Returns the Unicode character that the specified key would produce 2658 * when the specified meta bits (see {@link MetaKeyKeyListener}) 2659 * were active. 2660 * </p><p> 2661 * Returns 0 if the key is not one that is used to type Unicode 2662 * characters. 2663 * </p><p> 2664 * If the return value has bit {@link KeyCharacterMap#COMBINING_ACCENT} set, the 2665 * key is a "dead key" that should be combined with another to 2666 * actually produce a character -- see {@link KeyCharacterMap#getDeadChar} -- 2667 * after masking with {@link KeyCharacterMap#COMBINING_ACCENT_MASK}. 2668 * </p> 2669 * 2670 * @return The associated character or combining accent, or 0 if none. 2671 */ getUnicodeChar()2672 public int getUnicodeChar() { 2673 return getUnicodeChar(mMetaState); 2674 } 2675 2676 /** 2677 * Gets the Unicode character generated by the specified key and meta 2678 * key state combination. 2679 * <p> 2680 * Returns the Unicode character that the specified key would produce 2681 * when the specified meta bits (see {@link MetaKeyKeyListener}) 2682 * were active. 2683 * </p><p> 2684 * Returns 0 if the key is not one that is used to type Unicode 2685 * characters. 2686 * </p><p> 2687 * If the return value has bit {@link KeyCharacterMap#COMBINING_ACCENT} set, the 2688 * key is a "dead key" that should be combined with another to 2689 * actually produce a character -- see {@link KeyCharacterMap#getDeadChar} -- 2690 * after masking with {@link KeyCharacterMap#COMBINING_ACCENT_MASK}. 2691 * </p> 2692 * 2693 * @param metaState The meta key modifier state. 2694 * @return The associated character or combining accent, or 0 if none. 2695 */ getUnicodeChar(int metaState)2696 public int getUnicodeChar(int metaState) { 2697 return getKeyCharacterMap().get(mKeyCode, metaState); 2698 } 2699 2700 /** 2701 * Get the character conversion data for a given key code. 2702 * 2703 * @param results A {@link KeyCharacterMap.KeyData} instance that will be 2704 * filled with the results. 2705 * @return True if the key was mapped. If the key was not mapped, results is not modified. 2706 * 2707 * @deprecated instead use {@link #getDisplayLabel()}, 2708 * {@link #getNumber()} or {@link #getUnicodeChar(int)}. 2709 */ 2710 @Deprecated getKeyData(KeyData results)2711 public boolean getKeyData(KeyData results) { 2712 return getKeyCharacterMap().getKeyData(mKeyCode, results); 2713 } 2714 2715 /** 2716 * Gets the first character in the character array that can be generated 2717 * by the specified key code. 2718 * <p> 2719 * This is a convenience function that returns the same value as 2720 * {@link #getMatch(char[],int) getMatch(chars, 0)}. 2721 * </p> 2722 * 2723 * @param chars The array of matching characters to consider. 2724 * @return The matching associated character, or 0 if none. 2725 */ getMatch(char[] chars)2726 public char getMatch(char[] chars) { 2727 return getMatch(chars, 0); 2728 } 2729 2730 /** 2731 * Gets the first character in the character array that can be generated 2732 * by the specified key code. If there are multiple choices, prefers 2733 * the one that would be generated with the specified meta key modifier state. 2734 * 2735 * @param chars The array of matching characters to consider. 2736 * @param metaState The preferred meta key modifier state. 2737 * @return The matching associated character, or 0 if none. 2738 */ getMatch(char[] chars, int metaState)2739 public char getMatch(char[] chars, int metaState) { 2740 return getKeyCharacterMap().getMatch(mKeyCode, chars, metaState); 2741 } 2742 2743 /** 2744 * Gets the number or symbol associated with the key. 2745 * <p> 2746 * The character value is returned, not the numeric value. 2747 * If the key is not a number, but is a symbol, the symbol is retuned. 2748 * </p><p> 2749 * This method is intended to to support dial pads and other numeric or 2750 * symbolic entry on keyboards where certain keys serve dual function 2751 * as alphabetic and symbolic keys. This method returns the number 2752 * or symbol associated with the key independent of whether the user 2753 * has pressed the required modifier. 2754 * </p><p> 2755 * For example, on one particular keyboard the keys on the top QWERTY row generate 2756 * numbers when ALT is pressed such that ALT-Q maps to '1'. So for that keyboard 2757 * when {@link #getNumber} is called with {@link KeyEvent#KEYCODE_Q} it returns '1' 2758 * so that the user can type numbers without pressing ALT when it makes sense. 2759 * </p> 2760 * 2761 * @return The associated numeric or symbolic character, or 0 if none. 2762 */ getNumber()2763 public char getNumber() { 2764 return getKeyCharacterMap().getNumber(mKeyCode); 2765 } 2766 2767 /** 2768 * Returns true if this key produces a glyph. 2769 * 2770 * @return True if the key is a printing key. 2771 */ isPrintingKey()2772 public boolean isPrintingKey() { 2773 return getKeyCharacterMap().isPrintingKey(mKeyCode); 2774 } 2775 2776 /** 2777 * @deprecated Use {@link #dispatch(Callback, DispatcherState, Object)} instead. 2778 */ 2779 @Deprecated dispatch(Callback receiver)2780 public final boolean dispatch(Callback receiver) { 2781 return dispatch(receiver, null, null); 2782 } 2783 2784 /** 2785 * Deliver this key event to a {@link Callback} interface. If this is 2786 * an ACTION_MULTIPLE event and it is not handled, then an attempt will 2787 * be made to deliver a single normal event. 2788 * 2789 * @param receiver The Callback that will be given the event. 2790 * @param state State information retained across events. 2791 * @param target The target of the dispatch, for use in tracking. 2792 * 2793 * @return The return value from the Callback method that was called. 2794 */ dispatch(Callback receiver, DispatcherState state, Object target)2795 public final boolean dispatch(Callback receiver, DispatcherState state, 2796 Object target) { 2797 switch (mAction) { 2798 case ACTION_DOWN: { 2799 mFlags &= ~FLAG_START_TRACKING; 2800 if (DEBUG) Log.v(TAG, "Key down to " + target + " in " + state 2801 + ": " + this); 2802 boolean res = receiver.onKeyDown(mKeyCode, this); 2803 if (state != null) { 2804 if (res && mRepeatCount == 0 && (mFlags&FLAG_START_TRACKING) != 0) { 2805 if (DEBUG) Log.v(TAG, " Start tracking!"); 2806 state.startTracking(this, target); 2807 } else if (isLongPress() && state.isTracking(this)) { 2808 try { 2809 if (receiver.onKeyLongPress(mKeyCode, this)) { 2810 if (DEBUG) Log.v(TAG, " Clear from long press!"); 2811 state.performedLongPress(this); 2812 res = true; 2813 } 2814 } catch (AbstractMethodError e) { 2815 } 2816 } 2817 } 2818 return res; 2819 } 2820 case ACTION_UP: 2821 if (DEBUG) Log.v(TAG, "Key up to " + target + " in " + state 2822 + ": " + this); 2823 if (state != null) { 2824 state.handleUpEvent(this); 2825 } 2826 return receiver.onKeyUp(mKeyCode, this); 2827 case ACTION_MULTIPLE: 2828 final int count = mRepeatCount; 2829 final int code = mKeyCode; 2830 if (receiver.onKeyMultiple(code, count, this)) { 2831 return true; 2832 } 2833 if (code != KeyEvent.KEYCODE_UNKNOWN) { 2834 mAction = ACTION_DOWN; 2835 mRepeatCount = 0; 2836 boolean handled = receiver.onKeyDown(code, this); 2837 if (handled) { 2838 mAction = ACTION_UP; 2839 receiver.onKeyUp(code, this); 2840 } 2841 mAction = ACTION_MULTIPLE; 2842 mRepeatCount = count; 2843 return handled; 2844 } 2845 return false; 2846 } 2847 return false; 2848 } 2849 2850 /** 2851 * Use with {@link KeyEvent#dispatch(Callback, DispatcherState, Object)} 2852 * for more advanced key dispatching, such as long presses. 2853 */ 2854 public static class DispatcherState { 2855 int mDownKeyCode; 2856 Object mDownTarget; 2857 SparseIntArray mActiveLongPresses = new SparseIntArray(); 2858 2859 /** 2860 * Reset back to initial state. 2861 */ reset()2862 public void reset() { 2863 if (DEBUG) Log.v(TAG, "Reset: " + this); 2864 mDownKeyCode = 0; 2865 mDownTarget = null; 2866 mActiveLongPresses.clear(); 2867 } 2868 2869 /** 2870 * Stop any tracking associated with this target. 2871 */ reset(Object target)2872 public void reset(Object target) { 2873 if (mDownTarget == target) { 2874 if (DEBUG) Log.v(TAG, "Reset in " + target + ": " + this); 2875 mDownKeyCode = 0; 2876 mDownTarget = null; 2877 } 2878 } 2879 2880 /** 2881 * Start tracking the key code associated with the given event. This 2882 * can only be called on a key down. It will allow you to see any 2883 * long press associated with the key, and will result in 2884 * {@link KeyEvent#isTracking} return true on the long press and up 2885 * events. 2886 * 2887 * <p>This is only needed if you are directly dispatching events, rather 2888 * than handling them in {@link Callback#onKeyDown}. 2889 */ startTracking(KeyEvent event, Object target)2890 public void startTracking(KeyEvent event, Object target) { 2891 if (event.getAction() != ACTION_DOWN) { 2892 throw new IllegalArgumentException( 2893 "Can only start tracking on a down event"); 2894 } 2895 if (DEBUG) Log.v(TAG, "Start trackingt in " + target + ": " + this); 2896 mDownKeyCode = event.getKeyCode(); 2897 mDownTarget = target; 2898 } 2899 2900 /** 2901 * Return true if the key event is for a key code that is currently 2902 * being tracked by the dispatcher. 2903 */ isTracking(KeyEvent event)2904 public boolean isTracking(KeyEvent event) { 2905 return mDownKeyCode == event.getKeyCode(); 2906 } 2907 2908 /** 2909 * Keep track of the given event's key code as having performed an 2910 * action with a long press, so no action should occur on the up. 2911 * <p>This is only needed if you are directly dispatching events, rather 2912 * than handling them in {@link Callback#onKeyLongPress}. 2913 */ performedLongPress(KeyEvent event)2914 public void performedLongPress(KeyEvent event) { 2915 mActiveLongPresses.put(event.getKeyCode(), 1); 2916 } 2917 2918 /** 2919 * Handle key up event to stop tracking. This resets the dispatcher state, 2920 * and updates the key event state based on it. 2921 * <p>This is only needed if you are directly dispatching events, rather 2922 * than handling them in {@link Callback#onKeyUp}. 2923 */ handleUpEvent(KeyEvent event)2924 public void handleUpEvent(KeyEvent event) { 2925 final int keyCode = event.getKeyCode(); 2926 if (DEBUG) Log.v(TAG, "Handle key up " + event + ": " + this); 2927 int index = mActiveLongPresses.indexOfKey(keyCode); 2928 if (index >= 0) { 2929 if (DEBUG) Log.v(TAG, " Index: " + index); 2930 event.mFlags |= FLAG_CANCELED | FLAG_CANCELED_LONG_PRESS; 2931 mActiveLongPresses.removeAt(index); 2932 } 2933 if (mDownKeyCode == keyCode) { 2934 if (DEBUG) Log.v(TAG, " Tracking!"); 2935 event.mFlags |= FLAG_TRACKING; 2936 mDownKeyCode = 0; 2937 mDownTarget = null; 2938 } 2939 } 2940 } 2941 2942 @Override toString()2943 public String toString() { 2944 StringBuilder msg = new StringBuilder(); 2945 msg.append("KeyEvent { action=").append(actionToString(mAction)); 2946 msg.append(", keyCode=").append(keyCodeToString(mKeyCode)); 2947 msg.append(", scanCode=").append(mScanCode); 2948 if (mCharacters != null) { 2949 msg.append(", characters=\"").append(mCharacters).append("\""); 2950 } 2951 msg.append(", metaState=").append(metaStateToString(mMetaState)); 2952 msg.append(", flags=0x").append(Integer.toHexString(mFlags)); 2953 msg.append(", repeatCount=").append(mRepeatCount); 2954 msg.append(", eventTime=").append(mEventTime); 2955 msg.append(", downTime=").append(mDownTime); 2956 msg.append(", deviceId=").append(mDeviceId); 2957 msg.append(", source=0x").append(Integer.toHexString(mSource)); 2958 msg.append(", displayId=").append(mDisplayId); 2959 msg.append(" }"); 2960 return msg.toString(); 2961 } 2962 2963 /** 2964 * Returns a string that represents the symbolic name of the specified action 2965 * such as "ACTION_DOWN", or an equivalent numeric constant such as "35" if unknown. 2966 * 2967 * @param action The action. 2968 * @return The symbolic name of the specified action. 2969 * @hide 2970 */ 2971 @TestApi actionToString(int action)2972 public static String actionToString(int action) { 2973 switch (action) { 2974 case ACTION_DOWN: 2975 return "ACTION_DOWN"; 2976 case ACTION_UP: 2977 return "ACTION_UP"; 2978 case ACTION_MULTIPLE: 2979 return "ACTION_MULTIPLE"; 2980 default: 2981 return Integer.toString(action); 2982 } 2983 } 2984 2985 /** 2986 * Returns a string that represents the symbolic name of the specified keycode 2987 * such as "KEYCODE_A", "KEYCODE_DPAD_UP", or an equivalent numeric constant 2988 * such as "1001" if unknown. 2989 * 2990 * This function is intended to be used mostly for debugging, logging, and testing. It is not 2991 * locale-specific and is not intended to be used in a user-facing manner. 2992 * 2993 * @param keyCode The key code. 2994 * @return The symbolic name of the specified keycode. 2995 * 2996 * @see KeyCharacterMap#getDisplayLabel 2997 */ keyCodeToString(int keyCode)2998 public static String keyCodeToString(int keyCode) { 2999 String symbolicName = nativeKeyCodeToString(keyCode); 3000 return symbolicName != null ? LABEL_PREFIX + symbolicName : Integer.toString(keyCode); 3001 } 3002 3003 /** 3004 * Gets a keycode by its symbolic name such as "KEYCODE_A" or an equivalent 3005 * numeric constant such as "29". For symbolic names, 3006 * starting in {@link android.os.Build.VERSION_CODES#Q} the prefix "KEYCODE_" is optional. 3007 * 3008 * @param symbolicName The symbolic name of the keycode. 3009 * @return The keycode or {@link #KEYCODE_UNKNOWN} if not found. 3010 * @see #keyCodeToString(int) 3011 */ keyCodeFromString(@onNull String symbolicName)3012 public static int keyCodeFromString(@NonNull String symbolicName) { 3013 try { 3014 int keyCode = Integer.parseInt(symbolicName); 3015 if (keyCodeIsValid(keyCode)) { 3016 return keyCode; 3017 } 3018 } catch (NumberFormatException ex) { 3019 } 3020 3021 if (symbolicName.startsWith(LABEL_PREFIX)) { 3022 symbolicName = symbolicName.substring(LABEL_PREFIX.length()); 3023 } 3024 int keyCode = nativeKeyCodeFromString(symbolicName); 3025 if (keyCodeIsValid(keyCode)) { 3026 return keyCode; 3027 } 3028 return KEYCODE_UNKNOWN; 3029 } 3030 keyCodeIsValid(int keyCode)3031 private static boolean keyCodeIsValid(int keyCode) { 3032 return keyCode >= KEYCODE_UNKNOWN && keyCode <= LAST_KEYCODE; 3033 } 3034 3035 /** 3036 * Returns a string that represents the symbolic name of the specified combined meta 3037 * key modifier state flags such as "0", "META_SHIFT_ON", 3038 * "META_ALT_ON|META_SHIFT_ON" or an equivalent numeric constant such as "0x10000000" 3039 * if unknown. 3040 * 3041 * @param metaState The meta state. 3042 * @return The symbolic name of the specified combined meta state flags. 3043 * @hide 3044 */ metaStateToString(int metaState)3045 public static String metaStateToString(int metaState) { 3046 if (metaState == 0) { 3047 return "0"; 3048 } 3049 StringBuilder result = null; 3050 int i = 0; 3051 while (metaState != 0) { 3052 final boolean isSet = (metaState & 1) != 0; 3053 metaState >>>= 1; // unsigned shift! 3054 if (isSet) { 3055 final String name = META_SYMBOLIC_NAMES[i]; 3056 if (result == null) { 3057 if (metaState == 0) { 3058 return name; 3059 } 3060 result = new StringBuilder(name); 3061 } else { 3062 result.append('|'); 3063 result.append(name); 3064 } 3065 } 3066 i += 1; 3067 } 3068 return result.toString(); 3069 } 3070 3071 public static final @android.annotation.NonNull Parcelable.Creator<KeyEvent> CREATOR 3072 = new Parcelable.Creator<KeyEvent>() { 3073 @Override 3074 public KeyEvent createFromParcel(Parcel in) { 3075 in.readInt(); // skip token, we already know this is a KeyEvent 3076 return KeyEvent.createFromParcelBody(in); 3077 } 3078 3079 @Override 3080 public KeyEvent[] newArray(int size) { 3081 return new KeyEvent[size]; 3082 } 3083 }; 3084 3085 /** @hide */ createFromParcelBody(Parcel in)3086 public static KeyEvent createFromParcelBody(Parcel in) { 3087 return new KeyEvent(in); 3088 } 3089 KeyEvent(Parcel in)3090 private KeyEvent(Parcel in) { 3091 mDeviceId = in.readInt(); 3092 mSource = in.readInt(); 3093 mDisplayId = in.readInt(); 3094 mAction = in.readInt(); 3095 mKeyCode = in.readInt(); 3096 mRepeatCount = in.readInt(); 3097 mMetaState = in.readInt(); 3098 mScanCode = in.readInt(); 3099 mFlags = in.readInt(); 3100 mDownTime = in.readLong(); 3101 mEventTime = in.readLong(); 3102 mCharacters = in.readString(); 3103 } 3104 3105 @Override writeToParcel(Parcel out, int flags)3106 public void writeToParcel(Parcel out, int flags) { 3107 out.writeInt(PARCEL_TOKEN_KEY_EVENT); 3108 3109 out.writeInt(mDeviceId); 3110 out.writeInt(mSource); 3111 out.writeInt(mDisplayId); 3112 out.writeInt(mAction); 3113 out.writeInt(mKeyCode); 3114 out.writeInt(mRepeatCount); 3115 out.writeInt(mMetaState); 3116 out.writeInt(mScanCode); 3117 out.writeInt(mFlags); 3118 out.writeLong(mDownTime); 3119 out.writeLong(mEventTime); 3120 out.writeString(mCharacters); 3121 } 3122 } 3123