Add section on input devices.
Change-Id: Ib9c4909881df505b11537c28bd08182933a5565a
diff --git a/src/tech/input/key-character-map-files.md b/src/tech/input/key-character-map-files.md
new file mode 100644
index 0000000..4a9ec34
--- /dev/null
+++ b/src/tech/input/key-character-map-files.md
@@ -0,0 +1,493 @@
+<!--
+ Copyright 2011 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+# 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.
+
+* `/system/usr/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm`
+* `/system/usr/keychars/Vendor_XXXX_Product_XXXX.kcm`
+* `/system/usr/keychars/DEVICE_NAME.kcm`
+* `/data/system/devices/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm`
+* `/data/system/devices/keychars/Vendor_XXXX_Product_XXXX.kcm`
+* `/data/system/devices/keychars/DEVICE_NAME.kcm`
+* `/system/usr/keychars/Generic.kcm`
+* `/data/system/devices/keychars/Generic.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
+keystokes 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](/tech/input/validate-keymaps.html) tool.