src.android.view.KeyEvent Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of android-all Show documentation
Show all versions of android-all Show documentation
A library jar that provides APIs for Applications written for the Google Android Platform.
/*
* Copyright (C) 2006 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.view;
import static android.os.IInputConstants.INPUT_EVENT_FLAG_IS_ACCESSIBILITY_EVENT;
import static android.view.Display.INVALID_DISPLAY;
import android.annotation.NonNull;
import android.annotation.Nullable;
import android.annotation.TestApi;
import android.compat.annotation.UnsupportedAppUsage;
import android.os.Build;
import android.os.Parcel;
import android.os.Parcelable;
import android.text.method.MetaKeyKeyListener;
import android.util.Log;
import android.util.SparseIntArray;
import android.view.KeyCharacterMap.KeyData;
import java.util.concurrent.TimeUnit;
/**
* Object used to report key and button events.
*
* Each key press is described by a sequence of key events. A key press
* starts with a key event with {@link #ACTION_DOWN}. If the key is held
* sufficiently long that it repeats, then the initial down is followed
* additional key events with {@link #ACTION_DOWN} and a non-zero value for
* {@link #getRepeatCount()}. The last key event is a {@link #ACTION_UP}
* for the key up. If the key press is canceled, the key up event will have the
* {@link #FLAG_CANCELED} flag set.
*
* Key events are generally accompanied by a key code ({@link #getKeyCode()}),
* scan code ({@link #getScanCode()}) and meta state ({@link #getMetaState()}).
* Key code constants are defined in this class. Scan code constants are raw
* device-specific codes obtained from the OS and so are not generally meaningful
* to applications unless interpreted using the {@link KeyCharacterMap}.
* Meta states describe the pressed state of key modifiers
* such as {@link #META_SHIFT_ON} or {@link #META_ALT_ON}.
*
* Key codes typically correspond one-to-one with individual keys on an input device.
* Many keys and key combinations serve quite different functions on different
* input devices so care must be taken when interpreting them. Always use the
* {@link KeyCharacterMap} associated with the input device when mapping keys
* to characters. Be aware that there may be multiple key input devices active
* at the same time and each will have its own key character map.
*
* As soft input methods can use multiple and inventive ways of inputting text,
* there is no guarantee that any key press on a soft keyboard will generate a key
* event: this is left to the IME's discretion, and in fact sending such events is
* discouraged. You should never rely on receiving KeyEvents for any key on a soft
* input method. In particular, the default software keyboard will never send any
* key event to any application targetting Jelly Bean or later, and will only send
* events for some presses of the delete and return keys to applications targetting
* Ice Cream Sandwich or earlier. Be aware that other software input methods may
* never send key events regardless of the version. Consider using editor actions
* like {@link android.view.inputmethod.EditorInfo#IME_ACTION_DONE} if you need
* specific interaction with the software keyboard, as it gives more visibility to
* the user as to how your application will react to key presses.
*
* When interacting with an IME, the framework may deliver key events
* with the special action {@link #ACTION_MULTIPLE} that either specifies
* that single repeated key code or a sequence of characters to insert.
*
* In general, the framework cannot guarantee that the key events it delivers
* to a view always constitute complete key sequences since some events may be dropped
* or modified by containing views before they are delivered. The view implementation
* should be prepared to handle {@link #FLAG_CANCELED} and should tolerate anomalous
* situations such as receiving a new {@link #ACTION_DOWN} without first having
* received an {@link #ACTION_UP} for the prior key press.
*
* Refer to {@link InputDevice} for more information about how different kinds of
* input devices and sources represent keys and buttons.
*
*/
public class KeyEvent extends InputEvent implements Parcelable {
/** Key code constant: Unknown key code. */
public static final int KEYCODE_UNKNOWN = 0;
/** Key code constant: Soft Left key.
* Usually situated below the display on phones and used as a multi-function
* feature key for selecting a software defined function shown on the bottom left
* of the display. */
public static final int KEYCODE_SOFT_LEFT = 1;
/** Key code constant: Soft Right key.
* Usually situated below the display on phones and used as a multi-function
* feature key for selecting a software defined function shown on the bottom right
* of the display. */
public static final int KEYCODE_SOFT_RIGHT = 2;
/** Key code constant: Home key.
* This key is handled by the framework and is never delivered to applications. */
public static final int KEYCODE_HOME = 3;
/** Key code constant: Back key. */
public static final int KEYCODE_BACK = 4;
/** Key code constant: Call key. */
public static final int KEYCODE_CALL = 5;
/** Key code constant: End Call key. */
public static final int KEYCODE_ENDCALL = 6;
/** Key code constant: '0' key. */
public static final int KEYCODE_0 = 7;
/** Key code constant: '1' key. */
public static final int KEYCODE_1 = 8;
/** Key code constant: '2' key. */
public static final int KEYCODE_2 = 9;
/** Key code constant: '3' key. */
public static final int KEYCODE_3 = 10;
/** Key code constant: '4' key. */
public static final int KEYCODE_4 = 11;
/** Key code constant: '5' key. */
public static final int KEYCODE_5 = 12;
/** Key code constant: '6' key. */
public static final int KEYCODE_6 = 13;
/** Key code constant: '7' key. */
public static final int KEYCODE_7 = 14;
/** Key code constant: '8' key. */
public static final int KEYCODE_8 = 15;
/** Key code constant: '9' key. */
public static final int KEYCODE_9 = 16;
/** Key code constant: '*' key. */
public static final int KEYCODE_STAR = 17;
/** Key code constant: '#' key. */
public static final int KEYCODE_POUND = 18;
/** Key code constant: Directional Pad Up key.
* May also be synthesized from trackball motions. */
public static final int KEYCODE_DPAD_UP = 19;
/** Key code constant: Directional Pad Down key.
* May also be synthesized from trackball motions. */
public static final int KEYCODE_DPAD_DOWN = 20;
/** Key code constant: Directional Pad Left key.
* May also be synthesized from trackball motions. */
public static final int KEYCODE_DPAD_LEFT = 21;
/** Key code constant: Directional Pad Right key.
* May also be synthesized from trackball motions. */
public static final int KEYCODE_DPAD_RIGHT = 22;
/** Key code constant: Directional Pad Center key.
* May also be synthesized from trackball motions. */
public static final int KEYCODE_DPAD_CENTER = 23;
/** Key code constant: Volume Up key.
* Adjusts the speaker volume up. */
public static final int KEYCODE_VOLUME_UP = 24;
/** Key code constant: Volume Down key.
* Adjusts the speaker volume down. */
public static final int KEYCODE_VOLUME_DOWN = 25;
/** Key code constant: Power key. */
public static final int KEYCODE_POWER = 26;
/** Key code constant: Camera key.
* Used to launch a camera application or take pictures. */
public static final int KEYCODE_CAMERA = 27;
/** Key code constant: Clear key. */
public static final int KEYCODE_CLEAR = 28;
/** Key code constant: 'A' key. */
public static final int KEYCODE_A = 29;
/** Key code constant: 'B' key. */
public static final int KEYCODE_B = 30;
/** Key code constant: 'C' key. */
public static final int KEYCODE_C = 31;
/** Key code constant: 'D' key. */
public static final int KEYCODE_D = 32;
/** Key code constant: 'E' key. */
public static final int KEYCODE_E = 33;
/** Key code constant: 'F' key. */
public static final int KEYCODE_F = 34;
/** Key code constant: 'G' key. */
public static final int KEYCODE_G = 35;
/** Key code constant: 'H' key. */
public static final int KEYCODE_H = 36;
/** Key code constant: 'I' key. */
public static final int KEYCODE_I = 37;
/** Key code constant: 'J' key. */
public static final int KEYCODE_J = 38;
/** Key code constant: 'K' key. */
public static final int KEYCODE_K = 39;
/** Key code constant: 'L' key. */
public static final int KEYCODE_L = 40;
/** Key code constant: 'M' key. */
public static final int KEYCODE_M = 41;
/** Key code constant: 'N' key. */
public static final int KEYCODE_N = 42;
/** Key code constant: 'O' key. */
public static final int KEYCODE_O = 43;
/** Key code constant: 'P' key. */
public static final int KEYCODE_P = 44;
/** Key code constant: 'Q' key. */
public static final int KEYCODE_Q = 45;
/** Key code constant: 'R' key. */
public static final int KEYCODE_R = 46;
/** Key code constant: 'S' key. */
public static final int KEYCODE_S = 47;
/** Key code constant: 'T' key. */
public static final int KEYCODE_T = 48;
/** Key code constant: 'U' key. */
public static final int KEYCODE_U = 49;
/** Key code constant: 'V' key. */
public static final int KEYCODE_V = 50;
/** Key code constant: 'W' key. */
public static final int KEYCODE_W = 51;
/** Key code constant: 'X' key. */
public static final int KEYCODE_X = 52;
/** Key code constant: 'Y' key. */
public static final int KEYCODE_Y = 53;
/** Key code constant: 'Z' key. */
public static final int KEYCODE_Z = 54;
/** Key code constant: ',' key. */
public static final int KEYCODE_COMMA = 55;
/** Key code constant: '.' key. */
public static final int KEYCODE_PERIOD = 56;
/** Key code constant: Left Alt modifier key. */
public static final int KEYCODE_ALT_LEFT = 57;
/** Key code constant: Right Alt modifier key. */
public static final int KEYCODE_ALT_RIGHT = 58;
/** Key code constant: Left Shift modifier key. */
public static final int KEYCODE_SHIFT_LEFT = 59;
/** Key code constant: Right Shift modifier key. */
public static final int KEYCODE_SHIFT_RIGHT = 60;
/** Key code constant: Tab key. */
public static final int KEYCODE_TAB = 61;
/** Key code constant: Space key. */
public static final int KEYCODE_SPACE = 62;
/** Key code constant: Symbol modifier key.
* Used to enter alternate symbols. */
public static final int KEYCODE_SYM = 63;
/** Key code constant: Explorer special function key.
* Used to launch a browser application. */
public static final int KEYCODE_EXPLORER = 64;
/** Key code constant: Envelope special function key.
* Used to launch a mail application. */
public static final int KEYCODE_ENVELOPE = 65;
/** Key code constant: Enter key. */
public static final int KEYCODE_ENTER = 66;
/** Key code constant: Backspace key.
* Deletes characters before the insertion point, unlike {@link #KEYCODE_FORWARD_DEL}. */
public static final int KEYCODE_DEL = 67;
/** Key code constant: '`' (backtick) key. */
public static final int KEYCODE_GRAVE = 68;
/** Key code constant: '-'. */
public static final int KEYCODE_MINUS = 69;
/** Key code constant: '=' key. */
public static final int KEYCODE_EQUALS = 70;
/** Key code constant: '[' key. */
public static final int KEYCODE_LEFT_BRACKET = 71;
/** Key code constant: ']' key. */
public static final int KEYCODE_RIGHT_BRACKET = 72;
/** Key code constant: '\' key. */
public static final int KEYCODE_BACKSLASH = 73;
/** Key code constant: ';' key. */
public static final int KEYCODE_SEMICOLON = 74;
/** Key code constant: ''' (apostrophe) key. */
public static final int KEYCODE_APOSTROPHE = 75;
/** Key code constant: '/' key. */
public static final int KEYCODE_SLASH = 76;
/** Key code constant: '@' key. */
public static final int KEYCODE_AT = 77;
/** Key code constant: Number modifier key.
* Used to enter numeric symbols.
* This key is not Num Lock; it is more like {@link #KEYCODE_ALT_LEFT} and is
* interpreted as an ALT key by {@link android.text.method.MetaKeyKeyListener}. */
public static final int KEYCODE_NUM = 78;
/** Key code constant: Headset Hook key.
* Used to hang up calls and stop media. */
public static final int KEYCODE_HEADSETHOOK = 79;
/** Key code constant: Camera Focus key.
* Used to focus the camera. */
public static final int KEYCODE_FOCUS = 80; // *Camera* focus
/** Key code constant: '+' key. */
public static final int KEYCODE_PLUS = 81;
/** Key code constant: Menu key. */
public static final int KEYCODE_MENU = 82;
/** Key code constant: Notification key. */
public static final int KEYCODE_NOTIFICATION = 83;
/** Key code constant: Search key. */
public static final int KEYCODE_SEARCH = 84;
/** Key code constant: Play/Pause media key. */
public static final int KEYCODE_MEDIA_PLAY_PAUSE= 85;
/** Key code constant: Stop media key. */
public static final int KEYCODE_MEDIA_STOP = 86;
/** Key code constant: Play Next media key. */
public static final int KEYCODE_MEDIA_NEXT = 87;
/** Key code constant: Play Previous media key. */
public static final int KEYCODE_MEDIA_PREVIOUS = 88;
/** Key code constant: Rewind media key. */
public static final int KEYCODE_MEDIA_REWIND = 89;
/** Key code constant: Fast Forward media key. */
public static final int KEYCODE_MEDIA_FAST_FORWARD = 90;
/** Key code constant: Mute key.
* Mute key for the microphone (unlike {@link #KEYCODE_VOLUME_MUTE}, which is the speaker mute
* key). */
public static final int KEYCODE_MUTE = 91;
/** Key code constant: Page Up key. */
public static final int KEYCODE_PAGE_UP = 92;
/** Key code constant: Page Down key. */
public static final int KEYCODE_PAGE_DOWN = 93;
/** Key code constant: Picture Symbols modifier key.
* Used to switch symbol sets (Emoji, Kao-moji). */
public static final int KEYCODE_PICTSYMBOLS = 94; // switch symbol-sets (Emoji,Kao-moji)
/** Key code constant: Switch Charset modifier key.
* Used to switch character sets (Kanji, Katakana). */
public static final int KEYCODE_SWITCH_CHARSET = 95; // switch char-sets (Kanji,Katakana)
/** Key code constant: A Button key.
* On a game controller, the A button should be either the button labeled A
* or the first button on the bottom row of controller buttons. */
public static final int KEYCODE_BUTTON_A = 96;
/** Key code constant: B Button key.
* On a game controller, the B button should be either the button labeled B
* or the second button on the bottom row of controller buttons. */
public static final int KEYCODE_BUTTON_B = 97;
/** Key code constant: C Button key.
* On a game controller, the C button should be either the button labeled C
* or the third button on the bottom row of controller buttons. */
public static final int KEYCODE_BUTTON_C = 98;
/** Key code constant: X Button key.
* On a game controller, the X button should be either the button labeled X
* or the first button on the upper row of controller buttons. */
public static final int KEYCODE_BUTTON_X = 99;
/** Key code constant: Y Button key.
* On a game controller, the Y button should be either the button labeled Y
* or the second button on the upper row of controller buttons. */
public static final int KEYCODE_BUTTON_Y = 100;
/** Key code constant: Z Button key.
* On a game controller, the Z button should be either the button labeled Z
* or the third button on the upper row of controller buttons. */
public static final int KEYCODE_BUTTON_Z = 101;
/** Key code constant: L1 Button key.
* On a game controller, the L1 button should be either the button labeled L1 (or L)
* or the top left trigger button. */
public static final int KEYCODE_BUTTON_L1 = 102;
/** Key code constant: R1 Button key.
* On a game controller, the R1 button should be either the button labeled R1 (or R)
* or the top right trigger button. */
public static final int KEYCODE_BUTTON_R1 = 103;
/** Key code constant: L2 Button key.
* On a game controller, the L2 button should be either the button labeled L2
* or the bottom left trigger button. */
public static final int KEYCODE_BUTTON_L2 = 104;
/** Key code constant: R2 Button key.
* On a game controller, the R2 button should be either the button labeled R2
* or the bottom right trigger button. */
public static final int KEYCODE_BUTTON_R2 = 105;
/** Key code constant: Left Thumb Button key.
* On a game controller, the left thumb button indicates that the left (or only)
* joystick is pressed. */
public static final int KEYCODE_BUTTON_THUMBL = 106;
/** Key code constant: Right Thumb Button key.
* On a game controller, the right thumb button indicates that the right
* joystick is pressed. */
public static final int KEYCODE_BUTTON_THUMBR = 107;
/** Key code constant: Start Button key.
* On a game controller, the button labeled Start. */
public static final int KEYCODE_BUTTON_START = 108;
/** Key code constant: Select Button key.
* On a game controller, the button labeled Select. */
public static final int KEYCODE_BUTTON_SELECT = 109;
/** Key code constant: Mode Button key.
* On a game controller, the button labeled Mode. */
public static final int KEYCODE_BUTTON_MODE = 110;
/** Key code constant: Escape key. */
public static final int KEYCODE_ESCAPE = 111;
/** Key code constant: Forward Delete key.
* Deletes characters ahead of the insertion point, unlike {@link #KEYCODE_DEL}. */
public static final int KEYCODE_FORWARD_DEL = 112;
/** Key code constant: Left Control modifier key. */
public static final int KEYCODE_CTRL_LEFT = 113;
/** Key code constant: Right Control modifier key. */
public static final int KEYCODE_CTRL_RIGHT = 114;
/** Key code constant: Caps Lock key. */
public static final int KEYCODE_CAPS_LOCK = 115;
/** Key code constant: Scroll Lock key. */
public static final int KEYCODE_SCROLL_LOCK = 116;
/** Key code constant: Left Meta modifier key. */
public static final int KEYCODE_META_LEFT = 117;
/** Key code constant: Right Meta modifier key. */
public static final int KEYCODE_META_RIGHT = 118;
/** Key code constant: Function modifier key. */
public static final int KEYCODE_FUNCTION = 119;
/** Key code constant: System Request / Print Screen key. */
public static final int KEYCODE_SYSRQ = 120;
/** Key code constant: Break / Pause key. */
public static final int KEYCODE_BREAK = 121;
/** Key code constant: Home Movement key.
* Used for scrolling or moving the cursor around to the start of a line
* or to the top of a list. */
public static final int KEYCODE_MOVE_HOME = 122;
/** Key code constant: End Movement key.
* Used for scrolling or moving the cursor around to the end of a line
* or to the bottom of a list. */
public static final int KEYCODE_MOVE_END = 123;
/** Key code constant: Insert key.
* Toggles insert / overwrite edit mode. */
public static final int KEYCODE_INSERT = 124;
/** Key code constant: Forward key.
* Navigates forward in the history stack. Complement of {@link #KEYCODE_BACK}. */
public static final int KEYCODE_FORWARD = 125;
/** Key code constant: Play media key. */
public static final int KEYCODE_MEDIA_PLAY = 126;
/** Key code constant: Pause media key. */
public static final int KEYCODE_MEDIA_PAUSE = 127;
/** Key code constant: Close media key.
* May be used to close a CD tray, for example. */
public static final int KEYCODE_MEDIA_CLOSE = 128;
/** Key code constant: Eject media key.
* May be used to eject a CD tray, for example. */
public static final int KEYCODE_MEDIA_EJECT = 129;
/** Key code constant: Record media key. */
public static final int KEYCODE_MEDIA_RECORD = 130;
/** Key code constant: F1 key. */
public static final int KEYCODE_F1 = 131;
/** Key code constant: F2 key. */
public static final int KEYCODE_F2 = 132;
/** Key code constant: F3 key. */
public static final int KEYCODE_F3 = 133;
/** Key code constant: F4 key. */
public static final int KEYCODE_F4 = 134;
/** Key code constant: F5 key. */
public static final int KEYCODE_F5 = 135;
/** Key code constant: F6 key. */
public static final int KEYCODE_F6 = 136;
/** Key code constant: F7 key. */
public static final int KEYCODE_F7 = 137;
/** Key code constant: F8 key. */
public static final int KEYCODE_F8 = 138;
/** Key code constant: F9 key. */
public static final int KEYCODE_F9 = 139;
/** Key code constant: F10 key. */
public static final int KEYCODE_F10 = 140;
/** Key code constant: F11 key. */
public static final int KEYCODE_F11 = 141;
/** Key code constant: F12 key. */
public static final int KEYCODE_F12 = 142;
/** Key code constant: Num Lock key.
* This is the Num Lock key; it is different from {@link #KEYCODE_NUM}.
* This key alters the behavior of other keys on the numeric keypad. */
public static final int KEYCODE_NUM_LOCK = 143;
/** Key code constant: Numeric keypad '0' key. */
public static final int KEYCODE_NUMPAD_0 = 144;
/** Key code constant: Numeric keypad '1' key. */
public static final int KEYCODE_NUMPAD_1 = 145;
/** Key code constant: Numeric keypad '2' key. */
public static final int KEYCODE_NUMPAD_2 = 146;
/** Key code constant: Numeric keypad '3' key. */
public static final int KEYCODE_NUMPAD_3 = 147;
/** Key code constant: Numeric keypad '4' key. */
public static final int KEYCODE_NUMPAD_4 = 148;
/** Key code constant: Numeric keypad '5' key. */
public static final int KEYCODE_NUMPAD_5 = 149;
/** Key code constant: Numeric keypad '6' key. */
public static final int KEYCODE_NUMPAD_6 = 150;
/** Key code constant: Numeric keypad '7' key. */
public static final int KEYCODE_NUMPAD_7 = 151;
/** Key code constant: Numeric keypad '8' key. */
public static final int KEYCODE_NUMPAD_8 = 152;
/** Key code constant: Numeric keypad '9' key. */
public static final int KEYCODE_NUMPAD_9 = 153;
/** Key code constant: Numeric keypad '/' key (for division). */
public static final int KEYCODE_NUMPAD_DIVIDE = 154;
/** Key code constant: Numeric keypad '*' key (for multiplication). */
public static final int KEYCODE_NUMPAD_MULTIPLY = 155;
/** Key code constant: Numeric keypad '-' key (for subtraction). */
public static final int KEYCODE_NUMPAD_SUBTRACT = 156;
/** Key code constant: Numeric keypad '+' key (for addition). */
public static final int KEYCODE_NUMPAD_ADD = 157;
/** Key code constant: Numeric keypad '.' key (for decimals or digit grouping). */
public static final int KEYCODE_NUMPAD_DOT = 158;
/** Key code constant: Numeric keypad ',' key (for decimals or digit grouping). */
public static final int KEYCODE_NUMPAD_COMMA = 159;
/** Key code constant: Numeric keypad Enter key. */
public static final int KEYCODE_NUMPAD_ENTER = 160;
/** Key code constant: Numeric keypad '=' key. */
public static final int KEYCODE_NUMPAD_EQUALS = 161;
/** Key code constant: Numeric keypad '(' key. */
public static final int KEYCODE_NUMPAD_LEFT_PAREN = 162;
/** Key code constant: Numeric keypad ')' key. */
public static final int KEYCODE_NUMPAD_RIGHT_PAREN = 163;
/** Key code constant: Volume Mute key.
* Mute key for speaker (unlike {@link #KEYCODE_MUTE}, which is the mute key for the
* microphone). This key should normally be implemented as a toggle such that the first press
* mutes the speaker and the second press restores the original volume.
*/
public static final int KEYCODE_VOLUME_MUTE = 164;
/** Key code constant: Info key.
* Common on TV remotes to show additional information related to what is
* currently being viewed. */
public static final int KEYCODE_INFO = 165;
/** Key code constant: Channel up key.
* On TV remotes, increments the television channel. */
public static final int KEYCODE_CHANNEL_UP = 166;
/** Key code constant: Channel down key.
* On TV remotes, decrements the television channel. */
public static final int KEYCODE_CHANNEL_DOWN = 167;
/** Key code constant: Zoom in key. */
public static final int KEYCODE_ZOOM_IN = 168;
/** Key code constant: Zoom out key. */
public static final int KEYCODE_ZOOM_OUT = 169;
/** Key code constant: TV key.
* On TV remotes, switches to viewing live TV. */
public static final int KEYCODE_TV = 170;
/** Key code constant: Window key.
* On TV remotes, toggles picture-in-picture mode or other windowing functions.
* On Android Wear devices, triggers a display offset. */
public static final int KEYCODE_WINDOW = 171;
/** Key code constant: Guide key.
* On TV remotes, shows a programming guide. */
public static final int KEYCODE_GUIDE = 172;
/** Key code constant: DVR key.
* On some TV remotes, switches to a DVR mode for recorded shows. */
public static final int KEYCODE_DVR = 173;
/** Key code constant: Bookmark key.
* On some TV remotes, bookmarks content or web pages. */
public static final int KEYCODE_BOOKMARK = 174;
/** Key code constant: Toggle captions key.
* Switches the mode for closed-captioning text, for example during television shows. */
public static final int KEYCODE_CAPTIONS = 175;
/** Key code constant: Settings key.
* Starts the system settings activity. */
public static final int KEYCODE_SETTINGS = 176;
/**
* Key code constant: TV power key.
* On HDMI TV panel devices and Android TV devices that don't support HDMI, toggles the power
* state of the device.
* On HDMI source devices, toggles the power state of the HDMI-connected TV via HDMI-CEC and
* makes the source device follow this power state.
*/
public static final int KEYCODE_TV_POWER = 177;
/** Key code constant: TV input key.
* On TV remotes, switches the input on a television screen. */
public static final int KEYCODE_TV_INPUT = 178;
/** Key code constant: Set-top-box power key.
* On TV remotes, toggles the power on an external Set-top-box. */
public static final int KEYCODE_STB_POWER = 179;
/** Key code constant: Set-top-box input key.
* On TV remotes, switches the input mode on an external Set-top-box. */
public static final int KEYCODE_STB_INPUT = 180;
/** Key code constant: A/V Receiver power key.
* On TV remotes, toggles the power on an external A/V Receiver. */
public static final int KEYCODE_AVR_POWER = 181;
/** Key code constant: A/V Receiver input key.
* On TV remotes, switches the input mode on an external A/V Receiver. */
public static final int KEYCODE_AVR_INPUT = 182;
/** Key code constant: Red "programmable" key.
* On TV remotes, acts as a contextual/programmable key. */
public static final int KEYCODE_PROG_RED = 183;
/** Key code constant: Green "programmable" key.
* On TV remotes, actsas a contextual/programmable key. */
public static final int KEYCODE_PROG_GREEN = 184;
/** Key code constant: Yellow "programmable" key.
* On TV remotes, acts as a contextual/programmable key. */
public static final int KEYCODE_PROG_YELLOW = 185;
/** Key code constant: Blue "programmable" key.
* On TV remotes, acts as a contextual/programmable key. */
public static final int KEYCODE_PROG_BLUE = 186;
/** Key code constant: App switch key.
* Should bring up the application switcher dialog. */
public static final int KEYCODE_APP_SWITCH = 187;
/** Key code constant: Generic Game Pad Button #1.*/
public static final int KEYCODE_BUTTON_1 = 188;
/** Key code constant: Generic Game Pad Button #2.*/
public static final int KEYCODE_BUTTON_2 = 189;
/** Key code constant: Generic Game Pad Button #3.*/
public static final int KEYCODE_BUTTON_3 = 190;
/** Key code constant: Generic Game Pad Button #4.*/
public static final int KEYCODE_BUTTON_4 = 191;
/** Key code constant: Generic Game Pad Button #5.*/
public static final int KEYCODE_BUTTON_5 = 192;
/** Key code constant: Generic Game Pad Button #6.*/
public static final int KEYCODE_BUTTON_6 = 193;
/** Key code constant: Generic Game Pad Button #7.*/
public static final int KEYCODE_BUTTON_7 = 194;
/** Key code constant: Generic Game Pad Button #8.*/
public static final int KEYCODE_BUTTON_8 = 195;
/** Key code constant: Generic Game Pad Button #9.*/
public static final int KEYCODE_BUTTON_9 = 196;
/** Key code constant: Generic Game Pad Button #10.*/
public static final int KEYCODE_BUTTON_10 = 197;
/** Key code constant: Generic Game Pad Button #11.*/
public static final int KEYCODE_BUTTON_11 = 198;
/** Key code constant: Generic Game Pad Button #12.*/
public static final int KEYCODE_BUTTON_12 = 199;
/** Key code constant: Generic Game Pad Button #13.*/
public static final int KEYCODE_BUTTON_13 = 200;
/** Key code constant: Generic Game Pad Button #14.*/
public static final int KEYCODE_BUTTON_14 = 201;
/** Key code constant: Generic Game Pad Button #15.*/
public static final int KEYCODE_BUTTON_15 = 202;
/** Key code constant: Generic Game Pad Button #16.*/
public static final int KEYCODE_BUTTON_16 = 203;
/** Key code constant: Language Switch key.
* Toggles the current input language such as switching between English and Japanese on
* a QWERTY keyboard. On some devices, the same function may be performed by
* pressing Shift+Spacebar. */
public static final int KEYCODE_LANGUAGE_SWITCH = 204;
/** Key code constant: Manner Mode key.
* Toggles silent or vibrate mode on and off to make the device behave more politely
* in certain settings such as on a crowded train. On some devices, the key may only
* operate when long-pressed. */
public static final int KEYCODE_MANNER_MODE = 205;
/** Key code constant: 3D Mode key.
* Toggles the display between 2D and 3D mode. */
public static final int KEYCODE_3D_MODE = 206;
/** Key code constant: Contacts special function key.
* Used to launch an address book application. */
public static final int KEYCODE_CONTACTS = 207;
/** Key code constant: Calendar special function key.
* Used to launch a calendar application. */
public static final int KEYCODE_CALENDAR = 208;
/** Key code constant: Music special function key.
* Used to launch a music player application. */
public static final int KEYCODE_MUSIC = 209;
/** Key code constant: Calculator special function key.
* Used to launch a calculator application. */
public static final int KEYCODE_CALCULATOR = 210;
/** Key code constant: Japanese full-width / half-width key. */
public static final int KEYCODE_ZENKAKU_HANKAKU = 211;
/** Key code constant: Japanese alphanumeric key. */
public static final int KEYCODE_EISU = 212;
/** Key code constant: Japanese non-conversion key. */
public static final int KEYCODE_MUHENKAN = 213;
/** Key code constant: Japanese conversion key. */
public static final int KEYCODE_HENKAN = 214;
/** Key code constant: Japanese katakana / hiragana key. */
public static final int KEYCODE_KATAKANA_HIRAGANA = 215;
/** Key code constant: Japanese Yen key. */
public static final int KEYCODE_YEN = 216;
/** Key code constant: Japanese Ro key. */
public static final int KEYCODE_RO = 217;
/** Key code constant: Japanese kana key. */
public static final int KEYCODE_KANA = 218;
/** Key code constant: Assist key.
* Launches the global assist activity. Not delivered to applications. */
public static final int KEYCODE_ASSIST = 219;
/** Key code constant: Brightness Down key.
* Adjusts the screen brightness down. */
public static final int KEYCODE_BRIGHTNESS_DOWN = 220;
/** Key code constant: Brightness Up key.
* Adjusts the screen brightness up. */
public static final int KEYCODE_BRIGHTNESS_UP = 221;
/** Key code constant: Audio Track key.
* Switches the audio tracks. */
public static final int KEYCODE_MEDIA_AUDIO_TRACK = 222;
/** Key code constant: Sleep key.
* Puts the device to sleep. Behaves somewhat like {@link #KEYCODE_POWER} but it
* has no effect if the device is already asleep. */
public static final int KEYCODE_SLEEP = 223;
/** Key code constant: Wakeup key.
* Wakes up the device. Behaves somewhat like {@link #KEYCODE_POWER} but it
* has no effect if the device is already awake. */
public static final int KEYCODE_WAKEUP = 224;
/** Key code constant: Pairing key.
* Initiates peripheral pairing mode. Useful for pairing remote control
* devices or game controllers, especially if no other input mode is
* available. */
public static final int KEYCODE_PAIRING = 225;
/** Key code constant: Media Top Menu key.
* Goes to the top of media menu. */
public static final int KEYCODE_MEDIA_TOP_MENU = 226;
/** Key code constant: '11' key. */
public static final int KEYCODE_11 = 227;
/** Key code constant: '12' key. */
public static final int KEYCODE_12 = 228;
/** Key code constant: Last Channel key.
* Goes to the last viewed channel. */
public static final int KEYCODE_LAST_CHANNEL = 229;
/** Key code constant: TV data service key.
* Displays data services like weather, sports. */
public static final int KEYCODE_TV_DATA_SERVICE = 230;
/** Key code constant: Voice Assist key.
* Launches the global voice assist activity. Not delivered to applications. */
public static final int KEYCODE_VOICE_ASSIST = 231;
/** Key code constant: Radio key.
* Toggles TV service / Radio service. */
public static final int KEYCODE_TV_RADIO_SERVICE = 232;
/** Key code constant: Teletext key.
* Displays Teletext service. */
public static final int KEYCODE_TV_TELETEXT = 233;
/** Key code constant: Number entry key.
* Initiates to enter multi-digit channel nubmber when each digit key is assigned
* for selecting separate channel. Corresponds to Number Entry Mode (0x1D) of CEC
* User Control Code. */
public static final int KEYCODE_TV_NUMBER_ENTRY = 234;
/** Key code constant: Analog Terrestrial key.
* Switches to analog terrestrial broadcast service. */
public static final int KEYCODE_TV_TERRESTRIAL_ANALOG = 235;
/** Key code constant: Digital Terrestrial key.
* Switches to digital terrestrial broadcast service. */
public static final int KEYCODE_TV_TERRESTRIAL_DIGITAL = 236;
/** Key code constant: Satellite key.
* Switches to digital satellite broadcast service. */
public static final int KEYCODE_TV_SATELLITE = 237;
/** Key code constant: BS key.
* Switches to BS digital satellite broadcasting service available in Japan. */
public static final int KEYCODE_TV_SATELLITE_BS = 238;
/** Key code constant: CS key.
* Switches to CS digital satellite broadcasting service available in Japan. */
public static final int KEYCODE_TV_SATELLITE_CS = 239;
/** Key code constant: BS/CS key.
* Toggles between BS and CS digital satellite services. */
public static final int KEYCODE_TV_SATELLITE_SERVICE = 240;
/** Key code constant: Toggle Network key.
* Toggles selecting broacast services. */
public static final int KEYCODE_TV_NETWORK = 241;
/** Key code constant: Antenna/Cable key.
* Toggles broadcast input source between antenna and cable. */
public static final int KEYCODE_TV_ANTENNA_CABLE = 242;
/** Key code constant: HDMI #1 key.
* Switches to HDMI input #1. */
public static final int KEYCODE_TV_INPUT_HDMI_1 = 243;
/** Key code constant: HDMI #2 key.
* Switches to HDMI input #2. */
public static final int KEYCODE_TV_INPUT_HDMI_2 = 244;
/** Key code constant: HDMI #3 key.
* Switches to HDMI input #3. */
public static final int KEYCODE_TV_INPUT_HDMI_3 = 245;
/** Key code constant: HDMI #4 key.
* Switches to HDMI input #4. */
public static final int KEYCODE_TV_INPUT_HDMI_4 = 246;
/** Key code constant: Composite #1 key.
* Switches to composite video input #1. */
public static final int KEYCODE_TV_INPUT_COMPOSITE_1 = 247;
/** Key code constant: Composite #2 key.
* Switches to composite video input #2. */
public static final int KEYCODE_TV_INPUT_COMPOSITE_2 = 248;
/** Key code constant: Component #1 key.
* Switches to component video input #1. */
public static final int KEYCODE_TV_INPUT_COMPONENT_1 = 249;
/** Key code constant: Component #2 key.
* Switches to component video input #2. */
public static final int KEYCODE_TV_INPUT_COMPONENT_2 = 250;
/** Key code constant: VGA #1 key.
* Switches to VGA (analog RGB) input #1. */
public static final int KEYCODE_TV_INPUT_VGA_1 = 251;
/** Key code constant: Audio description key.
* Toggles audio description off / on. */
public static final int KEYCODE_TV_AUDIO_DESCRIPTION = 252;
/** Key code constant: Audio description mixing volume up key.
* Louden audio description volume as compared with normal audio volume. */
public static final int KEYCODE_TV_AUDIO_DESCRIPTION_MIX_UP = 253;
/** Key code constant: Audio description mixing volume down key.
* Lessen audio description volume as compared with normal audio volume. */
public static final int KEYCODE_TV_AUDIO_DESCRIPTION_MIX_DOWN = 254;
/** Key code constant: Zoom mode key.
* Changes Zoom mode (Normal, Full, Zoom, Wide-zoom, etc.) */
public static final int KEYCODE_TV_ZOOM_MODE = 255;
/** Key code constant: Contents menu key.
* Goes to the title list. Corresponds to Contents Menu (0x0B) of CEC User Control
* Code */
public static final int KEYCODE_TV_CONTENTS_MENU = 256;
/** Key code constant: Media context menu key.
* Goes to the context menu of media contents. Corresponds to Media Context-sensitive
* Menu (0x11) of CEC User Control Code. */
public static final int KEYCODE_TV_MEDIA_CONTEXT_MENU = 257;
/** Key code constant: Timer programming key.
* Goes to the timer recording menu. Corresponds to Timer Programming (0x54) of
* CEC User Control Code. */
public static final int KEYCODE_TV_TIMER_PROGRAMMING = 258;
/** Key code constant: Help key. */
public static final int KEYCODE_HELP = 259;
/** Key code constant: Navigate to previous key.
* Goes backward by one item in an ordered collection of items. */
public static final int KEYCODE_NAVIGATE_PREVIOUS = 260;
/** Key code constant: Navigate to next key.
* Advances to the next item in an ordered collection of items. */
public static final int KEYCODE_NAVIGATE_NEXT = 261;
/** Key code constant: Navigate in key.
* Activates the item that currently has focus or expands to the next level of a navigation
* hierarchy. */
public static final int KEYCODE_NAVIGATE_IN = 262;
/** Key code constant: Navigate out key.
* Backs out one level of a navigation hierarchy or collapses the item that currently has
* focus. */
public static final int KEYCODE_NAVIGATE_OUT = 263;
/** Key code constant: Primary stem key for Wear
* Main power/reset button on watch. */
public static final int KEYCODE_STEM_PRIMARY = 264;
/** Key code constant: Generic stem key 1 for Wear */
public static final int KEYCODE_STEM_1 = 265;
/** Key code constant: Generic stem key 2 for Wear */
public static final int KEYCODE_STEM_2 = 266;
/** Key code constant: Generic stem key 3 for Wear */
public static final int KEYCODE_STEM_3 = 267;
/** Key code constant: Directional Pad Up-Left */
public static final int KEYCODE_DPAD_UP_LEFT = 268;
/** Key code constant: Directional Pad Down-Left */
public static final int KEYCODE_DPAD_DOWN_LEFT = 269;
/** Key code constant: Directional Pad Up-Right */
public static final int KEYCODE_DPAD_UP_RIGHT = 270;
/** Key code constant: Directional Pad Down-Right */
public static final int KEYCODE_DPAD_DOWN_RIGHT = 271;
/** Key code constant: Skip forward media key. */
public static final int KEYCODE_MEDIA_SKIP_FORWARD = 272;
/** Key code constant: Skip backward media key. */
public static final int KEYCODE_MEDIA_SKIP_BACKWARD = 273;
/** Key code constant: Step forward media key.
* Steps media forward, one frame at a time. */
public static final int KEYCODE_MEDIA_STEP_FORWARD = 274;
/** Key code constant: Step backward media key.
* Steps media backward, one frame at a time. */
public static final int KEYCODE_MEDIA_STEP_BACKWARD = 275;
/** Key code constant: put device to sleep unless a wakelock is held. */
public static final int KEYCODE_SOFT_SLEEP = 276;
/** Key code constant: Cut key. */
public static final int KEYCODE_CUT = 277;
/** Key code constant: Copy key. */
public static final int KEYCODE_COPY = 278;
/** Key code constant: Paste key. */
public static final int KEYCODE_PASTE = 279;
/** Key code constant: Consumed by the system for navigation up */
public static final int KEYCODE_SYSTEM_NAVIGATION_UP = 280;
/** Key code constant: Consumed by the system for navigation down */
public static final int KEYCODE_SYSTEM_NAVIGATION_DOWN = 281;
/** Key code constant: Consumed by the system for navigation left*/
public static final int KEYCODE_SYSTEM_NAVIGATION_LEFT = 282;
/** Key code constant: Consumed by the system for navigation right */
public static final int KEYCODE_SYSTEM_NAVIGATION_RIGHT = 283;
/** Key code constant: Show all apps */
public static final int KEYCODE_ALL_APPS = 284;
/** Key code constant: Refresh key. */
public static final int KEYCODE_REFRESH = 285;
/** Key code constant: Thumbs up key. Apps can use this to let user upvote content. */
public static final int KEYCODE_THUMBS_UP = 286;
/** Key code constant: Thumbs down key. Apps can use this to let user downvote content. */
public static final int KEYCODE_THUMBS_DOWN = 287;
/**
* Key code constant: Used to switch current {@link android.accounts.Account} that is
* consuming content. May be consumed by system to set account globally.
*/
public static final int KEYCODE_PROFILE_SWITCH = 288;
/** Key code constant: Video Application key #1. */
public static final int KEYCODE_VIDEO_APP_1 = 289;
/** Key code constant: Video Application key #2. */
public static final int KEYCODE_VIDEO_APP_2 = 290;
/** Key code constant: Video Application key #3. */
public static final int KEYCODE_VIDEO_APP_3 = 291;
/** Key code constant: Video Application key #4. */
public static final int KEYCODE_VIDEO_APP_4 = 292;
/** Key code constant: Video Application key #5. */
public static final int KEYCODE_VIDEO_APP_5 = 293;
/** Key code constant: Video Application key #6. */
public static final int KEYCODE_VIDEO_APP_6 = 294;
/** Key code constant: Video Application key #7. */
public static final int KEYCODE_VIDEO_APP_7 = 295;
/** Key code constant: Video Application key #8. */
public static final int KEYCODE_VIDEO_APP_8 = 296;
/** Key code constant: Featured Application key #1. */
public static final int KEYCODE_FEATURED_APP_1 = 297;
/** Key code constant: Featured Application key #2. */
public static final int KEYCODE_FEATURED_APP_2 = 298;
/** Key code constant: Featured Application key #3. */
public static final int KEYCODE_FEATURED_APP_3 = 299;
/** Key code constant: Featured Application key #4. */
public static final int KEYCODE_FEATURED_APP_4 = 300;
/** Key code constant: Demo Application key #1. */
public static final int KEYCODE_DEMO_APP_1 = 301;
/** Key code constant: Demo Application key #2. */
public static final int KEYCODE_DEMO_APP_2 = 302;
/** Key code constant: Demo Application key #3. */
public static final int KEYCODE_DEMO_APP_3 = 303;
/** Key code constant: Demo Application key #4. */
public static final int KEYCODE_DEMO_APP_4 = 304;
/**
* Integer value of the last KEYCODE. Increases as new keycodes are added to KeyEvent.
* @hide
*/
@TestApi
public static final int LAST_KEYCODE = KEYCODE_DEMO_APP_4;
// NOTE: If you add a new keycode here you must also add it to:
// isSystem()
// isWakeKey()
// frameworks/native/include/android/keycodes.h
// frameworks/native/include/input/InputEventLabels.h
// frameworks/base/core/res/res/values/attrs.xml
// emulator?
// LAST_KEYCODE
//
// Also Android currently does not reserve code ranges for vendor-
// specific key codes. If you have new key codes to have, you
// MUST contribute a patch to the open source project to define
// those new codes. This is intended to maintain a consistent
// set of key code definitions across all Android devices.
// Symbolic names of all metakeys in bit order from least significant to most significant.
// Accordingly there are exactly 32 values in this table.
@UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553)
private static final String[] META_SYMBOLIC_NAMES = new String[] {
"META_SHIFT_ON",
"META_ALT_ON",
"META_SYM_ON",
"META_FUNCTION_ON",
"META_ALT_LEFT_ON",
"META_ALT_RIGHT_ON",
"META_SHIFT_LEFT_ON",
"META_SHIFT_RIGHT_ON",
"META_CAP_LOCKED",
"META_ALT_LOCKED",
"META_SYM_LOCKED",
"0x00000800",
"META_CTRL_ON",
"META_CTRL_LEFT_ON",
"META_CTRL_RIGHT_ON",
"0x00008000",
"META_META_ON",
"META_META_LEFT_ON",
"META_META_RIGHT_ON",
"0x00080000",
"META_CAPS_LOCK_ON",
"META_NUM_LOCK_ON",
"META_SCROLL_LOCK_ON",
"0x00800000",
"0x01000000",
"0x02000000",
"0x04000000",
"0x08000000",
"0x10000000",
"0x20000000",
"0x40000000",
"0x80000000",
};
private static final String LABEL_PREFIX = "KEYCODE_";
/**
* @deprecated There are now more than MAX_KEYCODE keycodes.
* Use {@link #getMaxKeyCode()} instead.
*/
@Deprecated
public static final int MAX_KEYCODE = 84;
/**
* {@link #getAction} value: the key has been pressed down.
*/
public static final int ACTION_DOWN = 0;
/**
* {@link #getAction} value: the key has been released.
*/
public static final int ACTION_UP = 1;
/**
* @deprecated No longer used by the input system.
* {@link #getAction} value: multiple duplicate key events have
* occurred in a row, or a complex string is being delivered. If the
* key code is not {@link #KEYCODE_UNKNOWN} then the
* {@link #getRepeatCount()} method returns the number of times
* the given key code should be executed.
* Otherwise, if the key code is {@link #KEYCODE_UNKNOWN}, then
* this is a sequence of characters as returned by {@link #getCharacters}.
*/
@Deprecated
public static final int ACTION_MULTIPLE = 2;
/**
* SHIFT key locked in CAPS mode.
* Reserved for use by {@link MetaKeyKeyListener} for a published constant in its API.
* @hide
*/
@UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553)
public static final int META_CAP_LOCKED = 0x100;
/**
* ALT key locked.
* Reserved for use by {@link MetaKeyKeyListener} for a published constant in its API.
* @hide
*/
@UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553)
public static final int META_ALT_LOCKED = 0x200;
/**
* SYM key locked.
* Reserved for use by {@link MetaKeyKeyListener} for a published constant in its API.
* @hide
*/
@UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553)
public static final int META_SYM_LOCKED = 0x400;
/**
* Text is in selection mode.
* Reserved for use by {@link MetaKeyKeyListener} for a private unpublished constant
* in its API that is currently being retained for legacy reasons.
* @hide
*/
@UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553)
public static final int META_SELECTING = 0x800;
/**
* This mask is used to check whether one of the ALT meta keys is pressed.
*
* @see #isAltPressed()
* @see #getMetaState()
* @see #KEYCODE_ALT_LEFT
* @see #KEYCODE_ALT_RIGHT
*/
public static final int META_ALT_ON = 0x02;
/**
* This mask is used to check whether the left ALT meta key is pressed.
*
* @see #isAltPressed()
* @see #getMetaState()
* @see #KEYCODE_ALT_LEFT
*/
public static final int META_ALT_LEFT_ON = 0x10;
/**
* This mask is used to check whether the right the ALT meta key is pressed.
*
* @see #isAltPressed()
* @see #getMetaState()
* @see #KEYCODE_ALT_RIGHT
*/
public static final int META_ALT_RIGHT_ON = 0x20;
/**
* This mask is used to check whether one of the SHIFT meta keys is pressed.
*
* @see #isShiftPressed()
* @see #getMetaState()
* @see #KEYCODE_SHIFT_LEFT
* @see #KEYCODE_SHIFT_RIGHT
*/
public static final int META_SHIFT_ON = 0x1;
/**
* This mask is used to check whether the left SHIFT meta key is pressed.
*
* @see #isShiftPressed()
* @see #getMetaState()
* @see #KEYCODE_SHIFT_LEFT
*/
public static final int META_SHIFT_LEFT_ON = 0x40;
/**
* This mask is used to check whether the right SHIFT meta key is pressed.
*
* @see #isShiftPressed()
* @see #getMetaState()
* @see #KEYCODE_SHIFT_RIGHT
*/
public static final int META_SHIFT_RIGHT_ON = 0x80;
/**
* This mask is used to check whether the SYM meta key is pressed.
*
* @see #isSymPressed()
* @see #getMetaState()
*/
public static final int META_SYM_ON = 0x4;
/**
* This mask is used to check whether the FUNCTION meta key is pressed.
*
* @see #isFunctionPressed()
* @see #getMetaState()
*/
public static final int META_FUNCTION_ON = 0x8;
/**
* This mask is used to check whether one of the CTRL meta keys is pressed.
*
* @see #isCtrlPressed()
* @see #getMetaState()
* @see #KEYCODE_CTRL_LEFT
* @see #KEYCODE_CTRL_RIGHT
*/
public static final int META_CTRL_ON = 0x1000;
/**
* This mask is used to check whether the left CTRL meta key is pressed.
*
* @see #isCtrlPressed()
* @see #getMetaState()
* @see #KEYCODE_CTRL_LEFT
*/
public static final int META_CTRL_LEFT_ON = 0x2000;
/**
* This mask is used to check whether the right CTRL meta key is pressed.
*
* @see #isCtrlPressed()
* @see #getMetaState()
* @see #KEYCODE_CTRL_RIGHT
*/
public static final int META_CTRL_RIGHT_ON = 0x4000;
/**
* This mask is used to check whether one of the META meta keys is pressed.
*
* @see #isMetaPressed()
* @see #getMetaState()
* @see #KEYCODE_META_LEFT
* @see #KEYCODE_META_RIGHT
*/
public static final int META_META_ON = 0x10000;
/**
* This mask is used to check whether the left META meta key is pressed.
*
* @see #isMetaPressed()
* @see #getMetaState()
* @see #KEYCODE_META_LEFT
*/
public static final int META_META_LEFT_ON = 0x20000;
/**
* This mask is used to check whether the right META meta key is pressed.
*
* @see #isMetaPressed()
* @see #getMetaState()
* @see #KEYCODE_META_RIGHT
*/
public static final int META_META_RIGHT_ON = 0x40000;
/**
* This mask is used to check whether the CAPS LOCK meta key is on.
*
* @see #isCapsLockOn()
* @see #getMetaState()
* @see #KEYCODE_CAPS_LOCK
*/
public static final int META_CAPS_LOCK_ON = 0x100000;
/**
* This mask is used to check whether the NUM LOCK meta key is on.
*
* @see #isNumLockOn()
* @see #getMetaState()
* @see #KEYCODE_NUM_LOCK
*/
public static final int META_NUM_LOCK_ON = 0x200000;
/**
* This mask is used to check whether the SCROLL LOCK meta key is on.
*
* @see #isScrollLockOn()
* @see #getMetaState()
* @see #KEYCODE_SCROLL_LOCK
*/
public static final int META_SCROLL_LOCK_ON = 0x400000;
/**
* This mask is a combination of {@link #META_SHIFT_ON}, {@link #META_SHIFT_LEFT_ON}
* and {@link #META_SHIFT_RIGHT_ON}.
*/
public static final int META_SHIFT_MASK = META_SHIFT_ON
| META_SHIFT_LEFT_ON | META_SHIFT_RIGHT_ON;
/**
* This mask is a combination of {@link #META_ALT_ON}, {@link #META_ALT_LEFT_ON}
* and {@link #META_ALT_RIGHT_ON}.
*/
public static final int META_ALT_MASK = META_ALT_ON
| META_ALT_LEFT_ON | META_ALT_RIGHT_ON;
/**
* This mask is a combination of {@link #META_CTRL_ON}, {@link #META_CTRL_LEFT_ON}
* and {@link #META_CTRL_RIGHT_ON}.
*/
public static final int META_CTRL_MASK = META_CTRL_ON
| META_CTRL_LEFT_ON | META_CTRL_RIGHT_ON;
/**
* This mask is a combination of {@link #META_META_ON}, {@link #META_META_LEFT_ON}
* and {@link #META_META_RIGHT_ON}.
*/
public static final int META_META_MASK = META_META_ON
| META_META_LEFT_ON | META_META_RIGHT_ON;
/**
* This mask is set if the device woke because of this key event.
*
* @deprecated This flag will never be set by the system since the system
* consumes all wake keys itself.
*/
@Deprecated
public static final int FLAG_WOKE_HERE = 0x1;
/**
* This mask is set if the key event was generated by a software keyboard.
*/
public static final int FLAG_SOFT_KEYBOARD = 0x2;
/**
* This mask is set if we don't want the key event to cause us to leave
* touch mode.
*/
public static final int FLAG_KEEP_TOUCH_MODE = 0x4;
/**
* This mask is set if an event was known to come from a trusted part
* of the system. That is, the event is known to come from the user,
* and could not have been spoofed by a third party component.
*/
public static final int FLAG_FROM_SYSTEM = 0x8;
/**
* This mask is used for compatibility, to identify enter keys that are
* coming from an IME whose enter key has been auto-labelled "next" or
* "done". This allows TextView to dispatch these as normal enter keys
* for old applications, but still do the appropriate action when
* receiving them.
*/
public static final int FLAG_EDITOR_ACTION = 0x10;
/**
* When associated with up key events, this indicates that the key press
* has been canceled. Typically this is used with virtual touch screen
* keys, where the user can slide from the virtual key area on to the
* display: in that case, the application will receive a canceled up
* event and should not perform the action normally associated with the
* key. Note that for this to work, the application can not perform an
* action for a key until it receives an up or the long press timeout has
* expired.
*/
public static final int FLAG_CANCELED = 0x20;
/**
* This key event was generated by a virtual (on-screen) hard key area.
* Typically this is an area of the touchscreen, outside of the regular
* display, dedicated to "hardware" buttons.
*/
public static final int FLAG_VIRTUAL_HARD_KEY = 0x40;
/**
* This flag is set for the first key repeat that occurs after the
* long press timeout.
*/
public static final int FLAG_LONG_PRESS = 0x80;
/**
* Set when a key event has {@link #FLAG_CANCELED} set because a long
* press action was executed while it was down.
*/
public static final int FLAG_CANCELED_LONG_PRESS = 0x100;
/**
* Set for {@link #ACTION_UP} when this event's key code is still being
* tracked from its initial down. That is, somebody requested that tracking
* started on the key down and a long press has not caused
* the tracking to be canceled.
*/
public static final int FLAG_TRACKING = 0x200;
/**
* Set when a key event has been synthesized to implement default behavior
* for an event that the application did not handle.
* Fallback key events are generated by unhandled trackball motions
* (to emulate a directional keypad) and by certain unhandled key presses
* that are declared in the key map (such as special function numeric keypad
* keys when numlock is off).
*/
public static final int FLAG_FALLBACK = 0x400;
/**
* This flag indicates that this event was modified by or generated from an accessibility
* service. Value = 0x800
* @hide
*/
@TestApi
public static final int FLAG_IS_ACCESSIBILITY_EVENT = INPUT_EVENT_FLAG_IS_ACCESSIBILITY_EVENT;
/**
* Signifies that the key is being predispatched.
* @hide
*/
public static final int FLAG_PREDISPATCH = 0x20000000;
/**
* Private control to determine when an app is tracking a key sequence.
* @hide
*/
public static final int FLAG_START_TRACKING = 0x40000000;
/**
* Private flag that indicates when the system has detected that this key event
* may be inconsistent with respect to the sequence of previously delivered key events,
* such as when a key up event is sent but the key was not down.
*
* @hide
* @see #isTainted
* @see #setTainted
*/
public static final int FLAG_TAINTED = 0x80000000;
/**
* Returns the maximum keycode.
*/
public static int getMaxKeyCode() {
return LAST_KEYCODE;
}
/**
* Get the character that is produced by putting accent on the character
* c.
* For example, getDeadChar('`', 'e') returns è.
*/
public static int getDeadChar(int accent, int c) {
return KeyCharacterMap.getDeadChar(accent, c);
}
static final boolean DEBUG = false;
static final String TAG = "KeyEvent";
private static final int MAX_RECYCLED = 10;
private static final Object gRecyclerLock = new Object();
private static int gRecyclerUsed;
private static KeyEvent gRecyclerTop;
private KeyEvent mNext;
private int mId;
@UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553)
private int mDeviceId;
@UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.P, trackingBug = 115609023)
private int mSource;
private int mDisplayId;
private @Nullable byte[] mHmac;
@UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553)
private int mMetaState;
@UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553)
private int mAction;
@UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553)
private int mKeyCode;
@UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553)
private int mScanCode;
@UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553)
private int mRepeatCount;
@UnsupportedAppUsage
private int mFlags;
/**
* The time when the key initially was pressed, in nanoseconds. Only millisecond precision is
* exposed as public api, so this must always be converted to / from milliseconds when used.
*/
private long mDownTime;
/**
* The time when the current key event occurred. If mAction is ACTION_DOWN, then this is equal
* to mDownTime. Only millisecond precision is exposed as public api, so this must always be
* converted to / from milliseconds when used.
*/
private long mEventTime;
@UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553)
private String mCharacters;
public interface Callback {
/**
* Called when a key down event has occurred. If you return true,
* you can first call {@link KeyEvent#startTracking()
* KeyEvent.startTracking()} to have the framework track the event
* through its {@link #onKeyUp(int, KeyEvent)} and also call your
* {@link #onKeyLongPress(int, KeyEvent)} if it occurs.
*
* @param keyCode The value in event.getKeyCode().
* @param event Description of the key event.
*
* @return If you handled the event, return true. If you want to allow
* the event to be handled by the next receiver, return false.
*/
boolean onKeyDown(int keyCode, KeyEvent event);
/**
* Called when a long press has occurred. If you return true,
* the final key up will have {@link KeyEvent#FLAG_CANCELED} and
* {@link KeyEvent#FLAG_CANCELED_LONG_PRESS} set. Note that in
* order to receive this callback, someone in the event change
* must return true from {@link #onKeyDown} and
* call {@link KeyEvent#startTracking()} on the event.
*
* @param keyCode The value in event.getKeyCode().
* @param event Description of the key event.
*
* @return If you handled the event, return true. If you want to allow
* the event to be handled by the next receiver, return false.
*/
boolean onKeyLongPress(int keyCode, KeyEvent event);
/**
* Called when a key up event has occurred.
*
* @param keyCode The value in event.getKeyCode().
* @param event Description of the key event.
*
* @return If you handled the event, return true. If you want to allow
* the event to be handled by the next receiver, return false.
*/
boolean onKeyUp(int keyCode, KeyEvent event);
/**
* Called when a user's interaction with an analog control, such as
* flinging a trackball, generates simulated down/up events for the same
* key multiple times in quick succession.
*
* @param keyCode The value in event.getKeyCode().
* @param count Number of pairs as returned by event.getRepeatCount().
* @param event Description of the key event.
*
* @return If you handled the event, return true. If you want to allow
* the event to be handled by the next receiver, return false.
*/
boolean onKeyMultiple(int keyCode, int count, KeyEvent event);
}
private static native String nativeKeyCodeToString(int keyCode);
private static native int nativeKeyCodeFromString(String keyCode);
private static native int nativeNextId();
private KeyEvent() {}
/**
* Create a new key event.
*
* @param action Action code: either {@link #ACTION_DOWN},
* {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}.
* @param code The key code.
*/
public KeyEvent(int action, int code) {
mId = nativeNextId();
mAction = action;
mKeyCode = code;
mRepeatCount = 0;
mDeviceId = KeyCharacterMap.VIRTUAL_KEYBOARD;
}
/**
* Create a new key event.
*
* @param downTime The time (in {@link android.os.SystemClock#uptimeMillis})
* at which this key code originally went down.
* @param eventTime The time (in {@link android.os.SystemClock#uptimeMillis})
* at which this event happened.
* @param action Action code: either {@link #ACTION_DOWN},
* {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}.
* @param code The key code.
* @param repeat A repeat count for down events (> 0 if this is after the
* initial down) or event count for multiple events.
*/
public KeyEvent(long downTime, long eventTime, int action,
int code, int repeat) {
mId = nativeNextId();
mDownTime = TimeUnit.NANOSECONDS.convert(downTime, TimeUnit.MILLISECONDS);
mEventTime = TimeUnit.NANOSECONDS.convert(eventTime, TimeUnit.MILLISECONDS);
mAction = action;
mKeyCode = code;
mRepeatCount = repeat;
mDeviceId = KeyCharacterMap.VIRTUAL_KEYBOARD;
}
/**
* Create a new key event.
*
* @param downTime The time (in {@link android.os.SystemClock#uptimeMillis})
* at which this key code originally went down.
* @param eventTime The time (in {@link android.os.SystemClock#uptimeMillis})
* at which this event happened.
* @param action Action code: either {@link #ACTION_DOWN},
* {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}.
* @param code The key code.
* @param repeat A repeat count for down events (> 0 if this is after the
* initial down) or event count for multiple events.
* @param metaState Flags indicating which meta keys are currently pressed.
*/
public KeyEvent(long downTime, long eventTime, int action,
int code, int repeat, int metaState) {
mId = nativeNextId();
mDownTime = TimeUnit.NANOSECONDS.convert(downTime, TimeUnit.MILLISECONDS);
mEventTime = TimeUnit.NANOSECONDS.convert(eventTime, TimeUnit.MILLISECONDS);
mAction = action;
mKeyCode = code;
mRepeatCount = repeat;
mMetaState = metaState;
mDeviceId = KeyCharacterMap.VIRTUAL_KEYBOARD;
}
/**
* Create a new key event.
*
* @param downTime The time (in {@link android.os.SystemClock#uptimeMillis})
* at which this key code originally went down.
* @param eventTime The time (in {@link android.os.SystemClock#uptimeMillis})
* at which this event happened.
* @param action Action code: either {@link #ACTION_DOWN},
* {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}.
* @param code The key code.
* @param repeat A repeat count for down events (> 0 if this is after the
* initial down) or event count for multiple events.
* @param metaState Flags indicating which meta keys are currently pressed.
* @param deviceId The device ID that generated the key event.
* @param scancode Raw device scan code of the event.
*/
public KeyEvent(long downTime, long eventTime, int action,
int code, int repeat, int metaState,
int deviceId, int scancode) {
mId = nativeNextId();
mDownTime = TimeUnit.NANOSECONDS.convert(downTime, TimeUnit.MILLISECONDS);
mEventTime = TimeUnit.NANOSECONDS.convert(eventTime, TimeUnit.MILLISECONDS);
mAction = action;
mKeyCode = code;
mRepeatCount = repeat;
mMetaState = metaState;
mDeviceId = deviceId;
mScanCode = scancode;
}
/**
* Create a new key event.
*
* @param downTime The time (in {@link android.os.SystemClock#uptimeMillis})
* at which this key code originally went down.
* @param eventTime The time (in {@link android.os.SystemClock#uptimeMillis})
* at which this event happened.
* @param action Action code: either {@link #ACTION_DOWN},
* {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}.
* @param code The key code.
* @param repeat A repeat count for down events (> 0 if this is after the
* initial down) or event count for multiple events.
* @param metaState Flags indicating which meta keys are currently pressed.
* @param deviceId The device ID that generated the key event.
* @param scancode Raw device scan code of the event.
* @param flags The flags for this key event
*/
public KeyEvent(long downTime, long eventTime, int action,
int code, int repeat, int metaState,
int deviceId, int scancode, int flags) {
mId = nativeNextId();
mDownTime = TimeUnit.NANOSECONDS.convert(downTime, TimeUnit.MILLISECONDS);
mEventTime = TimeUnit.NANOSECONDS.convert(eventTime, TimeUnit.MILLISECONDS);
mAction = action;
mKeyCode = code;
mRepeatCount = repeat;
mMetaState = metaState;
mDeviceId = deviceId;
mScanCode = scancode;
mFlags = flags;
}
/**
* Create a new key event.
*
* @param downTime The time (in {@link android.os.SystemClock#uptimeMillis})
* at which this key code originally went down.
* @param eventTime The time (in {@link android.os.SystemClock#uptimeMillis})
* at which this event happened.
* @param action Action code: either {@link #ACTION_DOWN},
* {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}.
* @param code The key code.
* @param repeat A repeat count for down events (> 0 if this is after the
* initial down) or event count for multiple events.
* @param metaState Flags indicating which meta keys are currently pressed.
* @param deviceId The device ID that generated the key event.
* @param scancode Raw device scan code of the event.
* @param flags The flags for this key event
* @param source The input source such as {@link InputDevice#SOURCE_KEYBOARD}.
*/
public KeyEvent(long downTime, long eventTime, int action,
int code, int repeat, int metaState,
int deviceId, int scancode, int flags, int source) {
mId = nativeNextId();
mDownTime = TimeUnit.NANOSECONDS.convert(downTime, TimeUnit.MILLISECONDS);
mEventTime = TimeUnit.NANOSECONDS.convert(eventTime, TimeUnit.MILLISECONDS);
mAction = action;
mKeyCode = code;
mRepeatCount = repeat;
mMetaState = metaState;
mDeviceId = deviceId;
mScanCode = scancode;
mFlags = flags;
mSource = source;
mDisplayId = INVALID_DISPLAY;
}
/**
* Create a new key event for a string of characters. The key code,
* action, repeat count and source will automatically be set to
* {@link #KEYCODE_UNKNOWN}, {@link #ACTION_MULTIPLE}, 0, and
* {@link InputDevice#SOURCE_KEYBOARD} for you.
*
* @param time The time (in {@link android.os.SystemClock#uptimeMillis})
* at which this event occured.
* @param characters The string of characters.
* @param deviceId The device ID that generated the key event.
* @param flags The flags for this key event
*/
public KeyEvent(long time, String characters, int deviceId, int flags) {
mId = nativeNextId();
mDownTime = TimeUnit.NANOSECONDS.convert(time, TimeUnit.MILLISECONDS);
mEventTime = TimeUnit.NANOSECONDS.convert(time, TimeUnit.MILLISECONDS);
mCharacters = characters;
mAction = ACTION_MULTIPLE;
mKeyCode = KEYCODE_UNKNOWN;
mRepeatCount = 0;
mDeviceId = deviceId;
mFlags = flags;
mSource = InputDevice.SOURCE_KEYBOARD;
mDisplayId = INVALID_DISPLAY;
}
/**
* Make an exact copy of an existing key event.
*/
public KeyEvent(KeyEvent origEvent) {
mId = origEvent.mId;
mDownTime = origEvent.mDownTime;
mEventTime = origEvent.mEventTime;
mAction = origEvent.mAction;
mKeyCode = origEvent.mKeyCode;
mRepeatCount = origEvent.mRepeatCount;
mMetaState = origEvent.mMetaState;
mDeviceId = origEvent.mDeviceId;
mSource = origEvent.mSource;
mDisplayId = origEvent.mDisplayId;
mHmac = origEvent.mHmac == null ? null : origEvent.mHmac.clone();
mScanCode = origEvent.mScanCode;
mFlags = origEvent.mFlags;
mCharacters = origEvent.mCharacters;
}
/**
* Copy an existing key event, modifying its time and repeat count.
*
* @deprecated Use {@link #changeTimeRepeat(KeyEvent, long, int)}
* instead.
*
* @param origEvent The existing event to be copied.
* @param eventTime The new event time
* (in {@link android.os.SystemClock#uptimeMillis}) of the event.
* @param newRepeat The new repeat count of the event.
*/
@Deprecated
public KeyEvent(KeyEvent origEvent, long eventTime, int newRepeat) {
mId = nativeNextId(); // Not an exact copy so assign a new ID.
mDownTime = origEvent.mDownTime;
mEventTime = TimeUnit.NANOSECONDS.convert(eventTime, TimeUnit.MILLISECONDS);
mAction = origEvent.mAction;
mKeyCode = origEvent.mKeyCode;
mRepeatCount = newRepeat;
mMetaState = origEvent.mMetaState;
mDeviceId = origEvent.mDeviceId;
mSource = origEvent.mSource;
mDisplayId = origEvent.mDisplayId;
mHmac = null; // Don't copy HMAC, it will be invalid because eventTime is changing
mScanCode = origEvent.mScanCode;
mFlags = origEvent.mFlags;
mCharacters = origEvent.mCharacters;
}
private static KeyEvent obtain() {
final KeyEvent ev;
synchronized (gRecyclerLock) {
ev = gRecyclerTop;
if (ev == null) {
return new KeyEvent();
}
gRecyclerTop = ev.mNext;
gRecyclerUsed -= 1;
}
ev.mNext = null;
ev.prepareForReuse();
return ev;
}
/**
* Obtains a (potentially recycled) key event. Used by native code to create a Java object.
*
* @hide
*/
private static KeyEvent obtain(int id, long downTimeNanos, long eventTimeNanos, int action,
int code, int repeat, int metaState,
int deviceId, int scancode, int flags, int source, int displayId, @Nullable byte[] hmac,
String characters) {
KeyEvent ev = obtain();
ev.mId = id;
ev.mDownTime = downTimeNanos;
ev.mEventTime = eventTimeNanos;
ev.mAction = action;
ev.mKeyCode = code;
ev.mRepeatCount = repeat;
ev.mMetaState = metaState;
ev.mDeviceId = deviceId;
ev.mScanCode = scancode;
ev.mFlags = flags;
ev.mSource = source;
ev.mDisplayId = displayId;
ev.mHmac = hmac;
ev.mCharacters = characters;
return ev;
}
/**
* Obtains a (potentially recycled) key event.
*
* @hide
*/
public static KeyEvent obtain(long downTime, long eventTime, int action,
int code, int repeat, int metaState,
int deviceId, int scanCode, int flags, int source, int displayId, String characters) {
downTime = TimeUnit.NANOSECONDS.convert(downTime, TimeUnit.MILLISECONDS);
eventTime = TimeUnit.NANOSECONDS.convert(eventTime, TimeUnit.MILLISECONDS);
return obtain(nativeNextId(), downTime, eventTime, action, code, repeat, metaState,
deviceId, scanCode, flags, source, displayId, null /* hmac */, characters);
}
/**
* Obtains a (potentially recycled) key event.
*
* @hide
*/
@UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553)
public static KeyEvent obtain(long downTime, long eventTime, int action,
int code, int repeat, int metaState,
int deviceId, int scancode, int flags, int source, String characters) {
// Do not convert downTime and eventTime here. We are calling the obtain method above,
// which will do the conversion. Just specify INVALID_DISPLAY and forward the request.
return obtain(downTime, eventTime, action, code, repeat, metaState, deviceId, scancode,
flags, source, INVALID_DISPLAY, characters);
}
/**
/**
* Obtains a (potentially recycled) copy of another key event.
*
* @hide
*/
public static KeyEvent obtain(KeyEvent other) {
KeyEvent ev = obtain();
ev.mId = other.mId;
ev.mDownTime = other.mDownTime;
ev.mEventTime = other.mEventTime;
ev.mAction = other.mAction;
ev.mKeyCode = other.mKeyCode;
ev.mRepeatCount = other.mRepeatCount;
ev.mMetaState = other.mMetaState;
ev.mDeviceId = other.mDeviceId;
ev.mScanCode = other.mScanCode;
ev.mFlags = other.mFlags;
ev.mSource = other.mSource;
ev.mDisplayId = other.mDisplayId;
ev.mHmac = other.mHmac == null ? null : other.mHmac.clone();
ev.mCharacters = other.mCharacters;
return ev;
}
/** @hide */
@Override
public KeyEvent copy() {
return obtain(this);
}
/**
* Recycles a key event.
* Key events should only be recycled if they are owned by the system since user
* code expects them to be essentially immutable, "tracking" notwithstanding.
*
* @hide
*/
@Override
@UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.P, trackingBug = 115609023)
public final void recycle() {
super.recycle();
mCharacters = null;
synchronized (gRecyclerLock) {
if (gRecyclerUsed < MAX_RECYCLED) {
gRecyclerUsed++;
mNext = gRecyclerTop;
gRecyclerTop = this;
}
}
}
/** @hide */
@Override
public final void recycleIfNeededAfterDispatch() {
// Do nothing.
}
/** @hide */
@Override
public int getId() {
return mId;
}
/**
* Create a new key event that is the same as the given one, but whose
* event time and repeat count are replaced with the given value.
*
* @param event The existing event to be copied. This is not modified.
* @param eventTime The new event time
* (in {@link android.os.SystemClock#uptimeMillis}) of the event.
* @param newRepeat The new repeat count of the event.
*/
public static KeyEvent changeTimeRepeat(KeyEvent event, long eventTime,
int newRepeat) {
return new KeyEvent(event, eventTime, newRepeat);
}
/**
* Create a new key event that is the same as the given one, but whose
* event time and repeat count are replaced with the given value.
*
* @param event The existing event to be copied. This is not modified.
* @param eventTime The new event time
* (in {@link android.os.SystemClock#uptimeMillis}) of the event.
* @param newRepeat The new repeat count of the event.
* @param newFlags New flags for the event, replacing the entire value
* in the original event.
*/
public static KeyEvent changeTimeRepeat(KeyEvent event, long eventTime,
int newRepeat, int newFlags) {
KeyEvent ret = new KeyEvent(event);
ret.mId = nativeNextId(); // Not an exact copy so assign a new ID.
ret.mEventTime = TimeUnit.NANOSECONDS.convert(eventTime, TimeUnit.MILLISECONDS);
ret.mRepeatCount = newRepeat;
ret.mFlags = newFlags;
return ret;
}
/**
* Copy an existing key event, modifying its action.
*
* @param origEvent The existing event to be copied.
* @param action The new action code of the event.
*/
private KeyEvent(KeyEvent origEvent, int action) {
mId = nativeNextId(); // Not an exact copy so assign a new ID.
mDownTime = origEvent.mDownTime;
mEventTime = origEvent.mEventTime;
mAction = action;
mKeyCode = origEvent.mKeyCode;
mRepeatCount = origEvent.mRepeatCount;
mMetaState = origEvent.mMetaState;
mDeviceId = origEvent.mDeviceId;
mSource = origEvent.mSource;
mDisplayId = origEvent.mDisplayId;
mHmac = null; // Don't copy the hmac, it will be invalid since action is changing
mScanCode = origEvent.mScanCode;
mFlags = origEvent.mFlags;
// Don't copy mCharacters, since one way or the other we'll lose it
// when changing the action.
}
/**
* Create a new key event that is the same as the given one, but whose
* action is replaced with the given value.
*
* @param event The existing event to be copied. This is not modified.
* @param action The new action code of the event.
*/
public static KeyEvent changeAction(KeyEvent event, int action) {
return new KeyEvent(event, action);
}
/**
* Create a new key event that is the same as the given one, but whose
* flags are replaced with the given value.
*
* @param event The existing event to be copied. This is not modified.
* @param flags The new flags constant.
*/
public static KeyEvent changeFlags(KeyEvent event, int flags) {
event = new KeyEvent(event);
event.mId = nativeNextId(); // Not an exact copy so assign a new ID.
event.mFlags = flags;
return event;
}
/** @hide */
@Override
public final boolean isTainted() {
return (mFlags & FLAG_TAINTED) != 0;
}
/** @hide */
@Override
public final void setTainted(boolean tainted) {
mFlags = tainted ? mFlags | FLAG_TAINTED : mFlags & ~FLAG_TAINTED;
}
/**
* Don't use in new code, instead explicitly check
* {@link #getAction()}.
*
* @return If the action is ACTION_DOWN, returns true; else false.
*
* @deprecated
* @hide
*/
@UnsupportedAppUsage
@Deprecated public final boolean isDown() {
return mAction == ACTION_DOWN;
}
/** Is this a system key? System keys can not be used for menu shortcuts.
*/
public final boolean isSystem() {
return isSystemKey(mKeyCode);
}
/** @hide */
public final boolean isWakeKey() {
return isWakeKey(mKeyCode);
}
/**
* Returns true if the specified keycode is a gamepad button.
* @return True if the keycode is a gamepad button, such as {@link #KEYCODE_BUTTON_A}.
*/
public static final boolean isGamepadButton(int keyCode) {
switch (keyCode) {
case KeyEvent.KEYCODE_BUTTON_A:
case KeyEvent.KEYCODE_BUTTON_B:
case KeyEvent.KEYCODE_BUTTON_C:
case KeyEvent.KEYCODE_BUTTON_X:
case KeyEvent.KEYCODE_BUTTON_Y:
case KeyEvent.KEYCODE_BUTTON_Z:
case KeyEvent.KEYCODE_BUTTON_L1:
case KeyEvent.KEYCODE_BUTTON_R1:
case KeyEvent.KEYCODE_BUTTON_L2:
case KeyEvent.KEYCODE_BUTTON_R2:
case KeyEvent.KEYCODE_BUTTON_THUMBL:
case KeyEvent.KEYCODE_BUTTON_THUMBR:
case KeyEvent.KEYCODE_BUTTON_START:
case KeyEvent.KEYCODE_BUTTON_SELECT:
case KeyEvent.KEYCODE_BUTTON_MODE:
case KeyEvent.KEYCODE_BUTTON_1:
case KeyEvent.KEYCODE_BUTTON_2:
case KeyEvent.KEYCODE_BUTTON_3:
case KeyEvent.KEYCODE_BUTTON_4:
case KeyEvent.KEYCODE_BUTTON_5:
case KeyEvent.KEYCODE_BUTTON_6:
case KeyEvent.KEYCODE_BUTTON_7:
case KeyEvent.KEYCODE_BUTTON_8:
case KeyEvent.KEYCODE_BUTTON_9:
case KeyEvent.KEYCODE_BUTTON_10:
case KeyEvent.KEYCODE_BUTTON_11:
case KeyEvent.KEYCODE_BUTTON_12:
case KeyEvent.KEYCODE_BUTTON_13:
case KeyEvent.KEYCODE_BUTTON_14:
case KeyEvent.KEYCODE_BUTTON_15:
case KeyEvent.KEYCODE_BUTTON_16:
return true;
default:
return false;
}
}
/** Whether key will, by default, trigger a click on the focused view.
* @hide
*/
@UnsupportedAppUsage
public static final boolean isConfirmKey(int keyCode) {
switch (keyCode) {
case KeyEvent.KEYCODE_DPAD_CENTER:
case KeyEvent.KEYCODE_ENTER:
case KeyEvent.KEYCODE_SPACE:
case KeyEvent.KEYCODE_NUMPAD_ENTER:
return true;
default:
return false;
}
}
/**
* Returns whether this key will be sent to the
* {@link android.media.session.MediaSession.Callback} if not handled.
*/
public static final boolean isMediaSessionKey(int keyCode) {
switch (keyCode) {
case KeyEvent.KEYCODE_MEDIA_PLAY:
case KeyEvent.KEYCODE_MEDIA_PAUSE:
case KeyEvent.KEYCODE_MEDIA_PLAY_PAUSE:
case KeyEvent.KEYCODE_MUTE:
case KeyEvent.KEYCODE_HEADSETHOOK:
case KeyEvent.KEYCODE_MEDIA_STOP:
case KeyEvent.KEYCODE_MEDIA_NEXT:
case KeyEvent.KEYCODE_MEDIA_PREVIOUS:
case KeyEvent.KEYCODE_MEDIA_REWIND:
case KeyEvent.KEYCODE_MEDIA_RECORD:
case KeyEvent.KEYCODE_MEDIA_FAST_FORWARD:
return true;
}
return false;
}
/** Is this a system key? System keys can not be used for menu shortcuts.
* @hide
*/
public static final boolean isSystemKey(int keyCode) {
switch (keyCode) {
case KeyEvent.KEYCODE_MENU:
case KeyEvent.KEYCODE_SOFT_RIGHT:
case KeyEvent.KEYCODE_HOME:
case KeyEvent.KEYCODE_BACK:
case KeyEvent.KEYCODE_CALL:
case KeyEvent.KEYCODE_ENDCALL:
case KeyEvent.KEYCODE_VOLUME_UP:
case KeyEvent.KEYCODE_VOLUME_DOWN:
case KeyEvent.KEYCODE_VOLUME_MUTE:
case KeyEvent.KEYCODE_MUTE:
case KeyEvent.KEYCODE_POWER:
case KeyEvent.KEYCODE_HEADSETHOOK:
case KeyEvent.KEYCODE_MEDIA_PLAY:
case KeyEvent.KEYCODE_MEDIA_PAUSE:
case KeyEvent.KEYCODE_MEDIA_PLAY_PAUSE:
case KeyEvent.KEYCODE_MEDIA_STOP:
case KeyEvent.KEYCODE_MEDIA_NEXT:
case KeyEvent.KEYCODE_MEDIA_PREVIOUS:
case KeyEvent.KEYCODE_MEDIA_REWIND:
case KeyEvent.KEYCODE_MEDIA_RECORD:
case KeyEvent.KEYCODE_MEDIA_FAST_FORWARD:
case KeyEvent.KEYCODE_CAMERA:
case KeyEvent.KEYCODE_FOCUS:
case KeyEvent.KEYCODE_SEARCH:
case KeyEvent.KEYCODE_BRIGHTNESS_DOWN:
case KeyEvent.KEYCODE_BRIGHTNESS_UP:
case KeyEvent.KEYCODE_MEDIA_AUDIO_TRACK:
case KeyEvent.KEYCODE_SYSTEM_NAVIGATION_UP:
case KeyEvent.KEYCODE_SYSTEM_NAVIGATION_DOWN:
case KeyEvent.KEYCODE_SYSTEM_NAVIGATION_LEFT:
case KeyEvent.KEYCODE_SYSTEM_NAVIGATION_RIGHT:
return true;
}
return false;
}
/** @hide */
public static final boolean isWakeKey(int keyCode) {
switch (keyCode) {
case KeyEvent.KEYCODE_CAMERA:
case KeyEvent.KEYCODE_MENU:
case KeyEvent.KEYCODE_PAIRING:
case KeyEvent.KEYCODE_STEM_1:
case KeyEvent.KEYCODE_STEM_2:
case KeyEvent.KEYCODE_STEM_3:
case KeyEvent.KEYCODE_WAKEUP:
return true;
}
return false;
}
/** @hide */
public static final boolean isMetaKey(int keyCode) {
return keyCode == KeyEvent.KEYCODE_META_LEFT || keyCode == KeyEvent.KEYCODE_META_RIGHT;
}
/** @hide */
public static final boolean isAltKey(int keyCode) {
return keyCode == KeyEvent.KEYCODE_ALT_LEFT || keyCode == KeyEvent.KEYCODE_ALT_RIGHT;
}
/** {@inheritDoc} */
@Override
public final int getDeviceId() {
return mDeviceId;
}
/** {@inheritDoc} */
@Override
public final int getSource() {
return mSource;
}
/** {@inheritDoc} */
@Override
public final void setSource(int source) {
mSource = source;
}
/** @hide */
@Override
public final int getDisplayId() {
return mDisplayId;
}
/** @hide */
@TestApi
@Override
public final void setDisplayId(int displayId) {
mDisplayId = displayId;
}
/**
* Returns the state of the meta keys.
*
* @return an integer in which each bit set to 1 represents a pressed
* meta key
*
* @see #isAltPressed()
* @see #isShiftPressed()
* @see #isSymPressed()
* @see #isCtrlPressed()
* @see #isMetaPressed()
* @see #isFunctionPressed()
* @see #isCapsLockOn()
* @see #isNumLockOn()
* @see #isScrollLockOn()
* @see #META_ALT_ON
* @see #META_ALT_LEFT_ON
* @see #META_ALT_RIGHT_ON
* @see #META_SHIFT_ON
* @see #META_SHIFT_LEFT_ON
* @see #META_SHIFT_RIGHT_ON
* @see #META_SYM_ON
* @see #META_FUNCTION_ON
* @see #META_CTRL_ON
* @see #META_CTRL_LEFT_ON
* @see #META_CTRL_RIGHT_ON
* @see #META_META_ON
* @see #META_META_LEFT_ON
* @see #META_META_RIGHT_ON
* @see #META_CAPS_LOCK_ON
* @see #META_NUM_LOCK_ON
* @see #META_SCROLL_LOCK_ON
* @see #getModifiers
*/
public final int getMetaState() {
return mMetaState;
}
/**
* Returns the state of the modifier keys.
*
* For the purposes of this function, {@link #KEYCODE_CAPS_LOCK},
* {@link #KEYCODE_SCROLL_LOCK}, and {@link #KEYCODE_NUM_LOCK} are
* not considered modifier keys. Consequently, this function specifically masks out
* {@link #META_CAPS_LOCK_ON}, {@link #META_SCROLL_LOCK_ON} and {@link #META_NUM_LOCK_ON}.
*
* The value returned consists of the meta state (from {@link #getMetaState})
* normalized using {@link #normalizeMetaState(int)} and then masked with
* {@link #getModifierMetaStateMask} so that only valid modifier bits are retained.
*
*
* @return An integer in which each bit set to 1 represents a pressed modifier key.
* @see #getMetaState
*/
public final int getModifiers() {
return normalizeMetaState(mMetaState) & META_MODIFIER_MASK;
}
/**
* Modifies the flags of the event.
*
* @param newFlags New flags for the event, replacing the entire value.
* @hide
*/
public final void setFlags(int newFlags) {
mFlags = newFlags;
}
/**
* Returns the flags for this key event.
*
* @see #FLAG_WOKE_HERE
*/
public final int getFlags() {
return mFlags;
}
// Mask of all modifier key meta states. Specifically excludes locked keys like caps lock.
@UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553)
private static final int META_MODIFIER_MASK =
META_SHIFT_ON | META_SHIFT_LEFT_ON | META_SHIFT_RIGHT_ON
| META_ALT_ON | META_ALT_LEFT_ON | META_ALT_RIGHT_ON
| META_CTRL_ON | META_CTRL_LEFT_ON | META_CTRL_RIGHT_ON
| META_META_ON | META_META_LEFT_ON | META_META_RIGHT_ON
| META_SYM_ON | META_FUNCTION_ON;
// Mask of all lock key meta states.
@UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553)
private static final int META_LOCK_MASK =
META_CAPS_LOCK_ON | META_NUM_LOCK_ON | META_SCROLL_LOCK_ON;
// Mask of all valid meta states.
@UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553)
private static final int META_ALL_MASK = META_MODIFIER_MASK | META_LOCK_MASK;
// Mask of all synthetic meta states that are reserved for API compatibility with
// historical uses in MetaKeyKeyListener.
@UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553)
private static final int META_SYNTHETIC_MASK =
META_CAP_LOCKED | META_ALT_LOCKED | META_SYM_LOCKED | META_SELECTING;
// Mask of all meta states that are not valid use in specifying a modifier key.
// These bits are known to be used for purposes other than specifying modifiers.
@UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553)
private static final int META_INVALID_MODIFIER_MASK =
META_LOCK_MASK | META_SYNTHETIC_MASK;
/**
* Gets a mask that includes all valid modifier key meta state bits.
*
* For the purposes of this function, {@link #KEYCODE_CAPS_LOCK},
* {@link #KEYCODE_SCROLL_LOCK}, and {@link #KEYCODE_NUM_LOCK} are
* not considered modifier keys. Consequently, the mask specifically excludes
* {@link #META_CAPS_LOCK_ON}, {@link #META_SCROLL_LOCK_ON} and {@link #META_NUM_LOCK_ON}.
*
*
* @return The modifier meta state mask which is a combination of
* {@link #META_SHIFT_ON}, {@link #META_SHIFT_LEFT_ON}, {@link #META_SHIFT_RIGHT_ON},
* {@link #META_ALT_ON}, {@link #META_ALT_LEFT_ON}, {@link #META_ALT_RIGHT_ON},
* {@link #META_CTRL_ON}, {@link #META_CTRL_LEFT_ON}, {@link #META_CTRL_RIGHT_ON},
* {@link #META_META_ON}, {@link #META_META_LEFT_ON}, {@link #META_META_RIGHT_ON},
* {@link #META_SYM_ON}, {@link #META_FUNCTION_ON}.
*/
public static int getModifierMetaStateMask() {
return META_MODIFIER_MASK;
}
/**
* Returns true if this key code is a modifier key.
*
* For the purposes of this function, {@link #KEYCODE_CAPS_LOCK},
* {@link #KEYCODE_SCROLL_LOCK}, and {@link #KEYCODE_NUM_LOCK} are
* not considered modifier keys. Consequently, this function return false
* for those keys.
*
*
* @return True if the key code is one of
* {@link #KEYCODE_SHIFT_LEFT} {@link #KEYCODE_SHIFT_RIGHT},
* {@link #KEYCODE_ALT_LEFT}, {@link #KEYCODE_ALT_RIGHT},
* {@link #KEYCODE_CTRL_LEFT}, {@link #KEYCODE_CTRL_RIGHT},
* {@link #KEYCODE_META_LEFT}, or {@link #KEYCODE_META_RIGHT},
* {@link #KEYCODE_SYM}, {@link #KEYCODE_NUM}, {@link #KEYCODE_FUNCTION}.
*/
public static boolean isModifierKey(int keyCode) {
switch (keyCode) {
case KEYCODE_SHIFT_LEFT:
case KEYCODE_SHIFT_RIGHT:
case KEYCODE_ALT_LEFT:
case KEYCODE_ALT_RIGHT:
case KEYCODE_CTRL_LEFT:
case KEYCODE_CTRL_RIGHT:
case KEYCODE_META_LEFT:
case KEYCODE_META_RIGHT:
case KEYCODE_SYM:
case KEYCODE_NUM:
case KEYCODE_FUNCTION:
return true;
default:
return false;
}
}
/**
* Normalizes the specified meta state.
*
* The meta state is normalized such that if either the left or right modifier meta state
* bits are set then the result will also include the universal bit for that modifier.
*
* If the specified meta state contains {@link #META_ALT_LEFT_ON} then
* the result will also contain {@link #META_ALT_ON} in addition to {@link #META_ALT_LEFT_ON}
* and the other bits that were specified in the input. The same is process is
* performed for shift, control and meta.
*
* If the specified meta state contains synthetic meta states defined by
* {@link MetaKeyKeyListener}, then those states are translated here and the original
* synthetic meta states are removed from the result.
* {@link MetaKeyKeyListener#META_CAP_LOCKED} is translated to {@link #META_CAPS_LOCK_ON}.
* {@link MetaKeyKeyListener#META_ALT_LOCKED} is translated to {@link #META_ALT_ON}.
* {@link MetaKeyKeyListener#META_SYM_LOCKED} is translated to {@link #META_SYM_ON}.
*
* Undefined meta state bits are removed.
*
*
* @param metaState The meta state.
* @return The normalized meta state.
*/
public static int normalizeMetaState(int metaState) {
if ((metaState & (META_SHIFT_LEFT_ON | META_SHIFT_RIGHT_ON)) != 0) {
metaState |= META_SHIFT_ON;
}
if ((metaState & (META_ALT_LEFT_ON | META_ALT_RIGHT_ON)) != 0) {
metaState |= META_ALT_ON;
}
if ((metaState & (META_CTRL_LEFT_ON | META_CTRL_RIGHT_ON)) != 0) {
metaState |= META_CTRL_ON;
}
if ((metaState & (META_META_LEFT_ON | META_META_RIGHT_ON)) != 0) {
metaState |= META_META_ON;
}
if ((metaState & MetaKeyKeyListener.META_CAP_LOCKED) != 0) {
metaState |= META_CAPS_LOCK_ON;
}
if ((metaState & MetaKeyKeyListener.META_ALT_LOCKED) != 0) {
metaState |= META_ALT_ON;
}
if ((metaState & MetaKeyKeyListener.META_SYM_LOCKED) != 0) {
metaState |= META_SYM_ON;
}
return metaState & META_ALL_MASK;
}
/**
* Returns true if no modifiers keys are pressed according to the specified meta state.
*
* For the purposes of this function, {@link #KEYCODE_CAPS_LOCK},
* {@link #KEYCODE_SCROLL_LOCK}, and {@link #KEYCODE_NUM_LOCK} are
* not considered modifier keys. Consequently, this function ignores
* {@link #META_CAPS_LOCK_ON}, {@link #META_SCROLL_LOCK_ON} and {@link #META_NUM_LOCK_ON}.
*
* The meta state is normalized prior to comparison using {@link #normalizeMetaState(int)}.
*
*
* @param metaState The meta state to consider.
* @return True if no modifier keys are pressed.
* @see #hasNoModifiers()
*/
public static boolean metaStateHasNoModifiers(int metaState) {
return (normalizeMetaState(metaState) & META_MODIFIER_MASK) == 0;
}
/**
* Returns true if only the specified modifier keys are pressed according to
* the specified meta state. Returns false if a different combination of modifier
* keys are pressed.
*
* For the purposes of this function, {@link #KEYCODE_CAPS_LOCK},
* {@link #KEYCODE_SCROLL_LOCK}, and {@link #KEYCODE_NUM_LOCK} are
* not considered modifier keys. Consequently, this function ignores
* {@link #META_CAPS_LOCK_ON}, {@link #META_SCROLL_LOCK_ON} and {@link #META_NUM_LOCK_ON}.
*
* If the specified modifier mask includes directional modifiers, such as
* {@link #META_SHIFT_LEFT_ON}, then this method ensures that the
* modifier is pressed on that side.
* If the specified modifier mask includes non-directional modifiers, such as
* {@link #META_SHIFT_ON}, then this method ensures that the modifier
* is pressed on either side.
* If the specified modifier mask includes both directional and non-directional modifiers
* for the same type of key, such as {@link #META_SHIFT_ON} and {@link #META_SHIFT_LEFT_ON},
* then this method throws an illegal argument exception.
*
*
* @param metaState The meta state to consider.
* @param modifiers The meta state of the modifier keys to check. May be a combination
* of modifier meta states as defined by {@link #getModifierMetaStateMask()}. May be 0 to
* ensure that no modifier keys are pressed.
* @return True if only the specified modifier keys are pressed.
* @throws IllegalArgumentException if the modifiers parameter contains invalid modifiers
* @see #hasModifiers
*/
public static boolean metaStateHasModifiers(int metaState, int modifiers) {
// Note: For forward compatibility, we allow the parameter to contain meta states
// that we do not recognize but we explicitly disallow meta states that
// are not valid modifiers.
if ((modifiers & META_INVALID_MODIFIER_MASK) != 0) {
throw new IllegalArgumentException("modifiers must not contain "
+ "META_CAPS_LOCK_ON, META_NUM_LOCK_ON, META_SCROLL_LOCK_ON, "
+ "META_CAP_LOCKED, META_ALT_LOCKED, META_SYM_LOCKED, "
+ "or META_SELECTING");
}
metaState = normalizeMetaState(metaState) & META_MODIFIER_MASK;
metaState = metaStateFilterDirectionalModifiers(metaState, modifiers,
META_SHIFT_ON, META_SHIFT_LEFT_ON, META_SHIFT_RIGHT_ON);
metaState = metaStateFilterDirectionalModifiers(metaState, modifiers,
META_ALT_ON, META_ALT_LEFT_ON, META_ALT_RIGHT_ON);
metaState = metaStateFilterDirectionalModifiers(metaState, modifiers,
META_CTRL_ON, META_CTRL_LEFT_ON, META_CTRL_RIGHT_ON);
metaState = metaStateFilterDirectionalModifiers(metaState, modifiers,
META_META_ON, META_META_LEFT_ON, META_META_RIGHT_ON);
return metaState == modifiers;
}
private static int metaStateFilterDirectionalModifiers(int metaState,
int modifiers, int basic, int left, int right) {
final boolean wantBasic = (modifiers & basic) != 0;
final int directional = left | right;
final boolean wantLeftOrRight = (modifiers & directional) != 0;
if (wantBasic) {
if (wantLeftOrRight) {
throw new IllegalArgumentException("modifiers must not contain "
+ metaStateToString(basic) + " combined with "
+ metaStateToString(left) + " or " + metaStateToString(right));
}
return metaState & ~directional;
} else if (wantLeftOrRight) {
return metaState & ~basic;
} else {
return metaState;
}
}
/**
* Returns true if no modifier keys are pressed.
*
* For the purposes of this function, {@link #KEYCODE_CAPS_LOCK},
* {@link #KEYCODE_SCROLL_LOCK}, and {@link #KEYCODE_NUM_LOCK} are
* not considered modifier keys. Consequently, this function ignores
* {@link #META_CAPS_LOCK_ON}, {@link #META_SCROLL_LOCK_ON} and {@link #META_NUM_LOCK_ON}.
*
* The meta state is normalized prior to comparison using {@link #normalizeMetaState(int)}.
*
*
* @return True if no modifier keys are pressed.
* @see #metaStateHasNoModifiers
*/
public final boolean hasNoModifiers() {
return metaStateHasNoModifiers(mMetaState);
}
/**
* Returns true if only the specified modifiers keys are pressed.
* Returns false if a different combination of modifier keys are pressed.
*
* For the purposes of this function, {@link #KEYCODE_CAPS_LOCK},
* {@link #KEYCODE_SCROLL_LOCK}, and {@link #KEYCODE_NUM_LOCK} are
* not considered modifier keys. Consequently, this function ignores
* {@link #META_CAPS_LOCK_ON}, {@link #META_SCROLL_LOCK_ON} and {@link #META_NUM_LOCK_ON}.
*
* If the specified modifier mask includes directional modifiers, such as
* {@link #META_SHIFT_LEFT_ON}, then this method ensures that the
* modifier is pressed on that side.
* If the specified modifier mask includes non-directional modifiers, such as
* {@link #META_SHIFT_ON}, then this method ensures that the modifier
* is pressed on either side.
* If the specified modifier mask includes both directional and non-directional modifiers
* for the same type of key, such as {@link #META_SHIFT_ON} and {@link #META_SHIFT_LEFT_ON},
* then this method throws an illegal argument exception.
*
*
* @param modifiers The meta state of the modifier keys to check. May be a combination
* of modifier meta states as defined by {@link #getModifierMetaStateMask()}. May be 0 to
* ensure that no modifier keys are pressed.
* @return True if only the specified modifier keys are pressed.
* @throws IllegalArgumentException if the modifiers parameter contains invalid modifiers
* @see #metaStateHasModifiers
*/
public final boolean hasModifiers(int modifiers) {
return metaStateHasModifiers(mMetaState, modifiers);
}
/**
* Returns the pressed state of the ALT meta key.
*
* @return true if the ALT key is pressed, false otherwise
*
* @see #KEYCODE_ALT_LEFT
* @see #KEYCODE_ALT_RIGHT
* @see #META_ALT_ON
*/
public final boolean isAltPressed() {
return (mMetaState & META_ALT_ON) != 0;
}
/**
* Returns the pressed state of the SHIFT meta key.
*
* @return true if the SHIFT key is pressed, false otherwise
*
* @see #KEYCODE_SHIFT_LEFT
* @see #KEYCODE_SHIFT_RIGHT
* @see #META_SHIFT_ON
*/
public final boolean isShiftPressed() {
return (mMetaState & META_SHIFT_ON) != 0;
}
/**
* Returns the pressed state of the SYM meta key.
*
* @return true if the SYM key is pressed, false otherwise
*
* @see #KEYCODE_SYM
* @see #META_SYM_ON
*/
public final boolean isSymPressed() {
return (mMetaState & META_SYM_ON) != 0;
}
/**
* Returns the pressed state of the CTRL meta key.
*
* @return true if the CTRL key is pressed, false otherwise
*
* @see #KEYCODE_CTRL_LEFT
* @see #KEYCODE_CTRL_RIGHT
* @see #META_CTRL_ON
*/
public final boolean isCtrlPressed() {
return (mMetaState & META_CTRL_ON) != 0;
}
/**
* Returns the pressed state of the META meta key.
*
* @return true if the META key is pressed, false otherwise
*
* @see #KEYCODE_META_LEFT
* @see #KEYCODE_META_RIGHT
* @see #META_META_ON
*/
public final boolean isMetaPressed() {
return (mMetaState & META_META_ON) != 0;
}
/**
* Returns the pressed state of the FUNCTION meta key.
*
* @return true if the FUNCTION key is pressed, false otherwise
*
* @see #KEYCODE_FUNCTION
* @see #META_FUNCTION_ON
*/
public final boolean isFunctionPressed() {
return (mMetaState & META_FUNCTION_ON) != 0;
}
/**
* Returns the locked state of the CAPS LOCK meta key.
*
* @return true if the CAPS LOCK key is on, false otherwise
*
* @see #KEYCODE_CAPS_LOCK
* @see #META_CAPS_LOCK_ON
*/
public final boolean isCapsLockOn() {
return (mMetaState & META_CAPS_LOCK_ON) != 0;
}
/**
* Returns the locked state of the NUM LOCK meta key.
*
* @return true if the NUM LOCK key is on, false otherwise
*
* @see #KEYCODE_NUM_LOCK
* @see #META_NUM_LOCK_ON
*/
public final boolean isNumLockOn() {
return (mMetaState & META_NUM_LOCK_ON) != 0;
}
/**
* Returns the locked state of the SCROLL LOCK meta key.
*
* @return true if the SCROLL LOCK key is on, false otherwise
*
* @see #KEYCODE_SCROLL_LOCK
* @see #META_SCROLL_LOCK_ON
*/
public final boolean isScrollLockOn() {
return (mMetaState & META_SCROLL_LOCK_ON) != 0;
}
/**
* Retrieve the action of this key event. May be either
* {@link #ACTION_DOWN}, {@link #ACTION_UP}, or {@link #ACTION_MULTIPLE}.
*
* @return The event action: ACTION_DOWN, ACTION_UP, or ACTION_MULTIPLE.
*/
public final int getAction() {
return mAction;
}
/**
* For {@link #ACTION_UP} events, indicates that the event has been
* canceled as per {@link #FLAG_CANCELED}.
*/
public final boolean isCanceled() {
return (mFlags&FLAG_CANCELED) != 0;
}
/**
* Set {@link #FLAG_CANCELED} flag for the key event.
*
* @hide
*/
@Override
public final void cancel() {
mFlags |= FLAG_CANCELED;
}
/**
* Call this during {@link Callback#onKeyDown} to have the system track
* the key through its final up (possibly including a long press). Note
* that only one key can be tracked at a time -- if another key down
* event is received while a previous one is being tracked, tracking is
* stopped on the previous event.
*/
public final void startTracking() {
mFlags |= FLAG_START_TRACKING;
}
/**
* For {@link #ACTION_UP} events, indicates that the event is still being
* tracked from its initial down event as per
* {@link #FLAG_TRACKING}.
*/
public final boolean isTracking() {
return (mFlags&FLAG_TRACKING) != 0;
}
/**
* For {@link #ACTION_DOWN} events, indicates that the event has been
* canceled as per {@link #FLAG_LONG_PRESS}.
*/
public final boolean isLongPress() {
return (mFlags&FLAG_LONG_PRESS) != 0;
}
/**
* Retrieve the key code of the key event. This is the physical key that
* was pressed, not the Unicode character.
*
* @return The key code of the event.
*/
public final int getKeyCode() {
return mKeyCode;
}
/**
* For the special case of a {@link #ACTION_MULTIPLE} event with key
* code of {@link #KEYCODE_UNKNOWN}, this is a raw string of characters
* associated with the event. In all other cases it is null.
*
* @return Returns a String of 1 or more characters associated with
* the event.
*
* @deprecated no longer used by the input system.
*/
@Deprecated
public final String getCharacters() {
return mCharacters;
}
/**
* Retrieve the hardware key id of this key event. These values are not
* reliable and vary from device to device.
*
* {@more}
* Mostly this is here for debugging purposes.
*/
public final int getScanCode() {
return mScanCode;
}
/**
* Retrieve the repeat count of the event. For key down events,
* this is the number of times the key has repeated with the first
* down starting at 0 and counting up from there. For key up events,
* this is always equal to zero. For multiple key events,
* this is the number of down/up pairs that have occurred.
*
* @return The number of times the key has repeated.
*/
public final int getRepeatCount() {
return mRepeatCount;
}
/**
* Modifies the down time and the event time of the event.
*
* @param downTime The new down time (in {@link android.os.SystemClock#uptimeMillis}) of the
* event.
* @param eventTime The new event time (in {@link android.os.SystemClock#uptimeMillis}) of the
* event.
* @hide
*/
public final void setTime(long downTime, long eventTime) {
mDownTime = TimeUnit.NANOSECONDS.convert(downTime, TimeUnit.MILLISECONDS);
mEventTime = TimeUnit.NANOSECONDS.convert(eventTime, TimeUnit.MILLISECONDS);
}
/**
* Retrieve the time of the most recent key down event,
* in the {@link android.os.SystemClock#uptimeMillis} time base. If this
* is a down event, this will be the same as {@link #getEventTime()}.
* Note that when chording keys, this value is the down time of the
* most recently pressed key, which may not be the same physical
* key of this event.
*
* @return Returns the most recent key down time, in the
* {@link android.os.SystemClock#uptimeMillis} time base
*/
public final long getDownTime() {
return TimeUnit.MILLISECONDS.convert(mDownTime, TimeUnit.NANOSECONDS);
}
/**
* Retrieve the time this event occurred,
* in the {@link android.os.SystemClock#uptimeMillis} time base.
*
* @return Returns the time this event occurred,
* in the {@link android.os.SystemClock#uptimeMillis} time base.
*/
@Override
public final long getEventTime() {
return TimeUnit.MILLISECONDS.convert(mEventTime, TimeUnit.NANOSECONDS);
}
/**
* Retrieve the time this event occurred,
* in the {@link android.os.SystemClock#uptimeMillis} time base but with
* nanosecond (instead of millisecond) precision.
*
* The value is in nanosecond precision but it may not have nanosecond accuracy.
*
*
* @return Returns the time this event occurred,
* in the {@link android.os.SystemClock#uptimeMillis} time base but with
* nanosecond (instead of millisecond) precision.
*
* @hide
*/
@Override
public final long getEventTimeNano() {
return mEventTime;
}
/**
* Renamed to {@link #getDeviceId}.
*
* @hide
* @deprecated use {@link #getDeviceId()} instead.
*/
@Deprecated
public final int getKeyboardDevice() {
return mDeviceId;
}
/**
* Gets the {@link KeyCharacterMap} associated with the keyboard device.
*
* @return The associated key character map.
* @throws {@link KeyCharacterMap.UnavailableException} if the key character map
* could not be loaded because it was malformed or the default key character map
* is missing from the system.
*
* @see KeyCharacterMap#load
*/
public final KeyCharacterMap getKeyCharacterMap() {
return KeyCharacterMap.load(mDeviceId);
}
/**
* Gets the primary character for this key.
* In other words, the label that is physically printed on it.
*
* @return The display label character, or 0 if none (eg. for non-printing keys).
*/
public char getDisplayLabel() {
return getKeyCharacterMap().getDisplayLabel(mKeyCode);
}
/**
* Gets the Unicode character generated by the specified key and meta
* key state combination.
*
* Returns the Unicode character that the specified key would produce
* when the specified meta bits (see {@link MetaKeyKeyListener})
* were active.
*
* Returns 0 if the key is not one that is used to type Unicode
* characters.
*
* If the return value has bit {@link KeyCharacterMap#COMBINING_ACCENT} set, the
* key is a "dead key" that should be combined with another to
* actually produce a character -- see {@link KeyCharacterMap#getDeadChar} --
* after masking with {@link KeyCharacterMap#COMBINING_ACCENT_MASK}.
*
*
* @return The associated character or combining accent, or 0 if none.
*/
public int getUnicodeChar() {
return getUnicodeChar(mMetaState);
}
/**
* Gets the Unicode character generated by the specified key and meta
* key state combination.
*
* Returns the Unicode character that the specified key would produce
* when the specified meta bits (see {@link MetaKeyKeyListener})
* were active.
*
* Returns 0 if the key is not one that is used to type Unicode
* characters.
*
* If the return value has bit {@link KeyCharacterMap#COMBINING_ACCENT} set, the
* key is a "dead key" that should be combined with another to
* actually produce a character -- see {@link KeyCharacterMap#getDeadChar} --
* after masking with {@link KeyCharacterMap#COMBINING_ACCENT_MASK}.
*
*
* @param metaState The meta key modifier state.
* @return The associated character or combining accent, or 0 if none.
*/
public int getUnicodeChar(int metaState) {
return getKeyCharacterMap().get(mKeyCode, metaState);
}
/**
* Get the character conversion data for a given key code.
*
* @param results A {@link KeyCharacterMap.KeyData} instance that will be
* filled with the results.
* @return True if the key was mapped. If the key was not mapped, results is not modified.
*
* @deprecated instead use {@link #getDisplayLabel()},
* {@link #getNumber()} or {@link #getUnicodeChar(int)}.
*/
@Deprecated
public boolean getKeyData(KeyData results) {
return getKeyCharacterMap().getKeyData(mKeyCode, results);
}
/**
* Gets the first character in the character array that can be generated
* by the specified key code.
*
* This is a convenience function that returns the same value as
* {@link #getMatch(char[],int) getMatch(chars, 0)}.
*
*
* @param chars The array of matching characters to consider.
* @return The matching associated character, or 0 if none.
*/
public char getMatch(char[] chars) {
return getMatch(chars, 0);
}
/**
* Gets the first character in the character array that can be generated
* by the specified key code. If there are multiple choices, prefers
* the one that would be generated with the specified meta key modifier state.
*
* @param chars The array of matching characters to consider.
* @param metaState The preferred meta key modifier state.
* @return The matching associated character, or 0 if none.
*/
public char getMatch(char[] chars, int metaState) {
return getKeyCharacterMap().getMatch(mKeyCode, chars, metaState);
}
/**
* Gets the number or symbol associated with the key.
*
* The character value is returned, not the numeric value.
* If the key is not a number, but is a symbol, the symbol is retuned.
*
* This method is intended to to support dial pads and other numeric or
* symbolic entry on keyboards where certain keys serve dual function
* as alphabetic and symbolic keys. This method returns the number
* or symbol associated with the key independent of whether the user
* has pressed the required modifier.
*
* For example, on one particular keyboard the keys on the top QWERTY row generate
* numbers when ALT is pressed such that ALT-Q maps to '1'. So for that keyboard
* when {@link #getNumber} is called with {@link KeyEvent#KEYCODE_Q} it returns '1'
* so that the user can type numbers without pressing ALT when it makes sense.
*
*
* @return The associated numeric or symbolic character, or 0 if none.
*/
public char getNumber() {
return getKeyCharacterMap().getNumber(mKeyCode);
}
/**
* Returns true if this key produces a glyph.
*
* @return True if the key is a printing key.
*/
public boolean isPrintingKey() {
return getKeyCharacterMap().isPrintingKey(mKeyCode);
}
/**
* @deprecated Use {@link #dispatch(Callback, DispatcherState, Object)} instead.
*/
@Deprecated
public final boolean dispatch(Callback receiver) {
return dispatch(receiver, null, null);
}
/**
* Deliver this key event to a {@link Callback} interface. If this is
* an ACTION_MULTIPLE event and it is not handled, then an attempt will
* be made to deliver a single normal event.
*
* @param receiver The Callback that will be given the event.
* @param state State information retained across events.
* @param target The target of the dispatch, for use in tracking.
*
* @return The return value from the Callback method that was called.
*/
public final boolean dispatch(Callback receiver, DispatcherState state,
Object target) {
switch (mAction) {
case ACTION_DOWN: {
mFlags &= ~FLAG_START_TRACKING;
if (DEBUG) Log.v(TAG, "Key down to " + target + " in " + state
+ ": " + this);
boolean res = receiver.onKeyDown(mKeyCode, this);
if (state != null) {
if (res && mRepeatCount == 0 && (mFlags&FLAG_START_TRACKING) != 0) {
if (DEBUG) Log.v(TAG, " Start tracking!");
state.startTracking(this, target);
} else if (isLongPress() && state.isTracking(this)) {
try {
if (receiver.onKeyLongPress(mKeyCode, this)) {
if (DEBUG) Log.v(TAG, " Clear from long press!");
state.performedLongPress(this);
res = true;
}
} catch (AbstractMethodError e) {
}
}
}
return res;
}
case ACTION_UP:
if (DEBUG) Log.v(TAG, "Key up to " + target + " in " + state
+ ": " + this);
if (state != null) {
state.handleUpEvent(this);
}
return receiver.onKeyUp(mKeyCode, this);
case ACTION_MULTIPLE:
final int count = mRepeatCount;
final int code = mKeyCode;
if (receiver.onKeyMultiple(code, count, this)) {
return true;
}
if (code != KeyEvent.KEYCODE_UNKNOWN) {
mAction = ACTION_DOWN;
mRepeatCount = 0;
boolean handled = receiver.onKeyDown(code, this);
if (handled) {
mAction = ACTION_UP;
receiver.onKeyUp(code, this);
}
mAction = ACTION_MULTIPLE;
mRepeatCount = count;
return handled;
}
return false;
}
return false;
}
/**
* Use with {@link KeyEvent#dispatch(Callback, DispatcherState, Object)}
* for more advanced key dispatching, such as long presses.
*/
public static class DispatcherState {
int mDownKeyCode;
Object mDownTarget;
SparseIntArray mActiveLongPresses = new SparseIntArray();
/**
* Reset back to initial state.
*/
public void reset() {
if (DEBUG) Log.v(TAG, "Reset: " + this);
mDownKeyCode = 0;
mDownTarget = null;
mActiveLongPresses.clear();
}
/**
* Stop any tracking associated with this target.
*/
public void reset(Object target) {
if (mDownTarget == target) {
if (DEBUG) Log.v(TAG, "Reset in " + target + ": " + this);
mDownKeyCode = 0;
mDownTarget = null;
}
}
/**
* Start tracking the key code associated with the given event. This
* can only be called on a key down. It will allow you to see any
* long press associated with the key, and will result in
* {@link KeyEvent#isTracking} return true on the long press and up
* events.
*
* This is only needed if you are directly dispatching events, rather
* than handling them in {@link Callback#onKeyDown}.
*/
public void startTracking(KeyEvent event, Object target) {
if (event.getAction() != ACTION_DOWN) {
throw new IllegalArgumentException(
"Can only start tracking on a down event");
}
if (DEBUG) Log.v(TAG, "Start trackingt in " + target + ": " + this);
mDownKeyCode = event.getKeyCode();
mDownTarget = target;
}
/**
* Return true if the key event is for a key code that is currently
* being tracked by the dispatcher.
*/
public boolean isTracking(KeyEvent event) {
return mDownKeyCode == event.getKeyCode();
}
/**
* Keep track of the given event's key code as having performed an
* action with a long press, so no action should occur on the up.
*
This is only needed if you are directly dispatching events, rather
* than handling them in {@link Callback#onKeyLongPress}.
*/
public void performedLongPress(KeyEvent event) {
mActiveLongPresses.put(event.getKeyCode(), 1);
}
/**
* Handle key up event to stop tracking. This resets the dispatcher state,
* and updates the key event state based on it.
*
This is only needed if you are directly dispatching events, rather
* than handling them in {@link Callback#onKeyUp}.
*/
public void handleUpEvent(KeyEvent event) {
final int keyCode = event.getKeyCode();
if (DEBUG) Log.v(TAG, "Handle key up " + event + ": " + this);
int index = mActiveLongPresses.indexOfKey(keyCode);
if (index >= 0) {
if (DEBUG) Log.v(TAG, " Index: " + index);
event.mFlags |= FLAG_CANCELED | FLAG_CANCELED_LONG_PRESS;
mActiveLongPresses.removeAt(index);
}
if (mDownKeyCode == keyCode) {
if (DEBUG) Log.v(TAG, " Tracking!");
event.mFlags |= FLAG_TRACKING;
mDownKeyCode = 0;
mDownTarget = null;
}
}
}
@Override
public String toString() {
StringBuilder msg = new StringBuilder();
msg.append("KeyEvent { action=").append(actionToString(mAction));
msg.append(", keyCode=").append(keyCodeToString(mKeyCode));
msg.append(", scanCode=").append(mScanCode);
if (mCharacters != null) {
msg.append(", characters=\"").append(mCharacters).append("\"");
}
msg.append(", metaState=").append(metaStateToString(mMetaState));
msg.append(", flags=0x").append(Integer.toHexString(mFlags));
msg.append(", repeatCount=").append(mRepeatCount);
msg.append(", eventTime=").append(mEventTime);
msg.append(", downTime=").append(mDownTime);
msg.append(", deviceId=").append(mDeviceId);
msg.append(", source=0x").append(Integer.toHexString(mSource));
msg.append(", displayId=").append(mDisplayId);
msg.append(" }");
return msg.toString();
}
/**
* Returns a string that represents the symbolic name of the specified action
* such as "ACTION_DOWN", or an equivalent numeric constant such as "35" if unknown.
*
* @param action The action.
* @return The symbolic name of the specified action.
* @hide
*/
@TestApi
public static String actionToString(int action) {
switch (action) {
case ACTION_DOWN:
return "ACTION_DOWN";
case ACTION_UP:
return "ACTION_UP";
case ACTION_MULTIPLE:
return "ACTION_MULTIPLE";
default:
return Integer.toString(action);
}
}
/**
* Returns a string that represents the symbolic name of the specified keycode
* such as "KEYCODE_A", "KEYCODE_DPAD_UP", or an equivalent numeric constant
* such as "1001" if unknown.
*
* This function is intended to be used mostly for debugging, logging, and testing. It is not
* locale-specific and is not intended to be used in a user-facing manner.
*
* @param keyCode The key code.
* @return The symbolic name of the specified keycode.
*
* @see KeyCharacterMap#getDisplayLabel
*/
public static String keyCodeToString(int keyCode) {
String symbolicName = nativeKeyCodeToString(keyCode);
return symbolicName != null ? LABEL_PREFIX + symbolicName : Integer.toString(keyCode);
}
/**
* Gets a keycode by its symbolic name such as "KEYCODE_A" or an equivalent
* numeric constant such as "29". For symbolic names,
* starting in {@link android.os.Build.VERSION_CODES#Q} the prefix "KEYCODE_" is optional.
*
* @param symbolicName The symbolic name of the keycode.
* @return The keycode or {@link #KEYCODE_UNKNOWN} if not found.
* @see #keyCodeToString(int)
*/
public static int keyCodeFromString(@NonNull String symbolicName) {
try {
int keyCode = Integer.parseInt(symbolicName);
if (keyCodeIsValid(keyCode)) {
return keyCode;
}
} catch (NumberFormatException ex) {
}
if (symbolicName.startsWith(LABEL_PREFIX)) {
symbolicName = symbolicName.substring(LABEL_PREFIX.length());
}
int keyCode = nativeKeyCodeFromString(symbolicName);
if (keyCodeIsValid(keyCode)) {
return keyCode;
}
return KEYCODE_UNKNOWN;
}
private static boolean keyCodeIsValid(int keyCode) {
return keyCode >= KEYCODE_UNKNOWN && keyCode <= LAST_KEYCODE;
}
/**
* Returns a string that represents the symbolic name of the specified combined meta
* key modifier state flags such as "0", "META_SHIFT_ON",
* "META_ALT_ON|META_SHIFT_ON" or an equivalent numeric constant such as "0x10000000"
* if unknown.
*
* @param metaState The meta state.
* @return The symbolic name of the specified combined meta state flags.
* @hide
*/
public static String metaStateToString(int metaState) {
if (metaState == 0) {
return "0";
}
StringBuilder result = null;
int i = 0;
while (metaState != 0) {
final boolean isSet = (metaState & 1) != 0;
metaState >>>= 1; // unsigned shift!
if (isSet) {
final String name = META_SYMBOLIC_NAMES[i];
if (result == null) {
if (metaState == 0) {
return name;
}
result = new StringBuilder(name);
} else {
result.append('|');
result.append(name);
}
}
i += 1;
}
return result.toString();
}
public static final @android.annotation.NonNull Parcelable.Creator CREATOR
= new Parcelable.Creator() {
@Override
public KeyEvent createFromParcel(Parcel in) {
in.readInt(); // skip token, we already know this is a KeyEvent
return KeyEvent.createFromParcelBody(in);
}
@Override
public KeyEvent[] newArray(int size) {
return new KeyEvent[size];
}
};
/** @hide */
public static KeyEvent createFromParcelBody(Parcel in) {
return new KeyEvent(in);
}
private KeyEvent(Parcel in) {
mId = in.readInt();
mDeviceId = in.readInt();
mSource = in.readInt();
mDisplayId = in.readInt();
mHmac = in.createByteArray();
mAction = in.readInt();
mKeyCode = in.readInt();
mRepeatCount = in.readInt();
mMetaState = in.readInt();
mScanCode = in.readInt();
mFlags = in.readInt();
mDownTime = in.readLong();
mEventTime = in.readLong();
mCharacters = in.readString();
}
@Override
public void writeToParcel(Parcel out, int flags) {
out.writeInt(PARCEL_TOKEN_KEY_EVENT);
out.writeInt(mId);
out.writeInt(mDeviceId);
out.writeInt(mSource);
out.writeInt(mDisplayId);
out.writeByteArray(mHmac);
out.writeInt(mAction);
out.writeInt(mKeyCode);
out.writeInt(mRepeatCount);
out.writeInt(mMetaState);
out.writeInt(mScanCode);
out.writeInt(mFlags);
out.writeLong(mDownTime);
out.writeLong(mEventTime);
out.writeString(mCharacters);
}
}