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