fuquan/allwinner_a64
1
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

upload android base code part8

Browse source
This commit is contained in:
August 2018-08-08 20:10:12 +08:00
parent 841ae54672
commit 5425409085
57075 changed files with 9846578 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

129
android/docs/source.android.com/en/devices/input/getevent.html Normal file
View file

@ -0,0 +1,129 @@
<html devsite>
<head>
<title>Getevent</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>The <code>getevent</code> tool runs on the device and provides information
about input devices and a live dump of kernel input events.</p>
<p>This tool is useful for ensuring device drivers are reporting the
expected set of capabilities for each input device and are generating the
desired stream of input events.</p>
<h2 id="showing-device-capabilities">Showing device capabilities</h2>
<p>Use the <code>-p</code> option with the <code>adb</code> command to see all of the keys and axes a device
reports.</p>
<pre class="devsite-terminal devsite-click-to-copy">adb shell su -- getevent -p</pre>
<p>The following example lists the Linux key codes and other events a
particular keyboard says it supports.</p>
<pre>
name: "Motorola Bluetooth Wireless Keyboard"
events:
KEY (0001): 0001 0002 0003 0004 0005 0006 0007 0008
0009 000a 000b 000c 000d 000e 000f 0010
0011 0012 0013 0014 0015 0016 0017 0018
0019 001a 001b 001c 001d 001e 001f 0020
0021 0022 0023 0024 0025 0026 0027 0028
0029 002a 002b 002c 002d 002e 002f 0030
0031 0032 0033 0034 0035 0036 0037 0038
0039 003a 003b 003c 003d 003e 003f 0040
0041 0042 0043 0044 0045 0046 0047 0048
0049 004a 004b 004c 004d 004e 004f 0050
0051 0052 0053 0055 0056 0057 0058 0059
005a 005b 005c 005d 005e 005f 0060 0061
0062 0063 0064 0066 0067 0068 0069 006a
006b 006c 006d 006e 006f 0071 0072 0073
0074 0075 0077 0079 007a 007b 007c 007d
007e 007f 0080 0081 0082 0083 0084 0085
0086 0087 0088 0089 008a 008c 008e 0090
0096 0098 009b 009c 009e 009f 00a1 00a3
00a4 00a5 00a6 00ab 00ac 00ad 00b0 00b1
00b2 00b3 00b4 00b7 00b8 00b9 00ba 00bb
00bc 00bd 00be 00bf 00c0 00c1 00c2 00d9
00f0 0110 0111 0112 01ba
REL (0002): 0000 0001 0008
ABS (0003): 0028 : value 223, min 0, max 255, fuzz 0, flat 0, resolution 0
0029 : value 0, min 0, max 255, fuzz 0, flat 0, resolution 0
002a : value 0, min 0, max 255, fuzz 0, flat 0, resolution 0
002b : value 0, min 0, max 255, fuzz 0, flat 0, resolution 0
MSC (0004): 0004
LED (0011): 0000 0001 0002 0003 0004
input props:
&lt;none&gt;
</pre>
<p>Use the <code>-i</code> option to get more information, including HID mapping
tables and debugging information.</p>
<p>Use the <code>-l</code> option to display textual labels for all event codes.</p>
<pre class="devsite-terminal devsite-click-to-copy">
adb shell su -- getevent -lp /dev/input/event1
</pre>
<p>Example:</p>
<pre>
name: "Melfas MMSxxx Touchscreen"
events:
ABS (0003): ABS_MT_SLOT : value 0, min 0, max 9, fuzz 0, flat 0, resolution 0
ABS_MT_TOUCH_MAJOR : value 0, min 0, max 30, fuzz 0, flat 0, resolution 0
ABS_MT_POSITION_X : value 0, min 0, max 720, fuzz 0, flat 0, resolution 0
ABS_MT_POSITION_Y : value 0, min 0, max 1280, fuzz 0, flat 0, resolution 0
ABS_MT_TRACKING_ID : value 0, min 0, max 65535, fuzz 0, flat 0, resolution 0
ABS_MT_PRESSURE : value 0, min 0, max 255, fuzz 0, flat 0, resolution 0
input props:
INPUT_PROP_DIRECT
</pre>
<h2 id="showing-live-events">Showing live events</h2>
<p>The following example shows a two-finger multi-touch gesture for a
touchscreen using the Linux multi-touch input protocol "B". The <code>-l</code>
option displays textual labels and the <code>-t</code> option displays
timestamps.</p>
<pre class="devsite-terminal devsite-click-to-copy">
adb shell su -- getevent -lt /dev/input/event1
</pre>
<p>Example:</p>
<pre>
[ 78826.389007] EV_ABS ABS_MT_TRACKING_ID 0000001f
[ 78826.389038] EV_ABS ABS_MT_PRESSURE 000000ab
[ 78826.389038] EV_ABS ABS_MT_POSITION_X 000000ab
[ 78826.389068] EV_ABS ABS_MT_POSITION_Y 0000025b
[ 78826.389068] EV_ABS ABS_MT_SLOT 00000001
[ 78826.389068] EV_ABS ABS_MT_TRACKING_ID 00000020
[ 78826.389068] EV_ABS ABS_MT_PRESSURE 000000b9
[ 78826.389099] EV_ABS ABS_MT_POSITION_X 0000019e
[ 78826.389099] EV_ABS ABS_MT_POSITION_Y 00000361
[ 78826.389099] EV_SYN SYN_REPORT 00000000
[ 78826.468688] EV_ABS ABS_MT_SLOT 00000000
[ 78826.468688] EV_ABS ABS_MT_TRACKING_ID ffffffff
[ 78826.468719] EV_ABS ABS_MT_SLOT 00000001
[ 78826.468719] EV_ABS ABS_MT_TRACKING_ID ffffffff
[ 78826.468719] EV_SYN SYN_REPORT 00000000
</pre>
<p class="note"><strong>Note:</strong> <code>getevent</code> timestamps use
the format $SECONDS.$MICROSECONDS in the CLOCK_MONOTONIC timebase. For details,
refer to getevent.c.</p>
</body>
</html>

BIN
android/docs/source.android.com/en/devices/input/images/ape_fwk_hal_input.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 1.6 KiB

