Android APIs
public abstract class

MetaKeyKeyListener

extends Object
java.lang.Object
   ↳ android.text.method.MetaKeyKeyListener
Known Direct Subclasses
Known Indirect Subclasses

Class Overview

This base class encapsulates the behavior for tracking the state of meta keys such as SHIFT, ALT and SYM as well as the pseudo-meta state of selecting text.

Key listeners that care about meta state should inherit from this class; you should not instantiate this class directly in a client.

This class provides two mechanisms for tracking meta state that can be used together or independently.

The behavior of this class varies according to the keyboard capabilities described by the KeyCharacterMap of the keyboard device such as the key modifier behavior.

MetaKeyKeyListener implements chorded and toggled key modifiers. When key modifiers are toggled into a latched or locked state, the state of the modifier is stored in the Editable text buffer or in a meta state integer managed by the client. These latched or locked modifiers should be considered to be held in addition to those that the keyboard already reported as being pressed in getMetaState(). In other words, the MetaKeyKeyListener augments the meta state provided by the keyboard; it does not replace it. This distinction is important to ensure that meta keys not handled by MetaKeyKeyListener such as KEYCODE_CAPS_LOCK or KEYCODE_NUM_LOCK are taken into consideration.

To ensure correct meta key behavior, the following pattern should be used when mapping key codes to characters:

