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