33
android/docs/source.android.com/en/devices/input/index.html Normal file
View file

@ -0,0 +1,33 @@
<html devsite>
<head>
<title>Input Technical Information</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.
-->
<img style="float: right; margin: 0px 135px 15px 15px;" src="images/ape_fwk_hal_input.png" alt="Android Input HAL icon"/>
<p>The Android input subsystem supports many different device classes,
including keyboard, joystick, trackball, mouse, and touch screen. The documentation in this section describes how to configure,
calibrate, test, and write drivers for input devices.</p>
</body>
</html>

140
android/docs/source.android.com/en/devices/input/input-device-configuration-files.html Normal file
View file

@ -0,0 +1,140 @@
<html devsite>
<head>
<title>Input Device Configuration 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>Input device configuration files (<code>.idc</code> files) contain device-specific
configuration properties that affect the behavior of input devices.</p>
<p>Input device configuration files are typically not necessary for standard
peripherals such as HID keyboards and mice since the default system behavior
usually ensures that they will work out of the box. On the other hand,
built-in embedded devices, particularly touch screens, almost always
require input device configuration files to specify their behavior.</p>
<h2 id="rationale">Rationale</h2>
<p>Android automatically detects and configures most input device capabilities
based on the event types and properties that are reported by the associated
Linux kernel input device driver.</p>
<p>For example, if an input device supports the <code>EV_REL</code> event type and codes
<code>REL_X</code> and <code>REL_Y</code> as well as the <code>EV_KEY</code> event type and <code>BTN_MOUSE</code>,
then Android will classify the input device as a mouse. The default behavior
for a mouse is to present an on-screen cursor which tracks the mouse's movements
and simulates touches when the mouse is clicked. Although the mouse can
be configured differently, the default behavior is usually sufficient for
standard mouse peripherals.</p>
<p>Certain classes of input devices are more ambiguous. For example, multi-touch
touch screens and touch pads both support the <code>EV_ABS</code> event type and codes
<code>ABS_MT_POSITION_X</code> and <code>ABS_MT_POSITION_Y</code> at a minimum. However, the intended
uses of these devices are quite different and cannot always be determined
automatically. Also, additional information is required to make sense of the
pressure and size information reported by touch devices. Hence touch devices,
especially built-in touch screens, usually need IDC files.</p>
<h2 id="location">Location</h2>
<p>Input device configuration 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/idc/Vendor_XXXX_Product_XXXX_Version_XXXX.idc</code></li>
<li><code>/system/usr/idc/Vendor_XXXX_Product_XXXX.idc</code></li>
<li><code>/system/usr/idc/DEVICE_NAME.idc</code></li>
<li><code>/data/system/devices/idc/Vendor_XXXX_Product_XXXX_Version_XXXX.idc</code></li>
<li><code>/data/system/devices/idc/Vendor_XXXX_Product_XXXX.idc</code></li>
<li><code>/data/system/devices/idc/DEVICE_NAME.idc</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="syntax">Syntax</h2>
<p>An input device configuration file is a plain text file consisting of property
assignments and comments.</p>
<h3 id="properties">Properties</h3>
<p>Property assignments each consist of a property name, an <code>=</code>, a property value,
and a new line. Like this:</p>
<pre class="devsite-click-to-copy">
property = value
</pre>
<p>Property names are non-empty literal text identifiers. They must not contain
whitespace. Each components of the input system defines a set of properties
that are used to configure its function.</p>
<p>Property values are non-empty string literals, integers or floating point numbers.
They must not contain whitespace or the reserved characters <code>\</code> or <code>"</code>.</p>
<p>Property names and values are case-sensitive.</p>
<h3 id="comments">Comments</h3>
<p>Comment lines begin with '#' and continue to the end of the line. Like this:</p>
<pre class="devsite-click-to-copy">
# A comment!
</pre>
<p>Blank lines are ignored.</p>
<h3 id="example">Example</h3>
<pre class="devsite-click-to-copy">
# This is an example of an input device configuration file.
# It might be used to describe the characteristics of a built-in touch screen.
# This is an internal device, not an external peripheral attached to the USB
# or Bluetooth bus.
device.internal = 1
# The device should behave as a touch screen, which uses the same orientation
# as the built-in display.
touch.deviceType = touchScreen
touch.orientationAware = 1
# Additional calibration properties...
# etc...
</pre>
<h2 id="common-properties">Common Properties</h2>
<p>The following property is common to all input device classes.</p>
<p>Refer to the documentation of each input device class for information about the
special properties used by each class.</p>
<h4 id="deviceinternal"><code>device.internal</code></h4>
<p><em>Definition:</em> <code>device.internal</code> = <code>0</code> | <code>1</code></p>
<p>Specifies whether the input device is an internal built-in component as opposed to an
externally attached (most likely removable) peripheral.</p>
<ul>
<li>
<p>If the value is <code>0</code>, the device is external.</p>
</li>
<li>
<p>If the value is <code>1</code>, the device is internal.</p>
</li>
<li>
<p>If the value is not specified, the default value is <code>0</code> for all devices on the
USB (BUS_USB) or Bluetooth (BUS_BLUETOOTH) bus, <code>1</code> otherwise.</p>
</li>
</ul>
<p>This property determines default policy decisions regarding wake events.</p>
<p>Internal input devices generally do not wake the display from sleep unless explicitly
configured to do so in the key layout file or in a hardcoded policy rule. This
distinction prevents key presses and touches from spuriously waking up your phone
when it is in your pocket. Usually there are only a small handful of wake keys defined.</p>
<p>Conversely, external input devices usually wake the device more aggressively because
they are assumed to be turned off or not plugged in during transport. For example,
pressing any key on an external keyboard is a good indicator that the user wants the
device to wake up and respond.</p>
<p>It is important to ensure that the value of the <code>device.internal</code> property is set
correctly for all internal input devices.</p>
<h2 id="validation">Validation</h2>
<p>Make sure to validate your input device configuration files using the
<a href="validate-keymaps.html">Validate Keymaps</a> tool.</p>
</body>
</html>

444
android/docs/source.android.com/en/devices/input/key-character-map-files.html Normal file
View file

