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