1 page.title=Key Layout Files 2 @jd:body 3 4 <!-- 5 Copyright 2013 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 <p>Key layout files (<code>.kl</code> files) are responsible for mapping Linux key codes 20 and axis codes to Android key codes and axis codes and specifying associated 21 policy flags.</p> 22 <p>Device-specific key layout files are <em>required</em> for all internal (built-in) 23 input devices that have keys, including special keys such as volume, power 24 and headset media keys.</p> 25 <p>Device-specific key layout files are <em>optional</em> for other input devices but 26 they are <em>recommended</em> for special-purpose keyboards and joysticks.</p> 27 <p>If no device-specific key layout file is available, then the system will 28 choose a default instead.</p> 29 <h2 id="location">Location</h2> 30 <p>Key layout files are located by USB vendor, product (and optionally version) 31 id or by input device name.</p> 32 <p>The following paths are consulted in order.</p> 33 <ul> 34 <li><code>/system/usr/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl</code></li> 35 <li><code>/system/usr/keylayout/Vendor_XXXX_Product_XXXX.kl</code></li> 36 <li><code>/system/usr/keylayout/DEVICE_NAME.kl</code></li> 37 <li><code>/data/system/devices/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl</code></li> 38 <li><code>/data/system/devices/keylayout/Vendor_XXXX_Product_XXXX.kl</code></li> 39 <li><code>/data/system/devices/keylayout/DEVICE_NAME.kl</code></li> 40 <li><code>/system/usr/keylayout/Generic.kl</code></li> 41 <li><code>/data/system/devices/keylayout/Generic.kl</code></li> 42 </ul> 43 <p>When constructing a file path that contains the device name, all characters 44 in the device name other than '0'-'9', 'a'-'z', 'A'-'Z', '-' or '<em>' are replaced by '</em>'.</p> 45 <h2 id="generic-key-layout-file">Generic Key Layout File</h2> 46 <p>The system provides a special built-in generic key layout file called <code>Generic.kl</code>. 47 This key layout is intended to support a variety of standard external 48 keyboards and joysticks.</p> 49 <p><em>Do not modify the generic key layout!</em></p> 50 <h2 id="syntax">Syntax</h2> 51 <p>A key layout file is a plain text file consisting of key or axis declarations 52 and flags.</p> 53 <h3 id="key-declarations">Key Declarations</h3> 54 <p>Key declarations each consist of the keyword <code>key</code> followed by a Linux key code 55 number and an Android key code name, or the keyword `usage` followed by a HID 56 usage and an Android key code name. The HID usage is represented as a 32-bit 57 integer, where the high 16-bits represent the HID usage page and the low 58 16-bits represent the HID usage ID. Either of these declarations can then be 59 followed by an optional set of whitespace delimited policy flags.</p> 60 <pre><code> 61 key 1 ESCAPE 62 key 114 VOLUME_DOWN WAKE 63 key 16 Q VIRTUAL WAKE 64 key usage 0x0c006F BRIGHTNESS_UP 65 </code></pre> 66 <p>The following policy flags are recognized:</p> 67 <ul> 68 <li><code>WAKE</code>: The key should wake the device when it is asleep. For historical reasons, 69 this flag behaves in the same manner as <code>WAKE_DROPPED</code> below.</li> 70 <li><code>WAKE_DROPPED</code>: The key should wake the device when it is asleep but the key itself 71 should be dropped when the wake-up occurs. In a sense, the key's action was to 72 wake the device, but the key itself is not processed.</li> 73 <li><code>SHIFT</code>: The key should be interpreted as if the SHIFT key were also pressed.</li> 74 <li><code>CAPS_LOCK</code>: The key should be interpreted as if the CAPS LOCK key were also pressed.</li> 75 <li><code>ALT</code>: The key should be interpreted as if the ALT key were also pressed.</li> 76 <li><code>ALT_GR</code>: The key should be interpreted as if the RIGHT ALT key were also pressed.</li> 77 <li><code>FUNCTION</code>: The key should be interpreted as if the FUNCTION key were also pressed.</li> 78 <li><code>VIRTUAL</code>: The key is a virtual soft key (capacitive button) that is adjacent to 79 the main touch screen. This causes special debouncing logic to be enabled, see below.</li> 80 <li><code>MENU</code>: Deprecated. Do not use.</li> 81 <li><code>LAUNCHER</code>: Deprecated. Do not use.</li> 82 </ul> 83 <h3 id="axis-declarations">Axis Declarations</h3> 84 <p>Axis declarations each consist of the keyword <code>axis</code> followed by a Linux axis code 85 number, and qualifiers that control the behavior of the axis including at least 86 one Android axis code name.</p> 87 <h4 id="basic-axes">Basic Axes</h4> 88 <p>A basic axis simply maps a Linux axis code to an Android axis code name.</p> 89 <p>The following declaration maps <code>ABS_X</code> (indicated by <code>0x00</code>) to <code>AXIS_X</code> (indicated by <code>X</code>).</p> 90 <pre><code>axis 0x00 X 91 </code></pre> 92 <p>In the above example, if the value of <code>ABS_X</code> is <code>5</code> then <code>AXIS_X</code> will be set to <code>5</code>.</p> 93 <h4 id="split-axes">Split Axes</h4> 94 <p>A split axis maps a Linux axis code to two Android axis code names, such that 95 values less than or greater than a threshold are split across two different axes when 96 mapped. This mapping is useful when a single physical axis reported by the device 97 encodes two different mutually exclusive logical axes.</p> 98 <p>The following declaration maps values of the <code>ABS_Y</code> axis (indicated by <code>0x01</code>) to 99 <code>AXIS_GAS</code> when less than <code>0x7f</code> or to <code>AXIS_BRAKE</code> when greater than <code>0x7f</code>.</p> 100 <pre><code>axis 0x01 split 0x7f GAS BRAKE 101 </code></pre> 102 <p>In the above example, if the value of <code>ABS_Y</code> is <code>0x7d</code> then <code>AXIS_GAS</code> is set 103 to <code>2</code> (<code>0x7f - 0x7d</code>) and <code>AXIS_BRAKE</code> is set to <code>0</code>. Conversely, if the value of 104 <code>ABS_Y</code> is <code>0x83</code> then <code>AXIS_GAS</code> is set to <code>0</code> and <code>AXIS_BRAKE</code> is set to <code>4</code> 105 (<code>0x83 - 0x7f</code>). Finally, if the value of <code>ABS_Y</code> equals the split value of <code>0x7f</code> 106 then both <code>AXIS_GAS</code> and <code>AXIS_BRAKE</code> are set to <code>0</code>.</p> 107 <h4 id="inverted-axes">Inverted Axes</h4> 108 <p>An inverted axis inverts the sign of the axis value.</p> 109 <p>The following declaration maps <code>ABS_RZ</code> (indicated by <code>0x05</code>) to <code>AXIS_BRAKE</code> 110 (indicated by <code>BRAKE</code>), and inverts the output by negating it.</p> 111 <pre><code>axis 0x05 invert BRAKE 112 </code></pre> 113 <p>In the above example, if the value of <code>ABS_RZ</code> is <code>2</code> then 114 <code>AXIS_BRAKE</code> is set to <code>-2</code>.</p> 115 <h4 id="center-flat-position-option">Center Flat Position Option</h4> 116 <p>The Linux input protocol provides a way for input device drivers to specify the 117 center flat position of joystick axes but not all of them do and some of them 118 provide incorrect values.</p> 119 <p>The center flat position is the neutral position of the axis, such as when 120 a directional pad is in the very middle of its range and the user is not 121 touching it.</p> 122 <p>To resolve this issue, an axis declaration may be followed by a <code>flat</code> 123 option that specifies the value of the center flat position for the axis.</p> 124 <pre><code>axis 0x03 Z flat 4096 125 </code></pre> 126 <p>In the above example, the center flat position is set to <code>4096</code>.</p> 127 <h3 id="comments">Comments</h3> 128 <p>Comment lines begin with '#' and continue to the end of the line. Like this:</p> 129 <pre><code># A comment! 130 </code></pre> 131 <p>Blank lines are ignored.</p> 132 <h3 id="examples">Examples</h3> 133 <h4 id="keyboard">Keyboard</h4> 134 <pre><code># This is an example of a key layout file for a keyboard. 135 136 key 1 ESCAPE 137 key 2 1 138 key 3 2 139 key 4 3 140 key 5 4 141 key 6 5 142 key 7 6 143 key 8 7 144 key 9 8 145 key 10 9 146 key 11 0 147 key 12 MINUS 148 key 13 EQUALS 149 key 14 DEL 150 151 # etc... 152 </code></pre> 153 <h4 id="system-controls">System Controls</h4> 154 <pre><code># This is an example of a key layout file for basic system controls, such as 155 # volume and power keys which are typically implemented as GPIO pins that 156 # the device decodes into key presses. 157 158 key 114 VOLUME_DOWN WAKE 159 key 115 VOLUME_UP WAKE 160 key 116 POWER WAKE 161 </code></pre> 162 <h4 id="capacitive-buttons">Capacitive Buttons</h4> 163 <pre><code># This is an example of a key layout file for a touch device with capacitive buttons. 164 165 key 139 MENU VIRTUAL 166 key 102 HOME VIRTUAL 167 key 158 BACK VIRTUAL 168 key 217 SEARCH VIRTUAL 169 </code></pre> 170 <h4 id="headset-jack-media-controls">Headset Jack Media Controls</h4> 171 <pre><code># This is an example of a key layout file for headset mounted media controls. 172 # A typical headset jack interface might have special control wires or detect known 173 # resistive loads as corresponding to media functions or volume controls. 174 # This file assumes that the driver decodes these signals and reports media 175 # controls as key presses. 176 177 key 163 MEDIA_NEXT WAKE 178 key 165 MEDIA_PREVIOUS WAKE 179 key 226 HEADSETHOOK WAKE 180 </code></pre> 181 <h4 id="joystick">Joystick</h4> 182 <pre><code># This is an example of a key layout file for a joystick. 183 184 # These are the buttons that the joystick supports, represented as keys. 185 key 304 BUTTON_A 186 key 305 BUTTON_B 187 key 307 BUTTON_X 188 key 308 BUTTON_Y 189 key 310 BUTTON_L1 190 key 311 BUTTON_R1 191 key 314 BUTTON_SELECT 192 key 315 BUTTON_START 193 key 316 BUTTON_MODE 194 key 317 BUTTON_THUMBL 195 key 318 BUTTON_THUMBR 196 197 # Left and right stick. 198 # The reported value for flat is 128 out of a range from -32767 to 32768, which is absurd. 199 # This confuses applications that rely on the flat value because the joystick actually 200 # settles in a flat range of +/- 4096 or so. We override it here. 201 axis 0x00 X flat 4096 202 axis 0x01 Y flat 4096 203 axis 0x03 Z flat 4096 204 axis 0x04 RZ flat 4096 205 206 # Triggers. 207 axis 0x02 LTRIGGER 208 axis 0x05 RTRIGGER 209 210 # Hat. 211 axis 0x10 HAT_X 212 axis 0x11 HAT_Y 213 </code></pre> 214 <h2 id="wake-keys">Wake Keys</h2> 215 <p>Wake keys are special keys that wake the device from sleep, such as the power key.</p> 216 <p>By default, for internal keyboard devices, no key is a wake key. For external 217 keyboard device, all keys are wake keys.</p> 218 <p>To make a key be a wake key, set the <code>WAKE_DROPPED</code> flag in the key layout file 219 for the keyboard device.</p> 220 <p>Note that the <code>WindowManagerPolicy</code> component is responsible for implementing wake 221 key behavior. Moreover, the key guard may prevent certain keys from functioning 222 as wake keys. A good place to start understanding wake key behavior is 223 <code>PhoneWindowManager.interceptKeyBeforeQueueing</code>.</p> 224 <h2 id="virtual-soft-keys">Virtual Soft Keys</h2> 225 <p>The input system provides special features for implementing virtual soft keys.</p> 226 <p>There are three cases:</p> 227 <ol> 228 <li> 229 <p>If the virtual soft keys are displayed graphically on the screen, as on the 230 Galaxy Nexus, then they are implemented by the Navigation Bar component in 231 the System UI package.</p> 232 <p>Because graphical virtual soft keys are implemented at a high layer in the 233 system, key layout files are not involved and the following information does 234 not apply.</p> 235 </li> 236 <li> 237 <p>If the virtual soft keys are implemented as an extended touchable region 238 that is part of the main touch screen, as on the Nexus One, then the 239 input system uses a virtual key map file to translate X / Y touch coordinates 240 into Linux key codes, then uses the key layout file to translate 241 Linux key codes into Android key codes.</p> 242 <p>Refer to the section on <a href="touch-devices.html">Touch Devices</a> 243 for more details about virtual key map files.</p> 244 <p>The key layout file for the touch screen input device must specify the 245 appropriate key mapping and include the <code>VIRTUAL</code> flag for each key.</p> 246 </li> 247 <li> 248 <p>If the virtual soft keys are implemented as capacitive buttons that are 249 separate from the main touch screen, as on the Nexus S, then the kernel 250 device driver or firmware is responsible for translating touches into 251 Linux key codes which the input system then translates into Android 252 key codes using the key layout file.</p> 253 <p>The key layout file for the capacitive button input device must specify the 254 appropriate key mapping and include the <code>VIRTUAL</code> flag for each key.</p> 255 </li> 256 </ol> 257 <p>When virtual soft key are located within or in close physical proximity of the 258 touch screen, it is easy for the user to accidentally press one of the buttons 259 when touching near the bottom of the screen or when sliding a finger from top 260 to bottom or from bottom to top on the screen.</p> 261 <p>To prevent this from happening, the input system applies a little debouncing 262 such that virtual soft key presses are ignored for a brief period of time 263 after the most recent touch on the touch screen. The delay is called the 264 virtual key quiet time.</p> 265 <p>To enable virtual soft key debouncing, we must do two things.</p> 266 <p>First, we provide a key layout file for the touch screen or capacitive button 267 input device with the <code>VIRTUAL</code> flag set for each key.</p> 268 <pre><code>key 139 MENU VIRTUAL 269 key 102 HOME VIRTUAL 270 key 158 BACK VIRTUAL 271 key 217 SEARCH VIRTUAL 272 </code></pre> 273 <p>Then, we set the value of the virtual key quiet time in a resource overlay 274 for the framework <code>config.xml</code> resource.</p> 275 <pre><code><!-- Specifies the amount of time to disable virtual keys after the screen is touched 276 in order to filter out accidental virtual key presses due to swiping gestures 277 or taps near the edge of the display. May be 0 to disable the feature. 278 It is recommended that this value be no more than 250 ms. 279 This feature should be disabled for most devices. --> 280 <integer name="config_virtualKeyQuietTimeMillis">250</integer> 281 </code></pre> 282 <h2 id="validation">Validation</h2> 283 <p>Make sure to validate your key layout files using the 284 <a href="validate-keymaps.html">Validate Keymaps</a> tool.</p> 285
