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