diff options
Diffstat (limited to 'en/devices/input/key-layout-files.html')
| -rw-r--r-- | en/devices/input/key-layout-files.html | 332 |
1 files changed, 0 insertions, 332 deletions
diff --git a/en/devices/input/key-layout-files.html b/en/devices/input/key-layout-files.html deleted file mode 100644 index be58e7e1..00000000 --- a/en/devices/input/key-layout-files.html +++ /dev/null @@ -1,332 +0,0 @@ -<html devsite> - <head> - <title>Key Layout Files</title> - <meta name="project_path" value="/_project.yaml" /> - <meta name="book_path" value="/_book.yaml" /> - </head> - <body> - <!-- - Copyright 2017 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. - --> - - - -<p>Key layout files (<code>.kl</code> files) map Linux key codes and axis codes -to Android key codes and axis codes and specify associated policy flags. -Device-specific key layout files are:</p> -<ul> -<li><em>Required</em> for internal (built-in) input devices with keys, including -special keys such as volume, power, and headset media keys.</li> -<li><em>Optional</em> for other input devices but <em>recommended</em> for -special-purpose keyboards and joysticks.</li> -</ul> -<p>If no device-specific key layout file is available, the system chooses a -default instead.</p> - -<h2 id="location">Location</h2> -<p>Key layout files are located by USB vendor, product (and optionally version) -id or by input device name. The following paths are consulted in order:</p> -<ul> -<li><code>/odm/usr/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl</code></li> -<li><code>/vendor/usr/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl</code></li> -<li><code>/system/usr/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl</code></li> -<li><code>/data/system/devices/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl</code></li> -<li><code>/odm/usr/keylayout/Vendor_XXXX_Product_XXXX.kl</code></li> -<li><code>/vendor/usr/keylayout/Vendor_XXXX_Product_XXXX.kl</code></li> -<li><code>/system/usr/keylayout/Vendor_XXXX_Product_XXXX.kl</code></li> -<li><code>/data/system/devices/keylayout/Vendor_XXXX_Product_XXXX.kl</code></li> -<li><code>/odm/usr/keylayout/DEVICE_NAME.kl</code></li> -<li><code>/vendor/usr/keylayout/DEVICE_NAME.kl</code></li> -<li><code>/system/usr/keylayout/DEVICE_NAME.kl</code></li> -<li><code>/data/system/devices/keylayout/DEVICE_NAME.kl</code></li> -<li><code>/odm/usr/keylayout/Generic.kl</code></li> -<li><code>/vendor/usr/keylayout/Generic.kl</code></li> -<li><code>/system/usr/keylayout/Generic.kl</code></li> -<li><code>/data/system/devices/keylayout/Generic.kl</code></li> -</ul> -<p>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 -'_'.</p> - -<h2 id="generic-key-layout-file">Generic key layout file</h2> -<p>The system provides a special built-in generic key layout file called -<code>Generic.kl</code>. This key layout is intended to support a variety of -standard external keyboards and joysticks. <strong>Do not modify the generic key -layout!</strong></p> - -<h2 id="syntax">Syntax</h2> -<p>A key layout file is a plain text file consisting of key or axis declarations -and flags.</p> - -<h3 id="key-declarations">Key declarations</h3> -<p>Key declarations consist of the keyword <code>key</code> followed by a Linux -key code number and Android key code name, or the keyword usage followed by a -HID usage and Android key code name. The HID usage is represented as a 32-bit -integer, where the high 16-bits represent the HID usage page and the low 16-bits -represent the HID usage ID. Either declaration can be followed by an optional -set of whitespace-delimited policy flags.</p> -<pre class="devsite-click-to-copy"> -key 1 ESCAPE -key 114 VOLUME_DOWN -key 16 Q VIRTUAL -key usage 0x0c006F BRIGHTNESS_UP -</pre> -<p>The following policy flags are recognized:</p> -<ul> -<li><code>FUNCTION</code>: The key should be interpreted as if the FUNCTION key -were also pressed.</li> -<li><code>GESTURE</code>: The key generated by a user gesture, such as palming -the touchscreen.</li> -<li><code>VIRTUAL</code>: The key is a virtual soft key (capacitive button) -adjacent to the main touch screen. This causes special debouncing logic to be -enabled (see below).</li> -</ul> - -<h3 id="axis-declarations">Axis declarations</h3> -<p>Axis declarations each consist of the keyword <code>axis</code> followed by a -Linux axis code number and qualifiers that control the behavior of the axis -including at least one Android axis code name.</p> - -<h4 id="basic-axes">Basic axes</h4> -<p>A basic axis simply maps a Linux axis code to an Android axis code name. The -following declaration maps <code>ABS_X</code> (indicated by <code>0x00</code>) -to <code>AXIS_X</code> (indicated by <code>X</code>).</p> -<pre class="devsite-click-to-copy"> -axis 0x00 X -</pre> -<p>In the above example, if the value of <code>ABS_X</code> is <code>5</code> -then <code>AXIS_X</code> is set to <code>5</code>.</p> - -<h4 id="split-axes">Split axes</h4> -<p>A split axis maps a Linux axis code to two Android axis code names, such that -values less than or greater than a threshold are split across two different axes -when mapped. This mapping is useful when a single physical axis reported by the -device encodes two different mutually exclusive logical axes.</p> -<p>The following declaration maps values of the <code>ABS_Y</code> axis -(indicated by <code>0x01</code>) to <code>AXIS_GAS</code> when less than -<code>0x7f</code> or to <code>AXIS_BRAKE</code> when greater than -<code>0x7f</code>.</p> -<pre class="devsite-click-to-copy"> -axis 0x01 split 0x7f GAS BRAKE</pre> -<p>In the above example, if the value of <code>ABS_Y</code> is <code>0x7d</code> -then <code>AXIS_GAS</code> is set to <code>2</code> (<code>0x7f - 0x7d</code>) -and <code>AXIS_BRAKE</code> is set to <code>0</code>. Conversely, if the value -of <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> -(<code>0x83 - 0x7f</code>). Finally, if the value of <code>ABS_Y</code> equals -the split value of <code>0x7f</code> then both <code>AXIS_GAS</code> and -<code>AXIS_BRAKE</code> are set to <code>0</code>.</p> - -<h4 id="inverted-axes">Inverted axes</h4> -<p>An inverted axis inverts the sign of the axis value. The following -declaration maps <code>ABS_RZ</code> (indicated by <code>0x05</code>) to -<code>AXIS_BRAKE</code> (indicated by <code>BRAKE</code>), and inverts the -output by negating it.</p> -<pre class="devsite-click-to-copy"> -axis 0x05 invert BRAKE -</pre> -<p>In the above example, if the value of <code>ABS_RZ</code> is <code>2</code> -then <code>AXIS_BRAKE</code> is set to <code>-2</code>.</p> - -<h4 id="center-flat-option">Center flat option</h4> -<p> A joystick device may report input events even when the joystick is not being used, due to noise. -This noise typically comes from the left and/or right sticks, and causes the driver to report - a position value near 0. -The "center flat" value specifies the amount of noise to expect from the controller at rest.</p> -<p>The Linux input protocol provides a way for input device drivers to specify -the center flat value of joystick axes, but not all drivers report it and some of them provide -incorrect values. To resolve this issue, an axis declaration may be followed by a -<code>flat</code> option that specifies the width of the region around the center -position of the axis that should be considered as centered.</p> -<p> For example, if a device driver reports values for <code>AXIS_X</code> between 0 and 100, -then 0 will be mapped to -1 and 100 will be mapped to 1 by the Android input system. -The center of the range will be 50 in the unscaled coordinates and 0 in the scaled coordinates. -If a flat value is equal to 10, -then the developers should assume that any <code>AXIS_X</code> value reported between --0.1 and 0.1 (between 40 and 60 in unscaled coordinates) is noise, and treat those values coming -from the joystick as zero.</p> -<p class="note"><strong>Note</strong>: While the key layout file specifies the value - for the driver coordinate space, -the value reported by android.view.InputDevice.MotionRange#getFlat() is in the Android -coordinate space.</p> - -<pre class="devsite-click-to-copy"> -axis 0x03 Z flat 4096 -</pre> -<p>In the above example, the center flat value is set to <code>4096</code>. -</p> - -<h3 id="comments">Comments</h3> -<p>Comment lines begin with # and continue to the end of the line:</p> -<pre class="devsite-click-to-copy"> -# A comment! -</pre> -<p>Blank lines are ignored.</p> - -<h3 id="examples">Examples</h3> - -<h4 id="keyboard">Keyboard</h4> -<pre class="devsite-click-to-copy"> -# This is an example of a key layout file for a keyboard. - -key 1 ESCAPE -key 2 1 -key 3 2 -key 4 3 -key 5 4 -key 6 5 -key 7 6 -key 8 7 -key 9 8 -key 10 9 -key 11 0 -key 12 MINUS -key 13 EQUALS -key 14 DEL - -# etc... -</pre> - -<h4 id="system-controls">System controls</h4> -<pre class="devsite-click-to-copy"> -# This is an example of a key layout file for basic system controls, -# such as volume and power keys which are typically implemented as GPIO pins -# the device decodes into key presses. - -key 114 VOLUME_DOWN -key 115 VOLUME_UP -key 116 POWER -</pre> - -<h4 id="capacitive-buttons">Capacitive buttons</h4> -<pre class="devsite-click-to-copy"> -# This is an example of a key layout file for a touch device with capacitive buttons. - -key 139 MENU VIRTUAL -key 172 HOME VIRTUAL -key 158 BACK VIRTUAL -key 217 SEARCH VIRTUAL -</pre> - -<h4 id="headset-jack-media-controls">Headset jack media controls</h4> -<pre class="devsite-click-to-copy"> -# This is an example of a key layout file for headset mounted media controls. -# A typical headset jack interface might have special control wires or detect known -# resistive loads as corresponding to media functions or volume controls. -# This file assumes that the driver decodes these signals and reports media -# controls as key presses. - -key 163 MEDIA_NEXT -key 165 MEDIA_PREVIOUS -key 226 HEADSETHOOK -</pre> - -<h4 id="joystick">Joystick</h4> -<pre class="devsite-click-to-copy"> -# This is an example of a key layout file for a joystick. - -# These are the buttons that the joystick supports, represented as keys. -key 304 BUTTON_A -key 305 BUTTON_B -key 307 BUTTON_X -key 308 BUTTON_Y -key 310 BUTTON_L1 -key 311 BUTTON_R1 -key 314 BUTTON_SELECT -key 315 BUTTON_START -key 316 BUTTON_MODE -key 317 BUTTON_THUMBL -key 318 BUTTON_THUMBR - -# Left and right stick. -# The reported value for flat is 128 in a range of -32767 to 32768, which is absurd. -# This confuses applications that rely on the flat value because the joystick -# actually settles in a flat range of +/- 4096 or so. We override it here. -axis 0x00 X flat 4096 -axis 0x01 Y flat 4096 -axis 0x03 Z flat 4096 -axis 0x04 RZ flat 4096 - -# Triggers. -axis 0x02 LTRIGGER -axis 0x05 RTRIGGER - -# Hat. -axis 0x10 HAT_X -axis 0x11 HAT_Y -</pre> - -<h2 id="virtual-soft-keys">Virtual soft keys</h2> -<p>The input system provides special features for implementing virtual soft keys -in the following use cases:</p> -<ol> -<li>If the virtual soft keys are displayed graphically on the screen (such as on -the Galaxy Nexus), they are implemented by the Navigation Bar component in the -System UI package. Because graphical virtual soft keys are implemented at a high -layer in the system, key layout files are not involved and the following -information does not apply.</li> -<li>If the virtual soft keys are implemented as an extended touchable region -that is part of the main touch screen (such as on the Nexus One), the input -system uses a virtual key map file to translate X/Y touch coordinates into -Linux key codes, then uses the key layout file to translate Linux key codes into -Android key codes (for details on virtual key map files, see -<a href="touch-devices.html">Touch Devices</a>). The key layout file for the -touch screen input device must specify the appropriate key mapping and include -the <code>VIRTUAL</code> flag for each key.</li> -<li>If the virtual soft keys are implemented as capacitive buttons separate from -the main touch screen (such as on the Nexus S), the kernel device driver or -firmware is responsible for translating touches into Linux key codes which the -input system then translates into Android key codes using the key layout file. -The key layout file for the capacitive button input device must specify the -appropriate key mapping and include the <code>VIRTUAL</code> flag for each key.</li> -</ol> -<p>When virtual soft keys are located within or in close physical proximity of -the touch screen, it is easy for users to accidentally press a button when -touching near the bottom of the screen or when sliding a finger top-to-bottom or -bottom-to-top on the screen. To prevent this, the input system applies a little -debouncing such that virtual soft key presses are ignored for a brief period of -time after the most recent touch on the touch screen (this delay is called the -<em>virtual key quiet time</em>).</p> -<p>To enable virtual soft key debouncing:</p> -<ol> -<li>Provide a key layout file for the touch screen or capacitive button -input device with the <code>VIRTUAL</code> flag set for each key. -<pre class="devsite-click-to-copy"> -key 139 MENU VIRTUAL -key 172 HOME VIRTUAL -key 158 BACK VIRTUAL -key 217 SEARCH VIRTUAL -</pre> -</li> -<li>Set the value of the virtual key quiet time in a resource overlay for the -framework <code>config.xml</code> resource. -<pre class="devsite-click-to-copy"> -<!-- Specifies the amount of time to disable virtual keys after the screen -is touched to filter out accidental virtual key presses due to swiping gestures -or taps near the edge of the display. May be 0 to disable the feature. -It is recommended that this value be no more than 250 ms. -This feature should be disabled for most devices. --> - -<integer name="config_virtualKeyQuietTimeMillis">250</integer> -</pre> -</li> -</ol> - -<h2 id="validation">Validation</h2> -<p>You should validate your key layout files using the -<a href="validate-keymaps.html">Validate Keymaps</a> tool.</p> - </body> -</html> |