FileDocCategorySizeDatePackage
KeyEvent.javaAPI DocAndroid 1.5 API34680Wed May 06 22:41:56 BST 2009android.view

KeyEvent

public class KeyEvent extends Object implements android.os.Parcelable
Contains constants for key events.

Fields Summary
public static final int
KEYCODE_UNKNOWN
public static final int
KEYCODE_SOFT_LEFT
public static final int
KEYCODE_SOFT_RIGHT
public static final int
KEYCODE_HOME
public static final int
KEYCODE_BACK
public static final int
KEYCODE_CALL
public static final int
KEYCODE_ENDCALL
public static final int
KEYCODE_0
public static final int
KEYCODE_1
public static final int
KEYCODE_2
public static final int
KEYCODE_3
public static final int
KEYCODE_4
public static final int
KEYCODE_5
public static final int
KEYCODE_6
public static final int
KEYCODE_7
public static final int
KEYCODE_8
public static final int
KEYCODE_9
public static final int
KEYCODE_STAR
public static final int
KEYCODE_POUND
public static final int
KEYCODE_DPAD_UP
public static final int
KEYCODE_DPAD_DOWN
public static final int
KEYCODE_DPAD_LEFT
public static final int
KEYCODE_DPAD_RIGHT
public static final int
KEYCODE_DPAD_CENTER
public static final int
KEYCODE_VOLUME_UP
public static final int
KEYCODE_VOLUME_DOWN
public static final int
KEYCODE_POWER
public static final int
KEYCODE_CAMERA
public static final int
KEYCODE_CLEAR
public static final int
KEYCODE_A
public static final int
KEYCODE_B
public static final int
KEYCODE_C
public static final int
KEYCODE_D
public static final int
KEYCODE_E
public static final int
KEYCODE_F
public static final int
KEYCODE_G
public static final int
KEYCODE_H
public static final int
KEYCODE_I
public static final int
KEYCODE_J
public static final int
KEYCODE_K
public static final int
KEYCODE_L
public static final int
KEYCODE_M
public static final int
KEYCODE_N
public static final int
KEYCODE_O
public static final int
KEYCODE_P
public static final int
KEYCODE_Q
public static final int
KEYCODE_R
public static final int
KEYCODE_S
public static final int
KEYCODE_T
public static final int
KEYCODE_U
public static final int
KEYCODE_V
public static final int
KEYCODE_W
public static final int
KEYCODE_X
public static final int
KEYCODE_Y
public static final int
KEYCODE_Z
public static final int
KEYCODE_COMMA
public static final int
KEYCODE_PERIOD
public static final int
KEYCODE_ALT_LEFT
public static final int
KEYCODE_ALT_RIGHT
public static final int
KEYCODE_SHIFT_LEFT
public static final int
KEYCODE_SHIFT_RIGHT
public static final int
KEYCODE_TAB
public static final int
KEYCODE_SPACE
public static final int
KEYCODE_SYM
public static final int
KEYCODE_EXPLORER
public static final int
KEYCODE_ENVELOPE
public static final int
KEYCODE_ENTER
public static final int
KEYCODE_DEL
public static final int
KEYCODE_GRAVE
public static final int
KEYCODE_MINUS
public static final int
KEYCODE_EQUALS
public static final int
KEYCODE_LEFT_BRACKET
public static final int
KEYCODE_RIGHT_BRACKET
public static final int
KEYCODE_BACKSLASH
public static final int
KEYCODE_SEMICOLON
public static final int
KEYCODE_APOSTROPHE
public static final int
KEYCODE_SLASH
public static final int
KEYCODE_AT
public static final int
KEYCODE_NUM
public static final int
KEYCODE_HEADSETHOOK
public static final int
KEYCODE_FOCUS
public static final int
KEYCODE_PLUS
public static final int
KEYCODE_MENU
public static final int
KEYCODE_NOTIFICATION
public static final int
KEYCODE_SEARCH
public static final int
KEYCODE_MEDIA_PLAY_PAUSE
public static final int
KEYCODE_MEDIA_STOP
public static final int
KEYCODE_MEDIA_NEXT
public static final int
KEYCODE_MEDIA_PREVIOUS
public static final int
KEYCODE_MEDIA_REWIND
public static final int
KEYCODE_MEDIA_FAST_FORWARD
public static final int
KEYCODE_MUTE
private static final int
LAST_KEYCODE
public static final int
MAX_KEYCODE
public static final int
ACTION_DOWN
{@link #getAction} value: the key has been pressed down.
public static final int
ACTION_UP
{@link #getAction} value: the key has been released.
public static final int
ACTION_MULTIPLE
{@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 {@link #KEYCODE_UNKNOWN} then the {#link {@link #getRepeatCount()} method returns the number of times the given key code should be executed. Otherwise, if the key code {@link #KEYCODE_UNKNOWN}, then this is a sequence of characters as returned by {@link #getCharacters}.
public static final int
META_ALT_ON

This mask is used to check whether one of the ALT meta keys is pressed.

public static final int
META_ALT_LEFT_ON

This mask is used to check whether the left ALT meta key is pressed.

public static final int
META_ALT_RIGHT_ON

This mask is used to check whether the right the ALT meta key is pressed.

public static final int
META_SHIFT_ON

This mask is used to check whether one of the SHIFT meta keys is pressed.

public static final int
META_SHIFT_LEFT_ON

This mask is used to check whether the left SHIFT meta key is pressed.

public static final int
META_SHIFT_RIGHT_ON

This mask is used to check whether the right SHIFT meta key is pressed.

public static final int
META_SYM_ON

This mask is used to check whether the SYM meta key is pressed.

public static final int
FLAG_WOKE_HERE
This mask is set if the device woke because of this key event.
public static final int
FLAG_SOFT_KEYBOARD
This mask is set if the key event was generated by a software keyboard.
public static final int
FLAG_KEEP_TOUCH_MODE
This mask is set if we don't want the key event to cause us to leave touch mode.
public static final int
FLAG_FROM_SYSTEM
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_EDITOR_ACTION
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.
private int
mMetaState
private int
mAction
private int
mKeyCode
private int
mScancode
private int
mRepeatCount
private int
mDeviceId
private int
mFlags
private long
mDownTime
private long
mEventTime
private String
mCharacters
public static final Parcelable.Creator
CREATOR
Constructors Summary
public KeyEvent(KeyEvent origEvent, long eventTime, int newRepeat)
Copy an existing key event, modifying its time and repeat count.

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.

        mDownTime = origEvent.mDownTime;
        mEventTime = eventTime;
        mAction = origEvent.mAction;
        mKeyCode = origEvent.mKeyCode;
        mRepeatCount = newRepeat;
        mMetaState = origEvent.mMetaState;
        mDeviceId = origEvent.mDeviceId;
        mScancode = origEvent.mScancode;
        mFlags = origEvent.mFlags;
        mCharacters = origEvent.mCharacters;
private KeyEvent(KeyEvent origEvent, int action)
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.

        mDownTime = origEvent.mDownTime;
        mEventTime = origEvent.mEventTime;
        mAction = action;
        mKeyCode = origEvent.mKeyCode;
        mRepeatCount = origEvent.mRepeatCount;
        mMetaState = origEvent.mMetaState;
        mDeviceId = origEvent.mDeviceId;
        mScancode = origEvent.mScancode;
        mFlags = origEvent.mFlags;
        // Don't copy mCharacters, since one way or the other we'll lose it
        // when changing the action.
public KeyEvent(int action, int code)
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.

        mAction = action;
        mKeyCode = code;
        mRepeatCount = 0;
public KeyEvent(long downTime, long eventTime, int action, int code, int repeat)
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.

        mDownTime = downTime;
        mEventTime = eventTime;
        mAction = action;
        mKeyCode = code;
        mRepeatCount = repeat;
private KeyEvent(android.os.Parcel in)

        mAction = in.readInt();
        mKeyCode = in.readInt();
        mRepeatCount = in.readInt();
        mMetaState = in.readInt();
        mDeviceId = in.readInt();
        mScancode = in.readInt();
        mFlags = in.readInt();
        mDownTime = in.readLong();
        mEventTime = in.readLong();
public KeyEvent(long downTime, long eventTime, int action, int code, int repeat, int metaState)
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.

        mDownTime = downTime;
        mEventTime = eventTime;
        mAction = action;
        mKeyCode = code;
        mRepeatCount = repeat;
        mMetaState = metaState;
public KeyEvent(long downTime, long eventTime, int action, int code, int repeat, int metaState, int device, int 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
device The device ID that generated the key event.
param
scancode Raw device scan code of the event.

        mDownTime = downTime;
        mEventTime = eventTime;
        mAction = action;
        mKeyCode = code;
        mRepeatCount = repeat;
        mMetaState = metaState;
        mDeviceId = device;
        mScancode = scancode;
public KeyEvent(long downTime, long eventTime, int action, int code, int repeat, int metaState, int device, int scancode, int 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
device 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

        mDownTime = downTime;
        mEventTime = eventTime;
        mAction = action;
        mKeyCode = code;
        mRepeatCount = repeat;
        mMetaState = metaState;
        mDeviceId = device;
        mScancode = scancode;
        mFlags = flags;
public KeyEvent(long time, String characters, int device, int flags)
Create a new key event for a string of characters. The key code, action, and repeat could will automatically be set to {@link #KEYCODE_UNKNOWN}, {@link #ACTION_MULTIPLE}, and 0 for you.

param
time The time (in {@link android.os.SystemClock#uptimeMillis}) at which this event occured.
param
characters The string of characters.
param
device The device ID that generated the key event.
param
flags The flags for this key event

        mDownTime = time;
        mEventTime = time;
        mCharacters = characters;
        mAction = ACTION_MULTIPLE;
        mKeyCode = KEYCODE_UNKNOWN;
        mRepeatCount = 0;
        mDeviceId = device;
        mFlags = flags;
public KeyEvent(KeyEvent origEvent)
Make an exact copy of an existing key event.

        mDownTime = origEvent.mDownTime;
        mEventTime = origEvent.mEventTime;
        mAction = origEvent.mAction;
        mKeyCode = origEvent.mKeyCode;
        mRepeatCount = origEvent.mRepeatCount;
        mMetaState = origEvent.mMetaState;
        mDeviceId = origEvent.mDeviceId;
        mScancode = origEvent.mScancode;
        mFlags = origEvent.mFlags;
        mCharacters = origEvent.mCharacters;
Methods Summary
public static android.view.KeyEventchangeAction(android.view.KeyEvent event, int 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.

        return new KeyEvent(event, action);
public static android.view.KeyEventchangeFlags(android.view.KeyEvent event, int flags)
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.

        event = new KeyEvent(event);
        event.mFlags = flags;
        return event;
public static android.view.KeyEventchangeTimeRepeat(android.view.KeyEvent event, long eventTime, int 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.

        return new KeyEvent(event, eventTime, newRepeat);
public intdescribeContents()


       
        return 0;
public final booleandispatch(android.view.KeyEvent$Callback receiver)
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.
return
The return value from the Callback method that was called.

        switch (mAction) {
            case ACTION_DOWN:
                return receiver.onKeyDown(mKeyCode, this);
            case ACTION_UP:
                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;
public final intgetAction()
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.

        return mAction;
public final java.lang.StringgetCharacters()
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.

        return mCharacters;
public static intgetDeadChar(int accent, int c)
Get the character that is produced by putting accent on the character c. For example, getDeadChar('`', 'e') returns è.

        return KeyCharacterMap.getDeadChar(accent, c);
public final intgetDeviceId()
Return the id for the keyboard that this event came from. A device id of 0 indicates the event didn't come from a physical device and maps to the default keymap. The other numbers are arbitrary and you shouldn't depend on the values.

see
KeyCharacterMap#load

        return mDeviceId;
public chargetDisplayLabel()
Get the primary character for this key. In other words, the label that is physically printed on it.

        return KeyCharacterMap.load(mDeviceId).getDisplayLabel(mKeyCode);
public final longgetDownTime()
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

        return mDownTime;
public final longgetEventTime()
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.

        return mEventTime;
public final intgetFlags()
Returns the flags for this key event.

see
#FLAG_WOKE_HERE

        return mFlags;
public final intgetKeyCode()
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.

        return mKeyCode;
public booleangetKeyData(android.view.KeyCharacterMap.KeyData results)
Get the characters conversion data for the key event..

param
results a {@link KeyData} that will be filled with the results.
return
whether the key was mapped or not. If the key was not mapped, results is not modified.

        return KeyCharacterMap.load(mDeviceId).getKeyData(mKeyCode, results);
public final intgetKeyboardDevice()
Renamed to {@link #getDeviceId}.

hide
deprecated

        return mDeviceId;
public chargetMatch(char[] chars)
The same as {@link #getMatch(char[],int) getMatch(chars, 0)}.

        return getMatch(chars, 0);
public chargetMatch(char[] chars, int modifiers)
If one of the chars in the array can be generated by the keyCode of this key event, return the char; otherwise return '\0'.

param
chars the characters to try to find
param
modifiers the modifier bits to prefer. If any of these bits are set, if there are multiple choices, that could work, the one for this modifier will be set.

        return KeyCharacterMap.load(mDeviceId).getMatch(mKeyCode, chars, modifiers);
public static intgetMaxKeyCode()
Returns the maximum keycode.

    
             
        
        return LAST_KEYCODE;
public final intgetMetaState()

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
#META_ALT_ON
see
#META_SHIFT_ON
see
#META_SYM_ON

        return mMetaState;
public chargetNumber()
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.

        return KeyCharacterMap.load(mDeviceId).getNumber(mKeyCode);
public final intgetRepeatCount()
Retrieve the repeat count of the event. For both key up and 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 multiple key events, this is the number of down/up pairs that have occurred.

return
The number of times the key has repeated.

        return mRepeatCount;
public final intgetScanCode()
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.

        return mScancode;
public intgetUnicodeChar()

Returns the Unicode character that the key would produce.

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 #getDeadChar} -- after masking with {@link KeyCharacterMap#COMBINING_ACCENT_MASK}. 

        return getUnicodeChar(mMetaState);
public intgetUnicodeChar(int meta)

Returns the Unicode character that the key would produce.

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 #getDeadChar} -- after masking with {@link KeyCharacterMap#COMBINING_ACCENT_MASK}. 

        return KeyCharacterMap.load(mDeviceId).get(mKeyCode, meta);
public final booleanisAltPressed()

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

        return (mMetaState & META_ALT_ON) != 0;
public final booleanisDown()
Don't use in new code, instead explicitly check {@link #getAction()}.

return
If the action is ACTION_DOWN, returns true; else false.
deprecated
hide

        return mAction == ACTION_DOWN;
public static booleanisModifierKey(int keyCode)
Returns true if this key code is a modifier key.

return
whether the provided keyCode is one of {@link #KEYCODE_SHIFT_LEFT} {@link #KEYCODE_SHIFT_RIGHT}, {@link #KEYCODE_ALT_LEFT}, {@link #KEYCODE_ALT_RIGHT} or {@link #KEYCODE_SYM}.

        return keyCode == KEYCODE_SHIFT_LEFT || keyCode == KEYCODE_SHIFT_RIGHT
                || keyCode == KEYCODE_ALT_LEFT || keyCode == KEYCODE_ALT_RIGHT
                || keyCode == KEYCODE_SYM;
public booleanisPrintingKey()
Does the key code of this key produce a glyph?

        return KeyCharacterMap.load(mDeviceId).isPrintingKey(mKeyCode);
public final booleanisShiftPressed()

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

        return (mMetaState & META_SHIFT_ON) != 0;
public final booleanisSymPressed()

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

        return (mMetaState & META_SYM_ON) != 0;
public final booleanisSystem()
Is this a system key? System keys can not be used for menu shortcuts. TODO: this information should come from a table somewhere. TODO: should the dpad keys be here? arguably, because they also shouldn't be menu shortcuts

        switch (mKeyCode) {
        case KEYCODE_MENU:
        case KEYCODE_SOFT_RIGHT:
        case KEYCODE_HOME:
        case KEYCODE_BACK:
        case KEYCODE_CALL:
        case KEYCODE_ENDCALL:
        case KEYCODE_VOLUME_UP:
        case KEYCODE_VOLUME_DOWN:
        case KEYCODE_MUTE:
        case KEYCODE_POWER:
        case KEYCODE_HEADSETHOOK:
        case KEYCODE_MEDIA_PLAY_PAUSE:
        case KEYCODE_MEDIA_STOP:
        case KEYCODE_MEDIA_NEXT:
        case KEYCODE_MEDIA_PREVIOUS:
        case KEYCODE_MEDIA_REWIND:
        case KEYCODE_MEDIA_FAST_FORWARD:
        case KEYCODE_CAMERA:
        case KEYCODE_FOCUS:
        case KEYCODE_SEARCH:
            return true;
        default:
            return false;
        }
public java.lang.StringtoString()

        return "KeyEvent{action=" + mAction + " code=" + mKeyCode
            + " repeat=" + mRepeatCount
            + " meta=" + mMetaState + " scancode=" + mScancode
            + " mFlags=" + mFlags + "}";
public voidwriteToParcel(android.os.Parcel out, int flags)

        out.writeInt(mAction);
        out.writeInt(mKeyCode);
        out.writeInt(mRepeatCount);
        out.writeInt(mMetaState);
        out.writeInt(mDeviceId);
        out.writeInt(mScancode);
        out.writeInt(mFlags);
        out.writeLong(mDownTime);
        out.writeLong(mEventTime);