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 17package android.view; 18 19import android.os.Parcel; 20import android.os.Parcelable; 21import android.text.method.MetaKeyKeyListener; 22import android.util.Log; 23import android.util.SparseIntArray; 24import 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 */ 80public 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 808 private static final int LAST_KEYCODE = KEYCODE_SYSTEM_NAVIGATION_RIGHT; 809 810 // NOTE: If you add a new keycode here you must also add it to: 811 // isSystem() 812 // isWakeKey() 813 // frameworks/native/include/android/keycodes.h 814 // frameworks/native/include/input/InputEventLabels.h 815 // frameworks/base/core/res/res/values/attrs.xml 816 // emulator? 817 // LAST_KEYCODE 818 // 819 // Also Android currently does not reserve code ranges for vendor- 820 // specific key codes. If you have new key codes to have, you 821 // MUST contribute a patch to the open source project to define 822 // those new codes. This is intended to maintain a consistent 823 // set of key code definitions across all Android devices. 824 825 // Symbolic names of all metakeys in bit order from least significant to most significant. 826 // Accordingly there are exactly 32 values in this table. 827 private static final String[] META_SYMBOLIC_NAMES = new String[] { 828 "META_SHIFT_ON", 829 "META_ALT_ON", 830 "META_SYM_ON", 831 "META_FUNCTION_ON", 832 "META_ALT_LEFT_ON", 833 "META_ALT_RIGHT_ON", 834 "META_SHIFT_LEFT_ON", 835 "META_SHIFT_RIGHT_ON", 836 "META_CAP_LOCKED", 837 "META_ALT_LOCKED", 838 "META_SYM_LOCKED", 839 "0x00000800", 840 "META_CTRL_ON", 841 "META_CTRL_LEFT_ON", 842 "META_CTRL_RIGHT_ON", 843 "0x00008000", 844 "META_META_ON", 845 "META_META_LEFT_ON", 846 "META_META_RIGHT_ON", 847 "0x00080000", 848 "META_CAPS_LOCK_ON", 849 "META_NUM_LOCK_ON", 850 "META_SCROLL_LOCK_ON", 851 "0x00800000", 852 "0x01000000", 853 "0x02000000", 854 "0x04000000", 855 "0x08000000", 856 "0x10000000", 857 "0x20000000", 858 "0x40000000", 859 "0x80000000", 860 }; 861 862 private static final String LABEL_PREFIX = "KEYCODE_"; 863 864 /** 865 * @deprecated There are now more than MAX_KEYCODE keycodes. 866 * Use {@link #getMaxKeyCode()} instead. 867 */ 868 @Deprecated 869 public static final int MAX_KEYCODE = 84; 870 871 /** 872 * {@link #getAction} value: the key has been pressed down. 873 */ 874 public static final int ACTION_DOWN = 0; 875 /** 876 * {@link #getAction} value: the key has been released. 877 */ 878 public static final int ACTION_UP = 1; 879 /** 880 * {@link #getAction} value: multiple duplicate key events have 881 * occurred in a row, or a complex string is being delivered. If the 882 * key code is not {#link {@link #KEYCODE_UNKNOWN} then the 883 * {#link {@link #getRepeatCount()} method returns the number of times 884 * the given key code should be executed. 885 * Otherwise, if the key code is {@link #KEYCODE_UNKNOWN}, then 886 * this is a sequence of characters as returned by {@link #getCharacters}. 887 */ 888 public static final int ACTION_MULTIPLE = 2; 889 890 /** 891 * SHIFT key locked in CAPS mode. 892 * Reserved for use by {@link MetaKeyKeyListener} for a published constant in its API. 893 * @hide 894 */ 895 public static final int META_CAP_LOCKED = 0x100; 896 897 /** 898 * ALT key locked. 899 * Reserved for use by {@link MetaKeyKeyListener} for a published constant in its API. 900 * @hide 901 */ 902 public static final int META_ALT_LOCKED = 0x200; 903 904 /** 905 * SYM key locked. 906 * Reserved for use by {@link MetaKeyKeyListener} for a published constant in its API. 907 * @hide 908 */ 909 public static final int META_SYM_LOCKED = 0x400; 910 911 /** 912 * Text is in selection mode. 913 * Reserved for use by {@link MetaKeyKeyListener} for a private unpublished constant 914 * in its API that is currently being retained for legacy reasons. 915 * @hide 916 */ 917 public static final int META_SELECTING = 0x800; 918 919 /** 920 * <p>This mask is used to check whether one of the ALT meta keys is pressed.</p> 921 * 922 * @see #isAltPressed() 923 * @see #getMetaState() 924 * @see #KEYCODE_ALT_LEFT 925 * @see #KEYCODE_ALT_RIGHT 926 */ 927 public static final int META_ALT_ON = 0x02; 928 929 /** 930 * <p>This mask is used to check whether the left ALT meta key is pressed.</p> 931 * 932 * @see #isAltPressed() 933 * @see #getMetaState() 934 * @see #KEYCODE_ALT_LEFT 935 */ 936 public static final int META_ALT_LEFT_ON = 0x10; 937 938 /** 939 * <p>This mask is used to check whether the right the ALT meta key is pressed.</p> 940 * 941 * @see #isAltPressed() 942 * @see #getMetaState() 943 * @see #KEYCODE_ALT_RIGHT 944 */ 945 public static final int META_ALT_RIGHT_ON = 0x20; 946 947 /** 948 * <p>This mask is used to check whether one of the SHIFT meta keys is pressed.</p> 949 * 950 * @see #isShiftPressed() 951 * @see #getMetaState() 952 * @see #KEYCODE_SHIFT_LEFT 953 * @see #KEYCODE_SHIFT_RIGHT 954 */ 955 public static final int META_SHIFT_ON = 0x1; 956 957 /** 958 * <p>This mask is used to check whether the left SHIFT meta key is pressed.</p> 959 * 960 * @see #isShiftPressed() 961 * @see #getMetaState() 962 * @see #KEYCODE_SHIFT_LEFT 963 */ 964 public static final int META_SHIFT_LEFT_ON = 0x40; 965 966 /** 967 * <p>This mask is used to check whether the right SHIFT meta key is pressed.</p> 968 * 969 * @see #isShiftPressed() 970 * @see #getMetaState() 971 * @see #KEYCODE_SHIFT_RIGHT 972 */ 973 public static final int META_SHIFT_RIGHT_ON = 0x80; 974 975 /** 976 * <p>This mask is used to check whether the SYM meta key is pressed.</p> 977 * 978 * @see #isSymPressed() 979 * @see #getMetaState() 980 */ 981 public static final int META_SYM_ON = 0x4; 982 983 /** 984 * <p>This mask is used to check whether the FUNCTION meta key is pressed.</p> 985 * 986 * @see #isFunctionPressed() 987 * @see #getMetaState() 988 */ 989 public static final int META_FUNCTION_ON = 0x8; 990 991 /** 992 * <p>This mask is used to check whether one of the CTRL meta keys is pressed.</p> 993 * 994 * @see #isCtrlPressed() 995 * @see #getMetaState() 996 * @see #KEYCODE_CTRL_LEFT 997 * @see #KEYCODE_CTRL_RIGHT 998 */ 999 public static final int META_CTRL_ON = 0x1000; 1000 1001 /** 1002 * <p>This mask is used to check whether the left CTRL meta key is pressed.</p> 1003 * 1004 * @see #isCtrlPressed() 1005 * @see #getMetaState() 1006 * @see #KEYCODE_CTRL_LEFT 1007 */ 1008 public static final int META_CTRL_LEFT_ON = 0x2000; 1009 1010 /** 1011 * <p>This mask is used to check whether the right CTRL meta key is pressed.</p> 1012 * 1013 * @see #isCtrlPressed() 1014 * @see #getMetaState() 1015 * @see #KEYCODE_CTRL_RIGHT 1016 */ 1017 public static final int META_CTRL_RIGHT_ON = 0x4000; 1018 1019 /** 1020 * <p>This mask is used to check whether one of the META meta keys is pressed.</p> 1021 * 1022 * @see #isMetaPressed() 1023 * @see #getMetaState() 1024 * @see #KEYCODE_META_LEFT 1025 * @see #KEYCODE_META_RIGHT 1026 */ 1027 public static final int META_META_ON = 0x10000; 1028 1029 /** 1030 * <p>This mask is used to check whether the left META meta key is pressed.</p> 1031 * 1032 * @see #isMetaPressed() 1033 * @see #getMetaState() 1034 * @see #KEYCODE_META_LEFT 1035 */ 1036 public static final int META_META_LEFT_ON = 0x20000; 1037 1038 /** 1039 * <p>This mask is used to check whether the right META meta key is pressed.</p> 1040 * 1041 * @see #isMetaPressed() 1042 * @see #getMetaState() 1043 * @see #KEYCODE_META_RIGHT 1044 */ 1045 public static final int META_META_RIGHT_ON = 0x40000; 1046 1047 /** 1048 * <p>This mask is used to check whether the CAPS LOCK meta key is on.</p> 1049 * 1050 * @see #isCapsLockOn() 1051 * @see #getMetaState() 1052 * @see #KEYCODE_CAPS_LOCK 1053 */ 1054 public static final int META_CAPS_LOCK_ON = 0x100000; 1055 1056 /** 1057 * <p>This mask is used to check whether the NUM LOCK meta key is on.</p> 1058 * 1059 * @see #isNumLockOn() 1060 * @see #getMetaState() 1061 * @see #KEYCODE_NUM_LOCK 1062 */ 1063 public static final int META_NUM_LOCK_ON = 0x200000; 1064 1065 /** 1066 * <p>This mask is used to check whether the SCROLL LOCK meta key is on.</p> 1067 * 1068 * @see #isScrollLockOn() 1069 * @see #getMetaState() 1070 * @see #KEYCODE_SCROLL_LOCK 1071 */ 1072 public static final int META_SCROLL_LOCK_ON = 0x400000; 1073 1074 /** 1075 * This mask is a combination of {@link #META_SHIFT_ON}, {@link #META_SHIFT_LEFT_ON} 1076 * and {@link #META_SHIFT_RIGHT_ON}. 1077 */ 1078 public static final int META_SHIFT_MASK = META_SHIFT_ON 1079 | META_SHIFT_LEFT_ON | META_SHIFT_RIGHT_ON; 1080 1081 /** 1082 * This mask is a combination of {@link #META_ALT_ON}, {@link #META_ALT_LEFT_ON} 1083 * and {@link #META_ALT_RIGHT_ON}. 1084 */ 1085 public static final int META_ALT_MASK = META_ALT_ON 1086 | META_ALT_LEFT_ON | META_ALT_RIGHT_ON; 1087 1088 /** 1089 * This mask is a combination of {@link #META_CTRL_ON}, {@link #META_CTRL_LEFT_ON} 1090 * and {@link #META_CTRL_RIGHT_ON}. 1091 */ 1092 public static final int META_CTRL_MASK = META_CTRL_ON 1093 | META_CTRL_LEFT_ON | META_CTRL_RIGHT_ON; 1094 1095 /** 1096 * This mask is a combination of {@link #META_META_ON}, {@link #META_META_LEFT_ON} 1097 * and {@link #META_META_RIGHT_ON}. 1098 */ 1099 public static final int META_META_MASK = META_META_ON 1100 | META_META_LEFT_ON | META_META_RIGHT_ON; 1101 1102 /** 1103 * This mask is set if the device woke because of this key event. 1104 * 1105 * @deprecated This flag will never be set by the system since the system 1106 * consumes all wake keys itself. 1107 */ 1108 @Deprecated 1109 public static final int FLAG_WOKE_HERE = 0x1; 1110 1111 /** 1112 * This mask is set if the key event was generated by a software keyboard. 1113 */ 1114 public static final int FLAG_SOFT_KEYBOARD = 0x2; 1115 1116 /** 1117 * This mask is set if we don't want the key event to cause us to leave 1118 * touch mode. 1119 */ 1120 public static final int FLAG_KEEP_TOUCH_MODE = 0x4; 1121 1122 /** 1123 * This mask is set if an event was known to come from a trusted part 1124 * of the system. That is, the event is known to come from the user, 1125 * and could not have been spoofed by a third party component. 1126 */ 1127 public static final int FLAG_FROM_SYSTEM = 0x8; 1128 1129 /** 1130 * This mask is used for compatibility, to identify enter keys that are 1131 * coming from an IME whose enter key has been auto-labelled "next" or 1132 * "done". This allows TextView to dispatch these as normal enter keys 1133 * for old applications, but still do the appropriate action when 1134 * receiving them. 1135 */ 1136 public static final int FLAG_EDITOR_ACTION = 0x10; 1137 1138 /** 1139 * When associated with up key events, this indicates that the key press 1140 * has been canceled. Typically this is used with virtual touch screen 1141 * keys, where the user can slide from the virtual key area on to the 1142 * display: in that case, the application will receive a canceled up 1143 * event and should not perform the action normally associated with the 1144 * key. Note that for this to work, the application can not perform an 1145 * action for a key until it receives an up or the long press timeout has 1146 * expired. 1147 */ 1148 public static final int FLAG_CANCELED = 0x20; 1149 1150 /** 1151 * This key event was generated by a virtual (on-screen) hard key area. 1152 * Typically this is an area of the touchscreen, outside of the regular 1153 * display, dedicated to "hardware" buttons. 1154 */ 1155 public static final int FLAG_VIRTUAL_HARD_KEY = 0x40; 1156 1157 /** 1158 * This flag is set for the first key repeat that occurs after the 1159 * long press timeout. 1160 */ 1161 public static final int FLAG_LONG_PRESS = 0x80; 1162 1163 /** 1164 * Set when a key event has {@link #FLAG_CANCELED} set because a long 1165 * press action was executed while it was down. 1166 */ 1167 public static final int FLAG_CANCELED_LONG_PRESS = 0x100; 1168 1169 /** 1170 * Set for {@link #ACTION_UP} when this event's key code is still being 1171 * tracked from its initial down. That is, somebody requested that tracking 1172 * started on the key down and a long press has not caused 1173 * the tracking to be canceled. 1174 */ 1175 public static final int FLAG_TRACKING = 0x200; 1176 1177 /** 1178 * Set when a key event has been synthesized to implement default behavior 1179 * for an event that the application did not handle. 1180 * Fallback key events are generated by unhandled trackball motions 1181 * (to emulate a directional keypad) and by certain unhandled key presses 1182 * that are declared in the key map (such as special function numeric keypad 1183 * keys when numlock is off). 1184 */ 1185 public static final int FLAG_FALLBACK = 0x400; 1186 1187 /** 1188 * Signifies that the key is being predispatched. 1189 * @hide 1190 */ 1191 public static final int FLAG_PREDISPATCH = 0x20000000; 1192 1193 /** 1194 * Private control to determine when an app is tracking a key sequence. 1195 * @hide 1196 */ 1197 public static final int FLAG_START_TRACKING = 0x40000000; 1198 1199 /** 1200 * Private flag that indicates when the system has detected that this key event 1201 * may be inconsistent with respect to the sequence of previously delivered key events, 1202 * such as when a key up event is sent but the key was not down. 1203 * 1204 * @hide 1205 * @see #isTainted 1206 * @see #setTainted 1207 */ 1208 public static final int FLAG_TAINTED = 0x80000000; 1209 1210 /** 1211 * Returns the maximum keycode. 1212 */ 1213 public static int getMaxKeyCode() { 1214 return LAST_KEYCODE; 1215 } 1216 1217 /** 1218 * Get the character that is produced by putting accent on the character 1219 * c. 1220 * For example, getDeadChar('`', 'e') returns è. 1221 */ 1222 public static int getDeadChar(int accent, int c) { 1223 return KeyCharacterMap.getDeadChar(accent, c); 1224 } 1225 1226 static final boolean DEBUG = false; 1227 static final String TAG = "KeyEvent"; 1228 1229 private static final int MAX_RECYCLED = 10; 1230 private static final Object gRecyclerLock = new Object(); 1231 private static int gRecyclerUsed; 1232 private static KeyEvent gRecyclerTop; 1233 1234 private KeyEvent mNext; 1235 1236 private int mDeviceId; 1237 private int mSource; 1238 private int mMetaState; 1239 private int mAction; 1240 private int mKeyCode; 1241 private int mScanCode; 1242 private int mRepeatCount; 1243 private int mFlags; 1244 private long mDownTime; 1245 private long mEventTime; 1246 private String mCharacters; 1247 1248 public interface Callback { 1249 /** 1250 * Called when a key down event has occurred. If you return true, 1251 * you can first call {@link KeyEvent#startTracking() 1252 * KeyEvent.startTracking()} to have the framework track the event 1253 * through its {@link #onKeyUp(int, KeyEvent)} and also call your 1254 * {@link #onKeyLongPress(int, KeyEvent)} if it occurs. 1255 * 1256 * @param keyCode The value in event.getKeyCode(). 1257 * @param event Description of the key event. 1258 * 1259 * @return If you handled the event, return true. If you want to allow 1260 * the event to be handled by the next receiver, return false. 1261 */ 1262 boolean onKeyDown(int keyCode, KeyEvent event); 1263 1264 /** 1265 * Called when a long press has occurred. If you return true, 1266 * the final key up will have {@link KeyEvent#FLAG_CANCELED} and 1267 * {@link KeyEvent#FLAG_CANCELED_LONG_PRESS} set. Note that in 1268 * order to receive this callback, someone in the event change 1269 * <em>must</em> return true from {@link #onKeyDown} <em>and</em> 1270 * call {@link KeyEvent#startTracking()} on the event. 1271 * 1272 * @param keyCode The value in event.getKeyCode(). 1273 * @param event Description of the key event. 1274 * 1275 * @return If you handled the event, return true. If you want to allow 1276 * the event to be handled by the next receiver, return false. 1277 */ 1278 boolean onKeyLongPress(int keyCode, KeyEvent event); 1279 1280 /** 1281 * Called when a key up event has occurred. 1282 * 1283 * @param keyCode The value in event.getKeyCode(). 1284 * @param event Description of the key event. 1285 * 1286 * @return If you handled the event, return true. If you want to allow 1287 * the event to be handled by the next receiver, return false. 1288 */ 1289 boolean onKeyUp(int keyCode, KeyEvent event); 1290 1291 /** 1292 * Called when a user's interaction with an analog control, such as 1293 * flinging a trackball, generates simulated down/up events for the same 1294 * key multiple times in quick succession. 1295 * 1296 * @param keyCode The value in event.getKeyCode(). 1297 * @param count Number of pairs as returned by event.getRepeatCount(). 1298 * @param event Description of the key event. 1299 * 1300 * @return If you handled the event, return true. If you want to allow 1301 * the event to be handled by the next receiver, return false. 1302 */ 1303 boolean onKeyMultiple(int keyCode, int count, KeyEvent event); 1304 } 1305 1306 private static native String nativeKeyCodeToString(int keyCode); 1307 private static native int nativeKeyCodeFromString(String keyCode); 1308 1309 private KeyEvent() { 1310 } 1311 1312 /** 1313 * Create a new key event. 1314 * 1315 * @param action Action code: either {@link #ACTION_DOWN}, 1316 * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}. 1317 * @param code The key code. 1318 */ 1319 public KeyEvent(int action, int code) { 1320 mAction = action; 1321 mKeyCode = code; 1322 mRepeatCount = 0; 1323 mDeviceId = KeyCharacterMap.VIRTUAL_KEYBOARD; 1324 } 1325 1326 /** 1327 * Create a new key event. 1328 * 1329 * @param downTime The time (in {@link android.os.SystemClock#uptimeMillis}) 1330 * at which this key code originally went down. 1331 * @param eventTime The time (in {@link android.os.SystemClock#uptimeMillis}) 1332 * at which this event happened. 1333 * @param action Action code: either {@link #ACTION_DOWN}, 1334 * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}. 1335 * @param code The key code. 1336 * @param repeat A repeat count for down events (> 0 if this is after the 1337 * initial down) or event count for multiple events. 1338 */ 1339 public KeyEvent(long downTime, long eventTime, int action, 1340 int code, int repeat) { 1341 mDownTime = downTime; 1342 mEventTime = eventTime; 1343 mAction = action; 1344 mKeyCode = code; 1345 mRepeatCount = repeat; 1346 mDeviceId = KeyCharacterMap.VIRTUAL_KEYBOARD; 1347 } 1348 1349 /** 1350 * Create a new key event. 1351 * 1352 * @param downTime The time (in {@link android.os.SystemClock#uptimeMillis}) 1353 * at which this key code originally went down. 1354 * @param eventTime The time (in {@link android.os.SystemClock#uptimeMillis}) 1355 * at which this event happened. 1356 * @param action Action code: either {@link #ACTION_DOWN}, 1357 * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}. 1358 * @param code The key code. 1359 * @param repeat A repeat count for down events (> 0 if this is after the 1360 * initial down) or event count for multiple events. 1361 * @param metaState Flags indicating which meta keys are currently pressed. 1362 */ 1363 public KeyEvent(long downTime, long eventTime, int action, 1364 int code, int repeat, int metaState) { 1365 mDownTime = downTime; 1366 mEventTime = eventTime; 1367 mAction = action; 1368 mKeyCode = code; 1369 mRepeatCount = repeat; 1370 mMetaState = metaState; 1371 mDeviceId = KeyCharacterMap.VIRTUAL_KEYBOARD; 1372 } 1373 1374 /** 1375 * Create a new key event. 1376 * 1377 * @param downTime The time (in {@link android.os.SystemClock#uptimeMillis}) 1378 * at which this key code originally went down. 1379 * @param eventTime The time (in {@link android.os.SystemClock#uptimeMillis}) 1380 * at which this event happened. 1381 * @param action Action code: either {@link #ACTION_DOWN}, 1382 * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}. 1383 * @param code The key code. 1384 * @param repeat A repeat count for down events (> 0 if this is after the 1385 * initial down) or event count for multiple events. 1386 * @param metaState Flags indicating which meta keys are currently pressed. 1387 * @param deviceId The device ID that generated the key event. 1388 * @param scancode Raw device scan code of the event. 1389 */ 1390 public KeyEvent(long downTime, long eventTime, int action, 1391 int code, int repeat, int metaState, 1392 int deviceId, int scancode) { 1393 mDownTime = downTime; 1394 mEventTime = eventTime; 1395 mAction = action; 1396 mKeyCode = code; 1397 mRepeatCount = repeat; 1398 mMetaState = metaState; 1399 mDeviceId = deviceId; 1400 mScanCode = scancode; 1401 } 1402 1403 /** 1404 * Create a new key event. 1405 * 1406 * @param downTime The time (in {@link android.os.SystemClock#uptimeMillis}) 1407 * at which this key code originally went down. 1408 * @param eventTime The time (in {@link android.os.SystemClock#uptimeMillis}) 1409 * at which this event happened. 1410 * @param action Action code: either {@link #ACTION_DOWN}, 1411 * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}. 1412 * @param code The key code. 1413 * @param repeat A repeat count for down events (> 0 if this is after the 1414 * initial down) or event count for multiple events. 1415 * @param metaState Flags indicating which meta keys are currently pressed. 1416 * @param deviceId The device ID that generated the key event. 1417 * @param scancode Raw device scan code of the event. 1418 * @param flags The flags for this key event 1419 */ 1420 public KeyEvent(long downTime, long eventTime, int action, 1421 int code, int repeat, int metaState, 1422 int deviceId, int scancode, int flags) { 1423 mDownTime = downTime; 1424 mEventTime = eventTime; 1425 mAction = action; 1426 mKeyCode = code; 1427 mRepeatCount = repeat; 1428 mMetaState = metaState; 1429 mDeviceId = deviceId; 1430 mScanCode = scancode; 1431 mFlags = flags; 1432 } 1433 1434 /** 1435 * Create a new key event. 1436 * 1437 * @param downTime The time (in {@link android.os.SystemClock#uptimeMillis}) 1438 * at which this key code originally went down. 1439 * @param eventTime The time (in {@link android.os.SystemClock#uptimeMillis}) 1440 * at which this event happened. 1441 * @param action Action code: either {@link #ACTION_DOWN}, 1442 * {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}. 1443 * @param code The key code. 1444 * @param repeat A repeat count for down events (> 0 if this is after the 1445 * initial down) or event count for multiple events. 1446 * @param metaState Flags indicating which meta keys are currently pressed. 1447 * @param deviceId The device ID that generated the key event. 1448 * @param scancode Raw device scan code of the event. 1449 * @param flags The flags for this key event 1450 * @param source The input source such as {@link InputDevice#SOURCE_KEYBOARD}. 1451 */ 1452 public KeyEvent(long downTime, long eventTime, int action, 1453 int code, int repeat, int metaState, 1454 int deviceId, int scancode, int flags, int source) { 1455 mDownTime = downTime; 1456 mEventTime = eventTime; 1457 mAction = action; 1458 mKeyCode = code; 1459 mRepeatCount = repeat; 1460 mMetaState = metaState; 1461 mDeviceId = deviceId; 1462 mScanCode = scancode; 1463 mFlags = flags; 1464 mSource = source; 1465 } 1466 1467 /** 1468 * Create a new key event for a string of characters. The key code, 1469 * action, repeat count and source will automatically be set to 1470 * {@link #KEYCODE_UNKNOWN}, {@link #ACTION_MULTIPLE}, 0, and 1471 * {@link InputDevice#SOURCE_KEYBOARD} for you. 1472 * 1473 * @param time The time (in {@link android.os.SystemClock#uptimeMillis}) 1474 * at which this event occured. 1475 * @param characters The string of characters. 1476 * @param deviceId The device ID that generated the key event. 1477 * @param flags The flags for this key event 1478 */ 1479 public KeyEvent(long time, String characters, int deviceId, int flags) { 1480 mDownTime = time; 1481 mEventTime = time; 1482 mCharacters = characters; 1483 mAction = ACTION_MULTIPLE; 1484 mKeyCode = KEYCODE_UNKNOWN; 1485 mRepeatCount = 0; 1486 mDeviceId = deviceId; 1487 mFlags = flags; 1488 mSource = InputDevice.SOURCE_KEYBOARD; 1489 } 1490 1491 /** 1492 * Make an exact copy of an existing key event. 1493 */ 1494 public KeyEvent(KeyEvent origEvent) { 1495 mDownTime = origEvent.mDownTime; 1496 mEventTime = origEvent.mEventTime; 1497 mAction = origEvent.mAction; 1498 mKeyCode = origEvent.mKeyCode; 1499 mRepeatCount = origEvent.mRepeatCount; 1500 mMetaState = origEvent.mMetaState; 1501 mDeviceId = origEvent.mDeviceId; 1502 mSource = origEvent.mSource; 1503 mScanCode = origEvent.mScanCode; 1504 mFlags = origEvent.mFlags; 1505 mCharacters = origEvent.mCharacters; 1506 } 1507 1508 /** 1509 * Copy an existing key event, modifying its time and repeat count. 1510 * 1511 * @deprecated Use {@link #changeTimeRepeat(KeyEvent, long, int)} 1512 * instead. 1513 * 1514 * @param origEvent The existing event to be copied. 1515 * @param eventTime The new event time 1516 * (in {@link android.os.SystemClock#uptimeMillis}) of the event. 1517 * @param newRepeat The new repeat count of the event. 1518 */ 1519 @Deprecated 1520 public KeyEvent(KeyEvent origEvent, long eventTime, int newRepeat) { 1521 mDownTime = origEvent.mDownTime; 1522 mEventTime = eventTime; 1523 mAction = origEvent.mAction; 1524 mKeyCode = origEvent.mKeyCode; 1525 mRepeatCount = newRepeat; 1526 mMetaState = origEvent.mMetaState; 1527 mDeviceId = origEvent.mDeviceId; 1528 mSource = origEvent.mSource; 1529 mScanCode = origEvent.mScanCode; 1530 mFlags = origEvent.mFlags; 1531 mCharacters = origEvent.mCharacters; 1532 } 1533 1534 private static KeyEvent obtain() { 1535 final KeyEvent ev; 1536 synchronized (gRecyclerLock) { 1537 ev = gRecyclerTop; 1538 if (ev == null) { 1539 return new KeyEvent(); 1540 } 1541 gRecyclerTop = ev.mNext; 1542 gRecyclerUsed -= 1; 1543 } 1544 ev.mNext = null; 1545 ev.prepareForReuse(); 1546 return ev; 1547 } 1548 1549 /** 1550 * Obtains a (potentially recycled) key event. 1551 * 1552 * @hide 1553 */ 1554 public static KeyEvent obtain(long downTime, long eventTime, int action, 1555 int code, int repeat, int metaState, 1556 int deviceId, int scancode, int flags, int source, String characters) { 1557 KeyEvent ev = obtain(); 1558 ev.mDownTime = downTime; 1559 ev.mEventTime = eventTime; 1560 ev.mAction = action; 1561 ev.mKeyCode = code; 1562 ev.mRepeatCount = repeat; 1563 ev.mMetaState = metaState; 1564 ev.mDeviceId = deviceId; 1565 ev.mScanCode = scancode; 1566 ev.mFlags = flags; 1567 ev.mSource = source; 1568 ev.mCharacters = characters; 1569 return ev; 1570 } 1571 1572 /** 1573 * Obtains a (potentially recycled) copy of another key event. 1574 * 1575 * @hide 1576 */ 1577 public static KeyEvent obtain(KeyEvent other) { 1578 KeyEvent ev = obtain(); 1579 ev.mDownTime = other.mDownTime; 1580 ev.mEventTime = other.mEventTime; 1581 ev.mAction = other.mAction; 1582 ev.mKeyCode = other.mKeyCode; 1583 ev.mRepeatCount = other.mRepeatCount; 1584 ev.mMetaState = other.mMetaState; 1585 ev.mDeviceId = other.mDeviceId; 1586 ev.mScanCode = other.mScanCode; 1587 ev.mFlags = other.mFlags; 1588 ev.mSource = other.mSource; 1589 ev.mCharacters = other.mCharacters; 1590 return ev; 1591 } 1592 1593 /** @hide */ 1594 @Override 1595 public KeyEvent copy() { 1596 return obtain(this); 1597 } 1598 1599 /** 1600 * Recycles a key event. 1601 * Key events should only be recycled if they are owned by the system since user 1602 * code expects them to be essentially immutable, "tracking" notwithstanding. 1603 * 1604 * @hide 1605 */ 1606 @Override 1607 public final void recycle() { 1608 super.recycle(); 1609 mCharacters = null; 1610 1611 synchronized (gRecyclerLock) { 1612 if (gRecyclerUsed < MAX_RECYCLED) { 1613 gRecyclerUsed++; 1614 mNext = gRecyclerTop; 1615 gRecyclerTop = this; 1616 } 1617 } 1618 } 1619 1620 /** @hide */ 1621 @Override 1622 public final void recycleIfNeededAfterDispatch() { 1623 // Do nothing. 1624 } 1625 1626 /** 1627 * Create a new key event that is the same as the given one, but whose 1628 * event time and repeat count are replaced with the given value. 1629 * 1630 * @param event The existing event to be copied. This is not modified. 1631 * @param eventTime The new event time 1632 * (in {@link android.os.SystemClock#uptimeMillis}) of the event. 1633 * @param newRepeat The new repeat count of the event. 1634 */ 1635 public static KeyEvent changeTimeRepeat(KeyEvent event, long eventTime, 1636 int newRepeat) { 1637 return new KeyEvent(event, eventTime, newRepeat); 1638 } 1639 1640 /** 1641 * Create a new key event that is the same as the given one, but whose 1642 * event time and repeat count are replaced with the given value. 1643 * 1644 * @param event The existing event to be copied. This is not modified. 1645 * @param eventTime The new event time 1646 * (in {@link android.os.SystemClock#uptimeMillis}) of the event. 1647 * @param newRepeat The new repeat count of the event. 1648 * @param newFlags New flags for the event, replacing the entire value 1649 * in the original event. 1650 */ 1651 public static KeyEvent changeTimeRepeat(KeyEvent event, long eventTime, 1652 int newRepeat, int newFlags) { 1653 KeyEvent ret = new KeyEvent(event); 1654 ret.mEventTime = eventTime; 1655 ret.mRepeatCount = newRepeat; 1656 ret.mFlags = newFlags; 1657 return ret; 1658 } 1659 1660 /** 1661 * Copy an existing key event, modifying its action. 1662 * 1663 * @param origEvent The existing event to be copied. 1664 * @param action The new action code of the event. 1665 */ 1666 private KeyEvent(KeyEvent origEvent, int action) { 1667 mDownTime = origEvent.mDownTime; 1668 mEventTime = origEvent.mEventTime; 1669 mAction = action; 1670 mKeyCode = origEvent.mKeyCode; 1671 mRepeatCount = origEvent.mRepeatCount; 1672 mMetaState = origEvent.mMetaState; 1673 mDeviceId = origEvent.mDeviceId; 1674 mSource = origEvent.mSource; 1675 mScanCode = origEvent.mScanCode; 1676 mFlags = origEvent.mFlags; 1677 // Don't copy mCharacters, since one way or the other we'll lose it 1678 // when changing the action. 1679 } 1680 1681 /** 1682 * Create a new key event that is the same as the given one, but whose 1683 * action is replaced with the given value. 1684 * 1685 * @param event The existing event to be copied. This is not modified. 1686 * @param action The new action code of the event. 1687 */ 1688 public static KeyEvent changeAction(KeyEvent event, int action) { 1689 return new KeyEvent(event, action); 1690 } 1691 1692 /** 1693 * Create a new key event that is the same as the given one, but whose 1694 * flags are replaced with the given value. 1695 * 1696 * @param event The existing event to be copied. This is not modified. 1697 * @param flags The new flags constant. 1698 */ 1699 public static KeyEvent changeFlags(KeyEvent event, int flags) { 1700 event = new KeyEvent(event); 1701 event.mFlags = flags; 1702 return event; 1703 } 1704 1705 /** @hide */ 1706 @Override 1707 public final boolean isTainted() { 1708 return (mFlags & FLAG_TAINTED) != 0; 1709 } 1710 1711 /** @hide */ 1712 @Override 1713 public final void setTainted(boolean tainted) { 1714 mFlags = tainted ? mFlags | FLAG_TAINTED : mFlags & ~FLAG_TAINTED; 1715 } 1716 1717 /** 1718 * Don't use in new code, instead explicitly check 1719 * {@link #getAction()}. 1720 * 1721 * @return If the action is ACTION_DOWN, returns true; else false. 1722 * 1723 * @deprecated 1724 * @hide 1725 */ 1726 @Deprecated public final boolean isDown() { 1727 return mAction == ACTION_DOWN; 1728 } 1729 1730 /** Is this a system key? System keys can not be used for menu shortcuts. 1731 */ 1732 public final boolean isSystem() { 1733 return isSystemKey(mKeyCode); 1734 } 1735 1736 /** @hide */ 1737 public final boolean isWakeKey() { 1738 return isWakeKey(mKeyCode); 1739 } 1740 1741 /** 1742 * Returns true if the specified keycode is a gamepad button. 1743 * @return True if the keycode is a gamepad button, such as {@link #KEYCODE_BUTTON_A}. 1744 */ 1745 public static final boolean isGamepadButton(int keyCode) { 1746 switch (keyCode) { 1747 case KeyEvent.KEYCODE_BUTTON_A: 1748 case KeyEvent.KEYCODE_BUTTON_B: 1749 case KeyEvent.KEYCODE_BUTTON_C: 1750 case KeyEvent.KEYCODE_BUTTON_X: 1751 case KeyEvent.KEYCODE_BUTTON_Y: 1752 case KeyEvent.KEYCODE_BUTTON_Z: 1753 case KeyEvent.KEYCODE_BUTTON_L1: 1754 case KeyEvent.KEYCODE_BUTTON_R1: 1755 case KeyEvent.KEYCODE_BUTTON_L2: 1756 case KeyEvent.KEYCODE_BUTTON_R2: 1757 case KeyEvent.KEYCODE_BUTTON_THUMBL: 1758 case KeyEvent.KEYCODE_BUTTON_THUMBR: 1759 case KeyEvent.KEYCODE_BUTTON_START: 1760 case KeyEvent.KEYCODE_BUTTON_SELECT: 1761 case KeyEvent.KEYCODE_BUTTON_MODE: 1762 case KeyEvent.KEYCODE_BUTTON_1: 1763 case KeyEvent.KEYCODE_BUTTON_2: 1764 case KeyEvent.KEYCODE_BUTTON_3: 1765 case KeyEvent.KEYCODE_BUTTON_4: 1766 case KeyEvent.KEYCODE_BUTTON_5: 1767 case KeyEvent.KEYCODE_BUTTON_6: 1768 case KeyEvent.KEYCODE_BUTTON_7: 1769 case KeyEvent.KEYCODE_BUTTON_8: 1770 case KeyEvent.KEYCODE_BUTTON_9: 1771 case KeyEvent.KEYCODE_BUTTON_10: 1772 case KeyEvent.KEYCODE_BUTTON_11: 1773 case KeyEvent.KEYCODE_BUTTON_12: 1774 case KeyEvent.KEYCODE_BUTTON_13: 1775 case KeyEvent.KEYCODE_BUTTON_14: 1776 case KeyEvent.KEYCODE_BUTTON_15: 1777 case KeyEvent.KEYCODE_BUTTON_16: 1778 return true; 1779 default: 1780 return false; 1781 } 1782 } 1783 1784 /** Whether key will, by default, trigger a click on the focused view. 1785 * @hide 1786 */ 1787 public static final boolean isConfirmKey(int keyCode) { 1788 switch (keyCode) { 1789 case KeyEvent.KEYCODE_DPAD_CENTER: 1790 case KeyEvent.KEYCODE_ENTER: 1791 case KeyEvent.KEYCODE_SPACE: 1792 case KeyEvent.KEYCODE_NUMPAD_ENTER: 1793 return true; 1794 default: 1795 return false; 1796 } 1797 } 1798 1799 /** 1800 * Whether this key is a media key, which can be send to apps that are 1801 * interested in media key events. 1802 * 1803 * @hide 1804 */ 1805 public static final boolean isMediaKey(int keyCode) { 1806 switch (keyCode) { 1807 case KeyEvent.KEYCODE_MEDIA_PLAY: 1808 case KeyEvent.KEYCODE_MEDIA_PAUSE: 1809 case KeyEvent.KEYCODE_MEDIA_PLAY_PAUSE: 1810 case KeyEvent.KEYCODE_MUTE: 1811 case KeyEvent.KEYCODE_HEADSETHOOK: 1812 case KeyEvent.KEYCODE_MEDIA_STOP: 1813 case KeyEvent.KEYCODE_MEDIA_NEXT: 1814 case KeyEvent.KEYCODE_MEDIA_PREVIOUS: 1815 case KeyEvent.KEYCODE_MEDIA_REWIND: 1816 case KeyEvent.KEYCODE_MEDIA_RECORD: 1817 case KeyEvent.KEYCODE_MEDIA_FAST_FORWARD: 1818 return true; 1819 } 1820 return false; 1821 } 1822 1823 1824 /** Is this a system key? System keys can not be used for menu shortcuts. 1825 * @hide 1826 */ 1827 public static final boolean isSystemKey(int keyCode) { 1828 switch (keyCode) { 1829 case KeyEvent.KEYCODE_MENU: 1830 case KeyEvent.KEYCODE_SOFT_RIGHT: 1831 case KeyEvent.KEYCODE_HOME: 1832 case KeyEvent.KEYCODE_BACK: 1833 case KeyEvent.KEYCODE_CALL: 1834 case KeyEvent.KEYCODE_ENDCALL: 1835 case KeyEvent.KEYCODE_VOLUME_UP: 1836 case KeyEvent.KEYCODE_VOLUME_DOWN: 1837 case KeyEvent.KEYCODE_VOLUME_MUTE: 1838 case KeyEvent.KEYCODE_MUTE: 1839 case KeyEvent.KEYCODE_POWER: 1840 case KeyEvent.KEYCODE_HEADSETHOOK: 1841 case KeyEvent.KEYCODE_MEDIA_PLAY: 1842 case KeyEvent.KEYCODE_MEDIA_PAUSE: 1843 case KeyEvent.KEYCODE_MEDIA_PLAY_PAUSE: 1844 case KeyEvent.KEYCODE_MEDIA_STOP: 1845 case KeyEvent.KEYCODE_MEDIA_NEXT: 1846 case KeyEvent.KEYCODE_MEDIA_PREVIOUS: 1847 case KeyEvent.KEYCODE_MEDIA_REWIND: 1848 case KeyEvent.KEYCODE_MEDIA_RECORD: 1849 case KeyEvent.KEYCODE_MEDIA_FAST_FORWARD: 1850 case KeyEvent.KEYCODE_CAMERA: 1851 case KeyEvent.KEYCODE_FOCUS: 1852 case KeyEvent.KEYCODE_SEARCH: 1853 case KeyEvent.KEYCODE_BRIGHTNESS_DOWN: 1854 case KeyEvent.KEYCODE_BRIGHTNESS_UP: 1855 case KeyEvent.KEYCODE_MEDIA_AUDIO_TRACK: 1856 case KeyEvent.KEYCODE_SYSTEM_NAVIGATION_UP: 1857 case KeyEvent.KEYCODE_SYSTEM_NAVIGATION_DOWN: 1858 case KeyEvent.KEYCODE_SYSTEM_NAVIGATION_LEFT: 1859 case KeyEvent.KEYCODE_SYSTEM_NAVIGATION_RIGHT: 1860 return true; 1861 } 1862 1863 return false; 1864 } 1865 1866 /** @hide */ 1867 public static final boolean isWakeKey(int keyCode) { 1868 switch (keyCode) { 1869 case KeyEvent.KEYCODE_BACK: 1870 case KeyEvent.KEYCODE_MENU: 1871 case KeyEvent.KEYCODE_WAKEUP: 1872 case KeyEvent.KEYCODE_PAIRING: 1873 case KeyEvent.KEYCODE_STEM_1: 1874 case KeyEvent.KEYCODE_STEM_2: 1875 case KeyEvent.KEYCODE_STEM_3: 1876 return true; 1877 } 1878 return false; 1879 } 1880 1881 /** @hide */ 1882 public static final boolean isMetaKey(int keyCode) { 1883 return keyCode == KeyEvent.KEYCODE_META_LEFT || keyCode == KeyEvent.KEYCODE_META_RIGHT; 1884 } 1885 1886 /** @hide */ 1887 public static final boolean isAltKey(int keyCode) { 1888 return keyCode == KeyEvent.KEYCODE_ALT_LEFT || keyCode == KeyEvent.KEYCODE_ALT_RIGHT; 1889 } 1890 1891 /** {@inheritDoc} */ 1892 @Override 1893 public final int getDeviceId() { 1894 return mDeviceId; 1895 } 1896 1897 /** {@inheritDoc} */ 1898 @Override 1899 public final int getSource() { 1900 return mSource; 1901 } 1902 1903 /** {@inheritDoc} */ 1904 @Override 1905 public final void setSource(int source) { 1906 mSource = source; 1907 } 1908 1909 /** 1910 * <p>Returns the state of the meta keys.</p> 1911 * 1912 * @return an integer in which each bit set to 1 represents a pressed 1913 * meta key 1914 * 1915 * @see #isAltPressed() 1916 * @see #isShiftPressed() 1917 * @see #isSymPressed() 1918 * @see #isCtrlPressed() 1919 * @see #isMetaPressed() 1920 * @see #isFunctionPressed() 1921 * @see #isCapsLockOn() 1922 * @see #isNumLockOn() 1923 * @see #isScrollLockOn() 1924 * @see #META_ALT_ON 1925 * @see #META_ALT_LEFT_ON 1926 * @see #META_ALT_RIGHT_ON 1927 * @see #META_SHIFT_ON 1928 * @see #META_SHIFT_LEFT_ON 1929 * @see #META_SHIFT_RIGHT_ON 1930 * @see #META_SYM_ON 1931 * @see #META_FUNCTION_ON 1932 * @see #META_CTRL_ON 1933 * @see #META_CTRL_LEFT_ON 1934 * @see #META_CTRL_RIGHT_ON 1935 * @see #META_META_ON 1936 * @see #META_META_LEFT_ON 1937 * @see #META_META_RIGHT_ON 1938 * @see #META_CAPS_LOCK_ON 1939 * @see #META_NUM_LOCK_ON 1940 * @see #META_SCROLL_LOCK_ON 1941 * @see #getModifiers 1942 */ 1943 public final int getMetaState() { 1944 return mMetaState; 1945 } 1946 1947 /** 1948 * Returns the state of the modifier keys. 1949 * <p> 1950 * For the purposes of this function, {@link #KEYCODE_CAPS_LOCK}, 1951 * {@link #KEYCODE_SCROLL_LOCK}, and {@link #KEYCODE_NUM_LOCK} are 1952 * not considered modifier keys. Consequently, this function specifically masks out 1953 * {@link #META_CAPS_LOCK_ON}, {@link #META_SCROLL_LOCK_ON} and {@link #META_NUM_LOCK_ON}. 1954 * </p><p> 1955 * The value returned consists of the meta state (from {@link #getMetaState}) 1956 * normalized using {@link #normalizeMetaState(int)} and then masked with 1957 * {@link #getModifierMetaStateMask} so that only valid modifier bits are retained. 1958 * </p> 1959 * 1960 * @return An integer in which each bit set to 1 represents a pressed modifier key. 1961 * @see #getMetaState 1962 */ 1963 public final int getModifiers() { 1964 return normalizeMetaState(mMetaState) & META_MODIFIER_MASK; 1965 } 1966 1967 /** 1968 * Returns the flags for this key event. 1969 * 1970 * @see #FLAG_WOKE_HERE 1971 */ 1972 public final int getFlags() { 1973 return mFlags; 1974 } 1975 1976 // Mask of all modifier key meta states. Specifically excludes locked keys like caps lock. 1977 private static final int META_MODIFIER_MASK = 1978 META_SHIFT_ON | META_SHIFT_LEFT_ON | META_SHIFT_RIGHT_ON 1979 | META_ALT_ON | META_ALT_LEFT_ON | META_ALT_RIGHT_ON 1980 | META_CTRL_ON | META_CTRL_LEFT_ON | META_CTRL_RIGHT_ON 1981 | META_META_ON | META_META_LEFT_ON | META_META_RIGHT_ON 1982 | META_SYM_ON | META_FUNCTION_ON; 1983 1984 // Mask of all lock key meta states. 1985 private static final int META_LOCK_MASK = 1986 META_CAPS_LOCK_ON | META_NUM_LOCK_ON | META_SCROLL_LOCK_ON; 1987 1988 // Mask of all valid meta states. 1989 private static final int META_ALL_MASK = META_MODIFIER_MASK | META_LOCK_MASK; 1990 1991 // Mask of all synthetic meta states that are reserved for API compatibility with 1992 // historical uses in MetaKeyKeyListener. 1993 private static final int META_SYNTHETIC_MASK = 1994 META_CAP_LOCKED | META_ALT_LOCKED | META_SYM_LOCKED | META_SELECTING; 1995 1996 // Mask of all meta states that are not valid use in specifying a modifier key. 1997 // These bits are known to be used for purposes other than specifying modifiers. 1998 private static final int META_INVALID_MODIFIER_MASK = 1999 META_LOCK_MASK | META_SYNTHETIC_MASK; 2000 2001 /** 2002 * Gets a mask that includes all valid modifier key meta state bits. 2003 * <p> 2004 * For the purposes of this function, {@link #KEYCODE_CAPS_LOCK}, 2005 * {@link #KEYCODE_SCROLL_LOCK}, and {@link #KEYCODE_NUM_LOCK} are 2006 * not considered modifier keys. Consequently, the mask specifically excludes 2007 * {@link #META_CAPS_LOCK_ON}, {@link #META_SCROLL_LOCK_ON} and {@link #META_NUM_LOCK_ON}. 2008 * </p> 2009 * 2010 * @return The modifier meta state mask which is a combination of 2011 * {@link #META_SHIFT_ON}, {@link #META_SHIFT_LEFT_ON}, {@link #META_SHIFT_RIGHT_ON}, 2012 * {@link #META_ALT_ON}, {@link #META_ALT_LEFT_ON}, {@link #META_ALT_RIGHT_ON}, 2013 * {@link #META_CTRL_ON}, {@link #META_CTRL_LEFT_ON}, {@link #META_CTRL_RIGHT_ON}, 2014 * {@link #META_META_ON}, {@link #META_META_LEFT_ON}, {@link #META_META_RIGHT_ON}, 2015 * {@link #META_SYM_ON}, {@link #META_FUNCTION_ON}. 2016 */ 2017 public static int getModifierMetaStateMask() { 2018 return META_MODIFIER_MASK; 2019 } 2020 2021 /** 2022 * Returns true if this key code is a modifier key. 2023 * <p> 2024 * For the purposes of this function, {@link #KEYCODE_CAPS_LOCK}, 2025 * {@link #KEYCODE_SCROLL_LOCK}, and {@link #KEYCODE_NUM_LOCK} are 2026 * not considered modifier keys. Consequently, this function return false 2027 * for those keys. 2028 * </p> 2029 * 2030 * @return True if the key code is one of 2031 * {@link #KEYCODE_SHIFT_LEFT} {@link #KEYCODE_SHIFT_RIGHT}, 2032 * {@link #KEYCODE_ALT_LEFT}, {@link #KEYCODE_ALT_RIGHT}, 2033 * {@link #KEYCODE_CTRL_LEFT}, {@link #KEYCODE_CTRL_RIGHT}, 2034 * {@link #KEYCODE_META_LEFT}, or {@link #KEYCODE_META_RIGHT}, 2035 * {@link #KEYCODE_SYM}, {@link #KEYCODE_NUM}, {@link #KEYCODE_FUNCTION}. 2036 */ 2037 public static boolean isModifierKey(int keyCode) { 2038 switch (keyCode) { 2039 case KEYCODE_SHIFT_LEFT: 2040 case KEYCODE_SHIFT_RIGHT: 2041 case KEYCODE_ALT_LEFT: 2042 case KEYCODE_ALT_RIGHT: 2043 case KEYCODE_CTRL_LEFT: 2044 case KEYCODE_CTRL_RIGHT: 2045 case KEYCODE_META_LEFT: 2046 case KEYCODE_META_RIGHT: 2047 case KEYCODE_SYM: 2048 case KEYCODE_NUM: 2049 case KEYCODE_FUNCTION: 2050 return true; 2051 default: 2052 return false; 2053 } 2054 } 2055 2056 /** 2057 * Normalizes the specified meta state. 2058 * <p> 2059 * The meta state is normalized such that if either the left or right modifier meta state 2060 * bits are set then the result will also include the universal bit for that modifier. 2061 * </p><p> 2062 * If the specified meta state contains {@link #META_ALT_LEFT_ON} then 2063 * the result will also contain {@link #META_ALT_ON} in addition to {@link #META_ALT_LEFT_ON} 2064 * and the other bits that were specified in the input. The same is process is 2065 * performed for shift, control and meta. 2066 * </p><p> 2067 * If the specified meta state contains synthetic meta states defined by 2068 * {@link MetaKeyKeyListener}, then those states are translated here and the original 2069 * synthetic meta states are removed from the result. 2070 * {@link MetaKeyKeyListener#META_CAP_LOCKED} is translated to {@link #META_CAPS_LOCK_ON}. 2071 * {@link MetaKeyKeyListener#META_ALT_LOCKED} is translated to {@link #META_ALT_ON}. 2072 * {@link MetaKeyKeyListener#META_SYM_LOCKED} is translated to {@link #META_SYM_ON}. 2073 * </p><p> 2074 * Undefined meta state bits are removed. 2075 * </p> 2076 * 2077 * @param metaState The meta state. 2078 * @return The normalized meta state. 2079 */ 2080 public static int normalizeMetaState(int metaState) { 2081 if ((metaState & (META_SHIFT_LEFT_ON | META_SHIFT_RIGHT_ON)) != 0) { 2082 metaState |= META_SHIFT_ON; 2083 } 2084 if ((metaState & (META_ALT_LEFT_ON | META_ALT_RIGHT_ON)) != 0) { 2085 metaState |= META_ALT_ON; 2086 } 2087 if ((metaState & (META_CTRL_LEFT_ON | META_CTRL_RIGHT_ON)) != 0) { 2088 metaState |= META_CTRL_ON; 2089 } 2090 if ((metaState & (META_META_LEFT_ON | META_META_RIGHT_ON)) != 0) { 2091 metaState |= META_META_ON; 2092 } 2093 if ((metaState & MetaKeyKeyListener.META_CAP_LOCKED) != 0) { 2094 metaState |= META_CAPS_LOCK_ON; 2095 } 2096 if ((metaState & MetaKeyKeyListener.META_ALT_LOCKED) != 0) { 2097 metaState |= META_ALT_ON; 2098 } 2099 if ((metaState & MetaKeyKeyListener.META_SYM_LOCKED) != 0) { 2100 metaState |= META_SYM_ON; 2101 } 2102 return metaState & META_ALL_MASK; 2103 } 2104 2105 /** 2106 * Returns true if no modifiers keys are pressed according to the specified meta state. 2107 * <p> 2108 * For the purposes of this function, {@link #KEYCODE_CAPS_LOCK}, 2109 * {@link #KEYCODE_SCROLL_LOCK}, and {@link #KEYCODE_NUM_LOCK} are 2110 * not considered modifier keys. Consequently, this function ignores 2111 * {@link #META_CAPS_LOCK_ON}, {@link #META_SCROLL_LOCK_ON} and {@link #META_NUM_LOCK_ON}. 2112 * </p><p> 2113 * The meta state is normalized prior to comparison using {@link #normalizeMetaState(int)}. 2114 * </p> 2115 * 2116 * @param metaState The meta state to consider. 2117 * @return True if no modifier keys are pressed. 2118 * @see #hasNoModifiers() 2119 */ 2120 public static boolean metaStateHasNoModifiers(int metaState) { 2121 return (normalizeMetaState(metaState) & META_MODIFIER_MASK) == 0; 2122 } 2123 2124 /** 2125 * Returns true if only the specified modifier keys are pressed according to 2126 * the specified meta state. Returns false if a different combination of modifier 2127 * keys are pressed. 2128 * <p> 2129 * For the purposes of this function, {@link #KEYCODE_CAPS_LOCK}, 2130 * {@link #KEYCODE_SCROLL_LOCK}, and {@link #KEYCODE_NUM_LOCK} are 2131 * not considered modifier keys. Consequently, this function ignores 2132 * {@link #META_CAPS_LOCK_ON}, {@link #META_SCROLL_LOCK_ON} and {@link #META_NUM_LOCK_ON}. 2133 * </p><p> 2134 * If the specified modifier mask includes directional modifiers, such as 2135 * {@link #META_SHIFT_LEFT_ON}, then this method ensures that the 2136 * modifier is pressed on that side. 2137 * If the specified modifier mask includes non-directional modifiers, such as 2138 * {@link #META_SHIFT_ON}, then this method ensures that the modifier 2139 * is pressed on either side. 2140 * If the specified modifier mask includes both directional and non-directional modifiers 2141 * for the same type of key, such as {@link #META_SHIFT_ON} and {@link #META_SHIFT_LEFT_ON}, 2142 * then this method throws an illegal argument exception. 2143 * </p> 2144 * 2145 * @param metaState The meta state to consider. 2146 * @param modifiers The meta state of the modifier keys to check. May be a combination 2147 * of modifier meta states as defined by {@link #getModifierMetaStateMask()}. May be 0 to 2148 * ensure that no modifier keys are pressed. 2149 * @return True if only the specified modifier keys are pressed. 2150 * @throws IllegalArgumentException if the modifiers parameter contains invalid modifiers 2151 * @see #hasModifiers 2152 */ 2153 public static boolean metaStateHasModifiers(int metaState, int modifiers) { 2154 // Note: For forward compatibility, we allow the parameter to contain meta states 2155 // that we do not recognize but we explicitly disallow meta states that 2156 // are not valid modifiers. 2157 if ((modifiers & META_INVALID_MODIFIER_MASK) != 0) { 2158 throw new IllegalArgumentException("modifiers must not contain " 2159 + "META_CAPS_LOCK_ON, META_NUM_LOCK_ON, META_SCROLL_LOCK_ON, " 2160 + "META_CAP_LOCKED, META_ALT_LOCKED, META_SYM_LOCKED, " 2161 + "or META_SELECTING"); 2162 } 2163 2164 metaState = normalizeMetaState(metaState) & META_MODIFIER_MASK; 2165 metaState = metaStateFilterDirectionalModifiers(metaState, modifiers, 2166 META_SHIFT_ON, META_SHIFT_LEFT_ON, META_SHIFT_RIGHT_ON); 2167 metaState = metaStateFilterDirectionalModifiers(metaState, modifiers, 2168 META_ALT_ON, META_ALT_LEFT_ON, META_ALT_RIGHT_ON); 2169 metaState = metaStateFilterDirectionalModifiers(metaState, modifiers, 2170 META_CTRL_ON, META_CTRL_LEFT_ON, META_CTRL_RIGHT_ON); 2171 metaState = metaStateFilterDirectionalModifiers(metaState, modifiers, 2172 META_META_ON, META_META_LEFT_ON, META_META_RIGHT_ON); 2173 return metaState == modifiers; 2174 } 2175 2176 private static int metaStateFilterDirectionalModifiers(int metaState, 2177 int modifiers, int basic, int left, int right) { 2178 final boolean wantBasic = (modifiers & basic) != 0; 2179 final int directional = left | right; 2180 final boolean wantLeftOrRight = (modifiers & directional) != 0; 2181 2182 if (wantBasic) { 2183 if (wantLeftOrRight) { 2184 throw new IllegalArgumentException("modifiers must not contain " 2185 + metaStateToString(basic) + " combined with " 2186 + metaStateToString(left) + " or " + metaStateToString(right)); 2187 } 2188 return metaState & ~directional; 2189 } else if (wantLeftOrRight) { 2190 return metaState & ~basic; 2191 } else { 2192 return metaState; 2193 } 2194 } 2195 2196 /** 2197 * Returns true if no modifier keys are pressed. 2198 * <p> 2199 * For the purposes of this function, {@link #KEYCODE_CAPS_LOCK}, 2200 * {@link #KEYCODE_SCROLL_LOCK}, and {@link #KEYCODE_NUM_LOCK} are 2201 * not considered modifier keys. Consequently, this function ignores 2202 * {@link #META_CAPS_LOCK_ON}, {@link #META_SCROLL_LOCK_ON} and {@link #META_NUM_LOCK_ON}. 2203 * </p><p> 2204 * The meta state is normalized prior to comparison using {@link #normalizeMetaState(int)}. 2205 * </p> 2206 * 2207 * @return True if no modifier keys are pressed. 2208 * @see #metaStateHasNoModifiers 2209 */ 2210 public final boolean hasNoModifiers() { 2211 return metaStateHasNoModifiers(mMetaState); 2212 } 2213 2214 /** 2215 * Returns true if only the specified modifiers keys are pressed. 2216 * Returns false if a different combination of modifier keys are pressed. 2217 * <p> 2218 * For the purposes of this function, {@link #KEYCODE_CAPS_LOCK}, 2219 * {@link #KEYCODE_SCROLL_LOCK}, and {@link #KEYCODE_NUM_LOCK} are 2220 * not considered modifier keys. Consequently, this function ignores 2221 * {@link #META_CAPS_LOCK_ON}, {@link #META_SCROLL_LOCK_ON} and {@link #META_NUM_LOCK_ON}. 2222 * </p><p> 2223 * If the specified modifier mask includes directional modifiers, such as 2224 * {@link #META_SHIFT_LEFT_ON}, then this method ensures that the 2225 * modifier is pressed on that side. 2226 * If the specified modifier mask includes non-directional modifiers, such as 2227 * {@link #META_SHIFT_ON}, then this method ensures that the modifier 2228 * is pressed on either side. 2229 * If the specified modifier mask includes both directional and non-directional modifiers 2230 * for the same type of key, such as {@link #META_SHIFT_ON} and {@link #META_SHIFT_LEFT_ON}, 2231 * then this method throws an illegal argument exception. 2232 * </p> 2233 * 2234 * @param modifiers The meta state of the modifier keys to check. May be a combination 2235 * of modifier meta states as defined by {@link #getModifierMetaStateMask()}. May be 0 to 2236 * ensure that no modifier keys are pressed. 2237 * @return True if only the specified modifier keys are pressed. 2238 * @throws IllegalArgumentException if the modifiers parameter contains invalid modifiers 2239 * @see #metaStateHasModifiers 2240 */ 2241 public final boolean hasModifiers(int modifiers) { 2242 return metaStateHasModifiers(mMetaState, modifiers); 2243 } 2244 2245 /** 2246 * <p>Returns the pressed state of the ALT meta key.</p> 2247 * 2248 * @return true if the ALT key is pressed, false otherwise 2249 * 2250 * @see #KEYCODE_ALT_LEFT 2251 * @see #KEYCODE_ALT_RIGHT 2252 * @see #META_ALT_ON 2253 */ 2254 public final boolean isAltPressed() { 2255 return (mMetaState & META_ALT_ON) != 0; 2256 } 2257 2258 /** 2259 * <p>Returns the pressed state of the SHIFT meta key.</p> 2260 * 2261 * @return true if the SHIFT key is pressed, false otherwise 2262 * 2263 * @see #KEYCODE_SHIFT_LEFT 2264 * @see #KEYCODE_SHIFT_RIGHT 2265 * @see #META_SHIFT_ON 2266 */ 2267 public final boolean isShiftPressed() { 2268 return (mMetaState & META_SHIFT_ON) != 0; 2269 } 2270 2271 /** 2272 * <p>Returns the pressed state of the SYM meta key.</p> 2273 * 2274 * @return true if the SYM key is pressed, false otherwise 2275 * 2276 * @see #KEYCODE_SYM 2277 * @see #META_SYM_ON 2278 */ 2279 public final boolean isSymPressed() { 2280 return (mMetaState & META_SYM_ON) != 0; 2281 } 2282 2283 /** 2284 * <p>Returns the pressed state of the CTRL meta key.</p> 2285 * 2286 * @return true if the CTRL key is pressed, false otherwise 2287 * 2288 * @see #KEYCODE_CTRL_LEFT 2289 * @see #KEYCODE_CTRL_RIGHT 2290 * @see #META_CTRL_ON 2291 */ 2292 public final boolean isCtrlPressed() { 2293 return (mMetaState & META_CTRL_ON) != 0; 2294 } 2295 2296 /** 2297 * <p>Returns the pressed state of the META meta key.</p> 2298 * 2299 * @return true if the META key is pressed, false otherwise 2300 * 2301 * @see #KEYCODE_META_LEFT 2302 * @see #KEYCODE_META_RIGHT 2303 * @see #META_META_ON 2304 */ 2305 public final boolean isMetaPressed() { 2306 return (mMetaState & META_META_ON) != 0; 2307 } 2308 2309 /** 2310 * <p>Returns the pressed state of the FUNCTION meta key.</p> 2311 * 2312 * @return true if the FUNCTION key is pressed, false otherwise 2313 * 2314 * @see #KEYCODE_FUNCTION 2315 * @see #META_FUNCTION_ON 2316 */ 2317 public final boolean isFunctionPressed() { 2318 return (mMetaState & META_FUNCTION_ON) != 0; 2319 } 2320 2321 /** 2322 * <p>Returns the locked state of the CAPS LOCK meta key.</p> 2323 * 2324 * @return true if the CAPS LOCK key is on, false otherwise 2325 * 2326 * @see #KEYCODE_CAPS_LOCK 2327 * @see #META_CAPS_LOCK_ON 2328 */ 2329 public final boolean isCapsLockOn() { 2330 return (mMetaState & META_CAPS_LOCK_ON) != 0; 2331 } 2332 2333 /** 2334 * <p>Returns the locked state of the NUM LOCK meta key.</p> 2335 * 2336 * @return true if the NUM LOCK key is on, false otherwise 2337 * 2338 * @see #KEYCODE_NUM_LOCK 2339 * @see #META_NUM_LOCK_ON 2340 */ 2341 public final boolean isNumLockOn() { 2342 return (mMetaState & META_NUM_LOCK_ON) != 0; 2343 } 2344 2345 /** 2346 * <p>Returns the locked state of the SCROLL LOCK meta key.</p> 2347 * 2348 * @return true if the SCROLL LOCK key is on, false otherwise 2349 * 2350 * @see #KEYCODE_SCROLL_LOCK 2351 * @see #META_SCROLL_LOCK_ON 2352 */ 2353 public final boolean isScrollLockOn() { 2354 return (mMetaState & META_SCROLL_LOCK_ON) != 0; 2355 } 2356 2357 /** 2358 * Retrieve the action of this key event. May be either 2359 * {@link #ACTION_DOWN}, {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}. 2360 * 2361 * @return The event action: ACTION_DOWN, ACTION_UP, or ACTION_MULTIPLE. 2362 */ 2363 public final int getAction() { 2364 return mAction; 2365 } 2366 2367 /** 2368 * For {@link #ACTION_UP} events, indicates that the event has been 2369 * canceled as per {@link #FLAG_CANCELED}. 2370 */ 2371 public final boolean isCanceled() { 2372 return (mFlags&FLAG_CANCELED) != 0; 2373 } 2374 2375 /** 2376 * Set {@link #FLAG_CANCELED} flag for the key event. 2377 * 2378 * @hide 2379 */ 2380 @Override 2381 public final void cancel() { 2382 mFlags |= FLAG_CANCELED; 2383 } 2384 2385 /** 2386 * Call this during {@link Callback#onKeyDown} to have the system track 2387 * the key through its final up (possibly including a long press). Note 2388 * that only one key can be tracked at a time -- if another key down 2389 * event is received while a previous one is being tracked, tracking is 2390 * stopped on the previous event. 2391 */ 2392 public final void startTracking() { 2393 mFlags |= FLAG_START_TRACKING; 2394 } 2395 2396 /** 2397 * For {@link #ACTION_UP} events, indicates that the event is still being 2398 * tracked from its initial down event as per 2399 * {@link #FLAG_TRACKING}. 2400 */ 2401 public final boolean isTracking() { 2402 return (mFlags&FLAG_TRACKING) != 0; 2403 } 2404 2405 /** 2406 * For {@link #ACTION_DOWN} events, indicates that the event has been 2407 * canceled as per {@link #FLAG_LONG_PRESS}. 2408 */ 2409 public final boolean isLongPress() { 2410 return (mFlags&FLAG_LONG_PRESS) != 0; 2411 } 2412 2413 /** 2414 * Retrieve the key code of the key event. This is the physical key that 2415 * was pressed, <em>not</em> the Unicode character. 2416 * 2417 * @return The key code of the event. 2418 */ 2419 public final int getKeyCode() { 2420 return mKeyCode; 2421 } 2422 2423 /** 2424 * For the special case of a {@link #ACTION_MULTIPLE} event with key 2425 * code of {@link #KEYCODE_UNKNOWN}, this is a raw string of characters 2426 * associated with the event. In all other cases it is null. 2427 * 2428 * @return Returns a String of 1 or more characters associated with 2429 * the event. 2430 */ 2431 public final String getCharacters() { 2432 return mCharacters; 2433 } 2434 2435 /** 2436 * Retrieve the hardware key id of this key event. These values are not 2437 * reliable and vary from device to device. 2438 * 2439 * {@more} 2440 * Mostly this is here for debugging purposes. 2441 */ 2442 public final int getScanCode() { 2443 return mScanCode; 2444 } 2445 2446 /** 2447 * Retrieve the repeat count of the event. For both key up and key down 2448 * events, this is the number of times the key has repeated with the first 2449 * down starting at 0 and counting up from there. For multiple key 2450 * events, this is the number of down/up pairs that have occurred. 2451 * 2452 * @return The number of times the key has repeated. 2453 */ 2454 public final int getRepeatCount() { 2455 return mRepeatCount; 2456 } 2457 2458 /** 2459 * Retrieve the time of the most recent key down event, 2460 * in the {@link android.os.SystemClock#uptimeMillis} time base. If this 2461 * is a down event, this will be the same as {@link #getEventTime()}. 2462 * Note that when chording keys, this value is the down time of the 2463 * most recently pressed key, which may <em>not</em> be the same physical 2464 * key of this event. 2465 * 2466 * @return Returns the most recent key down time, in the 2467 * {@link android.os.SystemClock#uptimeMillis} time base 2468 */ 2469 public final long getDownTime() { 2470 return mDownTime; 2471 } 2472 2473 /** 2474 * Retrieve the time this event occurred, 2475 * in the {@link android.os.SystemClock#uptimeMillis} time base. 2476 * 2477 * @return Returns the time this event occurred, 2478 * in the {@link android.os.SystemClock#uptimeMillis} time base. 2479 */ 2480 @Override 2481 public final long getEventTime() { 2482 return mEventTime; 2483 } 2484 2485 /** 2486 * Retrieve the time this event occurred, 2487 * in the {@link android.os.SystemClock#uptimeMillis} time base but with 2488 * nanosecond (instead of millisecond) precision. 2489 * <p> 2490 * The value is in nanosecond precision but it may not have nanosecond accuracy. 2491 * </p> 2492 * 2493 * @return Returns the time this event occurred, 2494 * in the {@link android.os.SystemClock#uptimeMillis} time base but with 2495 * nanosecond (instead of millisecond) precision. 2496 * 2497 * @hide 2498 */ 2499 @Override 2500 public final long getEventTimeNano() { 2501 return mEventTime * 1000000L; 2502 } 2503 2504 /** 2505 * Renamed to {@link #getDeviceId}. 2506 * 2507 * @hide 2508 * @deprecated use {@link #getDeviceId()} instead. 2509 */ 2510 @Deprecated 2511 public final int getKeyboardDevice() { 2512 return mDeviceId; 2513 } 2514 2515 /** 2516 * Gets the {@link KeyCharacterMap} associated with the keyboard device. 2517 * 2518 * @return The associated key character map. 2519 * @throws {@link KeyCharacterMap.UnavailableException} if the key character map 2520 * could not be loaded because it was malformed or the default key character map 2521 * is missing from the system. 2522 * 2523 * @see KeyCharacterMap#load 2524 */ 2525 public final KeyCharacterMap getKeyCharacterMap() { 2526 return KeyCharacterMap.load(mDeviceId); 2527 } 2528 2529 /** 2530 * Gets the primary character for this key. 2531 * In other words, the label that is physically printed on it. 2532 * 2533 * @return The display label character, or 0 if none (eg. for non-printing keys). 2534 */ 2535 public char getDisplayLabel() { 2536 return getKeyCharacterMap().getDisplayLabel(mKeyCode); 2537 } 2538 2539 /** 2540 * Gets the Unicode character generated by the specified key and meta 2541 * key state combination. 2542 * <p> 2543 * Returns the Unicode character that the specified key would produce 2544 * when the specified meta bits (see {@link MetaKeyKeyListener}) 2545 * were active. 2546 * </p><p> 2547 * Returns 0 if the key is not one that is used to type Unicode 2548 * characters. 2549 * </p><p> 2550 * If the return value has bit {@link KeyCharacterMap#COMBINING_ACCENT} set, the 2551 * key is a "dead key" that should be combined with another to 2552 * actually produce a character -- see {@link KeyCharacterMap#getDeadChar} -- 2553 * after masking with {@link KeyCharacterMap#COMBINING_ACCENT_MASK}. 2554 * </p> 2555 * 2556 * @return The associated character or combining accent, or 0 if none. 2557 */ 2558 public int getUnicodeChar() { 2559 return getUnicodeChar(mMetaState); 2560 } 2561 2562 /** 2563 * Gets the Unicode character generated by the specified key and meta 2564 * key state combination. 2565 * <p> 2566 * Returns the Unicode character that the specified key would produce 2567 * when the specified meta bits (see {@link MetaKeyKeyListener}) 2568 * were active. 2569 * </p><p> 2570 * Returns 0 if the key is not one that is used to type Unicode 2571 * characters. 2572 * </p><p> 2573 * If the return value has bit {@link KeyCharacterMap#COMBINING_ACCENT} set, the 2574 * key is a "dead key" that should be combined with another to 2575 * actually produce a character -- see {@link KeyCharacterMap#getDeadChar} -- 2576 * after masking with {@link KeyCharacterMap#COMBINING_ACCENT_MASK}. 2577 * </p> 2578 * 2579 * @param metaState The meta key modifier state. 2580 * @return The associated character or combining accent, or 0 if none. 2581 */ 2582 public int getUnicodeChar(int metaState) { 2583 return getKeyCharacterMap().get(mKeyCode, metaState); 2584 } 2585 2586 /** 2587 * Get the character conversion data for a given key code. 2588 * 2589 * @param results A {@link KeyCharacterMap.KeyData} instance that will be 2590 * filled with the results. 2591 * @return True if the key was mapped. If the key was not mapped, results is not modified. 2592 * 2593 * @deprecated instead use {@link #getDisplayLabel()}, 2594 * {@link #getNumber()} or {@link #getUnicodeChar(int)}. 2595 */ 2596 @Deprecated 2597 public boolean getKeyData(KeyData results) { 2598 return getKeyCharacterMap().getKeyData(mKeyCode, results); 2599 } 2600 2601 /** 2602 * Gets the first character in the character array that can be generated 2603 * by the specified key code. 2604 * <p> 2605 * This is a convenience function that returns the same value as 2606 * {@link #getMatch(char[],int) getMatch(chars, 0)}. 2607 * </p> 2608 * 2609 * @param chars The array of matching characters to consider. 2610 * @return The matching associated character, or 0 if none. 2611 */ 2612 public char getMatch(char[] chars) { 2613 return getMatch(chars, 0); 2614 } 2615 2616 /** 2617 * Gets the first character in the character array that can be generated 2618 * by the specified key code. If there are multiple choices, prefers 2619 * the one that would be generated with the specified meta key modifier state. 2620 * 2621 * @param chars The array of matching characters to consider. 2622 * @param metaState The preferred meta key modifier state. 2623 * @return The matching associated character, or 0 if none. 2624 */ 2625 public char getMatch(char[] chars, int metaState) { 2626 return getKeyCharacterMap().getMatch(mKeyCode, chars, metaState); 2627 } 2628 2629 /** 2630 * Gets the number or symbol associated with the key. 2631 * <p> 2632 * The character value is returned, not the numeric value. 2633 * If the key is not a number, but is a symbol, the symbol is retuned. 2634 * </p><p> 2635 * This method is intended to to support dial pads and other numeric or 2636 * symbolic entry on keyboards where certain keys serve dual function 2637 * as alphabetic and symbolic keys. This method returns the number 2638 * or symbol associated with the key independent of whether the user 2639 * has pressed the required modifier. 2640 * </p><p> 2641 * For example, on one particular keyboard the keys on the top QWERTY row generate 2642 * numbers when ALT is pressed such that ALT-Q maps to '1'. So for that keyboard 2643 * when {@link #getNumber} is called with {@link KeyEvent#KEYCODE_Q} it returns '1' 2644 * so that the user can type numbers without pressing ALT when it makes sense. 2645 * </p> 2646 * 2647 * @return The associated numeric or symbolic character, or 0 if none. 2648 */ 2649 public char getNumber() { 2650 return getKeyCharacterMap().getNumber(mKeyCode); 2651 } 2652 2653 /** 2654 * Returns true if this key produces a glyph. 2655 * 2656 * @return True if the key is a printing key. 2657 */ 2658 public boolean isPrintingKey() { 2659 return getKeyCharacterMap().isPrintingKey(mKeyCode); 2660 } 2661 2662 /** 2663 * @deprecated Use {@link #dispatch(Callback, DispatcherState, Object)} instead. 2664 */ 2665 @Deprecated 2666 public final boolean dispatch(Callback receiver) { 2667 return dispatch(receiver, null, null); 2668 } 2669 2670 /** 2671 * Deliver this key event to a {@link Callback} interface. If this is 2672 * an ACTION_MULTIPLE event and it is not handled, then an attempt will 2673 * be made to deliver a single normal event. 2674 * 2675 * @param receiver The Callback that will be given the event. 2676 * @param state State information retained across events. 2677 * @param target The target of the dispatch, for use in tracking. 2678 * 2679 * @return The return value from the Callback method that was called. 2680 */ 2681 public final boolean dispatch(Callback receiver, DispatcherState state, 2682 Object target) { 2683 switch (mAction) { 2684 case ACTION_DOWN: { 2685 mFlags &= ~FLAG_START_TRACKING; 2686 if (DEBUG) Log.v(TAG, "Key down to " + target + " in " + state 2687 + ": " + this); 2688 boolean res = receiver.onKeyDown(mKeyCode, this); 2689 if (state != null) { 2690 if (res && mRepeatCount == 0 && (mFlags&FLAG_START_TRACKING) != 0) { 2691 if (DEBUG) Log.v(TAG, " Start tracking!"); 2692 state.startTracking(this, target); 2693 } else if (isLongPress() && state.isTracking(this)) { 2694 try { 2695 if (receiver.onKeyLongPress(mKeyCode, this)) { 2696 if (DEBUG) Log.v(TAG, " Clear from long press!"); 2697 state.performedLongPress(this); 2698 res = true; 2699 } 2700 } catch (AbstractMethodError e) { 2701 } 2702 } 2703 } 2704 return res; 2705 } 2706 case ACTION_UP: 2707 if (DEBUG) Log.v(TAG, "Key up to " + target + " in " + state 2708 + ": " + this); 2709 if (state != null) { 2710 state.handleUpEvent(this); 2711 } 2712 return receiver.onKeyUp(mKeyCode, this); 2713 case ACTION_MULTIPLE: 2714 final int count = mRepeatCount; 2715 final int code = mKeyCode; 2716 if (receiver.onKeyMultiple(code, count, this)) { 2717 return true; 2718 } 2719 if (code != KeyEvent.KEYCODE_UNKNOWN) { 2720 mAction = ACTION_DOWN; 2721 mRepeatCount = 0; 2722 boolean handled = receiver.onKeyDown(code, this); 2723 if (handled) { 2724 mAction = ACTION_UP; 2725 receiver.onKeyUp(code, this); 2726 } 2727 mAction = ACTION_MULTIPLE; 2728 mRepeatCount = count; 2729 return handled; 2730 } 2731 return false; 2732 } 2733 return false; 2734 } 2735 2736 /** 2737 * Use with {@link KeyEvent#dispatch(Callback, DispatcherState, Object)} 2738 * for more advanced key dispatching, such as long presses. 2739 */ 2740 public static class DispatcherState { 2741 int mDownKeyCode; 2742 Object mDownTarget; 2743 SparseIntArray mActiveLongPresses = new SparseIntArray(); 2744 2745 /** 2746 * Reset back to initial state. 2747 */ 2748 public void reset() { 2749 if (DEBUG) Log.v(TAG, "Reset: " + this); 2750 mDownKeyCode = 0; 2751 mDownTarget = null; 2752 mActiveLongPresses.clear(); 2753 } 2754 2755 /** 2756 * Stop any tracking associated with this target. 2757 */ 2758 public void reset(Object target) { 2759 if (mDownTarget == target) { 2760 if (DEBUG) Log.v(TAG, "Reset in " + target + ": " + this); 2761 mDownKeyCode = 0; 2762 mDownTarget = null; 2763 } 2764 } 2765 2766 /** 2767 * Start tracking the key code associated with the given event. This 2768 * can only be called on a key down. It will allow you to see any 2769 * long press associated with the key, and will result in 2770 * {@link KeyEvent#isTracking} return true on the long press and up 2771 * events. 2772 * 2773 * <p>This is only needed if you are directly dispatching events, rather 2774 * than handling them in {@link Callback#onKeyDown}. 2775 */ 2776 public void startTracking(KeyEvent event, Object target) { 2777 if (event.getAction() != ACTION_DOWN) { 2778 throw new IllegalArgumentException( 2779 "Can only start tracking on a down event"); 2780 } 2781 if (DEBUG) Log.v(TAG, "Start trackingt in " + target + ": " + this); 2782 mDownKeyCode = event.getKeyCode(); 2783 mDownTarget = target; 2784 } 2785 2786 /** 2787 * Return true if the key event is for a key code that is currently 2788 * being tracked by the dispatcher. 2789 */ 2790 public boolean isTracking(KeyEvent event) { 2791 return mDownKeyCode == event.getKeyCode(); 2792 } 2793 2794 /** 2795 * Keep track of the given event's key code as having performed an 2796 * action with a long press, so no action should occur on the up. 2797 * <p>This is only needed if you are directly dispatching events, rather 2798 * than handling them in {@link Callback#onKeyLongPress}. 2799 */ 2800 public void performedLongPress(KeyEvent event) { 2801 mActiveLongPresses.put(event.getKeyCode(), 1); 2802 } 2803 2804 /** 2805 * Handle key up event to stop tracking. This resets the dispatcher state, 2806 * and updates the key event state based on it. 2807 * <p>This is only needed if you are directly dispatching events, rather 2808 * than handling them in {@link Callback#onKeyUp}. 2809 */ 2810 public void handleUpEvent(KeyEvent event) { 2811 final int keyCode = event.getKeyCode(); 2812 if (DEBUG) Log.v(TAG, "Handle key up " + event + ": " + this); 2813 int index = mActiveLongPresses.indexOfKey(keyCode); 2814 if (index >= 0) { 2815 if (DEBUG) Log.v(TAG, " Index: " + index); 2816 event.mFlags |= FLAG_CANCELED | FLAG_CANCELED_LONG_PRESS; 2817 mActiveLongPresses.removeAt(index); 2818 } 2819 if (mDownKeyCode == keyCode) { 2820 if (DEBUG) Log.v(TAG, " Tracking!"); 2821 event.mFlags |= FLAG_TRACKING; 2822 mDownKeyCode = 0; 2823 mDownTarget = null; 2824 } 2825 } 2826 } 2827 2828 @Override 2829 public String toString() { 2830 StringBuilder msg = new StringBuilder(); 2831 msg.append("KeyEvent { action=").append(actionToString(mAction)); 2832 msg.append(", keyCode=").append(keyCodeToString(mKeyCode)); 2833 msg.append(", scanCode=").append(mScanCode); 2834 if (mCharacters != null) { 2835 msg.append(", characters=\"").append(mCharacters).append("\""); 2836 } 2837 msg.append(", metaState=").append(metaStateToString(mMetaState)); 2838 msg.append(", flags=0x").append(Integer.toHexString(mFlags)); 2839 msg.append(", repeatCount=").append(mRepeatCount); 2840 msg.append(", eventTime=").append(mEventTime); 2841 msg.append(", downTime=").append(mDownTime); 2842 msg.append(", deviceId=").append(mDeviceId); 2843 msg.append(", source=0x").append(Integer.toHexString(mSource)); 2844 msg.append(" }"); 2845 return msg.toString(); 2846 } 2847 2848 /** 2849 * Returns a string that represents the symbolic name of the specified action 2850 * such as "ACTION_DOWN", or an equivalent numeric constant such as "35" if unknown. 2851 * 2852 * @param action The action. 2853 * @return The symbolic name of the specified action. 2854 * @hide 2855 */ 2856 public static String actionToString(int action) { 2857 switch (action) { 2858 case ACTION_DOWN: 2859 return "ACTION_DOWN"; 2860 case ACTION_UP: 2861 return "ACTION_UP"; 2862 case ACTION_MULTIPLE: 2863 return "ACTION_MULTIPLE"; 2864 default: 2865 return Integer.toString(action); 2866 } 2867 } 2868 2869 /** 2870 * Returns a string that represents the symbolic name of the specified keycode 2871 * such as "KEYCODE_A", "KEYCODE_DPAD_UP", or an equivalent numeric constant 2872 * such as "1001" if unknown. 2873 * 2874 * @param keyCode The key code. 2875 * @return The symbolic name of the specified keycode. 2876 * 2877 * @see KeyCharacterMap#getDisplayLabel 2878 */ 2879 public static String keyCodeToString(int keyCode) { 2880 String symbolicName = nativeKeyCodeToString(keyCode); 2881 return symbolicName != null ? LABEL_PREFIX + symbolicName : Integer.toString(keyCode); 2882 } 2883 2884 /** 2885 * Gets a keycode by its symbolic name such as "KEYCODE_A" or an equivalent 2886 * numeric constant such as "1001". 2887 * 2888 * @param symbolicName The symbolic name of the keycode. 2889 * @return The keycode or {@link #KEYCODE_UNKNOWN} if not found. 2890 * @see #keycodeToString(int) 2891 */ 2892 public static int keyCodeFromString(String symbolicName) { 2893 if (symbolicName.startsWith(LABEL_PREFIX)) { 2894 symbolicName = symbolicName.substring(LABEL_PREFIX.length()); 2895 int keyCode = nativeKeyCodeFromString(symbolicName); 2896 if (keyCode > 0) { 2897 return keyCode; 2898 } 2899 } 2900 try { 2901 return Integer.parseInt(symbolicName, 10); 2902 } catch (NumberFormatException ex) { 2903 return KEYCODE_UNKNOWN; 2904 } 2905 } 2906 2907 /** 2908 * Returns a string that represents the symbolic name of the specified combined meta 2909 * key modifier state flags such as "0", "META_SHIFT_ON", 2910 * "META_ALT_ON|META_SHIFT_ON" or an equivalent numeric constant such as "0x10000000" 2911 * if unknown. 2912 * 2913 * @param metaState The meta state. 2914 * @return The symbolic name of the specified combined meta state flags. 2915 * @hide 2916 */ 2917 public static String metaStateToString(int metaState) { 2918 if (metaState == 0) { 2919 return "0"; 2920 } 2921 StringBuilder result = null; 2922 int i = 0; 2923 while (metaState != 0) { 2924 final boolean isSet = (metaState & 1) != 0; 2925 metaState >>>= 1; // unsigned shift! 2926 if (isSet) { 2927 final String name = META_SYMBOLIC_NAMES[i]; 2928 if (result == null) { 2929 if (metaState == 0) { 2930 return name; 2931 } 2932 result = new StringBuilder(name); 2933 } else { 2934 result.append('|'); 2935 result.append(name); 2936 } 2937 } 2938 i += 1; 2939 } 2940 return result.toString(); 2941 } 2942 2943 public static final Parcelable.Creator<KeyEvent> CREATOR 2944 = new Parcelable.Creator<KeyEvent>() { 2945 @Override 2946 public KeyEvent createFromParcel(Parcel in) { 2947 in.readInt(); // skip token, we already know this is a KeyEvent 2948 return KeyEvent.createFromParcelBody(in); 2949 } 2950 2951 @Override 2952 public KeyEvent[] newArray(int size) { 2953 return new KeyEvent[size]; 2954 } 2955 }; 2956 2957 /** @hide */ 2958 public static KeyEvent createFromParcelBody(Parcel in) { 2959 return new KeyEvent(in); 2960 } 2961 2962 private KeyEvent(Parcel in) { 2963 mDeviceId = in.readInt(); 2964 mSource = in.readInt(); 2965 mAction = in.readInt(); 2966 mKeyCode = in.readInt(); 2967 mRepeatCount = in.readInt(); 2968 mMetaState = in.readInt(); 2969 mScanCode = in.readInt(); 2970 mFlags = in.readInt(); 2971 mDownTime = in.readLong(); 2972 mEventTime = in.readLong(); 2973 } 2974 2975 @Override 2976 public void writeToParcel(Parcel out, int flags) { 2977 out.writeInt(PARCEL_TOKEN_KEY_EVENT); 2978 2979 out.writeInt(mDeviceId); 2980 out.writeInt(mSource); 2981 out.writeInt(mAction); 2982 out.writeInt(mKeyCode); 2983 out.writeInt(mRepeatCount); 2984 out.writeInt(mMetaState); 2985 out.writeInt(mScanCode); 2986 out.writeInt(mFlags); 2987 out.writeLong(mDownTime); 2988 out.writeLong(mEventTime); 2989 } 2990} 2991