Key character map files

Key character map files (.kcm files) are responsible for mapping combinations of Android key codes with modifiers to Unicode characters.

Device-specific key layout files are required for all internal (built-in) input devices that have keys, if only to tell the system that the device is special purpose only (not a full keyboard).

Device-specific key layout files are optional for external keyboards, and often aren't needed at all. The system provides a generic key character map that is suitable for many external keyboards.

If no device-specific key layout file is available, then the system will choose a default instead.

Location

Key character map files are located by USB vendor, product (and optionally version) id or by input device name.

The following paths are consulted in order.

/odm/usr/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm
/vendor/usr/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm
/system/usr/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm
/data/system/devices/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm
/odm/usr/keychars/Vendor_XXXX_Product_XXXX.kcm
/vendor/usr/keychars/Vendor_XXXX_Product_XXXX.kcm
/system/usr/keychars/Vendor_XXXX_Product_XXXX.kcm
/data/system/devices/keychars/Vendor_XXXX_Product_XXXX.kcm
/odm/usr/keychars/DEVICE_NAME.kcm
/vendor/usr/keychars/DEVICE_NAME.kcm
/system/usr/keychars/DEVICE_NAME.kcm
/data/system/devices/keychars/DEVICE_NAME.kcm
/odm/usr/keychars/Generic.kcm
/vendor/usr/keychars/Generic.kcm
/system/usr/keychars/Generic.kcm
/data/system/devices/keychars/Generic.kcm
/odm/usr/keychars/Virtual.kcm
/vendor/usr/keychars/Virtual.kcm
/system/usr/keychars/Virtual.kcm
/data/system/devices/keychars/Virtual.kcm

When constructing a file path that contains the device name, all characters in the device name other than '0'-'9', 'a'-'z', 'A'-'Z', '-' or '_' are replaced by '_'.

Generic key character map file

The system provides a special built-in key character map file called Generic.kcm. This key character map is intended to support a variety of standard external keyboards.

Do not modify the generic key character map!

Virtual key character map file

The system provides a special built-in key character map file called Virtual.kcm that is used by the virtual keyboard devices.

The virtual keyboard device is a synthetic input device whose id is -1 (see KeyCharacterMap.VIRTUAL_KEYBOARD). It is present on all Android devices beginning with Android Honeycomb 3.0. The purpose of the virtual keyboard device is to provide a known built-in input device that can be used for injecting keystrokes into applications by the IME or by test instrumentation, even for devices that do not have built-in keyboards.

The virtual keyboard is assumed to have a full QWERTY layout that is the same on all devices. This makes it possible for applications to inject keystrokes using the virtual keyboard device and always get the same results.

Do not modify the virtual key character map!

Syntax

A key character map file is a plain text file consisting of a keyboard type declaration and a set of key declarations.

Keyboard type declaration

A keyboard type declaration describes the overall behavior of the keyboard. A character map file must contain a keyboard type declaration. For clarity, it is often placed at the top of the file.

type FULL

The following keyboard types are recognized:

NUMERIC: 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.

Corresponds to KeyCharacterMap.NUMERIC.
PREDICTIVE: A keyboard with all the letters, but with more than one letter per key.

This type of keyboard is generally designed for thumb typing.

Corresponds to KeyCharacterMap.PREDICTIVE.
ALPHA: 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.
FULL: 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.
SPECIAL_FUNCTION: A keyboard that is only used to perform system control 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.

The Generic.kcm and Virtual.kcm key character maps are both FULL keyboards.

Key declarations

Key declarations each consist of the keyword key followed by an Android key code name, an open curly brace, a set of properties and behaviors and a close curly brace.

key A {
    label:                              'A'
    base:                               'a'
    shift, capslock:                    'A'
    ctrl, alt, meta:                    none
}

Properties

Each key property establishes a mapping from a key to a behavior. To make the key character map files more compact, several properties can be mapped to the same behavior by separating them with a comma.

In the above example, the label property is assigned the 'A' behavior. Likewise, the ctrl, alt and meta properties are all simultaneously assigned the none behavior.

The following properties are recognized:

label: Specifies the label that is physically printed on the key, when it consists of a single character. This is the value that is returned by the KeyCharacterMap.getDisplayLabel method.
number: Specifies the behavior (character that should be typed) when a numeric text view has focus, such as when the user is typing a phone number.

Compact keyboards often combine multiple symbols into a single key, such that the same key might be used to type '1' and 'a' or '#' and 'q', perhaps. For these keys, the number property should be set to indicate which symbol should be typed in a numeric context, if any.

Some typical "numeric" symbols are digits '0' through '9', '#', '+', '(', ')', ',', and '.'.
base: Specifies the behavior (character that should be typed) when no modifiers are pressed.
<modifier> or <modifier1>+<modifier2>+...: Specifies the behavior (character that should be typed) when the key is pressed and all of the specified modifiers are active.