@ -0,0 +1,444 @@
<html devsite>
<head>
<title>Key Character Map 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 character map files (<code>.kcm</code> files) are responsible for mapping combinations
of Android key codes with modifiers to Unicode characters.</p>
<p>Device-specific key layout files are <em>required</em> for all internal (built-in)
input devices that have keys, if only to tell the system that the device
is special purpose only (not a full keyboard).</p>
<p>Device-specific key layout files are <em>optional</em> for external keyboards, and
often aren't needed at all. The system provides a generic key character map
that is suitable for many external keyboards.</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 character map 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/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm</code></li>
<li><code>/system/usr/keychars/Vendor_XXXX_Product_XXXX.kcm</code></li>
<li><code>/system/usr/keychars/DEVICE_NAME.kcm</code></li>
<li><code>/data/system/devices/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm</code></li>
<li><code>/data/system/devices/keychars/Vendor_XXXX_Product_XXXX.kcm</code></li>
<li><code>/data/system/devices/keychars/DEVICE_NAME.kcm</code></li>
<li><code>/system/usr/keychars/Generic.kcm</code></li>
<li><code>/data/system/devices/keychars/Generic.kcm</code></li>
<li><code>/system/usr/keychars/Virtual.kcm</code></li>
<li><code>/data/system/devices/keychars/Virtual.kcm</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-character-map-file">Generic Key Character Map File</h2>
<p>The system provides a special built-in key character map file called <code>Generic.kcm</code>.
This key character map is intended to support a variety of standard external
keyboards.</p>
<p><em>Do not modify the generic key character map!</em></p>
<h2 id="virtual-key-character-map-file">Virtual Key Character Map File</h2>
<p>The system provides a special built-in key character map file called <code>Virtual.kcm</code>
that is used by the virtual keyboard devices.</p>
<p>The virtual keyboard device is a synthetic input device whose id is -1
(see <code>KeyCharacterMap.VIRTUAL_KEYBOARD</code>). It is present on all Android devices
beginning with Android Honeycomb 3.0. The purpose of the virtual keyboard device
is to provide a known built-in input device that can be used for injecting
keystrokes into applications by the IME or by test instrumentation, even
for devices that do not have built-in keyboards.</p>
<p>The virtual keyboard is assumed to have a full QWERTY layout that is the
same on all devices. This makes it possible for applications to inject
keystrokes using the virtual keyboard device and always get the same results.</p>
<p><em>Do not modify the virtual key character map!</em></p>
<h2 id="syntax">Syntax</h2>
<p>A key character map file is a plain text file consisting of a keyboard type
declaration and a set of key declarations.</p>
<h3 id="keyboard-type-declaration">Keyboard Type Declaration</h3>
<p>A keyboard type declaration describes the overall behavior of the keyboard.
A character map file must contain a keyboard type declaration. For clarity,
it is often placed at the top of the file.</p>
<pre class="devsite-click-to-copy">
type FULL
</pre>
<p>The following keyboard types are recognized:</p>
<ul>
<li>
<p><code>NUMERIC</code>: A numeric (12-key) keyboard.</p>
<p>A numeric keyboard supports text entry using a multi-tap approach.
It may be necessary to tap a key multiple times to generate the desired letter or symbol.</p>
<p>This type of keyboard is generally designed for thumb typing.</p>
<p>Corresponds to <code>KeyCharacterMap.NUMERIC</code>.</p>
</li>
<li>
<p><code>PREDICTIVE</code>: A keyboard with all the letters, but with more than one letter per key.</p>
<p>This type of keyboard is generally designed for thumb typing.</p>
<p>Corresponds to <code>KeyCharacterMap.PREDICTIVE</code>.</p>
</li>
<li>
<p><code>ALPHA</code>: A keyboard with all the letters, and maybe some numbers.</p>
<p>An alphabetic keyboard supports text entry directly but may have a condensed
layout with a small form factor. In contrast to a <code>FULL</code> keyboard, some
symbols may only be accessible using special on-screen character pickers.
In addition, to improve typing speed and accuracy, the framework provides
special affordances for alphabetic keyboards such as auto-capitalization
and toggled / locked SHIFT and ALT keys.</p>
<p>This type of keyboard is generally designed for thumb typing.</p>
</li>
<li>
<p><code>FULL</code>: A full PC-style keyboard.</p>
<p>A full keyboard behaves like a PC keyboard. All symbols are accessed directly
by pressing keys on the keyboard without on-screen support or affordances such
as auto-capitalization.</p>
<p>This type of keyboard is generally designed for full two hand typing.</p>
</li>
<li>
<p><code>SPECIAL_FUNCTION</code>: A keyboard that is only used to perform system control functions
rather than for typing.</p>
<p>A special function keyboard consists only of non-printing keys such as
HOME and POWER that are not actually used for typing.</p>
</li>
</ul>
<p>The <code>Generic.kcm</code> and <code>Virtual.kcm</code> key character maps are both <code>FULL</code> keyboards.</p>
<h3 id="key-declarations">Key Declarations</h3>
<p>Key declarations each consist of the keyword <code>key</code> followed by an Android key code
name, an open curly brace, a set of properties and behaviors and a close curly brace.</p>
<pre class="devsite-click-to-copy">
key A {
label: 'A'
base: 'a'
shift, capslock: 'A'
ctrl, alt, meta: none
}
</pre>
<h4 id="properties">Properties</h4>
<p>Each key property establishes a mapping from a key to a behavior. To make the
key character map files more compact, several properties can be mapped to the
same behavior by separating them with a comma.</p>
<p>In the above example, the <code>label</code> property is assigned the <code>'A'</code> behavior.
Likewise, the <code>ctrl</code>, <code>alt</code> and <code>meta</code> properties are all simultaneously assigned
the <code>none</code> behavior.</p>
<p>The following properties are recognized:</p>
<ul>
<li>
<p><code>label</code>: Specifies the label that is physically printed on the key, when it
consists of a single character. This is the value that is returned by
the <code>KeyCharacterMap.getDisplayLabel</code> method.</p>
</li>
<li>
<p><code>number</code>: Specifies the behavior (character that should be typed) when a numeric
text view has focus, such as when the user is typing a phone number.</p>
<p>Compact keyboards often combine multiple symbols into a single key, such that
the same key might be used to type <code>'1'</code> and <code>'a'</code> or <code>'#'</code> and <code>'q'</code>, perhaps.
For these keys, the <code>number</code> property should be set to indicate which symbol
should be typed in a numeric context, if any.</p>
<p>Some typical "numeric" symbols are digits <code>'0'</code> through <code>'9'</code>, <code>'#'</code>, <code>'+'</code>,
<code>'('</code>, <code>')'</code>, <code>','</code>, and <code>'.'</code>.</p>
</li>
<li>
<p><code>base</code>: Specifies the behavior (character that should be typed) when no modifiers
are pressed.</p>
</li>
<li>
<p>&lt;modifier&gt; or &lt;modifier1&gt;<code>+</code>&lt;modifier2&gt;<code>+</code>...: Specifies the
behavior (character that should be typed) when the key is pressed and all of the
specified modifiers are active.</p>
<p>For example, the modifier property <code>shift</code> specifies a behavior that applies when
the either the LEFT SHIFT or RIGHT SHIFT modifier is pressed.</p>
<p>Similarly, the modifier property <code>rshift+ralt</code> specifies a behavior that applies
when the both RIGHT SHIFT and RIGHT ALT modifiers are pressed together.</p>
</li>
</ul>
<p>The following modifiers are recognized in modifier properties:</p>
<ul>
<li><code>shift</code>: Applies when either the LEFT SHIFT or RIGHT SHIFT modifier is pressed.</li>
<li><code>lshift</code>: Applies when the LEFT SHIFT modifier is pressed.</li>
<li><code>rshift</code>: Applies when the RIGHT SHIFT modifier is pressed.</li>
<li><code>alt</code>: Applies when either the LEFT ALT or RIGHT ALT modifier is pressed.</li>
<li><code>lalt</code>: Applies when the LEFT ALT modifier is pressed.</li>
<li><code>ralt</code>: Applies when the RIGHT ALT modifier is pressed.</li>
<li><code>ctrl</code>: Applies when either the LEFT CONTROL or RIGHT CONTROL modifier is pressed.</li>
<li><code>lctrl</code>: Applies when the LEFT CONTROL modifier is pressed.</li>
<li><code>rctrl</code>: Applies when the RIGHT CONTROL modifier is pressed.</li>
<li><code>meta</code>: Applies when either the LEFT META or RIGHT META modifier is pressed.</li>
<li><code>lmeta</code>: Applies when the LEFT META modifier is pressed.</li>
<li><code>rmeta</code>: Applies when the RIGHT META modifier is pressed.</li>
<li><code>sym</code>: Applies when the SYMBOL modifier is pressed.</li>
<li><code>fn</code>: Applies when the FUNCTION modifier is pressed.</li>
<li><code>capslock</code>: Applies when the CAPS LOCK modifier is locked.</li>
<li><code>numlock</code>: Applies when the NUM LOCK modifier is locked.</li>
<li><code>scrolllock</code>: Applies when the SCROLL LOCK modifier is locked.</li>
</ul>
<p>The order in which the properties are listed is significant. When mapping a key to
a behavior, the system scans all relevant properties in order and returns the last
applicable behavior that it found.</p>
<p>Consequently, properties that are specified later override properties that are
specified earlier for a given key.</p>
<h4 id="behaviors">Behaviors</h4>
<p>Each property maps to a behavior. The most common behavior is typing a character
but there are others.</p>
<p>The following behaviors are recognized:</p>
<ul>
<li>
<p><code>none</code>: Don't type a character.</p>
<p>This behavior is the default when no character is specified. Specifying <code>none</code>
is optional but it improves clarity.</p>
</li>
<li>
<p><code>'X'</code>: Type the specified character literal.</p>
<p>This behavior causes the specified character to be entered into the focused
text view. The character literal may be any ASCII character, or one of the
following escape sequences:</p>
<ul>
<li><code>'\\'</code>: Type a backslash character.</li>
<li><code>'\n'</code>: Type a new line character (use this for ENTER / RETURN).</li>
<li><code>'\t'</code>: Type a TAB character.</li>
<li><code>'\''</code>: Type an apostrophe character.</li>
<li><code>'\"'</code>: Type a quote character.</li>
<li><code>'\uXXXX'</code>: Type the Unicode character whose code point is given in hex by XXXX.</li>
</ul>
</li>
<li>
<p><code>fallback</code> &lt;Android key code name&gt;: Perform a default action if the key is not
handled by the application.</p>
<p>This behavior causes the system to simulate a different key press when an application
does not handle the specified key natively. It is used to support default behavior
for new keys that not all applications know how to handle, such as ESCAPE or
numeric keypad keys (when numlock is not pressed).</p>
<p>When a fallback behavior is performed, the application will receive two key presses:
one for the original key and another for the fallback key that was selected.
If the application handles the original key during key up, then the fallback key
event will be canceled (<code>KeyEvent.isCanceled</code> will return <code>true</code>).</p>
</li>
</ul>
<p>The system reserves two Unicode characters to perform special functions:</p>
<ul>
<li>
<p><code>'\uef00'</code>: When this behavior is performed, the text view consumes and removes the
four characters preceding the cursor, interprets them as hex digits, and inserts the
corresponding Unicode code point.</p>
</li>
<li>
<p><code>'\uef01'</code>: When this behavior is performed, the text view displays a
character picker dialog that contains miscellaneous symbols.</p>
</li>
</ul>
<p>The system recognizes the following Unicode characters as combining diacritical dead
key characters:</p>
<ul>
<li><code>'\u0300'</code>: Grave accent.</li>
<li><code>'\u0301'</code>: Acute accent.</li>
<li><code>'\u0302'</code>: Circumflex accent.</li>
<li><code>'\u0303'</code>: Tilde accent.</li>
<li><code>'\u0308'</code>: Umlaut accent.</li>
</ul>
<p>When a dead key is typed followed by another character, the dead key and the following
characters are composed. For example, when the user types a grave accent dead
key followed by the letter 'a', the result is '&agrave;'.</p>
<p>Refer to <code>KeyCharacterMap.getDeadChar</code> for more information about dead key handling.</p>
<h3 id="comments">Comments</h3>
<p>Comment lines begin with '#' and continue to the end of the line. Like this:</p>
<pre class="devsite-click-to-copy">
# A comment!
</pre>
<p>Blank lines are ignored.</p>
<h3 id="how-key-combinations-are-mapped-to-behaviors">How Key Combinations are Mapped to Behaviors</h3>
<p>When the user presses a key, the system looks up the behavior associated with
the combination of that key press and the currently pressed modifiers.</p>
<h4 id="shift-a">SHIFT + A</h4>
<p>Suppose the user pressed A and SHIFT together. The system first locates
the set of properties and behaviors associated with <code>KEYCODE_A</code>.</p>
<pre class="devsite-click-to-copy">
key A {
label: 'A'
base: 'a'
shift, capslock: 'A'
ctrl, alt, meta: none
}
</pre>
<p>The system scans the properties from first to last and left to right, ignoring
the <code>label</code> and <code>number</code> properties, which are special.</p>
<p>The first property encountered is <code>base</code>. The <code>base</code> property always applies to
a key, no matter what modifiers are pressed. It essentially specifies the default
behavior for the key unless it is overridden by following properties.
Since the <code>base</code> property applies to this key press, the system makes note
of the fact that its behavior is <code>'a'</code> (type the character <code>a</code>).</p>
<p>The system then continues to scan subsequent properties in case any of them
are more specific than <code>base</code> and override it. It encounters <code>shift</code> which
also applies to the key press SHIFT + A. So the system decides to ignore
the <code>base</code> property's behavior and chooses the behavior associated with
the <code>shift</code> property, which is <code>'A'</code> (type the character <code>A</code>).</p>
<p>It then continues to scan the table, however no other properties apply to this
key press (CAPS LOCK is not locked, neither CONTROL key is pressed, neither
ALT key is pressed and neither META key is pressed).</p>
<p>So the resulting behavior for the key combination SHIFT + A is <code>'A'</code>.</p>
<h4 id="control-a">CONTROL + A</h4>
<p>Now consider what would happen if the user pressed A and CONTROL together.</p>
<p>As before, the system would scan the table of properties. It would notice
that the <code>base</code> property applied but would also continue scanning until
it eventually reached the <code>control</code> property. As it happens, the <code>control</code>
property appears after <code>base</code> so its behavior overrides the <code>base</code> behavior.</p>
<p>So the resulting behavior for the key combination CONTROL + A is <code>none</code>.</p>
<h4 id="escape">ESCAPE</h4>
<p>Now suppose the user pressed ESCAPE.</p>
<pre class="devsite-click-to-copy">
key ESCAPE {
base: fallback BACK
alt, meta: fallback HOME
ctrl: fallback MENU
}
</pre>
<p>This time the system obtains the behavior <code>fallback BACK</code>, a fallback behavior.
Because no character literal appears, no character will be typed.</p>
<p>When processing the key, the system will first deliver <code>KEYCODE_ESCAPE</code> to the
application. If the application does not handle it, then the system will try
again but this time it will deliver <code>KEYCODE_BACK</code> to the application as
requested by the fallback behavior.</p>
<p>So applications that recognize and support <code>KEYCODE_ESCAPE</code> have the
opportunity to handle it as is, but other applications that do not can instead
perform the fallback action of treating the key as if it were <code>KEYCODE_BACK</code>.</p>
<h4 id="numpad_0-with-or-without-num-lock">NUMPAD_0 with or without NUM LOCK</h4>
<p>The numeric keypad keys have very different interpretations depending on whether
the NUM LOCK key is locked.</p>
<p>The following key declaration ensures that <code>KEYCODE_NUMPAD_0</code> types <code>0</code>
when NUM LOCK is pressed. When NUM LOCK is not pressed, the key is delivered
to the application as usual, and if it is not handled, then the fallback
key <code>KEYCODE_INSERT</code> is delivered instead.</p>
<pre class="devsite-click-to-copy">
key NUMPAD_0 {
label, number: '0'
base: fallback INSERT
numlock: '0'
ctrl, alt, meta: none
}
</pre>
<p>As we can see, fallback key declarations greatly improve compatibility
with older applications that do not recognize or directly support all of the keys
that are present on a full PC style keyboard.</p>
<h3 id="examples">Examples</h3>
<h4 id="full-keyboard">Full Keyboard</h4>
<pre class="devsite-click-to-copy">
# This is an example of part of a key character map file for a full keyboard
# include a few fallback behaviors for special keys that few applications
# handle themselves.
type FULL
key C {
label: 'C'
base: 'c'
shift, capslock: 'C'
alt: '\u00e7'
shift+alt: '\u00c7'
ctrl, meta: none
}
key SPACE {
label: ' '
base: ' '
ctrl: none
alt, meta: fallback SEARCH
}
key NUMPAD_9 {
label, number: '9'
base: fallback PAGE_UP
numlock: '9'
ctrl, alt, meta: none
}
</pre>
<h4 id="alphanumeric-keyboard">Alphanumeric Keyboard</h4>
<pre class="devsite-click-to-copy">
# This is an example of part of a key character map file for an alphanumeric
# thumb keyboard. Some keys are combined, such as `A` and `2`. Here we
# specify `number` labels to tell the system what to do when the user is
# typing a number into a dial pad.
#
# Also note the special character '\uef01' mapped to ALT+SPACE.
# Pressing this combination of keys invokes an on-screen character picker.
type ALPHA
key A {
label: 'A'
number: '2'
base: 'a'
shift, capslock: 'A'
alt: '#'
shift+alt, capslock+alt: none
}
key SPACE {
label: ' '
number: ' '
base: ' '
shift: ' '
alt: '\uef01'
shift+alt: '\uef01'
}
</pre>
<h4 id="game-pad">Game Pad</h4>
<pre class="devsite-click-to-copy">
# This is an example of part of a key character map file for a game pad.
# It defines fallback actions that enable the user to navigate the user interface
# by pressing buttons.
type SPECIAL_FUNCTION
key BUTTON_A {
base: fallback BACK
}
key BUTTON_X {
base: fallback DPAD_CENTER
}
key BUTTON_START {
base: fallback HOME
}
key BUTTON_SELECT {
base: fallback MENU
}
</pre>
<h2 id="compatibility-note">Compatibility Note</h2>
<p>Prior to Android Honeycomb 3.0, the Android key character map was specified
using a very different syntax and was compiled into a binary file format
(<code>.kcm.bin</code>) at build time.</p>
<p>Although the new format uses the same extension <code>.kcm</code>, the syntax is quite
different (and much more powerful).</p>
<p>As of Android Honeycomb 3.0, all Android key character map files must use
the new syntax and plain text file format that is described in this document.
The old syntax is not supported and the old <code>.kcm.bin</code> files are not recognized
by the system.</p>
<h2 id="language-note">Language Note</h2>
<p>Android does not currently support multilingual keyboards. Moreover, the
built-in generic key character map assumes a US English keyboard layout.</p>
<p>OEMs are encouraged to provide custom key character maps for their keyboards
if they are designed for other languages.</p>
<p>Future versions of Android may provide better support for multilingual keyboards
or user-selectable keyboard layouts.</p>
<h2 id="validation">Validation</h2>
<p>Make sure to validate your key character map files using the
<a href="validate-keymaps.html">Validate Keymaps</a> tool.</p>
</body>
</html>

