src/devices/input/key-layout-files.jd - platform/docs/source.android.com - Git at Google


            
            page.title=Key Layout Files

            
            @jd:body


            <!--

            
                Copyright 2013 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) are responsible for mapping Linux key codes

            
            and axis codes to Android key codes and axis codes and specifying associated

            
            policy flags.</p>

            
            <p>Device-specific key layout files are <em>required</em> for all internal (built-in)

            
            input devices that have keys, including special keys such as volume, power

            
            and headset media keys.</p>

            
            <p>Device-specific key layout files are <em>optional</em> for other input devices but

            
            they are <em>recommended</em> for special-purpose keyboards and joysticks.</p>

            
            <p>If no device-specific key layout file is available, then the system will

            
            choose 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.</p>

            
            <p>The following paths are consulted in order.</p>

            
            <ul>

            
            <li><code>/system/usr/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl</code></li>

            
            <li><code>/system/usr/keylayout/Vendor_XXXX_Product_XXXX.kl</code></li>

            
            <li><code>/system/usr/keylayout/DEVICE_NAME.kl</code></li>

            
            <li><code>/data/system/devices/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl</code></li>

            
            <li><code>/data/system/devices/keylayout/Vendor_XXXX_Product_XXXX.kl</code></li>

            
            <li><code>/data/system/devices/keylayout/DEVICE_NAME.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 '<em>' are replaced by '</em>'.</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.</p>

            
            <p><em>Do not modify the generic key layout!</em></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 each consist of the keyword <code>key</code> followed by a Linux key code

            
            number and an Android key code name, or the keyword `usage` followed by a HID

            
            usage and an 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 of these declarations can then be

            
            followed by an optional set of whitespace delimited policy flags.</p>

            
            <pre><code>

            
            key 1     ESCAPE

            
            key 114   VOLUME_DOWN       WAKE

            
            key 16    Q                 VIRTUAL     WAKE

            
            key usage 0x0c006F          BRIGHTNESS_UP

            
            </code></pre>

            
            <p>The following policy flags are recognized:</p>

            
            <ul>

            
            <li><code>WAKE</code>: The key should wake the device when it is asleep.  For historical reasons,

            
                this flag behaves in the same manner as <code>WAKE_DROPPED</code> below.</li>

            
            <li><code>WAKE_DROPPED</code>: The key should wake the device when it is asleep but the key itself

            
                should be dropped when the wake-up occurs.  In a sense, the key's action was to

            
                wake the device, but the key itself is not processed.</li>

            
            <li><code>SHIFT</code>: The key should be interpreted as if the SHIFT key were also pressed.</li>

            
            <li><code>CAPS_LOCK</code>: The key should be interpreted as if the CAPS LOCK key were also pressed.</li>

            
            <li><code>ALT</code>: The key should be interpreted as if the ALT key were also pressed.</li>

            
            <li><code>ALT_GR</code>: The key should be interpreted as if the RIGHT ALT key were also pressed.</li>

            
            <li><code>FUNCTION</code>: The key should be interpreted as if the FUNCTION key were also pressed.</li>

            
            <li><code>VIRTUAL</code>: The key is a virtual soft key (capacitive button) that is adjacent to

            
                the main touch screen.  This causes special debouncing logic to be enabled, see below.</li>

            
            <li><code>MENU</code>: Deprecated.  Do not use.</li>

            
            <li><code>LAUNCHER</code>: Deprecated.  Do not use.</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.</p>

            
            <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>

            
            <pre><code>axis 0x00 X

            
            </code></pre>

            
            <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>

            
            <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><code>axis 0x01 split 0x7f GAS BRAKE

            
            </code></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.</p>

            
            <p>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><code>axis 0x05 invert BRAKE

            
            </code></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-position-option">Center Flat Position Option</h4>

            
            <p>The Linux input protocol provides a way for input device drivers to specify the

            
            center flat position of joystick axes but not all of them do and some of them

            
            provide incorrect values.</p>

            
            <p>The center flat position is the neutral position of the axis, such as when

            
            a directional pad is in the very middle of its range and the user is not

            
            touching it.</p>

            
            <p>To resolve this issue, an axis declaration may be followed by a <code>flat</code>

            
            option that specifies the value of the center flat position for the axis.</p>

            
            <pre><code>axis 0x03 Z flat 4096

            
            </code></pre>

            
            <p>In the above example, the center flat position 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.  Like this:</p>

            
            <pre><code># A comment!

            
            </code></pre>

            
            <p>Blank lines are ignored.</p>

            
            <h3 id="examples">Examples</h3>

            
            <h4 id="keyboard">Keyboard</h4>

            
            <pre><code># 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...

            
            </code></pre>

            
            <h4 id="system-controls">System Controls</h4>

            
            <pre><code># 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 that

            
            # the device decodes into key presses.


            key 114   VOLUME_DOWN       WAKE

            
            key 115   VOLUME_UP         WAKE

            
            key 116   POWER             WAKE

            
            </code></pre>

            
            <h4 id="capacitive-buttons">Capacitive Buttons</h4>

            
            <pre><code># This is an example of a key layout file for a touch device with capacitive buttons.


            key 139    MENU           VIRTUAL

            
            key 102    HOME           VIRTUAL

            
            key 158    BACK           VIRTUAL

            
            key 217    SEARCH         VIRTUAL

            
            </code></pre>

            
            <h4 id="headset-jack-media-controls">Headset Jack Media Controls</h4>

            
            <pre><code># 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        WAKE

            
            key 165   MEDIA_PREVIOUS    WAKE

            
            key 226   HEADSETHOOK       WAKE

            
            </code></pre>

            
            <h4 id="joystick">Joystick</h4>

            
            <pre><code># 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 out of a range from -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

            
            </code></pre>

            
            <h2 id="wake-keys">Wake Keys</h2>

            
            <p>Wake keys are special keys that wake the device from sleep, such as the power key.</p>

            
            <p>By default, for internal keyboard devices, no key is a wake key.  For external

            
            keyboard device, all keys are wake keys.</p>

            
            <p>To make a key be a wake key, set the <code>WAKE_DROPPED</code> flag in the key layout file

            
            for the keyboard device.</p>

            
            <p>Note that the <code>WindowManagerPolicy</code> component is responsible for implementing wake

            
            key behavior.  Moreover, the key guard may prevent certain keys from functioning

            
            as wake keys.  A good place to start understanding wake key behavior is

            
            <code>PhoneWindowManager.interceptKeyBeforeQueueing</code>.</p>

            
            <h2 id="virtual-soft-keys">Virtual Soft Keys</h2>

            
            <p>The input system provides special features for implementing virtual soft keys.</p>

            
            <p>There are three cases:</p>

            
            <ol>

            
            <li>

            
            <p>If the virtual soft keys are displayed graphically on the screen, as on the

            
                Galaxy Nexus, then they are implemented by the Navigation Bar component in

            
                the System UI package.</p>

            
            <p>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.</p>

            
            </li>

            
            <li>

            
            <p>If the virtual soft keys are implemented as an extended touchable region

            
                that is part of the main touch screen, as on the Nexus One, then 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.</p>

            
            <p>Refer to the section on <a href="touch-devices.html">Touch Devices</a>

            
            for more details about virtual key map files.</p>

            
            <p>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.</p>

            
            </li>

            
            <li>

            
            <p>If the virtual soft keys are implemented as capacitive buttons that are

            
                separate from the main touch screen, as on the Nexus S, then 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.</p>

            
            <p>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.</p>

            
            </li>

            
            </ol>

            
            <p>When virtual soft key are located within or in close physical proximity of the

            
            touch screen, it is easy for the user to accidentally press one of the buttons

            
            when touching near the bottom of the screen or when sliding a finger from top

            
            to bottom or from bottom to top on the screen.</p>

            
            <p>To prevent this from happening, 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.  The delay is called the

            
            virtual key quiet time.</p>

            
            <p>To enable virtual soft key debouncing, we must do two things.</p>

            
            <p>First, we provide a key layout file for the touch screen or capacitive button

            
            input device with the <code>VIRTUAL</code> flag set for each key.</p>

            
            <pre><code>key 139    MENU           VIRTUAL

            
            key 102    HOME           VIRTUAL

            
            key 158    BACK           VIRTUAL

            
            key 217    SEARCH         VIRTUAL

            
            </code></pre>

            
            <p>Then, we set the value of the virtual key quiet time in a resource overlay

            
            for the framework <code>config.xml</code> resource.</p>

            
            <pre><code>&lt;!-- Specifies the amount of time to disable virtual keys after the screen is touched

            
                 in order 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. --&gt;

            
            &lt;integer name="config_virtualKeyQuietTimeMillis"&gt;250&lt;/integer&gt;

            
            </code></pre>

            
            <h2 id="validation">Validation</h2>

            
            <p>Make sure to validate your key layout files using the

            
            <a href="validate-keymaps.html">Validate Keymaps</a> tool.</p>
	page.title=Key Layout Files
	@jd:body

	<!--
	Copyright 2013 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) are responsible for mapping Linux key codes
	and axis codes to Android key codes and axis codes and specifying associated
	policy flags.</p>
	<p>Device-specific key layout files are <em>required</em> for all internal (built-in)
	input devices that have keys, including special keys such as volume, power
	and headset media keys.</p>
	<p>Device-specific key layout files are <em>optional</em> for other input devices but
	they are <em>recommended</em> for special-purpose keyboards and joysticks.</p>
	<p>If no device-specific key layout file is available, then the system will
	choose 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.</p>
	<p>The following paths are consulted in order.</p>
	<ul>
	<li><code>/system/usr/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl</code></li>
	<li><code>/system/usr/keylayout/Vendor_XXXX_Product_XXXX.kl</code></li>
	<li><code>/system/usr/keylayout/DEVICE_NAME.kl</code></li>
	<li><code>/data/system/devices/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl</code></li>
	<li><code>/data/system/devices/keylayout/Vendor_XXXX_Product_XXXX.kl</code></li>
	<li><code>/data/system/devices/keylayout/DEVICE_NAME.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 '<em>' are replaced by '</em>'.</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.</p>
	<p><em>Do not modify the generic key layout!</em></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 each consist of the keyword <code>key</code> followed by a Linux key code
	number and an Android key code name, or the keyword `usage` followed by a HID
	usage and an 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 of these declarations can then be
	followed by an optional set of whitespace delimited policy flags.</p>
	<pre><code>
	key 1 ESCAPE
	key 114 VOLUME_DOWN WAKE
	key 16 Q VIRTUAL WAKE
	key usage 0x0c006F BRIGHTNESS_UP
	</code></pre>
	<p>The following policy flags are recognized:</p>
	<ul>
	<li><code>WAKE</code>: The key should wake the device when it is asleep. For historical reasons,
	this flag behaves in the same manner as <code>WAKE_DROPPED</code> below.</li>
	<li><code>WAKE_DROPPED</code>: The key should wake the device when it is asleep but the key itself
	should be dropped when the wake-up occurs. In a sense, the key's action was to
	wake the device, but the key itself is not processed.</li>
	<li><code>SHIFT</code>: The key should be interpreted as if the SHIFT key were also pressed.</li>
	<li><code>CAPS_LOCK</code>: The key should be interpreted as if the CAPS LOCK key were also pressed.</li>
	<li><code>ALT</code>: The key should be interpreted as if the ALT key were also pressed.</li>
	<li><code>ALT_GR</code>: The key should be interpreted as if the RIGHT ALT key were also pressed.</li>
	<li><code>FUNCTION</code>: The key should be interpreted as if the FUNCTION key were also pressed.</li>
	<li><code>VIRTUAL</code>: The key is a virtual soft key (capacitive button) that is adjacent to
	the main touch screen. This causes special debouncing logic to be enabled, see below.</li>
	<li><code>MENU</code>: Deprecated. Do not use.</li>
	<li><code>LAUNCHER</code>: Deprecated. Do not use.</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.</p>
	<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>
	<pre><code>axis 0x00 X
	</code></pre>
	<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>
	<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><code>axis 0x01 split 0x7f GAS BRAKE
	</code></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.</p>
	<p>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><code>axis 0x05 invert BRAKE
	</code></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-position-option">Center Flat Position Option</h4>
	<p>The Linux input protocol provides a way for input device drivers to specify the
	center flat position of joystick axes but not all of them do and some of them
	provide incorrect values.</p>
	<p>The center flat position is the neutral position of the axis, such as when
	a directional pad is in the very middle of its range and the user is not
	touching it.</p>
	<p>To resolve this issue, an axis declaration may be followed by a <code>flat</code>
	option that specifies the value of the center flat position for the axis.</p>
	<pre><code>axis 0x03 Z flat 4096
	</code></pre>
	<p>In the above example, the center flat position 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. Like this:</p>
	<pre><code># A comment!
	</code></pre>
	<p>Blank lines are ignored.</p>
	<h3 id="examples">Examples</h3>
	<h4 id="keyboard">Keyboard</h4>
	<pre><code># 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...
	</code></pre>
	<h4 id="system-controls">System Controls</h4>
	<pre><code># 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 that
	# the device decodes into key presses.

	key 114 VOLUME_DOWN WAKE
	key 115 VOLUME_UP WAKE
	key 116 POWER WAKE
	</code></pre>
	<h4 id="capacitive-buttons">Capacitive Buttons</h4>
	<pre><code># This is an example of a key layout file for a touch device with capacitive buttons.

	key 139 MENU VIRTUAL
	key 102 HOME VIRTUAL
	key 158 BACK VIRTUAL
	key 217 SEARCH VIRTUAL
	</code></pre>
	<h4 id="headset-jack-media-controls">Headset Jack Media Controls</h4>
	<pre><code># 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 WAKE
	key 165 MEDIA_PREVIOUS WAKE
	key 226 HEADSETHOOK WAKE
	</code></pre>
	<h4 id="joystick">Joystick</h4>
	<pre><code># 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 out of a range from -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
	</code></pre>
	<h2 id="wake-keys">Wake Keys</h2>
	<p>Wake keys are special keys that wake the device from sleep, such as the power key.</p>
	<p>By default, for internal keyboard devices, no key is a wake key. For external
	keyboard device, all keys are wake keys.</p>
	<p>To make a key be a wake key, set the <code>WAKE_DROPPED</code> flag in the key layout file
	for the keyboard device.</p>
	<p>Note that the <code>WindowManagerPolicy</code> component is responsible for implementing wake
	key behavior. Moreover, the key guard may prevent certain keys from functioning
	as wake keys. A good place to start understanding wake key behavior is
	<code>PhoneWindowManager.interceptKeyBeforeQueueing</code>.</p>
	<h2 id="virtual-soft-keys">Virtual Soft Keys</h2>
	<p>The input system provides special features for implementing virtual soft keys.</p>
	<p>There are three cases:</p>
	<ol>
	<li>
	<p>If the virtual soft keys are displayed graphically on the screen, as on the
	Galaxy Nexus, then they are implemented by the Navigation Bar component in
	the System UI package.</p>
	<p>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.</p>
	</li>
	<li>
	<p>If the virtual soft keys are implemented as an extended touchable region
	that is part of the main touch screen, as on the Nexus One, then 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.</p>
	<p>Refer to the section on <a href="touch-devices.html">Touch Devices</a>
	for more details about virtual key map files.</p>
	<p>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.</p>
	</li>
	<li>
	<p>If the virtual soft keys are implemented as capacitive buttons that are
	separate from the main touch screen, as on the Nexus S, then 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.</p>
	<p>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.</p>
	</li>
	</ol>
	<p>When virtual soft key are located within or in close physical proximity of the
	touch screen, it is easy for the user to accidentally press one of the buttons
	when touching near the bottom of the screen or when sliding a finger from top
	to bottom or from bottom to top on the screen.</p>
	<p>To prevent this from happening, 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. The delay is called the
	virtual key quiet time.</p>
	<p>To enable virtual soft key debouncing, we must do two things.</p>
	<p>First, we provide a key layout file for the touch screen or capacitive button
	input device with the <code>VIRTUAL</code> flag set for each key.</p>
	<pre><code>key 139 MENU VIRTUAL
	key 102 HOME VIRTUAL
	key 158 BACK VIRTUAL
	key 217 SEARCH VIRTUAL
	</code></pre>
	<p>Then, we set the value of the virtual key quiet time in a resource overlay
	for the framework <code>config.xml</code> resource.</p>
	<pre><code><!-- Specifies the amount of time to disable virtual keys after the screen is touched
	in order 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>
	</code></pre>
	<h2 id="validation">Validation</h2>
	<p>Make sure to validate your key layout files using the
	<a href="validate-keymaps.html">Validate Keymaps</a> tool.</p>