MetaKeyKeyListener

public abstract class MetaKeyKeyListener
extends Object

java.lang.Object
   ↳ android.text.method.MetaKeyKeyListener


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 KeyEvent#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 KeyEvent#KEYCODE_CAPS_LOCK or KeyEvent#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 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 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 clearMetaKeyState(Editable content, int states)
long clearMetaKeyState(long state, int which)

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

void clearMetaKeyState(View view, Editable content, int states)
static final int getMetaState(CharSequence text)

Gets the state of the meta keys.

static final int getMetaState(CharSequence text, int meta)

Gets the state of a particular meta key.

static final int getMetaState(long state)

Gets the state of the meta keys.

static final int getMetaState(CharSequence text, KeyEvent event)

Gets the state of the meta keys for a specific key event.

static final int getMetaState(long state, int meta)

Gets the state of a particular meta key.

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

Gets the state of a particular meta key to use with a particular key event.

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.

Inherited methods

Constants

META_ALT_LOCKED

Added in API level 1
public static final int META_ALT_LOCKED

Flag that indicates that the ALT key is locked.

Constant Value: 512 (0x00000200)

META_ALT_ON

Added in API level 1
public static final int META_ALT_ON

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

Constant Value: 2 (0x00000002)

META_CAP_LOCKED

Added in API level 1
public static final int META_CAP_LOCKED

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

Constant Value: 256 (0x00000100)

META_SHIFT_ON

Added in API level 1
public static final int META_SHIFT_ON

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

Constant Value: 1 (0x00000001)

META_SYM_LOCKED

Added in API level 1
public static final int META_SYM_LOCKED

Flag that indicates that the SYM key is locked.

Constant Value: 1024 (0x00000400)

META_SYM_ON

Added in API level 1
public static final int META_SYM_ON

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

Constant Value: 4 (0x00000004)

Public constructors

MetaKeyKeyListener

public MetaKeyKeyListener ()

Public methods

adjustMetaAfterKeypress

Added in API level 1
public 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).

Parameters
content Spannable

adjustMetaAfterKeypress

Added in API level 3
public 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). Takes the current state, returns the new state.

Parameters
state long

Returns
long

clearMetaKeyState

Added in API level 3
public static void clearMetaKeyState (Editable content, 
                int states)

Parameters
content Editable

states int

clearMetaKeyState

Added in API level 3
public long clearMetaKeyState (long state, 
                int which)

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

Parameters
state long: the meta key state

which int: meta keys to clear, may be a combination of META_SHIFT_ON, META_ALT_ON or META_SYM_ON.

Returns
long

clearMetaKeyState

Added in API level 3
public void clearMetaKeyState (View view, 
                Editable content, 
                int states)

Parameters
view View

content Editable

states int

getMetaState

Added in API level 1
public static final int getMetaState (CharSequence text)

Gets the state of the meta keys.

Parameters
text CharSequence: 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.

getMetaState

Added in API level 1
public static final int getMetaState (CharSequence text, 
                int meta)

Gets the state of a particular meta key.

Parameters
text CharSequence: the buffer in which the meta key would have been pressed.

meta int: META_SHIFT_ON, META_ALT_ON, META_SYM_ON

Returns
int 0 if inactive, 1 if active, 2 if locked.

getMetaState

Added in API level 3
public static final int getMetaState (long state)

Gets the state of the meta keys.

Parameters
state long: the current meta state bits.

Returns
int an integer in which each bit set to one represents a pressed or locked meta key.

getMetaState

Added in API level 19
public static final int getMetaState (CharSequence text, 
                KeyEvent event)

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 CharSequence: the buffer in which the meta key would have been pressed.

event KeyEvent: 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.

getMetaState

Added in API level 3
public static final int getMetaState (long state, 
                int meta)

Gets the state of a particular meta key.

Parameters
state long: the current state bits.

meta int: META_SHIFT_ON, META_ALT_ON, or META_SYM_ON

Returns
int 0 if inactive, 1 if active, 2 if locked.

getMetaState

Added in API level 19
public static final int getMetaState (CharSequence text, 
                int meta, 
                KeyEvent event)

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 CharSequence: the buffer in which the meta key would have been pressed.

meta int: META_SHIFT_ON, META_ALT_ON, META_SYM_ON

event KeyEvent: the event for which to evaluate the meta state.

Returns
int 0 if inactive, 1 if active, 2 if locked.

handleKeyDown

Added in API level 3
public static long handleKeyDown (long state, 
                int keyCode, 
                KeyEvent event)

Handles presses of the meta keys.

Parameters
state long

keyCode int

event KeyEvent

Returns
long

handleKeyUp

Added in API level 3
public static long handleKeyUp (long state, 
                int keyCode, 
                KeyEvent event)

Handles release of the meta keys.

Parameters
state long

keyCode int

event KeyEvent

Returns
long

isMetaTracker

Added in API level 1
public 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.

Parameters
text CharSequence

what Object

Returns
boolean

isSelectingMetaTracker

Added in API level 3
public 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.

Parameters
text CharSequence

what Object

Returns
boolean

onKeyDown

Added in API level 1
public boolean onKeyDown (View view, 
                Editable content, 
                int keyCode, 
                KeyEvent event)

Handles presses of the meta keys.

Parameters
view View

content Editable

keyCode int

event KeyEvent

Returns
boolean

onKeyUp

Added in API level 1
public boolean onKeyUp (View view, 
                Editable content, 
                int keyCode, 
                KeyEvent event)

Handles release of the meta keys.

Parameters
view View

content Editable

keyCode int

event KeyEvent

Returns
boolean

resetLockedMeta

Added in API level 3
public 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.

Parameters
state long

Returns
long

resetMetaState

Added in API level 1
public static void resetMetaState (Spannable text)

Resets all meta state to inactive.

Parameters
text Spannable

Protected methods

resetLockedMeta

Added in API level 1
protected 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.

Parameters
content Spannable