For example, the modifier property shift specifies a behavior that applies when the either the LEFT SHIFT or RIGHT SHIFT modifier is pressed.

Similarly, the modifier property rshift+ralt specifies a behavior that applies when the both RIGHT SHIFT and RIGHT ALT modifiers are pressed together.

The following modifiers are recognized in modifier properties:

shift: Applies when either the LEFT SHIFT or RIGHT SHIFT modifier is pressed.
lshift: Applies when the LEFT SHIFT modifier is pressed.
rshift: Applies when the RIGHT SHIFT modifier is pressed.
alt: Applies when either the LEFT ALT or RIGHT ALT modifier is pressed.
lalt: Applies when the LEFT ALT modifier is pressed.
ralt: Applies when the RIGHT ALT modifier is pressed.
ctrl: Applies when either the LEFT CONTROL or RIGHT CONTROL modifier is pressed.
lctrl: Applies when the LEFT CONTROL modifier is pressed.
rctrl: Applies when the RIGHT CONTROL modifier is pressed.
meta: Applies when either the LEFT META or RIGHT META modifier is pressed.
lmeta: Applies when the LEFT META modifier is pressed.
rmeta: Applies when the RIGHT META modifier is pressed.
sym: Applies when the SYMBOL modifier is pressed.
fn: Applies when the FUNCTION modifier is pressed.
capslock: Applies when the CAPS LOCK modifier is locked.
numlock: Applies when the NUM LOCK modifier is locked.
scrolllock: Applies when the SCROLL LOCK modifier is locked.

The order in which the properties are listed is significant. When mapping a key to a behavior, the system scans all relevant properties in order and returns the last applicable behavior that it found.

Consequently, properties that are specified later override properties that are specified earlier for a given key.

Behaviors

Each property maps to a behavior. The most common behavior is typing a character but there are others.

The following behaviors are recognized:

none: Don't type a character.

This behavior is the default when no character is specified. Specifying none is optional but it improves clarity.
'X': Type the specified character literal.

This behavior causes the specified character to be entered into the focused text view. The character literal may be any ASCII character, or one of the following escape sequences:
- '\\': Type a backslash character.
- '\n': Type a new line character (use this for ENTER / RETURN).
- '\t': Type a TAB character.
- '\'': Type an apostrophe character.
- '\"': Type a quote character.
- '\uXXXX': Type the Unicode character whose code point is given in hex by XXXX.
fallback <Android key code name>: Perform a default action if the key is not handled by the application.

This behavior causes the system to simulate a different key press when an application does not handle the specified key natively. It is used to support default behavior for new keys that not all applications know how to handle, such as ESCAPE or numeric keypad keys (when numlock is not pressed).

When a fallback behavior is performed, the application will receive two key presses: one for the original key and another for the fallback key that was selected. If the application handles the original key during key up, then the fallback key event will be canceled (KeyEvent.isCanceled will return true).

The system reserves two Unicode characters to perform special functions:

'\uef00': When this behavior is performed, the text view consumes and removes the four characters preceding the cursor, interprets them as hex digits, and inserts the corresponding Unicode code point.
'\uef01': When this behavior is performed, the text view displays a character picker dialog that contains miscellaneous symbols.

The system recognizes the following Unicode characters as combining diacritical dead key characters:

'\u0300': Grave accent.
'\u0301': Acute accent.
'\u0302': Circumflex accent.
'\u0303': Tilde accent.
'\u0308': Umlaut accent.

When a dead key is typed followed by another character, the dead key and the following characters are composed. For example, when the user types a grave accent dead key followed by the letter 'a', the result is 'à'.

Refer to KeyCharacterMap.getDeadChar for more information about dead key handling.

Comments

Comment lines begin with '#' and continue to the end of the line. Like this:

# A comment!

Blank lines are ignored.

How key combinations are mapped to behaviors

When the user presses a key, the system looks up the behavior associated with the combination of that key press and the currently pressed modifiers.

SHIFT + A

Suppose the user pressed A and SHIFT together. The system first locates the set of properties and behaviors associated with KEYCODE_A.

key A {
    label:                              'A'
    base:                               'a'
    shift, capslock:                    'A'
    ctrl, alt, meta:                    none
}

The system scans the properties from first to last and left to right, ignoring the label and number properties, which are special.

The first property encountered is base. The base property always applies to a key, no matter what modifiers are pressed. It essentially specifies the default behavior for the key unless it is overridden by following properties. Since the base property applies to this key press, the system makes note of the fact that its behavior is 'a' (type the character a).

The system then continues to scan subsequent properties in case any of them are more specific than base and override it. It encounters shift which also applies to the key press SHIFT + A. So the system decides to ignore the base property's behavior and chooses the behavior associated with the shift property, which is 'A' (type the character A).