311
android/docs/source.android.com/en/devices/input/key-layout-files.html Normal file
View file

@ -0,0 +1,311 @@
<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>/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 &#39;0&#39;-&#39;9&#39;, &#39;a&#39;-&#39;z&#39;,
&#39;A&#39;-&#39;Z&#39;, &#39;-&#39; or &#39;&#95;&#39; are replaced by
&#39;&#95;&#39;.</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-position-option">Center Flat Position Option</h4>
<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>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 class="devsite-click-to-copy">
axis 0x03 Z flat 4096
</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:</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 102 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 102 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">
&lt;!-- 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. --&gt;
&lt;integer name="config_virtualKeyQuietTimeMillis"&gt;250&lt;/integer&gt;
</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>

6447
android/docs/source.android.com/en/devices/input/keyboard-devices.html Normal file
View file

File diff suppressed because it is too large Load diff

65
android/docs/source.android.com/en/devices/input/migration-guide.html Normal file
View file

@ -0,0 +1,65 @@
<html devsite>
<head>
<title>Migration Guide</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>This document contains a few helpful tips when migrating to new Android releases.</p>
<h2 id="migrating-to-android-gingerbread-23">Migrating to Android Gingerbread 2.3</h2>
<p>In Gingerbread, we added the concept of input device configuration files
(also referred to as input device calibration files in this release).</p>
<p>Make sure to provide an input device configuration file for all touch screens.
In particular, it is worth spending time providing a calibration reference for
touch size information.</p>
<h2 id="migrating-to-android-honeycomb-30">Migrating to Android Honeycomb 3.0</h2>
<p>In Honeycomb, we revised the key character map file format and started making
greater use of input device configuration files. We also added support for full
PC-style keyboards and introduced a new "Generic" key map, which
replaced the older emulator-specific "qwerty" key map (which was never
intended to be used as a general-purpose key map.)</p>
<p>Make sure to update all of your key character map files to use the new syntax.</p>
<p>If your peripherals relied on the old "qwerty" key map, then you
may need to provide new device-specific key maps to emulate the old behavior.
You should create a new key map for each device identified either by
USB product id / vendor id or by device name.</p>
<p>It is especially important to provide key character map files for all special
function input devices. These files should simple contain a line to set
the keyboard type to <code>SPECIAL_FUNCTION</code>.</p>
<p>A good way to ensure that all built-in input devices are appropriately configured
is to run <a
href="https://developer.android.com/studio/command-line/dumpsys.html">Dumpsys</a>
and look for devices that are inappropriately using <code>Generic.kcm</code>.</p>
<h2 id="migrating-to-android-honeycomb-32">Migrating to Android Honeycomb 3.2</h2>
<p>In Honeycomb 3.2, we added support for joysticks and extended the key layout file
format to enable joystick axis mapping.</p>
<h2 id="migrating-to-android-ice-cream-sandwich-40">Migrating to Android Ice Cream Sandwich 4.0</h2>
<p>In Ice Cream Sandwich 4.0, we changed the device driver requirements for touch screens
to follow the standard Linux multitouch input protocol and added support for
protocol "B". We also support digitizer tablets and stylus-based touch devices.</p>
<p>You will probably need to update your input device driver to implement the Linux
multitouch input protocol correctly according to the standard.</p>
<p>You will also need to update your input device configuration files because some
properties have been changed to be simpler and more systematic.</p>
<p>Refer to <a href="touch-devices.html">Touch Devices</a> for more details about
driver requirements.</p>
</body>
</html>

