public class KeyCharacterMap extends Object implements Parcelable
Modifier and Type | Class and Description |
---|---|
static class |
KeyCharacterMap.FallbackAction
Specifies a substitute key code and meta state as a fallback action
for an unhandled key.
|
static class |
KeyCharacterMap.KeyData
Deprecated.
instead use
getDisplayLabel(int) ,
getNumber(int) and get(int, int) . |
static class |
KeyCharacterMap.UnavailableException
Thrown by
load(int) when a key character map could not be loaded. |
Parcelable.ClassLoaderCreator<T>, Parcelable.Creator<T>
Modifier and Type | Field and Description |
---|---|
static int |
ALPHA
A keyboard with all the letters, and maybe some numbers.
|
static int |
BUILT_IN_KEYBOARD
Deprecated.
This constant should no longer be used because there is no
guarantee that a device has a built-in keyboard that can be used for
typing text. There might not be a built-in keyboard, the built-in keyboard
might be a
NUMERIC or SPECIAL_FUNCTION keyboard, or there
might be multiple keyboards installed including external keyboards.
When interpreting key presses received from the framework, applications should
use the device id specified in the KeyEvent received.
When synthesizing key presses for delivery elsewhere or when translating key presses
from unknown keyboards, applications should use the special VIRTUAL_KEYBOARD
device id. |
static int |
COMBINING_ACCENT |
static int |
COMBINING_ACCENT_MASK
Mask the return value from
get(int, int) with this value to get
a printable representation of the accent character of a "dead key." |
static Parcelable.Creator<KeyCharacterMap> |
CREATOR |
static int |
FULL
A full PC-style keyboard.
|
static char |
HEX_INPUT
This private-use character is used to trigger Unicode character
input by hex digits.
|
static int |
MODIFIER_BEHAVIOR_CHORDED
Modifier keys may be chorded with character keys.
|
static int |
MODIFIER_BEHAVIOR_CHORDED_OR_TOGGLED
Modifier keys may be chorded with character keys or they may toggle
into latched or locked states when pressed independently.
|
static int |
NUMERIC
A numeric (12-key) keyboard.
|
static char |
PICKER_DIALOG_INPUT
This private-use character is used to bring up a character picker for
miscellaneous symbols.
|
static int |
PREDICTIVE
A keyboard with all the letters, but with more than one letter per key.
|
static int |
SPECIAL_FUNCTION
A keyboard that is only used to control special functions rather than for typing.
|
static int |
VIRTUAL_KEYBOARD
The id of a generic virtual keyboard with a full layout that can be used to
synthesize key events.
|
CONTENTS_FILE_DESCRIPTOR, PARCELABLE_ELIDE_DUPLICATES, PARCELABLE_WRITE_RETURN_VALUE
Modifier and Type | Method and Description |
---|---|
int |
describeContents()
Describe the kinds of special objects contained in this Parcelable
instance's marshaled representation.
|
static boolean |
deviceHasKey(int keyCode)
Queries the framework about whether any physical keys exist on the
any keyboard attached to the device that are capable of producing the given key code.
|
static boolean[] |
deviceHasKeys(int[] keyCodes)
Queries the framework about whether any physical keys exist on the
any keyboard attached to the device that are capable of producing the given
array of key codes.
|
protected void |
finalize()
Called by the garbage collector on an object when garbage collection
determines that there are no more references to the object.
|
int |
get(int keyCode,
int metaState)
Gets the Unicode character generated by the specified key and meta
key state combination.
|
static int |
getDeadChar(int accent,
int c)
Get the character that is produced by combining the dead key producing accent
with the key producing character c.
|
char |
getDisplayLabel(int keyCode)
Gets the primary character for this key.
|
KeyEvent[] |
getEvents(char[] chars)
Get an array of KeyEvent objects that if put into the input stream
could plausibly generate the provided sequence of characters.
|
KeyCharacterMap.FallbackAction |
getFallbackAction(int keyCode,
int metaState)
Gets the fallback action to perform if the application does not
handle the specified key.
|
int |
getKeyboardType()
Gets the keyboard type.
|
boolean |
getKeyData(int keyCode,
KeyCharacterMap.KeyData results)
Deprecated.
instead use
getDisplayLabel(int) ,
getNumber(int) or get(int, int) . |
char |
getMatch(int keyCode,
char[] chars)
Gets the first character in the character array that can be generated
by the specified key code.
|
char |
getMatch(int keyCode,
char[] chars,
int metaState)
Gets the first character in the character array that can be generated
by the specified key code.
|
int |
getModifierBehavior()
Gets a constant that describes the behavior of this keyboard's modifier keys
such as
KeyEvent.KEYCODE_SHIFT_LEFT . |
char |
getNumber(int keyCode)
Gets the number or symbol associated with the key.
|
boolean |
isPrintingKey(int keyCode)
Returns true if the specified key produces a glyph.
|
static KeyCharacterMap |
load(int deviceId)
Loads the key character maps for the keyboard with the specified device id.
|
void |
writeToParcel(Parcel out,
int flags)
Flatten this object in to a Parcel.
|
@Deprecated public static final int BUILT_IN_KEYBOARD
NUMERIC
or SPECIAL_FUNCTION
keyboard, or there
might be multiple keyboards installed including external keyboards.
When interpreting key presses received from the framework, applications should
use the device id specified in the KeyEvent
received.
When synthesizing key presses for delivery elsewhere or when translating key presses
from unknown keyboards, applications should use the special VIRTUAL_KEYBOARD
device id.public static final int VIRTUAL_KEYBOARD
getEvents(char[])
.public static final int NUMERIC
A numeric keyboard supports text entry using a multi-tap approach. It may be necessary to tap a key multiple times to generate the desired letter or symbol.
This type of keyboard is generally designed for thumb typing.
public static final int PREDICTIVE
This type of keyboard is generally designed for thumb typing.
public static final int ALPHA
An alphabetic keyboard supports text entry directly but may have a condensed
layout with a small form factor. In contrast to a full keyboard
, some
symbols may only be accessible using special on-screen character pickers.
In addition, to improve typing speed and accuracy, the framework provides
special affordances for alphabetic keyboards such as auto-capitalization
and toggled / locked shift and alt keys.
This type of keyboard is generally designed for thumb typing.
public static final int FULL
A full keyboard behaves like a PC keyboard. All symbols are accessed directly by pressing keys on the keyboard without on-screen support or affordances such as auto-capitalization.
This type of keyboard is generally designed for full two hand typing.
public static final int SPECIAL_FUNCTION
A special function keyboard consists only of non-printing keys such as HOME and POWER that are not actually used for typing.
public static final char HEX_INPUT
public static final char PICKER_DIALOG_INPUT
public static final int MODIFIER_BEHAVIOR_CHORDED
#getModifierBehavior()} for more details.
,
Constant Field Valuespublic static final int MODIFIER_BEHAVIOR_CHORDED_OR_TOGGLED
#getModifierBehavior()} for more details.
,
Constant Field Valuespublic static final int COMBINING_ACCENT
public static final int COMBINING_ACCENT_MASK
get(int, int)
with this value to get
a printable representation of the accent character of a "dead key."public static final Parcelable.Creator<KeyCharacterMap> CREATOR
protected void finalize() throws Throwable
Object
finalize
method to dispose of
system resources or to perform other cleanup.
The general contract of finalize
is that it is invoked
if and when the JavaTM virtual
machine has determined that there is no longer any
means by which this object can be accessed by any thread that has
not yet died, except as a result of an action taken by the
finalization of some other object or class which is ready to be
finalized. The finalize
method may take any action, including
making this object available again to other threads; the usual purpose
of finalize
, however, is to perform cleanup actions before
the object is irrevocably discarded. For example, the finalize method
for an object that represents an input/output connection might perform
explicit I/O transactions to break the connection before the object is
permanently discarded.
The finalize
method of class Object
performs no
special action; it simply returns normally. Subclasses of
Object
may override this definition.
The Java programming language does not guarantee which thread will
invoke the finalize
method for any given object. It is
guaranteed, however, that the thread that invokes finalize will not
be holding any user-visible synchronization locks when finalize is
invoked. If an uncaught exception is thrown by the finalize method,
the exception is ignored and finalization of that object terminates.
After the finalize
method has been invoked for an object, no
further action is taken until the Java virtual machine has again
determined that there is no longer any means by which this object can
be accessed by any thread that has not yet died, including possible
actions by other objects or classes which are ready to be finalized,
at which point the object may be discarded.
The finalize
method is never invoked more than once by a Java
virtual machine for any given object.
Any exception thrown by the finalize
method causes
the finalization of this object to be halted, but is otherwise
ignored.
public static KeyCharacterMap load(int deviceId)
deviceId
- The device id of the keyboard.{@link
- 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.public int get(int keyCode, int metaState)
Returns the Unicode character that the specified key would produce
when the specified meta bits (see MetaKeyKeyListener
)
were active.
Returns 0 if the key is not one that is used to type Unicode characters.
If the return value has bit COMBINING_ACCENT
set, the
key is a "dead key" that should be combined with another to
actually produce a character -- see getDeadChar(int, int)
--
after masking with COMBINING_ACCENT_MASK
.
keyCode
- The key code.metaState
- The meta key modifier state.public KeyCharacterMap.FallbackAction getFallbackAction(int keyCode, int metaState)
When an application does not handle a particular key, the system may
translate the key to an alternate fallback key (specified in the
fallback action) and dispatch it to the application.
The event containing the fallback key is flagged
with KeyEvent.FLAG_FALLBACK
.
keyCode
- The key code.metaState
- The meta key modifier state.public char getNumber(int keyCode)
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 getNumber(int)
is called with KeyEvent.KEYCODE_Q
it returns '1'
so that the user can type numbers without pressing ALT when it makes sense.
keyCode
- The key code.public char getMatch(int keyCode, char[] chars)
This is a convenience function that returns the same value as
getMatch(keyCode, chars, 0)
.
keyCode
- The keycode.chars
- The array of matching characters to consider.public char getMatch(int keyCode, char[] chars, int metaState)
keyCode
- The key code.chars
- The array of matching characters to consider.metaState
- The preferred meta key modifier state.public char getDisplayLabel(int keyCode)
keyCode
- The key code.public static int getDeadChar(int accent, int c)
accent
- The accent character. eg. '`'c
- The basic character.@Deprecated public boolean getKeyData(int keyCode, KeyCharacterMap.KeyData results)
getDisplayLabel(int)
,
getNumber(int)
or get(int, int)
.keyCode
- The keyCode to query.results
- A KeyCharacterMap.KeyData
instance that will be filled with the results.public KeyEvent[] getEvents(char[] chars)
This function is primarily offered for instrumentation and testing purposes.
It may fail to map characters to key codes. In particular, the key character
map for the built-in keyboard
device id may be empty.
Consider using the key character map associated with the
virtual keyboard
device id instead.
For robust text entry, do not use this function. Instead construct a
KeyEvent
with action code KeyEvent.ACTION_MULTIPLE
that contains
the desired string using KeyEvent.KeyEvent(long, String, int, int)
.
chars
- The sequence of characters to generate.KeyEvent
objects, or null if the given char array
can not be generated using the current key character map.public boolean isPrintingKey(int keyCode)
keyCode
- The key code.public int getKeyboardType()
NUMERIC
, PREDICTIVE
, ALPHA
, FULL
or SPECIAL_FUNCTION
.
Different keyboard types have different semantics. Refer to the documentation associated with the keyboard type constants for details.
public int getModifierBehavior()
KeyEvent.KEYCODE_SHIFT_LEFT
.
Currently there are two behaviors that may be combined:
This function currently returns MODIFIER_BEHAVIOR_CHORDED
when the
keyboard type
is FULL
or SPECIAL_FUNCTION
and
MODIFIER_BEHAVIOR_CHORDED_OR_TOGGLED
otherwise.
In the future, the function may also take into account global keyboard
accessibility settings, other user preferences, or new device capabilities.
#MODIFIER_BEHAVIOR_CHORDED}
,
#MODIFIER_BEHAVIOR_CHORDED_OR_TOGGLED}
public static boolean deviceHasKey(int keyCode)
keyCode
- The key code to query.public static boolean[] deviceHasKeys(int[] keyCodes)
keyCodes
- The array of key codes to query.public void writeToParcel(Parcel out, int flags)
Parcelable
writeToParcel
in interface Parcelable
out
- The Parcel in which the object should be written.flags
- Additional flags about how the object should be written.
May be 0 or Parcelable.PARCELABLE_WRITE_RETURN_VALUE
.public int describeContents()
Parcelable
Parcelable.writeToParcel(Parcel, int)
,
the return value of this method must include the
Parcelable.CONTENTS_FILE_DESCRIPTOR
bit.describeContents
in interface Parcelable
Parcelable.CONTENTS_FILE_DESCRIPTOR