KeyCharacterMap
open class KeyCharacterMap : Parcelable
kotlin.Any | |
↳ | android.view.KeyCharacterMap |
Describes the keys provided by a keyboard device and their associated labels.
Summary
Nested classes | |
---|---|
open |
Describes the character mappings associated with a key. |
open |
Thrown by |
Constants | |
---|---|
static Int |
A keyboard with all the letters, and maybe some numbers. |
static Int |
The id of the device's primary built in keyboard is always 0. |
static Int | |
static Int |
Mask the return value from |
static Int |
A full PC-style keyboard. |
static Char |
This private-use character is used to trigger Unicode character input by hex digits. |
static Int |
Modifier keys may be chorded with character keys. |
static Int |
Modifier keys may be chorded with character keys or they may toggle into latched or locked states when pressed independently. |
static Int |
A numeric (12-key) keyboard. |
static Char |
This private-use character is used to bring up a character picker for miscellaneous symbols. |
static Int |
A keyboard with all the letters, but with more than one letter per key. |
static Int |
A keyboard that is only used to control special functions rather than for typing. |
static Int |
The id of a generic virtual keyboard with a full layout that can be used to synthesize key events. |
Inherited constants | |
---|---|
Public methods | |
---|---|
open Int | |
open static Boolean |
deviceHasKey(keyCode: Int) Queries the framework about whether any physical keys exist on any currently attached input devices that are capable of producing the given key code. |
open static BooleanArray! |
deviceHasKeys(keyCodes: IntArray!) Queries the framework about whether any physical keys exist on any currently attached input devices that are capable of producing the given array of key codes. |
open Boolean | |
open Int |
Gets the Unicode character generated by the specified key and meta key state combination. |
open static Int |
getDeadChar(accent: Int, c: Int) Get the character that is produced by combining the dead key producing accent with the key producing character c. |
open Char |
getDisplayLabel(keyCode: Int) Gets the primary character for this key. |
open Array<KeyEvent!>! |
Get an array of KeyEvent objects that if put into the input stream could plausibly generate the provided sequence of characters. |
open Boolean |
getKeyData(keyCode: Int, results: KeyCharacterMap.KeyData!) Get the character conversion data for a given key code. |
open Int |
Gets the keyboard type. |
open Char |
Gets the first character in the character array that can be generated by the specified key code. |
open Char |
Gets the first character in the character array that can be generated by the specified key code. |
open Int |
Gets a constant that describes the behavior of this keyboard's modifier keys such as |
open Char |
Gets the number or symbol associated with the key. |
open Boolean |
isPrintingKey(keyCode: Int) Returns true if the specified key produces a glyph. |
open static KeyCharacterMap! |
Loads the key character maps for the keyboard with the specified device id. |
open Unit |
writeToParcel(out: Parcel, flags: Int) |
Protected methods | |
---|---|
open Unit |
finalize() |
Properties | |
---|---|
static Parcelable.Creator<KeyCharacterMap!> |
Constants
ALPHA
static val ALPHA: Int
A keyboard with all the letters, and maybe some numbers.
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.
Value: 3
BUILT_IN_KEYBOARD
static valBUILT_IN_KEYBOARD: Int
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.
The id of the device's primary built in keyboard is always 0.
Value: 0
COMBINING_ACCENT_MASK
static val COMBINING_ACCENT_MASK: Int
Mask the return value from get(int,int)
with this value to get a printable representation of the accent character of a "dead key."
Value: 2147483647
FULL
static val FULL: Int
A full PC-style keyboard.
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.
Value: 4
HEX_INPUT
static val HEX_INPUT: Char
This private-use character is used to trigger Unicode character input by hex digits.
Value: 61184
MODIFIER_BEHAVIOR_CHORDED
static val MODIFIER_BEHAVIOR_CHORDED: Int
Modifier keys may be chorded with character keys.
Value: 0
See Also
MODIFIER_BEHAVIOR_CHORDED_OR_TOGGLED
static val MODIFIER_BEHAVIOR_CHORDED_OR_TOGGLED: Int
Modifier keys may be chorded with character keys or they may toggle into latched or locked states when pressed independently.
Value: 1
See Also
NUMERIC
static val NUMERIC: Int
A numeric (12-key) keyboard.
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.
Value: 1
PICKER_DIALOG_INPUT
static val PICKER_DIALOG_INPUT: Char
This private-use character is used to bring up a character picker for miscellaneous symbols.
Value: 61185
PREDICTIVE
static val PREDICTIVE: Int
A keyboard with all the letters, but with more than one letter per key.
This type of keyboard is generally designed for thumb typing.
Value: 2
SPECIAL_FUNCTION
static val SPECIAL_FUNCTION: Int
A keyboard that is only used to control special functions rather than for typing.
A special function keyboard consists only of non-printing keys such as HOME and POWER that are not actually used for typing.
Value: 5
VIRTUAL_KEYBOARD
static val VIRTUAL_KEYBOARD: Int
The id of a generic virtual keyboard with a full layout that can be used to synthesize key events. Typically used with getEvents
.
Value: -1
Public methods
describeContents
open fun describeContents(): Int
Return | |
---|---|
Int |
a bitmask indicating the set of special object types marshaled by this Parcelable object instance. Value is either 0 or android.os.Parcelable#CONTENTS_FILE_DESCRIPTOR |
deviceHasKey
open static fun deviceHasKey(keyCode: Int): Boolean
Queries the framework about whether any physical keys exist on any currently attached input devices that are capable of producing the given key code.
Parameters | |
---|---|
keyCode |
Int: The key code to query. |
Return | |
---|---|
Boolean |
True if at least one attached keyboard supports the specified key code. |
deviceHasKeys
open static fun deviceHasKeys(keyCodes: IntArray!): BooleanArray!
Queries the framework about whether any physical keys exist on any currently attached input devices that are capable of producing the given array of key codes.
Parameters | |
---|---|
keyCodes |
IntArray!: The array of key codes to query. |
Return | |
---|---|
BooleanArray! |
A new array of the same size as the key codes array whose elements are set to true if at least one attached keyboard supports the corresponding key code at the same index in the key codes array. |
equals
open fun equals(other: Any?): Boolean
Parameters | |
---|---|
obj |
the reference object with which to compare. |
Return | |
---|---|
Boolean |
true if this object is the same as the obj argument; false otherwise. |
get
open fun get(
keyCode: Int,
metaState: Int
): Int
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 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
-- after masking with COMBINING_ACCENT_MASK
.
Parameters | |
---|---|
keyCode |
Int: The key code. |
metaState |
Int: The meta key modifier state. |
Return | |
---|---|
Int |
The associated character or combining accent, or 0 if none. |
getDeadChar
open static fun getDeadChar(
accent: Int,
c: Int
): Int
Get the character that is produced by combining the dead key producing accent with the key producing character c. For example, getDeadChar('`', 'e') returns è. getDeadChar('^', ' ') returns '^' and getDeadChar('^', '^') returns '^'.
Parameters | |
---|---|
accent |
Int: The accent character. eg. '`' |
c |
Int: The basic character. |
Return | |
---|---|
Int |
The combined character, or 0 if the characters cannot be combined. |
getDisplayLabel
open fun getDisplayLabel(keyCode: Int): Char
Gets the primary character for this key. In other words, the label that is physically printed on it.
Parameters | |
---|---|
keyCode |
Int: The key code. |
Return | |
---|---|
Char |
The display label character, or 0 if none (eg. for non-printing keys). |
getEvents
open fun getEvents(chars: CharArray!): Array<KeyEvent!>!
Get an array of KeyEvent objects that if put into the input stream could plausibly generate the provided sequence of characters. It is not guaranteed that the sequence is the only way to generate these events or that it is optimal.
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)
.
Parameters | |
---|---|
chars |
CharArray!: The sequence of characters to generate. |
Return | |
---|---|
Array<KeyEvent!>! |
An array of KeyEvent objects, or null if the given char array can not be generated using the current key character map. |
Exceptions | |
---|---|
|
IllegalArgumentException if the passed array of characters is null. |
getKeyData
open fungetKeyData(
keyCode: Int,
results: KeyCharacterMap.KeyData!
): Boolean
Deprecated: instead use KeyCharacterMap#getDisplayLabel(int)
, KeyCharacterMap#getNumber(int)
or KeyCharacterMap#get(int, int)
.
Get the character conversion data for a given key code.
Parameters | |
---|---|
keyCode |
Int: The keyCode to query. |
results |
KeyCharacterMap.KeyData!: A KeyData instance that will be filled with the results. |
Return | |
---|---|
Boolean |
True if the key was mapped. If the key was not mapped, results is not modified. |
getKeyboardType
open fun getKeyboardType(): Int
Gets the keyboard type. Returns 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.
Return | |
---|---|
Int |
The keyboard type. |
getMatch
open fun getMatch(
keyCode: Int,
chars: CharArray!
): Char
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 getMatch(keyCode, chars, 0)
.
Parameters | |
---|---|
keyCode |
Int: The keycode. |
chars |
CharArray!: The array of matching characters to consider. |
Return | |
---|---|
Char |
The matching associated character, or 0 if none. |
Exceptions | |
---|---|
|
IllegalArgumentException if the passed array of characters is null. |
getMatch
open fun getMatch(
keyCode: Int,
chars: CharArray!,
metaState: Int
): Char
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.
Parameters | |
---|---|
keyCode |
Int: The key code. |
chars |
CharArray!: The array of matching characters to consider. |
metaState |
Int: The preferred meta key modifier state. |
Return | |
---|---|
Char |
The matching associated character, or 0 if none. |
Exceptions | |
---|---|
|
IllegalArgumentException if the passed array of characters is null. |
getModifierBehavior
open fun getModifierBehavior(): Int
Gets a constant that describes the behavior of this keyboard's modifier keys such as KeyEvent#KEYCODE_SHIFT_LEFT
.
Currently there are two behaviors that may be combined:
- Chorded behavior: When the modifier key is pressed together with one or more character keys, the keyboard inserts the modified keys and then resets the modifier state when the modifier key is released.
- Toggled behavior: When the modifier key is pressed and released on its own it first toggles into a latched state. When latched, the modifier will apply to next character key that is pressed and will then reset itself to the initial state. If the modifier is already latched and the modifier key is pressed and release on its own again, then it toggles into a locked state. When locked, the modifier will apply to all subsequent character keys that are pressed until unlocked by pressing the modifier key on its own one more time to reset it to the initial state. Toggled behavior is useful for small profile keyboards designed for thumb typing.
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.
Return | |
---|---|
Int |
The modifier behavior for this keyboard. |
getNumber
open fun getNumber(keyCode: Int): Char
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 getNumber
is called with KeyEvent#KEYCODE_Q
it returns '1' so that the user can type numbers without pressing ALT when it makes sense.
Parameters | |
---|---|
keyCode |
Int: The key code. |
Return | |
---|---|
Char |
The associated numeric or symbolic character, or 0 if none. |
isPrintingKey
open fun isPrintingKey(keyCode: Int): Boolean
Returns true if the specified key produces a glyph.
Parameters | |
---|---|
keyCode |
Int: The key code. |
Return | |
---|---|
Boolean |
True if the key is a printing key. |
load
open static fun load(deviceId: Int): KeyCharacterMap!
Loads the key character maps for the keyboard with the specified device id.
Parameters | |
---|---|
deviceId |
Int: The device id of the keyboard. |
Return | |
---|---|
KeyCharacterMap! |
The associated key character map. |
Exceptions | |
---|---|
|
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. |
writeToParcel
open fun writeToParcel(
out: Parcel,
flags: Int
): Unit
Parameters | |
---|---|
dest |
The Parcel in which the object should be written. This value cannot be null . |
flags |
Int: Additional flags about how the object should be written. May be 0 or PARCELABLE_WRITE_RETURN_VALUE . Value is either 0 or a combination of android.os.Parcelable#PARCELABLE_WRITE_RETURN_VALUE , and android.os.Parcelable.PARCELABLE_ELIDE_DUPLICATES |
Protected methods
finalize
protected open fun finalize(): Unit
Exceptions | |
---|---|
java.lang.Throwable |
the Exception raised by this method |