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