Merge "Docs: removing deprecated policy flags cleaning up html for single quotes, underscores Changing 'can' to 'should'"
diff --git a/src/devices/input/key-layout-files.jd b/src/devices/input/key-layout-files.jd
index 2b7cd53..b7830ad 100644
--- a/src/devices/input/key-layout-files.jd
+++ b/src/devices/input/key-layout-files.jd
@@ -24,20 +24,21 @@
</div>
</div>
-<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>
+<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.</p>
-<p>The following paths are consulted in order.</p>
+id or by input device name. 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>
@@ -49,95 +50,104 @@
<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>
+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.</p>
-<p><em>Do not modify the generic key layout!</em></p>
+<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 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
+<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><code>key 1 ESCAPE
+key 114 VOLUME_DOWN
+key 16 Q VIRTUAL
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>
+<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>
+<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>
+<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><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> 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><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>
+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>
+<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><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>
+<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. 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>Comment lines begin with # and continue to the end of the line:</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.
@@ -158,15 +168,17 @@
# 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
+<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
# the device decodes into key presses.
-key 114 VOLUME_DOWN WAKE
-key 115 VOLUME_UP WAKE
-key 116 POWER WAKE
+key 114 VOLUME_DOWN
+key 115 VOLUME_UP
+key 116 POWER
</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.
@@ -175,6 +187,7 @@
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
@@ -182,10 +195,11 @@
# 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
+key 163 MEDIA_NEXT
+key 165 MEDIA_PREVIOUS
+key 226 HEADSETHOOK
</code></pre>
+
<h4 id="joystick">Joystick</h4>
<pre><code># This is an example of a key layout file for a joystick.
@@ -203,9 +217,9 @@
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.
+# 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
@@ -219,74 +233,61 @@
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>
+<p>The input system provides special features for implementing virtual soft keys
+in the following use 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>
+<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 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>
+<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><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. -->
+</li>
+<li>Set the value of the virtual key quiet time in a resource overlay for the
+framework <code>config.xml</code> resource.
+<pre><code><!-- 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>
</code></pre>
+</li>
+</ol>
+
<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>
+<p>You should validate your key layout files using the
+<a href="validate-keymaps.html">Validate Keymaps</a> tool.</p>
\ No newline at end of file