private char getUnicodeChar(TextKeyListener listener, KeyEvent event, Editable textBuffer) { // Use the combined meta states from the event and the key listener. int metaState = event.getMetaState() | listener.getMetaState(textBuffer); return event.getUnicodeChar(metaState); }

Summary

Constants
int META_ALT_LOCKED Flag that indicates that the ALT key is locked.
int META_ALT_ON Flag that indicates that the ALT key is on.
int META_CAP_LOCKED Flag that indicates that the SHIFT key is locked in CAPS mode.
int META_SHIFT_ON Flag that indicates that the SHIFT key is on.
int META_SYM_LOCKED Flag that indicates that the SYM key is locked.
int META_SYM_ON Flag that indicates that the SYM key is on.
Public Constructors
MetaKeyKeyListener()
Public Methods
static long adjustMetaAfterKeypress(long state)
Call this method after you handle a keypress so that the meta state will be reset to unshifted (if it is not still down) or primed to be reset to unshifted (once it is released).
static void adjustMetaAfterKeypress(Spannable content)
Call this method after you handle a keypress so that the meta state will be reset to unshifted (if it is not still down) or primed to be reset to unshifted (once it is released).
static void clearMetaKeyState(Editable content, int states)
void clearMetaKeyState(View view, Editable content, int states)
long clearMetaKeyState(long state, int which)
Clears the state of the specified meta key if it is locked.
final static int getMetaState(CharSequence text)
Gets the state of the meta keys.
final static int getMetaState(CharSequence text, KeyEvent event)
Gets the state of the meta keys for a specific key event.
final static int getMetaState(long state, int meta)
Gets the state of a particular meta key.
final static int getMetaState(long state)
Gets the state of the meta keys.
final static int getMetaState(CharSequence text, int meta, KeyEvent event)
Gets the state of a particular meta key to use with a particular key event.
final static int getMetaState(CharSequence text, int meta)
Gets the state of a particular meta key.
static long handleKeyDown(long state, int keyCode, KeyEvent event)
Handles presses of the meta keys.
static long handleKeyUp(long state, int keyCode, KeyEvent event)
Handles release of the meta keys.
static boolean isMetaTracker(CharSequence text, Object what)
Returns true if this object is one that this class would use to keep track of any meta state in the specified text.
static boolean isSelectingMetaTracker(CharSequence text, Object what)
Returns true if this object is one that this class would use to keep track of the selecting meta state in the specified text.
boolean onKeyDown(View view, Editable content, int keyCode, KeyEvent event)
Handles presses of the meta keys.
boolean onKeyUp(View view, Editable content, int keyCode, KeyEvent event)
Handles release of the meta keys.
static long resetLockedMeta(long state)
Call this if you are a method that ignores the locked meta state (arrow keys, for example) and you handle a key.
static void resetMetaState(Spannable text)
Resets all meta state to inactive.
Protected Methods
static void resetLockedMeta(Spannable content)
Call this if you are a method that ignores the locked meta state (arrow keys, for example) and you handle a key.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int META_ALT_LOCKED

Added in API level 1

Flag that indicates that the ALT key is locked.

Constant Value: 512 (0x00000200)

public static final int META_ALT_ON

Added in API level 1

Flag that indicates that the ALT key is on. Value equals META_ALT_ON.

Constant Value: 2 (0x00000002)

public static final int META_CAP_LOCKED

Added in API level 1

Flag that indicates that the SHIFT key is locked in CAPS mode.

Constant Value: 256 (0x00000100)

public static final int META_SHIFT_ON

Added in API level 1

Flag that indicates that the SHIFT key is on. Value equals META_SHIFT_ON.

Constant Value: 1 (0x00000001)

public static final int META_SYM_LOCKED

Added in API level 1

Flag that indicates that the SYM key is locked.

Constant Value: 1024 (0x00000400)

public static final int META_SYM_ON

Added in API level 1

Flag that indicates that the SYM key is on. Value equals META_SYM_ON.

Constant Value: 4 (0x00000004)

Public Constructors

public MetaKeyKeyListener ()

Added in API level 1

Public Methods

public static long adjustMetaAfterKeypress (long state)

Added in API level 3

Call this method after you handle a keypress so that the meta state will be reset to unshifted (if it is not still down) or primed to be reset to unshifted (once it is released). Takes the current state, returns the new state.

Parameters
state
Returns
long

public static void adjustMetaAfterKeypress (Spannable content)

Added in API level 1

Call this method after you handle a keypress so that the meta state will be reset to unshifted (if it is not still down) or primed to be reset to unshifted (once it is released).

Parameters
content

public static void clearMetaKeyState (Editable content, int states)

Added in API level 3

Parameters
content
states

public void clearMetaKeyState (View view, Editable content, int states)

Added in API level 3

Parameters
view
content
states

public long clearMetaKeyState (long state, int which)

Added in API level 3

Clears the state of the specified meta key if it is locked.

Parameters
state the meta key state
which meta keys to clear, may be a combination of META_SHIFT_ON, META_ALT_ON or META_SYM_ON.
Returns
long

public static final int getMetaState (CharSequence text)

Added in API level 1

Gets the state of the meta keys.

Parameters
text the buffer in which the meta key would have been pressed.
Returns
int an integer in which each bit set to one represents a pressed or locked meta key.

public static final int getMetaState (CharSequence text, KeyEvent event)

Added in API level 19

Gets the state of the meta keys for a specific key event. For input devices that use toggled key modifiers, the `toggled' state is stored into the text buffer. This method retrieves the meta state for this event, accounting for the stored state. If the event has been created by a device that does not support toggled key modifiers, like a virtual device for example, the stored state is ignored.

Parameters
text the buffer in which the meta key would have been pressed.
event the event for which to evaluate the meta state.
Returns
int an integer in which each bit set to one represents a pressed or locked meta key.

public static final int getMetaState (long state, int meta)

Added in API level 3

Gets the state of a particular meta key.

Parameters
state the current state bits.
meta META_SHIFT_ON, META_ALT_ON, or META_SYM_ON
Returns
int 0 if inactive, 1 if active, 2 if locked.

public static final int getMetaState (long state)

Added in API level 3

Gets the state of the meta keys.

Parameters
state the current meta state bits.
Returns
int an integer in which each bit set to one represents a pressed or locked meta key.

public static final int getMetaState (CharSequence text, int meta, KeyEvent event)

Added in API level 19

Gets the state of a particular meta key to use with a particular key event. If the key event has been created by a device that does not support toggled key modifiers, like a virtual keyboard for example, only the meta state in the key event is considered.

Parameters
text the buffer in which the meta key would have been pressed.
meta META_SHIFT_ON, META_ALT_ON, META_SYM_ON
event the event for which to evaluate the meta state.
Returns
int 0 if inactive, 1 if active, 2 if locked.

public static final int getMetaState (CharSequence text, int meta)

Added in API level 1

Gets the state of a particular meta key.

Parameters
text the buffer in which the meta key would have been pressed.
meta META_SHIFT_ON, META_ALT_ON, META_SYM_ON
Returns
int 0 if inactive, 1 if active, 2 if locked.

public static long handleKeyDown (long state, int keyCode, KeyEvent event)

Added in API level 3

Handles presses of the meta keys.

Parameters
state
keyCode
event
Returns
long

public static long handleKeyUp (long state, int keyCode, KeyEvent event)

Added in API level 3

Handles release of the meta keys.

Parameters
state
keyCode
event
Returns
long

public static boolean isMetaTracker (CharSequence text, Object what)

Added in API level 1

Returns true if this object is one that this class would use to keep track of any meta state in the specified text.

Parameters
text
what
Returns
boolean

public static boolean isSelectingMetaTracker (CharSequence text, Object what)

Added in API level 3

Returns true if this object is one that this class would use to keep track of the selecting meta state in the specified text.

Parameters
text
what
Returns
boolean

public boolean onKeyDown (View view, Editable content, int keyCode, KeyEvent event)

Added in API level 1

Handles presses of the meta keys.

Parameters
view
content
keyCode
event
Returns
boolean

public boolean onKeyUp (View view, Editable content, int keyCode, KeyEvent event)

Added in API level 1

Handles release of the meta keys.

Parameters
view
content
keyCode
event
Returns
boolean

public static long resetLockedMeta (long state)

Added in API level 3

Call this if you are a method that ignores the locked meta state (arrow keys, for example) and you handle a key.

Parameters
state
Returns
long

public static void resetMetaState (Spannable text)

Added in API level 1

Resets all meta state to inactive.

Parameters
text

Protected Methods

protected static void resetLockedMeta (Spannable content)

Added in API level 1

Call this if you are a method that ignores the locked meta state (arrow keys, for example) and you handle a key.

Parameters
content