1 <!-- 2 Copyright 2011 The Android Open Source Project 3 4 Licensed under the Apache License, Version 2.0 (the "License"); 5 you may not use this file except in compliance with the License. 6 You may obtain a copy of the License at 7 8 http://www.apache.org/licenses/LICENSE-2.0 9 10 Unless required by applicable law or agreed to in writing, software 11 distributed under the License is distributed on an "AS IS" BASIS, 12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 See the License for the specific language governing permissions and 14 limitations under the License. 15 --> 16 17 # Key Character Map Files # 18 19 Key character map files (`.kcm` files) are responsible for mapping combinations 20 of Android key codes with modifiers to Unicode characters. 21 22 Device-specific key layout files are *required* for all internal (built-in) 23 input devices that have keys, if only to tell the system that the device 24 is special purpose only (not a full keyboard). 25 26 Device-specific key layout files are *optional* for external keyboards, and 27 often aren't needed at all. The system provides a generic key character map 28 that is suitable for many external keyboards. 29 30 If no device-specific key layout file is available, then the system will 31 choose a default instead. 32 33 ## Location ## 34 35 Key character map files are located by USB vendor, product (and optionally version) 36 id or by input device name. 37 38 The following paths are consulted in order. 39 40 * `/system/usr/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm` 41 * `/system/usr/keychars/Vendor_XXXX_Product_XXXX.kcm` 42 * `/system/usr/keychars/DEVICE_NAME.kcm` 43 * `/data/system/devices/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm` 44 * `/data/system/devices/keychars/Vendor_XXXX_Product_XXXX.kcm` 45 * `/data/system/devices/keychars/DEVICE_NAME.kcm` 46 * `/system/usr/keychars/Generic.kcm` 47 * `/data/system/devices/keychars/Generic.kcm` 48 * `/system/usr/keychars/Virtual.kcm` 49 * `/data/system/devices/keychars/Virtual.kcm` 50 51 When constructing a file path that contains the device name, all characters 52 in the device name other than '0'-'9', 'a'-'z', 'A'-'Z', '-' or '_' are replaced by '_'. 53 54 ## Generic Key Character Map File ## 55 56 The system provides a special built-in key character map file called `Generic.kcm`. 57 This key character map is intended to support a variety of standard external 58 keyboards. 59 60 *Do not modify the generic key character map!* 61 62 ## Virtual Key Character Map File ## 63 64 The system provides a special built-in key character map file called `Virtual.kcm` 65 that is used by the virtual keyboard devices. 66 67 The virtual keyboard device is a synthetic input device whose id is -1 68 (see `KeyCharacterMap.VIRTUAL_KEYBOARD`). It is present on all Android devices 69 beginning with Android Honeycomb 3.0. The purpose of the virtual keyboard device 70 is to provide a known built-in input device that can be used for injecting 71 keystokes into applications by the IME or by test instrumentation, even 72 for devices that do not have built-in keyboards. 73 74 The virtual keyboard is assumed to have a full QWERTY layout that is the 75 same on all devices. This makes it possible for applications to inject 76 keystrokes using the virtual keyboard device and always get the same results. 77 78 *Do not modify the virtual key character map!* 79 80 ## Syntax ## 81 82 A key character map file is a plain text file consisting of a keyboard type 83 declaration and a set of key declarations. 84 85 ### Keyboard Type Declaration ### 86 87 A keyboard type declaration describes the overall behavior of the keyboard. 88 A character map file must contain a keyboard type declaration. For clarity, 89 it is often placed at the top of the file. 90 91 type FULL 92 93 The following keyboard types are recognized: 94 95 * `NUMERIC`: A numeric (12-key) keyboard. 96 97 A numeric keyboard supports text entry using a multi-tap approach. 98 It may be necessary to tap a key multiple times to generate the desired letter or symbol. 99 100 This type of keyboard is generally designed for thumb typing. 101 102 Corresponds to `KeyCharacterMap.NUMERIC`. 103 104 * `PREDICTIVE`: A keyboard with all the letters, but with more than one letter per key. 105 106 This type of keyboard is generally designed for thumb typing. 107 108 Corresponds to `KeyCharacterMap.PREDICTIVE`. 109 110 * `ALPHA`: A keyboard with all the letters, and maybe some numbers. 111 112 An alphabetic keyboard supports text entry directly but may have a condensed 113 layout with a small form factor. In contrast to a `FULL` keyboard, some 114 symbols may only be accessible using special on-screen character pickers. 115 In addition, to improve typing speed and accuracy, the framework provides 116 special affordances for alphabetic keyboards such as auto-capitalization 117 and toggled / locked SHIFT and ALT keys. 118 119 This type of keyboard is generally designed for thumb typing. 120 121 * `FULL`: A full PC-style keyboard. 122 123 A full keyboard behaves like a PC keyboard. All symbols are accessed directly 124 by pressing keys on the keyboard without on-screen support or affordances such 125 as auto-capitalization. 126 127 This type of keyboard is generally designed for full two hand typing. 128 129 * `SPECIAL_FUNCTION`: A keyboard that is only used to perform system control functions 130 rather than for typing. 131 132 A special function keyboard consists only of non-printing keys such as 133 HOME and POWER that are not actually used for typing. 134 135 The `Generic.kcm` and `Virtual.kcm` key character maps are both `FULL` keyboards. 136 137 ### Key Declarations ### 138 139 Key declarations each consist of the keyword `key` followed by an Android key code 140 name, an open curly brace, a set of properties and behaviors and a close curly brace. 141 142 key A { 143 label: 'A' 144 base: 'a' 145 shift, capslock: 'A' 146 ctrl, alt, meta: none 147 } 148 149 #### Properties #### 150 151 Each key property establishes a mapping from a key to a behavior. To make the 152 key character map files more compact, several properties can be mapped to the 153 same behavior by separating them with a comma. 154 155 In the above example, the `label` property is assigned the `'A'` behavior. 156 Likewise, the `ctrl`, `alt` and `meta` properties are all simultaneously assigned 157 the `none` behavior. 158 159 The following properties are recognized: 160 161 * `label`: Specifies the label that is physically printed on the key, when it 162 consists of a single character. This is the value that is returned by 163 the `KeyCharacterMap.getDisplayLabel` method. 164 165 * `number`: Specifies the behavior (character that should be typed) when a numeric 166 text view has focus, such as when the user is typing a phone number. 167 168 Compact keyboards often combine multiple symbols into a single key, such that 169 the same key might be used to type `'1'` and `'a'` or `'#'` and `'q'`, perhaps. 170 For these keys, the `number` property should be set to indicate which symbol 171 should be typed in a numeric context, if any. 172 173 Some typical "numeric" symbols are digits `'0'` through `'9'`, `'#'`, `'+'`, 174 `'('`, `')'`, `','`, and `'.'`. 175 176 * `base`: Specifies the behavior (character that should be typed) when no modifiers 177 are pressed. 178 179 * <modifier> or <modifier1>`+`<modifier2>`+`...: Specifies the 180 behavior (character that should be typed) when the key is pressed and all of the 181 specified modifiers are active. 182 183 For example, the modifier property `shift` specifies a behavior that applies when 184 the either the LEFT SHIFT or RIGHT SHIFT modifier is pressed. 185 186 Similarly, the modifier property `rshift+ralt` specifies a behavior that applies 187 when the both RIGHT SHIFT and RIGHT ALT modifiers are pressed together. 188 189 The following modifiers are recognized in modifier properties: 190 191 * `shift`: Applies when either the LEFT SHIFT or RIGHT SHIFT modifier is pressed. 192 * `lshift`: Applies when the LEFT SHIFT modifier is pressed. 193 * `rshift`: Applies when the RIGHT SHIFT modifier is pressed. 194 * `alt`: Applies when either the LEFT ALT or RIGHT ALT modifier is pressed. 195 * `lalt`: Applies when the LEFT ALT modifier is pressed. 196 * `ralt`: Applies when the RIGHT ALT modifier is pressed. 197 * `ctrl`: Applies when either the LEFT CONTROL or RIGHT CONTROL modifier is pressed. 198 * `lctrl`: Applies when the LEFT CONTROL modifier is pressed. 199 * `rctrl`: Applies when the RIGHT CONTROL modifier is pressed. 200 * `meta`: Applies when either the LEFT META or RIGHT META modifier is pressed. 201 * `lmeta`: Applies when the LEFT META modifier is pressed. 202 * `rmeta`: Applies when the RIGHT META modifier is pressed. 203 * `sym`: Applies when the SYMBOL modifier is pressed. 204 * `fn`: Applies when the FUNCTION modifier is pressed. 205 * `capslock`: Applies when the CAPS LOCK modifier is locked. 206 * `numlock`: Applies when the NUM LOCK modifier is locked. 207 * `scrolllock`: Applies when the SCROLL LOCK modifier is locked. 208 209 The order in which the properties are listed is significant. When mapping a key to 210 a behavior, the system scans all relevant properties in order and returns the last 211 applicable behavior that it found. 212 213 Consequently, properties that are specified later override properties that are 214 specified earlier for a given key. 215 216 #### Behaviors #### 217 218 Each property maps to a behavior. The most common behavior is typing a character 219 but there are others. 220 221 The following behaviors are recognized: 222 223 * `none`: Don't type a character. 224 225 This behavior is the default when no character is specified. Specifying `none` 226 is optional but it improves clarity. 227 228 * `'X'`: Type the specified character literal. 229 230 This behavior causes the specified character to be entered into the focused 231 text view. The character literal may be any ASCII character, or one of the 232 following escape sequences: 233 234 * `'\\'`: Type a backslash character. 235 * `'\n'`: Type a new line character (use this for ENTER / RETURN). 236 * `'\t'`: Type a TAB character. 237 * `'\''`: Type an apostrophe character. 238 * `'\"'`: Type a quote character. 239 * `'\uXXXX'`: Type the Unicode character whose code point is given in hex by XXXX. 240 241 * `fallback` <Android key code name>: Perform a default action if the key is not 242 handled by the application. 243 244 This behavior causes the system to simulate a different key press when an application 245 does not handle the specified key natively. It is used to support default behavior 246 for new keys that not all applications know how to handle, such as ESCAPE or 247 numeric keypad keys (when numlock is not pressed). 248 249 When a fallback behavior is performed, the application will receive two key presses: 250 one for the original key and another for the fallback key that was selected. 251 If the application handles the original key during key up, then the fallback key 252 event will be canceled (`KeyEvent.isCanceled` will return `true`). 253 254 The system reserves two Unicode characters to perform special functions: 255 256 * `'\uef00'`: When this behavior is performed, the text view consumes and removes the 257 four characters preceding the cursor, interprets them as hex digits, and inserts the 258 corresponding Unicode code point. 259 260 * `'\uef01'`: When this behavior is performed, the text view displays a 261 character picker dialog that contains miscellaneous symbols. 262 263 The system recognizes the following Unicode characters as combining diacritical dead 264 key characters: 265 266 * `'\u0300'`: Grave accent. 267 * `'\u0301'`: Acute accent. 268 * `'\u0302'`: Circumflex accent. 269 * `'\u0303'`: Tilde accent. 270 * `'\u0308'`: Umlaut accent. 271 272 When a dead key is typed followed by another character, the dead key and the following 273 characters are composed. For example, when the user types a grave accent dead 274 key followed by the letter 'a', the result is 'à'. 275 276 Refer to `KeyCharacterMap.getDeadChar` for more information about dead key handling. 277 278 ### Comments ### 279 280 Comment lines begin with '#' and continue to the end of the line. Like this: 281 282 # A comment! 283 284 Blank lines are ignored. 285 286 ### How Key Combinations are Mapped to Behaviors ### 287 288 When the user presses a key, the system looks up the behavior associated with 289 the combination of that key press and the currently pressed modifiers. 290 291 #### SHIFT + A #### 292 293 Suppose the user pressed A and SHIFT together. The system first locates 294 the set of properties and behaviors associated with `KEYCODE_A`. 295 296 key A { 297 label: 'A' 298 base: 'a' 299 shift, capslock: 'A' 300 ctrl, alt, meta: none 301 } 302 303 The system scans the properties from first to last and left to right, ignoring 304 the `label` and `number` properties, which are special. 305 306 The first property encountered is `base`. The `base` property always applies to 307 a key, no matter what modifiers are pressed. It essentially specifies the default 308 behavior for the key unless it is overridden by following properties. 309 Since the `base` property applies to this key press, the system makes note 310 of the fact that its behavior is `'a'` (type the character `a`). 311 312 The system then continues to scan subsequent properties in case any of them 313 are more specific than `base` and override it. It encounters `shift` which 314 also applies to the key press SHIFT + A. So the system decides to ignore 315 the `base` property's behavior and chooses the behavior associated with 316 the `shift` property, which is `'A'` (type the character `A`). 317 318 It then continues to scan the table, however no other properties apply to this 319 key press (CAPS LOCK is not locked, neither CONTROL key is pressed, neither 320 ALT key is pressed and neither META key is pressed). 321 322 So the resulting behavior for the key combination SHIFT + A is `'A'`. 323 324 #### CONTROL + A #### 325 326 Now consider what would happen if the user pressed A and CONTROL together. 327 328 As before, the system would scan the table of properties. It would notice 329 that the `base` property applied but would also continue scanning until 330 it eventually reached the `control` property. As it happens, the `control` 331 property appears after `base` so its behavior overrides the `base` behavior. 332 333 So the resulting behavior for the key combination CONTROL + A is `none`. 334 335 #### ESCAPE #### 336 337 Now suppose the user pressed ESCAPE. 338 339 key ESCAPE { 340 base: fallback BACK 341 alt, meta: fallback HOME 342 ctrl: fallback MENU 343 } 344 345 This time the system obtains the behavior `fallback BACK`, a fallback behavior. 346 Because no character literal appears, no character will be typed. 347 348 When processing the key, the system will first deliver `KEYCODE_ESCAPE` to the 349 application. If the application does not handle it, then the system will try 350 again but this time it will deliver `KEYCODE_BACK` to the application as 351 requested by the fallback behavior. 352 353 So applications that recognize and support `KEYCODE_ESCAPE` have the 354 opportunity to handle it as is, but other applications that do not can instead 355 perform the fallback action of treating the key as if it were `KEYCODE_BACK`. 356 357 #### NUMPAD_0 with or without NUM LOCK #### 358 359 The numeric keypad keys have very different interpretations depending on whether 360 the NUM LOCK key is locked. 361 362 The following key declaration ensures that `KEYCODE_NUMPAD_0` types `0` 363 when NUM LOCK is pressed. When NUM LOCK is not pressed, the key is delivered 364 to the application as usual, and if it is not handled, then the fallback 365 key `KEYCODE_INSERT` is delivered instead. 366 367 key NUMPAD_0 { 368 label, number: '0' 369 base: fallback INSERT 370 numlock: '0' 371 ctrl, alt, meta: none 372 } 373 374 As we can see, fallback key declarations greatly improve compatibility 375 with older applications that do not recognize or directly support all of the keys 376 that are present on a full PC style keyboard. 377 378 ### Examples ### 379 380 #### Full Keyboard #### 381 382 # This is an example of part of a key character map file for a full keyboard 383 # include a few fallback behaviors for special keys that few applications 384 # handle themselves. 385 386 type FULL 387 388 key C { 389 label: 'C' 390 base: 'c' 391 shift, capslock: 'C' 392 alt: '\u00e7' 393 shift+alt: '\u00c7' 394 ctrl, meta: none 395 } 396 397 key SPACE { 398 label: ' ' 399 base: ' ' 400 ctrl: none 401 alt, meta: fallback SEARCH 402 } 403 404 key NUMPAD_9 { 405 label, number: '9' 406 base: fallback PAGE_UP 407 numlock: '9' 408 ctrl, alt, meta: none 409 } 410 411 #### Alphanumeric Keyboard #### 412 413 # This is an example of part of a key character map file for an alphanumeric 414 # thumb keyboard. Some keys are combined, such as `A` and `2`. Here we 415 # specify `number` labels to tell the system what to do when the user is 416 # typing a number into a dial pad. 417 # 418 # Also note the special character '\uef01' mapped to ALT+SPACE. 419 # Pressing this combination of keys invokes an on-screen character picker. 420 421 type ALPHA 422 423 key A { 424 label: 'A' 425 number: '2' 426 base: 'a' 427 shift, capslock: 'A' 428 alt: '#' 429 shift+alt, capslock+alt: none 430 } 431 432 key SPACE { 433 label: ' ' 434 number: ' ' 435 base: ' ' 436 shift: ' ' 437 alt: '\uef01' 438 shift+alt: '\uef01' 439 } 440 441 #### Game Pad #### 442 443 # This is an example of part of a key character map file for a game pad. 444 # It defines fallback actions that enable the user to navigate the user interface 445 # by pressing buttons. 446 447 type SPECIAL_FUNCTION 448 449 key BUTTON_A { 450 base: fallback BACK 451 } 452 453 key BUTTON_X { 454 base: fallback DPAD_CENTER 455 } 456 457 key BUTTON_START { 458 base: fallback HOME 459 } 460 461 key BUTTON_SELECT { 462 base: fallback MENU 463 } 464 465 ## Compatibility Note ## 466 467 Prior to Android Honeycomb 3.0, the Android key character map was specified 468 using a very different syntax and was compiled into a binary file format 469 (`.kcm.bin`) at build time. 470 471 Although the new format uses the same extension `.kcm`, the syntax is quite 472 different (and much more powerful). 473 474 As of Android Honeycomb 3.0, all Android key character map files must use 475 the new syntax and plain text file format that is described in this document. 476 The old syntax is not supported and the old `.kcm.bin` files are not recognized 477 by the system. 478 479 ## Language Note ## 480 481 Android does not currently support multilingual keyboards. Moreover, the 482 built-in generic key character map assumes a US English keyboard layout. 483 484 OEMs are encouraged to provide custom key character maps for their keyboards 485 if they are designed for other languages. 486 487 Future versions of Android may provide better support for multilingual keyboards 488 or user-selectable keyboard layouts. 489 490 ## Validation ## 491 492 Make sure to validate your key character map files using the 493 [Validate Keymaps](/tech/input/validate-keymaps.html) tool. 494