247
android/docs/source.android.com/en/devices/input/overview.html Normal file
View file

@ -0,0 +1,247 @@
<html devsite>
<head>
<title>Overview</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>The Android input subsystem nominally consists of an event pipeline
that traverses multiple layers of the system.</p>
<h2 id="input-pipeline">Input Pipeline</h2>
<p>At the lowest layer, the physical input device produces signals that
describe state changes such as key presses and touch contact points.
The device firmware encodes and transmits these signals in some way
such as by sending USB HID reports to the system or by producing
interrupts on an I2C bus.</p>
<p>The signals are then decoded by a device driver in the Linux kernel.
The Linux kernel provides drivers for many standard peripherals,
particularly those that adhere to the HID protocol. However, an OEM
must often provide custom drivers for embedded devices that are
tightly integrated into the system at a low-level, such as touch screens.</p>
<p>The input device drivers are responsible for translating device-specific
signals into a standard input event format, by way of the Linux
input protocol. The Linux input protocol defines a standard set of
event types and codes in the <code>linux/input.h</code> kernel header file.
In this way, components outside the kernel do not need to care about
the details such as physical scan codes, HID usages, I2C messages,
GPIO pins, and the like.</p>
<p>Next, the Android <code>EventHub</code> component reads input events from the kernel
by opening the <code>evdev</code> driver associated with each input device.
The Android InputReader component then decodes the input events
according to the device class and produces a stream of Android input
events. As part of this process, the Linux input protocol event codes
are translated into Android event codes according to the
input device configuration, keyboard layout files, and various
mapping tables.</p>
<p>Finally, the <code>InputReader</code> sends input events to the InputDispatcher
which forwards them to the appropriate window.</p>
<h2 id="control-points">Control Points</h2>
<p>There are several stages in the input pipeline which effect control
over the behavior of the input device.</p>
<h3 id="driver-and-firmware-configuration">Driver and Firmware Configuration</h3>
<p>Input device drivers frequently configure the behavior of the input
device by setting parameters in registers or even uploading the
firmware itself. This is particularly the case for embedded
devices such as touch screens where a large part of the calibration
process involves tuning these parameters or fixing the firmware
to provide the desired accuracy and responsiveness and to suppress
noise.</p>
<p>Driver configuration options are often specified as module parameters
in the kernel board support package (BSP) so that the same driver
can support multiple different hardware implementations.</p>
<p>This documentation does attempt to describe driver or firmware
configuration, but it does offer guidance as to device calibration
in general.</p>
<h3 id="board-configuration-properties">Board Configuration Properties</h3>
<p>The kernel board support package (BSP) may export board configuration
properties via SysFS that are used by the Android InputReader component,
such as the placement of virtual keys on a touch screen.</p>
<p>Refer to the device class sections for details about how different
devices use board configuration properties.</p>
<h3 id="resource-overlays">Resource Overlays</h3>
<p>A few input behaviors are configured by way of resource overlays
in <code>config.xml</code> such as the operation of lid switch.</p>
<p>Here are a few examples:</p>
<ul>
<li>
<p><code>config_lidKeyboardAccessibility</code>: Specifies the effect of the
lid switch on whether the hardware keyboard is accessible or hidden.</p>
</li>
<li>
<p><code>config_lidNavigationAccessibility</code>: Specifies the effect of the
lid switch on whether the trackpad is accessible or hidden.</p>
</li>
<li>
<p><code>config_longPressOnPowerBehavior</code>: Specifies what should happen when
the user holds down the power button.</p>
</li>
<li>
<p><code>config_lidOpenRotation</code>: Specifies the effect of the lid switch
on screen orientation.</p>
</li>
</ul>
<p>Refer to the documentation within <code>frameworks/base/core/res/res/values/config.xml</code>
for details about each configuration option.</p>
<h3 id="key-maps">Key Maps</h3>
<p>Key maps are used by the Android <code>EventHub</code> and <code>InputReader</code> components
to configure the mapping from Linux event codes to Android event codes
for keys, joystick buttons and joystick axes. The mapping may
be device or language dependent.</p>
<p>Refer to the device class sections for details about how different
devices use key maps.</p>
<h3 id="input-device-configuration-files">Input Device Configuration Files</h3>
<p>Input device configuration files are used by the Android <code>EventHub</code> and
<code>InputReader</code> components to configure special device characteristics
such as how touch size information is reported.</p>
<p>Refer to the device class sections for details about how different
devices use input device configuration maps.</p>
<h2 id="understanding-hid-usages-and-event-codes">Understanding HID Usages and Event Codes</h2>
<p>There are often several different identifiers used to refer to any
given key on a keyboard, button on a game controller, joystick axis
or other control. The relationships between these identifiers
are not always the same: they are dependent on a set of mapping tables,
some of which are fixed, and some which vary based on characteristics
of the device, the device driver, the current locale, the system
configuration, user preferences and other factors.</p>
<dl>
<dt>Physical Scan Code</dt>
<dd>
<p>A physical scan code is a device-specific identifier that is associated
with each key, button or other control. Because physical scan codes
often vary from one device to another, the firmware or device driver
is responsible for mapping them to standard identifiers such as
HID Usages or Linux key codes.</p>
<p>Scan codes are mainly of interest for keyboards. Other devices
typically communicate at a low-level using GPIO pins, I2C messages
or other means. Consequently, the upper layers of the software
stack rely on the device drivers to make sense of what is going on.</p>
</dd>
<dt>HID Usage</dt>
<dd>
<p>A HID usage is a standard identifier that is used to report the
state of a control such as a keyboard key, joystick axis,
mouse button, or touch contact point. Most USB and Bluetooth
input devices conform to the HID specification, which enables
the system to interface with them in a uniform manner.</p>
<p>The Android Framework relies on the Linux kernel HID drivers to
translate HID usage codes into Linux key codes and other identifiers.
Therefore HID usages are mainly of interest to peripheral manufacturers.</p>
</dd>
<dt>Linux Key Code</dt>
<dd>
<p>A Linux key code is a standard identifier for a key or button.
Linux key codes are defined in the <code>linux/input.h</code> header file using
constants that begin with the prefix <code>KEY_</code> or <code>BTN_</code>. The Linux
kernel input drivers are responsible for translating physical
scan codes, HID usages and other device-specific signals into Linux
key codes and delivering information about them as part of
<code>EV_KEY</code> events.</p>
<p>The Android API sometimes refers to the Linux key code associated
with a key as its "scan code". This is technically incorrect in
but it helps to distinguish Linux key codes from Android key codes
in the API.</p>
</dd>
<dt>Linux Relative or Absolute Axis Code</dt>
<dd>
<p>A Linux relative or absolute axis code is a standard identifier
for reporting relative movements or absolute positions along an
axis, such as the relative movements of a mouse along its X axis
or the absolute position of a joystick along its X axis.
Linux axis code are defined in the <code>linux/input.h</code> header file using
constants that begin with the prefix <code>REL_</code> or <code>ABS_</code>. The Linux
kernel input drivers are responsible for translating HID usages
and other device-specific signals into Linux axis codes and
delivering information about them as part of <code>EV_REL</code> and
<code>EV_ABS</code> events.</p>
</dd>
<dt>Linux Switch Code</dt>
<dd>
<p>A Linux switch code is a standard identifier for reporting the
state of a switch on a device, such as a lid switch. Linux
switch codes are defined in the <code>linux/input.h</code> header file
using constants that begin with the prefix <code>SW_</code>. The Linux
kernel input drivers report switch state changes as <code>EV_SW</code> events.</p>
<p>Android applications generally do not receive events from switches,
but the system may use them internally to control various
device-specific functions.</p>
</dd>
<dt>Android Key Code</dt>
<dd>
<p>An Android key code is a standard identifier defined in the Android
API for indicating a particular key such as 'HOME'. Android key codes
are defined by the <code>android.view.KeyEvent</code> class as constants that
begin with the prefix <code>KEYCODE_</code>.</p>
<p>The key layout specifies how Linux key codes are mapped to Android
key codes. Different key layouts may be used depending on the keyboard
model, language, country, layout, or special functions.</p>
<p>Combinations of Android key codes are transformed into character codes
using a device and locale specific key character map. For example,
when the keys identified as <code>KEYCODE_SHIFT</code> and <code>KEYCODE_A</code> are both
pressed together, the system looks up the combination in the key
character map and finds the capital letter 'A', which is then inserted
into the currently focused text widget.</p>
</dd>
<dt>Android Axis Code</dt>
<dd>
<p>An Android axis code is a standard identifier defined in the Android
API for indicating a particular device axis. Android axis codes are
defined by the <code>android.view.MotionEvent</code> class as constants that
begin with the prefix <code>AXIS_</code>.</p>
<p>The key layout specifies how Linux Axis Codes are mapped to Android
axis codes. Different key layouts may be used depending on the device
model, language, country, layout, or special functions.</p>
</dd>
<dt>Android Meta State</dt>
<dd>
<p>An Android meta state is a standard identifier defined in the Android
API for indicating which modifier keys are pressed. Android meta states
are defined by the <code>android.view.KeyEvent</code> class as constants that
begin with the prefix <code>META_</code>.</p>
<p>The current meta state is determined by the Android InputReader
component which monitors when modifier keys such as <code>KEYCODE_SHIFT_LEFT</code>
are pressed / released and sets / resets the appropriate meta state flag.</p>
<p>The relationship between modifier keys and meta states is hardcoded
but the key layout can alter how the modifier keys themselves are
mapped which in turns affects the meta states.</p>
</dd>
<dt>Android Button State</dt>
<dd>
<p>An Android button state is a standard identifier defined in the Android
API for indicating which buttons (on a mouse or stylus) are pressed.
Android button states are defined by the <code>android.view.MotionEvent</code>
class as constants that begin with the prefix <code>BUTTON_</code>.</p>
<p>The current button state is determined by the Android InputReader
component which monitors when buttons (on a mouse or stylus) are
pressed / released and sets / resets appropriate button state flag.</p>
<p>The relationship between buttons and button states is hardcoded.</p>
</dd>
</dl>
<h2 id="further-reading">Further Reading</h2>
<ol>
<li><a href="http://www.kernel.org/doc/Documentation/input/event-codes.txt">Linux input event codes</a></li>
<li><a href="http://www.kernel.org/doc/Documentation/input/multi-touch-protocol.txt">Linux multi-touch protocol</a></li>
<li><a href="http://www.kernel.org/doc/Documentation/input/input.txt">Linux input drivers</a></li>
<li><a href="http://www.kernel.org/doc/Documentation/input/ff.txt">Linux force feedback</a></li>
<li><a href="http://www.usb.org/developers/hidpage">HID information, including HID usage tables</a></li>
</ol>
</body>
</html>