It then continues to scan the table, however no other properties apply to this key press (CAPS LOCK is not locked, neither CONTROL key is pressed, neither ALT key is pressed and neither META key is pressed).

So the resulting behavior for the key combination SHIFT + A is 'A'.

CONTROL + A

Now consider what would happen if the user pressed A and CONTROL together.

As before, the system would scan the table of properties. It would notice that the base property applied but would also continue scanning until it eventually reached the control property. As it happens, the control property appears after base so its behavior overrides the base behavior.

So the resulting behavior for the key combination CONTROL + A is none.

ESCAPE

Now suppose the user pressed ESCAPE.

key ESCAPE {
    base:                               fallback BACK
    alt, meta:                          fallback HOME
    ctrl:                               fallback MENU
}

This time the system obtains the behavior fallback BACK, a fallback behavior. Because no character literal appears, no character will be typed.

When processing the key, the system will first deliver KEYCODE_ESCAPE to the application. If the application does not handle it, then the system will try again but this time it will deliver KEYCODE_BACK to the application as requested by the fallback behavior.

So applications that recognize and support KEYCODE_ESCAPE have the opportunity to handle it as is, but other applications that do not can instead perform the fallback action of treating the key as if it were KEYCODE_BACK.

NUMPAD_0 with or without NUM LOCK

The numeric keypad keys have very different interpretations depending on whether the NUM LOCK key is locked.

The following key declaration ensures that KEYCODE_NUMPAD_0 types 0 when NUM LOCK is pressed. When NUM LOCK is not pressed, the key is delivered to the application as usual, and if it is not handled, then the fallback key KEYCODE_INSERT is delivered instead.

key NUMPAD_0 {
    label, number:                      '0'
    base:                               fallback INSERT
    numlock:                            '0'
    ctrl, alt, meta:                    none
}

As we can see, fallback key declarations greatly improve compatibility with older applications that do not recognize or directly support all of the keys that are present on a full PC style keyboard.

Examples

Full keyboard

# This is an example of part of a key character map file for a full keyboard
# include a few fallback behaviors for special keys that few applications
# handle themselves.

type FULL

key C {
    label:                              'C'
    base:                               'c'
    shift, capslock:                    'C'
    alt:                                '\u00e7'
    shift+alt:                          '\u00c7'
    ctrl, meta:                         none
}

key SPACE {
    label:                              ' '
    base:                               ' '
    ctrl:                               none
    alt, meta:                          fallback SEARCH
}

key NUMPAD_9 {
    label, number:                      '9'
    base:                               fallback PAGE_UP
    numlock:                            '9'
    ctrl, alt, meta:                    none
}

Alphanumeric keyboard

# This is an example of part of a key character map file for an alphanumeric
# thumb keyboard.  Some keys are combined, such as `A` and `2`.  Here we
# specify `number` labels to tell the system what to do when the user is
# typing a number into a dial pad.
#
# Also note the special character '\uef01' mapped to ALT+SPACE.
# Pressing this combination of keys invokes an on-screen character picker.

type ALPHA

key A {
    label:                              'A'
    number:                             '2'
    base:                               'a'
    shift, capslock:                    'A'
    alt:                                '#'
    shift+alt, capslock+alt:            none
}

key SPACE {
    label:                              ' '
    number:                             ' '
    base:                               ' '
    shift:                              ' '
    alt:                                '\uef01'
    shift+alt:                          '\uef01'
}

Game pad

# This is an example of part of a key character map file for a game pad.
# It defines fallback actions that enable the user to navigate the user interface
# by pressing buttons.

type SPECIAL_FUNCTION

key BUTTON_A {
    base:                               fallback BACK
}

key BUTTON_X {
    base:                               fallback DPAD_CENTER
}

key BUTTON_START {
    base:                               fallback HOME
}

key BUTTON_SELECT {
    base:                               fallback MENU
}

Compatibility note

Prior to Android Honeycomb 3.0, the Android key character map was specified using a very different syntax and was compiled into a binary file format (.kcm.bin) at build time.

Although the new format uses the same extension .kcm, the syntax is quite different (and much more powerful).

As of Android Honeycomb 3.0, all Android key character map files must use the new syntax and plain text file format that is described in this document. The old syntax is not supported and the old .kcm.bin files are not recognized by the system.

Language note

Android does not currently support multilingual keyboards. Moreover, the built-in generic key character map assumes a US English keyboard layout.

OEMs are encouraged to provide custom key character maps for their keyboards if they are designed for other languages.

Future versions of Android may provide better support for multilingual keyboards or user-selectable keyboard layouts.

Validation

Make sure to validate your key character map files using the Validate Keymaps tool.