1182
android/docs/source.android.com/en/devices/input/touch-devices.html Normal file
View file

File diff suppressed because it is too large Load diff

106
android/docs/source.android.com/en/devices/input/validate-keymaps.html Normal file
View file

@ -0,0 +1,106 @@
<html devsite>
<head>
<title>Validate Keymaps Tool</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>The Android framework has a small tool called <code>validatekeymaps</code> to validate the
syntax of input device configuration files, key layout files, key character
maps files and virtual key definition files.</p>
<h2 id="compilation">Compilation</h2>
<p>To compile <code>validatekeymaps</code>, set up the development environment, download
the Android source tree, compile it, then run:</p>
<pre class="devsite-terminal devsite-click-to-copy">
mmm frameworks/base/tools/validatekeymaps
</pre>
<p>This command should compile a host tool called validatekeymaps into the
<code>out/host/&lt;os&gt;/bin</code> directory.</p>
<h2 id="usage">Usage</h2>
<p>If you ran <code>envsetup.sh</code> to set up your development environment, then the
<code>validatekeymaps</code> tool should already be on your path. You can verify
this by running <code>validatekeymaps</code>.</p>
<pre class="devsite-terminal devsite-click-to-copy">
validatekeymaps
</pre>
<p>You should see the following output:</p>
<pre>
Keymap Validation Tool
Usage:
validatekeymaps [*.kl] [*.kcm] [*.idc] [virtualkeys.*] [...]
Validates the specified key layouts, key character maps,
input device configurations, or virtual key definitions.
</pre>
<p>Then all you need to do is run <code>validatekeymaps</code> and give it the path of
one or more files to validate.</p>
<pre class="devsite-terminal devsite-click-to-copy">
validatekeymaps frameworks/base/data/keyboards/Generic.kl
</pre>
<p>Example:</p>
<pre>
Validating file 'frameworks/base/data/keyboards/Generic.kl'...
No errors.
Success.
</pre>
<p>And if there is an error...</p>
<pre class="devsite-terminal devsite-click-to-copy">
validatekeymaps Bad.kl
</pre>
<p>Example:</p>
<pre>
Validating file 'Bad.kl'...
E/KeyLayoutMap(87688): Bad.kl:24: Expected keyword, got 'ke'.
Error -22 parsing key layout file.
Failed!
</pre>
<h2 id="automation">Automation</h2>
<p>It is a <em>very</em> good idea to run <code>validatekeymaps</code> on all configuration files
before installing them on a device.</p>
<p>The process can easily be automated as part of the build system by using a
script or a makefile.</p>
<p>The following sample makefile is based on the contents of
<code>frameworks/base/data/keyboards/Android.mk</code>.</p>
<pre class="devsite-click-to-copy">
# This makefile performs build time validation of framework keymap files.
LOCAL_PATH := $(call my-dir)
# Validate all key maps.
include $(CLEAR_VARS)
validatekeymaps := $(HOST_OUT_EXECUTABLES)/validatekeymaps$(HOST_EXECUTABLE_SUFFIX)
files := MyKeyboard.kl MyKeyboard.kcm MyTouchScreen.idc
LOCAL_MODULE := validate_framework_keymaps
LOCAL_MODULE_TAGS := optional
LOCAL_REQUIRED_MODULES := validatekeymaps
validate_framework_keymaps: $(files)
$(hide) $(validatekeymaps) $(files)
include $(BUILD_PHONY_PACKAGE)
</pre>
</body>
</html>