1page.title=Touch Devices 2@jd:body 3 4<!-- 5 Copyright 2015 The Android Open Source Project 6 7 Licensed under the Apache License, Version 2.0 (the "License"); 8 you may not use this file except in compliance with the License. 9 You may obtain a copy of the License at 10 11 http://www.apache.org/licenses/LICENSE-2.0 12 13 Unless required by applicable law or agreed to in writing, software 14 distributed under the License is distributed on an "AS IS" BASIS, 15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 16 See the License for the specific language governing permissions and 17 limitations under the License. 18--> 19<div id="qv-wrapper"> 20 <div id="qv"> 21 <h2>In this document</h2> 22 <ol id="auto-toc"> 23 </ol> 24 </div> 25</div> 26 27<p>Android supports a variety of touch screens and touch pads, including 28stylus-based digitizer tablets.</p> 29<p>Touch screens are touch devices that are associated with a display such that 30the user has the impression of directly manipulating items on screen.</p> 31<p>Touch pads are touch devices that are not associated with a display such as a 32digitizer tablet. Touch pads are typically used for pointing or for 33absolute indirect positioning or gesture-based control of a user interface.</p> 34<p>Touch devices may have buttons whose functions are similar to mouse buttons.</p> 35<p>Touch devices can sometimes be manipulated using a variety of different tools 36such as fingers or a stylus depending on the underlying touch sensor technology.</p> 37<p>Touch devices are sometimes used to implement virtual keys. For example, on 38some Android devices, the touch screen sensor area extends beyond the edge of 39the display and serves dual purpose as part of a touch sensitive key pad.</p> 40<p>Due to the great variety of touch devices, Android relies on a large number of 41configuration properties to describe the characteristics and desired behavior 42of each device.</p> 43<h2 id="touch-device-classification">Touch Device Classification</h2> 44<p>An input device is classified as a <em>multi-touch</em> device if both of 45the following conditions hold:</p> 46<ul> 47<li> 48<p>The input device reports the presence of the <code>ABS_MT_POSITION_X</code> and 49 <code>ABS_MT_POSITION_Y</code> absolute axes.</p> 50</li> 51<li> 52<p>The input device does not have any gamepad buttons. This condition 53 resolves an ambiguity with certain gamepads that report axes with codes 54 that overlaps those of the MT axes.</p> 55</li> 56</ul> 57<p>An input device is classified as a <em>single-touch</em> device if both of the 58following conditions hold:</p> 59<ul> 60<li> 61<p>The input device is not classified as a multi-touch device. An input device 62 is either classified as a single-touch device or as a multi-touch device, 63 never both.</p> 64</li> 65<li> 66<p>The input device reports the presence of the <code>ABS_X</code> and <code>ABS_Y</code> absolute 67 axes, and the presence of the <code>BTN_TOUCH</code> key code.</p> 68</li> 69</ul> 70<p>Once an input device has been classified as a touch device, the presence 71of virtual keys is determined by attempting to load the virtual key map file 72for the device. If a virtual key map is available, then the key layout 73file for the device is also loaded.</p> 74<p>Refer to the section below about the location and format of virtual key map 75files.</p> 76<p>Next, the system loads the input device configuration file for the touch device.</p> 77<p><strong>All built-in touch devices should have input device configuration files.</strong> 78If no input device configuration file is present, the system will 79choose a default configuration that is appropriate for typical general-purpose 80touch peripherals such as external USB or Bluetooth HID touch screens 81or touch pads. These defaults are not designed for built-in touch screens and 82will most likely result in incorrect behavior.</p> 83<p>After the input device configuration loaded, the system will classify the 84input device as a <em>touch screen</em>, <em>touch pad</em> or <em>pointer</em> device.</p> 85<ul> 86<li> 87<p>A <em>touch screen</em> device is used for direct manipulation of objects on the 88 screen. Since the user is directly touching the screen, the system does 89 not require any additional affordances to indicate the objects being 90 manipulated.</p> 91</li> 92<li> 93<p>A <em>touch pad</em> device is used to provide absolute positioning information 94 to an application about touches on a given sensor area. It may be useful 95 for digitizer tablets.</p> 96</li> 97<li> 98<p>A <em>pointer</em> device is used for indirect manipulation of objects on the 99 screen using a cursor. Fingers are interpreted as multi-touch pointer 100 gestures. Other tools, such as styluses, are interpreted using 101 absolute positions.</p> 102<p>See <a href="#indirect-multi-touch-pointer-gestures">Indirect Multi-touch Pointer Gestures</a> 103for more information.</p> 104</li> 105</ul> 106<p>The following rules are used to classify the input device as a <em>touch screen</em>, 107<em>touch pad</em> or <em>pointer</em> device.</p> 108<ul> 109<li> 110<p>If the <code>touch.deviceType</code> property is set, then the device type will be 111 set as indicated.</p> 112</li> 113<li> 114<p>If the input device reports the presence of the <code>INPUT_PROP_DIRECT</code> 115 input property (via the <code>EVIOCGPROP</code> ioctl), then the device type will 116 be set to <em>touch screen</em>. This condition assumes that direct input touch 117 devices are attached to a display that is also connected.</p> 118</li> 119<li> 120<p>If the input device reports the presence of the <code>INPUT_PROP_POINTER</code> 121 input property (via the <code>EVIOCGPROP</code> ioctl), then the device type will 122 be set to <em>pointer</em>.</p> 123</li> 124<li> 125<p>If the input device reports the presence of the <code>REL_X</code> or <code>REL_Y</code> relative 126 axes, then the device type will be set to <em>touch pad</em>. This condition 127 resolves an ambiguity for input devices that consist of both a mouse and 128 a touch pad. In this case, the touch pad will not be used to control 129 the pointer because the mouse already controls it.</p> 130</li> 131<li> 132<p>Otherwise, the device type will be set to <em>pointer</em>. This default ensures 133 that touch pads that have not been designated any other special purpose 134 will serve to control the pointer.</p> 135</li> 136</ul> 137<h2 id="buttons">Buttons</h2> 138<p>Buttons are <em>optional</em> controls that may be used by applications to perform 139additional functions. Buttons on touch devices behave similarly to mouse 140buttons and are mainly of use with <em>pointer</em> type touch devices or with a 141stylus.</p> 142<p>The following buttons are supported:</p> 143<ul> 144<li> 145<p><code>BTN_LEFT</code>: mapped to <code>MotionEvent.BUTTON_PRIMARY</code>.</p> 146</li> 147<li> 148<p><code>BTN_RIGHT</code>: mapped to <code>MotionEvent.BUTTON_SECONDARY</code>.</p> 149</li> 150<li> 151<p><code>BTN_MIDDLE</code>: mapped to <code>MotionEvent.BUTTON_MIDDLE</code>.</p> 152</li> 153<li> 154<p><code>BTN_BACK</code> and <code>BTN_SIDE</code>: mapped to <code>MotionEvent.BUTTON_BACK</code>. 155 Pressing this button also synthesizes a key press with the key code 156 <code>KeyEvent.KEYCODE_BACK</code>.</p> 157</li> 158<li> 159<p><code>BTN_FORWARD</code> and <code>BTN_EXTRA</code>: mapped to <code>MotionEvent.BUTTON_FORWARD</code>. 160 Pressing this button also synthesizes a key press with the key code 161 <code>KeyEvent.KEYCODE_FORWARD</code>.</p> 162</li> 163<li> 164<p><code>BTN_STYLUS</code>: mapped to <code>MotionEvent.BUTTON_SECONDARY</code>.</p> 165</li> 166<li> 167<p><code>BTN_STYLUS2</code>: mapped to <code>MotionEvent.BUTTON_TERTIARY</code>.</p> 168</li> 169</ul> 170<h2 id="tools-and-tool-types">Tools and Tool Types</h2> 171<p>A <em>tool</em> is a finger, stylus or other apparatus that is used to interact with 172the touch device. Some touch devices can distinguish between different 173types of tools.</p> 174<p>Elsewhere in Android, as in the <code>MotionEvent</code> API, a <em>tool</em> is often referred 175to as a <em>pointer</em>.</p> 176<p>The following tool types are supported:</p> 177<ul> 178<li> 179<p><code>BTN_TOOL_FINGER</code> and <code>MT_TOOL_FINGER</code>: mapped to <code>MotionEvent.TOOL_TYPE_FINGER</code>.</p> 180</li> 181<li> 182<p><code>BTN_TOOL_PEN</code> and <code>MT_TOOL_PEN</code>: mapped to <code>MotionEvent.TOOL_TYPE_STYLUS</code>.</p> 183</li> 184<li> 185<p><code>BTN_TOOL_RUBBER</code>: mapped to <code>MotionEvent.TOOL_TYPE_ERASER</code>.</p> 186</li> 187<li> 188<p><code>BTN_TOOL_BRUSH</code>: mapped to <code>MotionEvent.TOOL_TYPE_STYLUS</code>.</p> 189</li> 190<li> 191<p><code>BTN_TOOL_PENCIL</code>: mapped to <code>MotionEvent.TOOL_TYPE_STYLUS</code>.</p> 192</li> 193<li> 194<p><code>BTN_TOOL_AIRBRUSH</code>: mapped to <code>MotionEvent.TOOL_TYPE_STYLUS</code>.</p> 195</li> 196<li> 197<p><code>BTN_TOOL_MOUSE</code>: mapped to <code>MotionEvent.TOOL_TYPE_MOUSE</code>.</p> 198</li> 199<li> 200<p><code>BTN_TOOL_LENS</code>: mapped to <code>MotionEvent.TOOL_TYPE_MOUSE</code>.</p> 201</li> 202<li> 203<p><code>BTN_TOOL_DOUBLETAP</code>, <code>BTN_TOOL_TRIPLETAP</code>, and <code>BTN_TOOL_QUADTAP</code>: 204 mapped to <code>MotionEvent.TOOL_TYPE_FINGER</code>.</p> 205</li> 206</ul> 207<h2 id="hovering-vs-touching-tools">Hovering vs. Touching Tools</h2> 208<p>Tools can either be in contact with the touch device or in range and hovering 209above it. Not all touch devices are able to sense the presence of a tool 210hovering above the touch device. Those that do, such as RF-based stylus digitizers, 211can often detect when the tool is within a limited range of the digitizer.</p> 212<p>The <code>InputReader</code> component takes care to distinguish touching tools from hovering 213tools. Likewise, touching tools and hovering tools are reported to applications 214in different ways.</p> 215<p>Touching tools are reported to applications as touch events 216using <code>MotionEvent.ACTION_DOWN</code>, <code>MotionEvent.ACTION_MOVE</code>, <code>MotionEvent.ACTION_DOWN</code>, 217<code>MotionEvent.ACTION_POINTER_DOWN</code> and <code>MotionEvent.ACTION_POINTER_UP</code>.</p> 218<p>Hovering tools are reported to applications as generic motion events using 219<code>MotionEvent.ACTION_HOVER_ENTER</code>, <code>MotionEvent.ACTION_HOVER_MOVE</code> 220and <code>MotionEvent.ACTION_HOVER_EXIT</code>.</p> 221<h2 id="touch-device-driver-requirements">Touch Device Driver Requirements</h2> 222<ol> 223<li> 224<p>Touch device drivers should only register axes and key codes for the axes 225 and buttons that they actually support. Registering excess axes or key codes 226 may confuse the device classification algorithm or cause the system to incorrectly 227 detect the capabilities of the device.</p> 228<p>For example, if the device reports the <code>BTN_TOUCH</code> key code, the system will 229assume that <code>BTN_TOUCH</code> will always be used to indicate whether the tool is 230actually touching the screen or is merely in range and hovering.</p> 231</li> 232<li> 233<p>Single-touch devices use the following Linux input events:</p> 234<ul> 235<li> 236<p><code>ABS_X</code>: <em>(REQUIRED)</em> Reports the X coordinate of the tool.</p> 237</li> 238<li> 239<p><code>ABS_Y</code>: <em>(REQUIRED)</em> Reports the Y coordinate of the tool.</p> 240</li> 241<li> 242<p><code>ABS_PRESSURE</code>: <em>(optional)</em> Reports the physical pressure applied to the tip 243 of the tool or the signal strength of the touch contact.</p> 244</li> 245<li> 246<p><code>ABS_TOOL_WIDTH</code>: <em>(optional)</em> Reports the cross-sectional area or width of the 247 touch contact or of the tool itself.</p> 248</li> 249<li> 250<p><code>ABS_DISTANCE</code>: <em>(optional)</em> Reports the distance of the tool from the surface of 251 the touch device.</p> 252</li> 253<li> 254<p><code>ABS_TILT_X</code>: <em>(optional)</em> Reports the tilt of the tool from the surface of the 255 touch device along the X axis.</p> 256</li> 257<li> 258<p><code>ABS_TILT_Y</code>: <em>(optional)</em> Reports the tilt of the tool from the surface of the 259 touch device along the Y axis.</p> 260</li> 261<li> 262<p><code>BTN_TOUCH</code>: <em>(REQUIRED)</em> Indicates whether the tool is touching the device.</p> 263</li> 264<li> 265<p><code>BTN_LEFT</code>, <code>BTN_RIGHT</code>, <code>BTN_MIDDLE</code>, <code>BTN_BACK</code>, <code>BTN_SIDE</code>, <code>BTN_FORWARD</code>, 266 <code>BTN_EXTRA</code>, <code>BTN_STYLUS</code>, <code>BTN_STYLUS2</code>: 267 <em>(optional)</em> Reports <a href="#buttons">button</a> states.</p> 268</li> 269<li> 270<p><code>BTN_TOOL_FINGER</code>, <code>BTN_TOOL_PEN</code>, <code>BTN_TOOL_RUBBER</code>, <code>BTN_TOOL_BRUSH</code>, 271 <code>BTN_TOOL_PENCIL</code>, <code>BTN_TOOL_AIRBRUSH</code>, <code>BTN_TOOL_MOUSE</code>, <code>BTN_TOOL_LENS</code>, 272 <code>BTN_TOOL_DOUBLETAP</code>, <code>BTN_TOOL_TRIPLETAP</code>, <code>BTN_TOOL_QUADTAP</code>: 273 <em>(optional)</em> Reports the <a href="#tools-and-tool-types">tool type</a>.</p> 274</li> 275</ul> 276</li> 277<li> 278<p>Multi-touch devices use the following Linux input events:</p> 279<ul> 280<li> 281<p><code>ABS_MT_POSITION_X</code>: <em>(REQUIRED)</em> Reports the X coordinate of the tool.</p> 282</li> 283<li> 284<p><code>ABS_MT_POSITION_Y</code>: <em>(REQUIRED)</em> Reports the Y coordinate of the tool.</p> 285</li> 286<li> 287<p><code>ABS_MT_PRESSURE</code>: <em>(optional)</em> Reports the physical pressure applied to the 288 tip of the tool or the signal strength of the touch contact.</p> 289</li> 290<li> 291<p><code>ABS_MT_TOUCH_MAJOR</code>: <em>(optional)</em> Reports the cross-sectional area of the 292 touch contact, or the length of the longer dimension of the touch contact.</p> 293</li> 294<li> 295<p><code>ABS_MT_TOUCH_MINOR</code>: <em>(optional)</em> Reports the length of the shorter dimension of the 296 touch contact. This axis should not be used if <code>ABS_MT_TOUCH_MAJOR</code> is reporting an 297 area measurement.</p> 298</li> 299<li> 300<p><code>ABS_MT_WIDTH_MAJOR</code>: <em>(optional)</em> Reports the cross-sectional area of the tool itself, 301 or the length of the longer dimension of the tool itself. 302 This axis should not be used if the dimensions of the tool itself are unknown.</p> 303</li> 304<li> 305<p><code>ABS_MT_WIDTH_MINOR</code>: <em>(optional)</em> Reports the length of the shorter dimension of 306 the tool itself. This axis should not be used if <code>ABS_MT_WIDTH_MAJOR</code> is reporting 307 an area measurement or if the dimensions of the tool itself are unknown.</p> 308</li> 309<li> 310<p><code>ABS_MT_ORIENTATION</code>: <em>(optional)</em> Reports the orientation of the tool.</p> 311</li> 312<li> 313<p><code>ABS_MT_DISTANCE</code>: <em>(optional)</em> Reports the distance of the tool from the 314 surface of the touch device.</p> 315</li> 316<li> 317<p><code>ABS_MT_TOOL_TYPE</code>: <em>(optional)</em> Reports the <a href="#tools-and-tool-types">tool type</a> as 318 <code>MT_TOOL_FINGER</code> or <code>MT_TOOL_PEN</code>.</p> 319</li> 320<li> 321<p><code>ABS_MT_TRACKING_ID</code>: <em>(optional)</em> Reports the tracking id of the tool. 322 The tracking id is an arbitrary non-negative integer that is used to identify 323 and track each tool independently when multiple tools are active. For example, 324 when multiple fingers are touching the device, each finger should be assigned a distinct 325 tracking id that is used as long as the finger remains in contact. Tracking ids 326 may be reused when their associated tools move out of range.</p> 327</li> 328<li> 329<p><code>ABS_MT_SLOT</code>: <em>(optional)</em> Reports the slot id of the tool, when using the Linux 330 multi-touch protocol 'B'. Refer to the Linux multi-touch protocol documentation 331 for more details.</p> 332</li> 333<li> 334<p><code>BTN_TOUCH</code>: <em>(REQUIRED)</em> Indicates whether the tool is touching the device.</p> 335</li> 336<li> 337<p><code>BTN_LEFT</code>, <code>BTN_RIGHT</code>, <code>BTN_MIDDLE</code>, <code>BTN_BACK</code>, <code>BTN_SIDE</code>, <code>BTN_FORWARD</code>, 338 <code>BTN_EXTRA</code>, <code>BTN_STYLUS</code>, <code>BTN_STYLUS2</code>: 339 <em>(optional)</em> Reports <a href="#buttons">button</a> states.</p> 340</li> 341<li> 342<p><code>BTN_TOOL_FINGER</code>, <code>BTN_TOOL_PEN</code>, <code>BTN_TOOL_RUBBER</code>, <code>BTN_TOOL_BRUSH</code>, 343 <code>BTN_TOOL_PENCIL</code>, <code>BTN_TOOL_AIRBRUSH</code>, <code>BTN_TOOL_MOUSE</code>, <code>BTN_TOOL_LENS</code>, 344 <code>BTN_TOOL_DOUBLETAP</code>, <code>BTN_TOOL_TRIPLETAP</code>, <code>BTN_TOOL_QUADTAP</code>: 345 <em>(optional)</em> Reports the <a href="#tools-and-tool-types">tool type</a>.</p> 346</li> 347</ul> 348</li> 349<li> 350<p>If axes for both the single-touch and multi-touch protocol are defined, then 351 only the multi-touch axes will be used and the single-touch axes will be ignored.</p> 352</li> 353<li> 354<p>The minimum and maximum values of the <code>ABS_X</code>, <code>ABS_Y</code>, <code>ABS_MT_POSITION_X</code> 355 and <code>ABS_MT_POSITION_Y</code> axes define the bounds of the active area of the device 356 in device-specific surface units. In the case of a touch screen, the active area 357 describes the part of the touch device that actually covers the display.</p> 358<p>For a touch screen, the system automatically interpolates the reported touch 359positions in surface units to obtain touch positions in display pixels according 360to the following calculation:</p> 361<pre><code>displayX = (x - minX) * displayWidth / (maxX - minX + 1) 362displayY = (y - minY) * displayHeight / (maxY - minY + 1) 363</code></pre> 364<p>A touch screen may report touches outside of the reported active area.</p> 365<p>Touches that are initiated outside the active area are not delivered to applications 366but may be used for virtual keys.</p> 367<p>Touches that are initiated inside the active area, or that enter and exit the display 368area are delivered to applications. Consequently, if a touch starts within the 369bounds of an application and then moves outside of the active area, the application 370may receive touch events with display coordinates that are negative or beyond the 371bounds of the display. This is expected behavior.</p> 372<p>A touch device should never clamp touch coordinates to the bounds of the active 373area. If a touch exits the active area, it should be reported as being outside of 374the active area, or it should not be reported at all.</p> 375<p>For example, if the user's finger is touching near the top-left corner of the 376touch screen, it may report a coordinate of (minX, minY). If the finger continues 377to move further outside of the active area, the touch screen should either start 378reporting coordinates with components less than minX and minY, such as 379(minX - 2, minY - 3), or it should stop reporting the touch altogether. 380In other words, the touch screen should <em>not</em> be reporting (minX, minY) 381when the user's finger is really touching outside of the active area.</p> 382<p>Clamping touch coordinates to the display edge creates an artificial 383hard boundary around the edge of the screen which prevents the system from 384smoothly tracking motions that enter or exit the bounds of the display area.</p> 385</li> 386<li> 387<p>The values reported by <code>ABS_PRESSURE</code> or <code>ABS_MT_PRESSURE</code>, if they 388 are reported at all, must be non-zero when the tool is touching the device 389 and zero otherwise to indicate that the tool is hovering.</p> 390<p>Reporting pressure information is <em>optional</em> but strongly recommended. 391Applications can use pressure information to implement pressure-sensitive drawing 392and other effects.</p> 393</li> 394<li> 395<p>The values reported by <code>ABS_TOOL_WIDTH</code>, <code>ABS_MT_TOUCH_MAJOR</code>, <code>ABS_MT_TOUCH_MINOR</code>, 396 <code>ABS_MT_WIDTH_MAJOR</code>, or <code>ABS_MT_WIDTH_MINOR</code> should be non-zero when the tool 397 is touching the device and zero otherwise, but this is not required. 398 For example, the touch device may be able to measure the size of finger touch 399 contacts but not stylus touch contacts.</p> 400<p>Reporting size information is <em>optional</em> but strongly recommended. 401Applications can use pressure information to implement size-sensitive drawing 402and other effects.</p> 403</li> 404<li> 405<p>The values reported by <code>ABS_DISTANCE</code> or <code>ABS_MT_DISTANCE</code> should approach 406 zero when the tool is touching the device. The distance may remain non-zero 407 even when the tool is in direct contact. The exact values reported depend 408 on the manner in which the hardware measures distance.</p> 409<p>Reporting distance information is <em>optional</em> but recommended for 410stylus devices.</p> 411</li> 412<li> 413<p>The values reported by <code>ABS_TILT_X</code> and <code>ABS_TILT_Y</code> should be zero when the 414 tool is perpendicular to the device. A non-zero tilt is taken as an indication 415 that the tool is held at an incline.</p> 416<p>The tilt angles along the X and Y axes are assumed to be specified in degrees 417from perpendicular. The center point (perfectly perpendicular) is given 418by <code>(max + min) / 2</code> for each axis. Values smaller than the center point 419represent a tilt up or to the left, values larger than the center point 420represent a tilt down or to the right.</p> 421<p>The <code>InputReader</code> converts the X and Y tilt components into a perpendicular 422tilt angle ranging from 0 to <code>PI / 2</code> radians and a planar orientation angle 423ranging from <code>-PI</code> to <code>PI</code> radians. This representation results in a 424description of orientation that is compatible with what is used to describe 425finger touches.</p> 426<p>Reporting tilt information is <em>optional</em> but recommended for stylus devices.</p> 427</li> 428<li> 429<p>If the tool type is reported by <code>ABS_MT_TOOL_TYPE</code>, it will supersede any tool 430 type information reported by <code>BTN_TOOL_*</code>. 431 If no tool type information is available at all, the tool type defaults to 432 <code>MotionEvent.TOOL_TYPE_FINGER</code>.</p> 433</li> 434<li> 435<p>A tool is determined to be active based on the following conditions:</p> 436<ul> 437<li> 438<p>When using the single-touch protocol, the tool is active if <code>BTN_TOUCH</code>, 439 or <code>BTN_TOOL_*</code> is 1.</p> 440<p>This condition implies that the <code>InputReader</code> needs to have at least some 441information about the nature of the tool, either whether it is touching, 442or at least its tool type. If no information is available, 443then the tool is assumed to be inactive (out of range).</p> 444</li> 445<li> 446<p>When using the multi-touch protocol 'A', the tool is active whenever it 447 appears in the most recent sync report. When the tool stops appearing in 448 sync reports, it ceases to exist.</p> 449</li> 450<li> 451<p>When using the multi-touch protocol 'B', the tool is active as long as 452 it has an active slot. When the slot it cleared, the tool ceases to exist.</p> 453</li> 454</ul> 455</li> 456<li> 457<p>A tool is determined to be hovering based on the following conditions:</p> 458<ul> 459<li> 460<p>If the tool is <code>BTN_TOOL_MOUSE</code> or <code>BTN_TOOL_LENS</code>, then the tool 461 is not hovering, even if either of the following conditions are true.</p> 462</li> 463<li> 464<p>If the tool is active and the driver reports pressure information, 465 and the reported pressure is zero, then the tool is hovering.</p> 466</li> 467<li> 468<p>If the tool is active and the driver supports the <code>BTN_TOUCH</code> key code and 469 <code>BTN_TOUCH</code> has a value of zero, then the tool is hovering.</p> 470</li> 471</ul> 472</li> 473<li> 474<p>The <code>InputReader</code> supports both multi-touch protocol 'A' and 'B'. New drivers 475 should use the 'B' protocol but either will work.</p> 476</li> 477<li> 478<p><strong>As of Android Ice Cream Sandwich 4.0, touch screen drivers may need to be changed 479 to comply with the Linux input protocol specification.</strong></p> 480<p>The following changes may be required:</p> 481<ul> 482<li> 483<p>When a tool becomes inactive (finger goes "up"), it should stop appearing 484 in subsequent multi-touch sync reports. When all tools become inactive 485 (all fingers go "up"), the driver should send an empty sync report packet, 486 such as <code>SYN_MT_REPORT</code> followed by <code>SYN_REPORT</code>.</p> 487<p>Previous versions of Android expected "up" events to be reported by sending 488a pressure value of 0. The old behavior was incompatible with the 489Linux input protocol specification and is no longer supported.</p> 490</li> 491<li> 492<p>Physical pressure or signal strength information should be reported using 493 <code>ABS_MT_PRESSURE</code>.</p> 494<p>Previous versions of Android retrieved pressure information from 495<code>ABS_MT_TOUCH_MAJOR</code>. The old behavior was incompatible with the 496Linux input protocol specification and is no longer supported.</p> 497</li> 498<li> 499<p>Touch size information should be reported using <code>ABS_MT_TOUCH_MAJOR</code>.</p> 500<p>Previous versions of Android retrieved size information from 501<code>ABS_MT_TOOL_MAJOR</code>. The old behavior was incompatible with the 502Linux input protocol specification and is no longer supported.</p> 503</li> 504</ul> 505<p>Touch device drivers no longer need Android-specific customizations. 506By relying on the standard Linux input protocol, Android can support a 507wider variety of touch peripherals, such as external HID multi-touch 508touch screens, using unmodified drivers.</p> 509</li> 510</ol> 511<h2 id="touch-device-operation">Touch Device Operation</h2> 512<p>The following is a brief summary of the touch device operation on Android.</p> 513<ol> 514<li> 515<p>The <code>EventHub</code> reads raw events from the <code>evdev</code> driver.</p> 516</li> 517<li> 518<p>The <code>InputReader</code> consumes the raw events and updates internal state about 519 the position and other characteristics of each tool. It also tracks 520 button states.</p> 521</li> 522<li> 523<p>If the BACK or FORWARD buttons were pressed or released, the <code>InputReader</code> 524 notifies the <code>InputDispatcher</code> about the key event.</p> 525</li> 526<li> 527<p>The <code>InputReader</code> determines whether a virtual key press occurred. If so, 528 it notifies the <code>InputDispatcher</code> about the key event.</p> 529</li> 530<li> 531<p>The <code>InputReader</code> determines whether the touch was initiated within the 532 bounds of the display. If so, it notifies the <code>InputDispatcher</code> about 533 the touch event.</p> 534</li> 535<li> 536<p>If there are no touching tools but there is at least one hovering tool, 537 the <code>InputReader</code> notifies the <code>InputDispatcher</code> about the hover event.</p> 538</li> 539<li> 540<p>If the touch device type is <em>pointer</em>, the <code>InputReader</code> performs pointer 541 gesture detection, moves the pointer and spots accordingly and notifies 542 the <code>InputDispatcher</code> about the pointer event.</p> 543</li> 544<li> 545<p>The <code>InputDispatcher</code> uses the <code>WindowManagerPolicy</code> to determine whether 546 the events should be dispatched and whether they should wake the device. 547 Then, the <code>InputDispatcher</code> delivers the events to the appropriate applications.</p> 548</li> 549</ol> 550<h2 id="touch-device-configuration">Touch Device Configuration</h2> 551<p>Touch device behavior is determined by the device's axes, buttons, input properties, 552input device configuration, virtual key map and key layout.</p> 553<p>Refer to the following sections for more details about the files that 554participate in keyboard configuration:</p> 555<ul> 556<li><a href="input-device-configuration-files.html">Input Device Configuration Files</a></li> 557<li><a href="#virtual-key-map-files">Virtual Key Map Files</a></li> 558</ul> 559<h3 id="properties">Properties</h3> 560<p>The system relies on many input device configuration properties to configure 561and calibrate touch device behavior.</p> 562<p>One reason for this is that the device drivers for touch devices often report 563the characteristics of touches using device-specific units.</p> 564<p>For example, many touch devices measure the touch contact area 565using an internal device-specific scale, such as the total number of 566sensor nodes that were triggered by the touch. This raw size value would 567not be meaningful applications because they would need to know about the 568physical size and other characteristics of the touch device sensor nodes.</p> 569<p>The system uses calibration parameters encoded in input device configuration 570files to decode, transform, and normalize the values reported by the touch 571device into a simpler standard representation that applications can understand.</p> 572<h3 id="documentation-conventions">Documentation Conventions</h3> 573<p>For documentation purposes, we will use the following conventions to describe 574the values used by the system during the calibration process.</p> 575<h4 id="raw-axis-values">Raw Axis Values</h4> 576<p>The following expressions denote the raw values reported by the touch 577device driver as <code>EV_ABS</code> events.</p> 578<dl> 579<dt><code>raw.x</code></dt> 580<dd>The value of the <code>ABS_X</code> or <code>ABS_MT_POSITION_X</code> axis.</dd> 581<dt><code>raw.y</code></dt> 582<dd>The value of the <code>ABS_Y</code> or <code>ABS_MT_POSITION_Y</code> axis.</dd> 583<dt><code>raw.pressure</code></dt> 584<dd>The value of the <code>ABS_PRESSURE</code> or <code>ABS_MT_PRESSURE</code> axis, or 0 if not available.</dd> 585<dt><code>raw.touchMajor</code></dt> 586<dd>The value of the <code>ABS_MT_TOUCH_MAJOR</code> axis, or 0 if not available.</dd> 587<dt><code>raw.touchMinor</code></dt> 588<dd>The value of the <code>ABS_MT_TOUCH_MINOR</code> axis, or <code>raw.touchMajor</code> if not available.</dd> 589<dt><code>raw.toolMajor</code></dt> 590<dd>The value of the <code>ABS_TOOL_WIDTH</code> or <code>ABS_MT_WIDTH_MAJOR</code> axis, or 0 if not available.</dd> 591<dt><code>raw.toolMinor</code></dt> 592<dd>The value of the <code>ABS_MT_WIDTH_MINOR</code> axis, or <code>raw.toolMajor</code> if not available.</dd> 593<dt><code>raw.orientation</code></dt> 594<dd>The value of the <code>ABS_MT_ORIENTATION</code> axis, or 0 if not available.</dd> 595<dt><code>raw.distance</code></dt> 596<dd>The value of the <code>ABS_DISTANCE</code> or <code>ABS_MT_DISTANCE</code> axis, or 0 if not available.</dd> 597<dt><code>raw.tiltX</code></dt> 598<dd>The value of the <code>ABS_TILT_X</code> axis, or 0 if not available.</dd> 599<dt><code>raw.tiltY</code></dt> 600<dd>The value of the <code>ABS_TILT_Y</code> axis, or 0 if not available.</dd> 601</dl> 602<h4 id="raw-axis-ranges">Raw Axis Ranges</h4> 603<p>The following expressions denote the bounds of raw values. They are obtained 604by calling <code>EVIOCGABS</code> ioctl for each axis.</p> 605<dl> 606<dt><code>raw.*.min</code></dt> 607<dd>The inclusive minimum value of the raw axis.</dd> 608<dt><code>raw.*.max</code></dt> 609<dd>The inclusive maximum value of the raw axis.</dd> 610<dt><code>raw.*.range</code></dt> 611<dd>Equivalent to <code>raw.*.max - raw.*.min</code>.</dd> 612<dt><code>raw.*.fuzz</code></dt> 613<dd>The accuracy of the raw axis. eg. fuzz = 1 implies values are accurate to +/- 1 unit.</dd> 614<dt><code>raw.width</code></dt> 615<dd>The inclusive width of the touch area, equivalent to <code>raw.x.range + 1</code>.</dd> 616<dt><code>raw.height</code></dt> 617<dd>The inclusive height of the touch area, equivalent to <code>raw.y.range + 1</code>.</dd> 618</dl> 619<h4 id="output-ranges">Output Ranges</h4> 620<p>The following expressions denote the characteristics of the output coordinate system. 621The system uses linear interpolation to translate touch position information from 622the surface units used by the touch device into the output units that will 623be reported to applications such as display pixels.</p> 624<dl> 625<dt><code>output.width</code></dt> 626<dd>The output width. For touch screens (associated with a display), this 627is the display width in pixels. For touch pads (not associated with a display), 628the output width equals <code>raw.width</code>, indicating that no interpolation will 629be performed.</dd> 630<dt><code>output.height</code></dt> 631<dd>The output height. For touch screens (associated with a display), this 632is the display height in pixels. For touch pads (not associated with a display), 633the output height equals <code>raw.height</code>, indicating that no interpolation will 634be performed.</dd> 635<dt><code>output.diag</code></dt> 636<dd>The diagonal length of the output coordinate system, equivalent to 637<code>sqrt(output.width ^2 + output.height ^2)</code>.</dd> 638</dl> 639<h3 id="basic-configuration">Basic Configuration</h3> 640<p>The touch input mapper uses many configuration properties in the input device 641configuration file to specify calibration values. The following table describes 642some general purpose configuration properties. All other properties are described 643in the following sections along with the fields they are used to calibrate.</p> 644<h4 id="touchdevicetype"><code>touch.deviceType</code></h4> 645<p><em>Definition:</em> <code>touch.deviceType</code> = <code>touchScreen</code> | <code>touchPad</code> | <code>pointer</code> | <code>default</code></p> 646<p>Specifies the touch device type.</p> 647<ul> 648<li> 649<p>If the value is <code>touchScreen</code>, the touch device is a touch screen associated 650 with a display.</p> 651</li> 652<li> 653<p>If the value is <code>touchPad</code>, the touch device is a touch pad not associated 654 with a display.</p> 655</li> 656<li> 657<p>If the value is <code>pointer</code>, the touch device is a touch pad not associated 658 with a display, and its motions are used for 659 <a href="#indirect-multi-touch-pointer-gestures">indirect multi-touch pointer gestures</a>.</p> 660</li> 661<li> 662<p>If the value is <code>default</code>, the system automatically detects the device type 663 according to the classification algorithm.</p> 664</li> 665</ul> 666<p>Refer to the <a href="#touch-device-classification">Classification</a> section for more details 667about how the device type influences the behavior of the touch device.</p> 668<p>Prior to Honeycomb, all touch devices were assumed to be touch screens.</p> 669<h4 id="touchorientationaware"><code>touch.orientationAware</code></h4> 670<p><em>Definition:</em> <code>touch.orientationAware</code> = <code>0</code> | <code>1</code></p> 671<p>Specifies whether the touch device should react to display orientation changes.</p> 672<ul> 673<li> 674<p>If the value is <code>1</code>, touch positions reported by the touch device are rotated 675 whenever the display orientation changes.</p> 676</li> 677<li> 678<p>If the value is <code>0</code>, touch positions reported by the touch device are immune 679 to display orientation changes.</p> 680</li> 681</ul> 682<p>The default value is <code>1</code> if the device is a touch screen, <code>0</code> otherwise.</p> 683<p>The system distinguishes between internal and external touch screens and displays. 684An orientation aware internal touch screen is rotated based on the orientation 685of the internal display. An orientation aware external touch screen is rotated 686based on the orientation of the external display.</p> 687<p>Orientation awareness is used to support rotation of touch screens on devices 688like the Nexus One. For example, when the device is rotated clockwise 90 degrees 689from its natural orientation, the absolute positions of touches are remapped such 690that a touch in the top-left corner of the touch screen's absolute coordinate system 691is reported as a touch in the top-left corner of the display's rotated coordinate system. 692This is done so that touches are reported with the same coordinate system that 693applications use to draw their visual elements.</p> 694<p>Prior to Honeycomb, all touch devices were assumed to be orientation aware.</p> 695<h4 id="touchgesturemode"><code>touch.gestureMode</code></h4> 696<p><em>Definition:</em> <code>touch.gestureMode</code> = <code>pointer</code> | <code>spots</code> | <code>default</code></p> 697<p>Specifies the presentation mode for pointer gestures. This configuration property 698is only relevant when the touch device is of type <em>pointer</em>.</p> 699<ul> 700<li> 701<p>If the value is <code>pointer</code>, the touch pad gestures are presented by way of a cursor 702 similar to a mouse pointer.</p> 703</li> 704<li> 705<p>If the value is <code>spots</code>, the touch pad gestures are presented by an anchor 706 that represents the centroid of the gesture and a set of circular spots 707 that represent the position of individual fingers.</p> 708</li> 709</ul> 710<p>The default value is <code>pointer</code> when the <code>INPUT_PROP_SEMI_MT</code> input property 711is set, or <code>spots</code> otherwise.</p> 712<h3 id="x-and-y-fields"><code>X</code> and <code>Y</code> Fields</h3> 713<p>The X and Y fields provide positional information for the center of the contact area.</p> 714<h4 id="calculation">Calculation</h4> 715<p>The calculation is straightforward: positional information from the touch driver is 716linearly interpolated to the output coordinate system.</p> 717<pre><code>xScale = output.width / raw.width 718yScale = output.height / raw.height 719 720If not orientation aware or screen rotation is 0 degrees: 721output.x = (raw.x - raw.x.min) * xScale 722output.y = (raw.y - raw.y.min) * yScale 723Else If rotation is 90 degrees: 724 output.x = (raw.y - raw.y.min) * yScale 725 output.y = (raw.x.max - raw.x) * xScale 726Else If rotation is 180 degrees: 727 output.x = (raw.x.max - raw.x) * xScale 728 output.y = (raw.y.max - raw.y) * yScale 729Else If rotation is 270 degrees: 730 output.x = (raw.y.max - raw.y) * yScale 731 output.y = (raw.x - raw.x.min) * xScale 732End If 733</code></pre> 734<h3 id="touchmajor-touchminor-toolmajor-toolminor-size-fields"><code>TouchMajor</code>, <code>TouchMinor</code>, <code>ToolMajor</code>, <code>ToolMinor</code>, <code>Size</code> Fields</h3> 735<p>The <code>TouchMajor</code> and <code>TouchMinor</code> fields describe the approximate dimensions 736of the contact area in output units (pixels).</p> 737<p>The <code>ToolMajor</code> and <code>ToolMinor</code> fields describe the approximate dimensions 738of the <a href="#tools-and-tool-types">tool</a> itself in output units (pixels).</p> 739<p>The <code>Size</code> field describes the normalized size of the touch relative to 740the largest possible touch that the touch device can sense. The smallest 741possible normalized size is 0.0 (no contact, or it is unmeasurable), and the largest 742possible normalized size is 1.0 (sensor area is saturated).</p> 743<p>When both the approximate length and breadth can be measured, then the <code>TouchMajor</code> field 744specifies the longer dimension and the <code>TouchMinor</code> field specifies the shorter dimension 745of the contact area. When only the approximate diameter of the contact area can be measured, 746then the <code>TouchMajor</code> and <code>TouchMinor</code> fields will be equal.</p> 747<p>Likewise, the <code>ToolMajor</code> field specifies the longer dimension and the <code>ToolMinor</code> 748field specifies the shorter dimension of the tool's cross-sectional area.</p> 749<p>If the touch size is unavailable but the tool size is available, then the tool size 750will be set equal to the touch size. Conversely, if the tool size is unavailable 751but the touch size is available, then the touch size will be set equal to the tool size.</p> 752<p>Touch devices measure or report the touch size and tool size in various ways. 753The current implementation supports three different kinds of measurements: 754diameter, area, and geometric bounding box in surface units.</p> 755<h4 id="touchsizecalibration"><code>touch.size.calibration</code></h4> 756<p><em>Definition:</em> <code>touch.size.calibration</code> = <code>none</code> | <code>geometric</code> | <code>diameter</code> 757| <code>area</code> | <code>default</code></p> 758<p>Specifies the kind of measurement used by the touch driver to report the 759touch size and tool size.</p> 760<ul> 761<li> 762<p>If the value is <code>none</code>, the size is set to zero.</p> 763</li> 764<li> 765<p>If the value is <code>geometric</code>, the size is assumed to be specified in the same 766 surface units as the position, so it is scaled in the same manner.</p> 767</li> 768<li> 769<p>If the value is <code>diameter</code>, the size is assumed to be proportional to 770 the diameter (width) of the touch or tool.</p> 771</li> 772<li> 773<p>If the value is <code>area</code>, the size is assumed to be proportional to the 774 area of the touch or tool.</p> 775</li> 776<li> 777<p>If the value is <code>default</code>, the system uses the <code>geometric</code> calibration if the 778 <code>raw.touchMajor</code> or <code>raw.toolMajor</code> axis is available, otherwise it uses 779 the <code>none</code> calibration.</p> 780</li> 781</ul> 782<h4 id="touchsizescale"><code>touch.size.scale</code></h4> 783<p><em>Definition:</em> <code>touch.size.scale</code> = <a non-negative floating point number></p> 784<p>Specifies a constant scale factor used in the calibration.</p> 785<p>The default value is <code>1.0</code>.</p> 786<h4 id="touchsizebias"><code>touch.size.bias</code></h4> 787<p><em>Definition:</em> <code>touch.size.bias</code> = <a non-negative floating point number></p> 788<p>Specifies a constant bias value used in the calibration.</p> 789<p>The default value is <code>0.0</code>.</p> 790<h4 id="touchsizeissummed"><code>touch.size.isSummed</code></h4> 791<p><em>Definition:</em> <code>touch.size.isSummed</code> = <code>0</code> | <code>1</code></p> 792<p>Specifies whether the size is reported as the sum of the sizes of all 793active contacts, or is reported individually for each contact.</p> 794<ul> 795<li> 796<p>If the value is <code>1</code>, the reported size will be divided by the number 797 of contacts prior to use.</p> 798</li> 799<li> 800<p>If the value is <code>0</code>, the reported size will be used as is.</p> 801</li> 802</ul> 803<p>The default value is <code>0</code>.</p> 804<p>Some touch devices, particularly "Semi-MT" devices cannot distinguish the 805individual dimensions of multiple contacts so they report a size measurement 806that represents their total area or width. This property should only be set to 807<code>1</code> for such devices. If in doubt, set this value to <code>0</code>.</p> 808<h4 id="calculation_1">Calculation</h4> 809<p>The calculation of the <code>TouchMajor</code>, <code>TouchMinor</code>, <code>ToolMajor</code>, <code>ToolMinor</code> 810and <code>Size</code> fields depends on the specified calibration parameters.</p> 811<pre><code>If raw.touchMajor and raw.toolMajor are available: 812 touchMajor = raw.touchMajor 813 touchMinor = raw.touchMinor 814 toolMajor = raw.toolMajor 815 toolMinor = raw.toolMinor 816Else If raw.touchMajor is available: 817 toolMajor = touchMajor = raw.touchMajor 818 toolMinor = touchMinor = raw.touchMinor 819Else If raw.toolMajor is available: 820 touchMajor = toolMajor = raw.toolMajor 821 touchMinor = toolMinor = raw.toolMinor 822Else 823 touchMajor = toolMajor = 0 824 touchMinor = toolMinor = 0 825 size = 0 826End If 827 828size = avg(touchMajor, touchMinor) 829 830If touch.size.isSummed == 1: 831 touchMajor = touchMajor / numberOfActiveContacts 832 touchMinor = touchMinor / numberOfActiveContacts 833 toolMajor = toolMajor / numberOfActiveContacts 834 toolMinor = toolMinor / numberOfActiveContacts 835 size = size / numberOfActiveContacts 836End If 837 838If touch.size.calibration == "none": 839 touchMajor = toolMajor = 0 840 touchMinor = toolMinor = 0 841 size = 0 842Else If touch.size.calibration == "geometric": 843 outputScale = average(output.width / raw.width, output.height / raw.height) 844 touchMajor = touchMajor * outputScale 845 touchMinor = touchMinor * outputScale 846 toolMajor = toolMajor * outputScale 847 toolMinor = toolMinor * outputScale 848Else If touch.size.calibration == "area": 849 touchMajor = sqrt(touchMajor) 850 touchMinor = touchMajor 851 toolMajor = sqrt(toolMajor) 852 toolMinor = toolMajor 853Else If touch.size.calibration == "diameter": 854 touchMinor = touchMajor 855 toolMinor = toolMajor 856End If 857 858If touchMajor != 0: 859 output.touchMajor = touchMajor * touch.size.scale + touch.size.bias 860Else 861 output.touchMajor = 0 862End If 863 864If touchMinor != 0: 865 output.touchMinor = touchMinor * touch.size.scale + touch.size.bias 866Else 867 output.touchMinor = 0 868End If 869 870If toolMajor != 0: 871 output.toolMajor = toolMajor * touch.size.scale + touch.size.bias 872Else 873 output.toolMajor = 0 874End If 875 876If toolMinor != 0: 877 output.toolMinor = toolMinor * touch.size.scale + touch.size.bias 878Else 879 output.toolMinor = 0 880End If 881 882output.size = size 883</code></pre> 884<h3 id="pressure-field"><code>Pressure</code> Field</h3> 885<p>The <code>Pressure</code> field describes the approximate physical pressure applied to the 886touch device as a normalized value between 0.0 (no touch) and 1.0 (full force).</p> 887<p>A zero pressure indicates that the tool is hovering.</p> 888<h4 id="touchpressurecalibration"><code>touch.pressure.calibration</code></h4> 889<p><em>Definition:</em> <code>touch.pressure.calibration</code> = <code>none</code> | <code>physical</code> | <code>amplitude</code> | <code>default</code></p> 890<p>Specifies the kind of measurement used by the touch driver to report the pressure.</p> 891<ul> 892<li> 893<p>If the value is <code>none</code>, the pressure is unknown so it is set to 1.0 when 894 touching and 0.0 when hovering.</p> 895</li> 896<li> 897<p>If the value is <code>physical</code>, the pressure axis is assumed to measure the actual 898 physical intensity of pressure applied to the touch pad.</p> 899</li> 900<li> 901<p>If the value is <code>amplitude</code>, the pressure axis is assumed to measure the signal 902 amplitude, which is related to the size of the contact and the pressure applied.</p> 903</li> 904<li> 905<p>If the value is <code>default</code>, the system uses the <code>physical</code> calibration if the 906 pressure axis available, otherwise uses <code>none</code>.</p> 907</li> 908</ul> 909<h4 id="touchpressurescale"><code>touch.pressure.scale</code></h4> 910<p><em>Definition:</em> <code>touch.pressure.scale</code> = <a non-negative floating point number></p> 911<p>Specifies a constant scale factor used in the calibration.</p> 912<p>The default value is <code>1.0 / raw.pressure.max</code>.</p> 913<h4 id="calculation_2">Calculation</h4> 914<p>The calculation of the <code>Pressure</code> field depends on the specified calibration parameters.</p> 915<pre><code>If touch.pressure.calibration == "physical" or "amplitude": 916 output.pressure = raw.pressure * touch.pressure.scale 917Else 918 If hovering: 919 output.pressure = 0 920 Else 921 output.pressure = 1 922 End If 923End If 924</code></pre> 925<h3 id="orientation-and-tilt-fields"><code>Orientation</code> and <code>Tilt</code> Fields</h3> 926<p>The <code>Orientation</code> field describes the orientation of the touch and tool as an 927angular measurement. An orientation of <code>0</code> indicates that the major axis is 928oriented vertically, <code>-PI/2</code> indicates that the major axis is oriented to the left, 929<code>PI/2</code> indicates that the major axis is oriented to the right. When a stylus 930tool is present, the orientation range may be described in a full circle range 931from <code>-PI</code> or <code>PI</code>.</p> 932<p>The <code>Tilt</code> field describes the inclination of the tool as an angular measurement. 933A tilt of <code>0</code> indicates that the tool is perpendicular to the surface. 934A tilt of <code>PI/2</code> indicates that the tool is flat on the surface.</p> 935<h4 id="touchorientationcalibration"><code>touch.orientation.calibration</code></h4> 936<p><em>Definition:</em> <code>touch.orientation.calibration</code> = <code>none</code> | <code>interpolated</code> | <code>vector</code> | <code>default</code></p> 937<p>Specifies the kind of measurement used by the touch driver to report the orientation.</p> 938<ul> 939<li> 940<p>If the value is <code>none</code>, the orientation is unknown so it is set to 0.</p> 941</li> 942<li> 943<p>If the value is <code>interpolated</code>, the orientation is linearly interpolated such that a 944 raw value of <code>raw.orientation.min</code> maps to <code>-PI/2</code> and a raw value of 945 <code>raw.orientation.max</code> maps to <code>PI/2</code>. The center value of 946 <code>(raw.orientation.min + raw.orientation.max) / 2</code> maps to <code>0</code>.</p> 947</li> 948<li> 949<p>If the value is <code>vector</code>, the orientation is interpreted as a packed vector consisiting 950 of two signed 4-bit fields. This representation is used on Atmel Object Based Protocol 951 parts. When decoded, the vector yields an orientation angle and confidence 952 magnitude. The confidence magnitude is used to scale the size information, 953 unless it is geometric.</p> 954</li> 955<li> 956<p>If the value is <code>default</code>, the system uses the <code>interpolated</code> calibration if the 957 orientation axis available, otherwise uses <code>none</code>.</p> 958</li> 959</ul> 960<h4 id="calculation_3">Calculation</h4> 961<p>The calculation of the <code>Orientation</code> and <code>Tilt</code> fields depends on the specified 962calibration parameters and available input.</p> 963<pre><code>If touch.tiltX and touch.tiltY are available: 964 tiltXCenter = average(raw.tiltX.min, raw.tiltX.max) 965 tiltYCenter = average(raw.tiltY.min, raw.tiltY.max) 966 tiltXAngle = (raw.tiltX - tiltXCenter) * PI / 180 967 tiltYAngle = (raw.tiltY - tiltYCenter) * PI / 180 968 output.orientation = atan2(-sin(tiltXAngle), sinf(tiltYAngle)) 969 output.tilt = acos(cos(tiltXAngle) * cos(tiltYAngle)) 970Else If touch.orientation.calibration == "interpolated": 971 center = average(raw.orientation.min, raw.orientation.max) 972 output.orientation = PI / (raw.orientation.max - raw.orientation.min) 973 output.tilt = 0 974Else If touch.orientation.calibration == "vector": 975 c1 = (raw.orientation & 0xF0) >> 4 976 c2 = raw.orientation & 0x0F 977 978 If c1 != 0 or c2 != 0: 979 If c1 >= 8 Then c1 = c1 - 16 980 If c2 >= 8 Then c2 = c2 - 16 981 angle = atan2(c1, c2) / 2 982 confidence = sqrt(c1*c1 + c2*c2) 983 984 output.orientation = angle 985 986 If touch.size.calibration == "diameter" or "area": 987 scale = 1.0 + confidence / 16 988 output.touchMajor *= scale 989 output.touchMinor /= scale 990 output.toolMajor *= scale 991 output.toolMinor /= scale 992 End If 993 Else 994 output.orientation = 0 995 End If 996 output.tilt = 0 997Else 998 output.orientation = 0 999 output.tilt = 0 1000End If 1001 1002If orientation aware: 1003 If screen rotation is 90 degrees: 1004 output.orientation = output.orientation - PI / 2 1005 Else If screen rotation is 270 degrees: 1006 output.orientation = output.orientation + PI / 2 1007 End If 1008End If 1009</code></pre> 1010<h3 id="distance-field"><code>Distance</code> Field</h3> 1011<p>The <code>Distance</code> field describes the distance between the tool and the touch device 1012surface. A value of 0.0 indicates direct contact and larger values indicate 1013increasing distance from the surface.</p> 1014<h4 id="touchdistancecalibration"><code>touch.distance.calibration</code></h4> 1015<p><em>Definition:</em> <code>touch.distance.calibration</code> = <code>none</code> | <code>scaled</code> | <code>default</code></p> 1016<p>Specifies the kind of measurement used by the touch driver to report the distance.</p> 1017<ul> 1018<li> 1019<p>If the value is <code>none</code>, the distance is unknown so it is set to 0.</p> 1020</li> 1021<li> 1022<p>If the value is <code>scaled</code>, the reported distance is multiplied by a 1023 constant scale factor.</p> 1024</li> 1025<li> 1026<p>If the value is <code>default</code>, the system uses the <code>scaled</code> calibration if the 1027 distance axis available, otherwise uses <code>none</code>.</p> 1028</li> 1029</ul> 1030<h4 id="touchdistancescale"><code>touch.distance.scale</code></h4> 1031<p><em>Definition:</em> <code>touch.distance.scale</code> = <a non-negative floating point number></p> 1032<p>Specifies a constant scale factor used in the calibration.</p> 1033<p>The default value is <code>1.0</code>.</p> 1034<h4 id="calculation_4">Calculation</h4> 1035<p>The calculation of the <code>Distance</code> field depends on the specified calibration parameters.</p> 1036<pre><code>If touch.distance.calibration == "scaled": 1037 output.distance = raw.distance * touch.distance.scale 1038Else 1039 output.distance = 0 1040End If 1041</code></pre> 1042<h3 id="example">Example</h3> 1043<pre><code># Input device configuration file for a touch screen that supports pressure, 1044# size and orientation. The pressure and size scale factors were obtained 1045# by measuring the characteristics of the device itself and deriving 1046# useful approximations based on the resolution of the touch sensor and the 1047# display. 1048# 1049# Note that these parameters are specific to a particular device model. 1050# Different parameters will need to be used for other devices. 1051 1052# Basic Parameters 1053touch.deviceType = touchScreen 1054touch.orientationAware = 1 1055 1056# Size 1057# Based on empirical measurements, we estimate the size of the contact 1058# using size = sqrt(area) * 28 + 0. 1059touch.size.calibration = area 1060touch.size.scale = 28 1061touch.size.bias = 0 1062touch.size.isSummed = 0 1063 1064# Pressure 1065# Driver reports signal strength as pressure. 1066# 1067# A normal index finger touch typically registers about 80 signal strength 1068# units although we don't expect these values to be accurate. 1069touch.pressure.calibration = amplitude 1070touch.pressure.scale = 0.0125 1071 1072# Orientation 1073touch.orientation.calibration = vector 1074</code></pre> 1075<h3 id="compatibility-notes">Compatibility Notes</h3> 1076<p>The configuration properties for touch devices changed significantly in 1077Android Ice Cream Sandwich 4.0. <strong>All input device configuration files for touch 1078devices must be updated to use the new configuration properties.</strong></p> 1079<p>Older touch device <a href="#touch-device-driver-requirements">drivers</a> may also need to be 1080updated.</p> 1081<h2 id="virtual-key-map-files">Virtual Key Map Files</h2> 1082<p>Touch devices are often used to implement virtual keys.</p> 1083<p>There are several ways of doing this, depending on the capabilities of the 1084touch controller. Some touch controllers can be directly configured to implement 1085soft keys by setting firmware registers. Other times it is desirable to perform 1086the mapping from touch coordinates to key codes in software.</p> 1087<p>When virtual keys are implemented in software, the kernel must export a virtual key map 1088file called <code>virtualkeys.<devicename></code> as a board property. For example, 1089if the touch screen device drivers reports its name as "touchyfeely" then 1090the virtual key map file must have the path <code>/sys/board_properties/virtualkeys.touchyfeely</code>.</p> 1091<p>A virtual key map file describes the coordinates and Linux key codes of virtual keys 1092on the touch screen.</p> 1093<p>In addition to the virtual key map file, there must be a corresponding key layout 1094file and key character map file to map the Linux key codes to Android key codes and 1095to specify the type of the keyboard device (usually <code>SPECIAL_FUNCTION</code>).</p> 1096<h3 id="syntax">Syntax</h3> 1097<p>A virtual key map file is a plain text file consisting of a sequence of virtual key 1098layout descriptions either separated by newlines or by colons.</p> 1099<p>Comment lines begin with '#' and continue to the end of the line.</p> 1100<p>Each virtual key is described by 6 colon-delimited components:</p> 1101<ul> 1102<li><code>0x01</code>: A version code. Must always be <code>0x01</code>.</li> 1103<li><Linux key code>: The Linux key code of the virtual key.</li> 1104<li><centerX>: The X pixel coordinate of the center of the virtual key.</li> 1105<li><centerY>: The Y pixel coordinate of the center of the virtual key.</li> 1106<li><width>: The width of the virtual key in pixels.</li> 1107<li><height>: The height of the virtual key in pixels.</li> 1108</ul> 1109<p>All coordinates and sizes are specified in terms of the display coordinate system.</p> 1110<p>Here is a virtual key map file all written on one line.</p> 1111<pre><code># All on one line 11120x01:158:55:835:90:55:0x01:139:172:835:125:55:0x01:102:298:835:115:55:0x01:217:412:835:95:55 1113</code></pre> 1114<p>The same virtual key map file can also be written on multiple lines.</p> 1115<pre><code># One key per line 11160x01:158:55:835:90:55 11170x01:139:172:835:125:55 11180x01:102:298:835:115:55 11190x01:217:412:835:95:55 1120</code></pre> 1121<p>In the above example, the touch screen has a resolution of 480x800. Accordingly, all of 1122the virtual keys have a <centerY> coordinate of 835, which is a little bit below 1123the visible area of the touch screen.</p> 1124<p>The first key has a Linux scan code of <code>158</code> (<code>KEY_BACK</code>), centerX of <code>55</code>, 1125centerY of <code>835</code>, width of <code>90</code> and height of <code>55</code>.</p> 1126<h3 id="example_1">Example</h3> 1127<p>Virtual key map file: <code>/sys/board_properties/virtualkeys.touchyfeely</code>.</p> 1128<pre><code>0x01:158:55:835:90:55 11290x01:139:172:835:125:55 11300x01:102:298:835:115:55 11310x01:217:412:835:95:55 1132</code></pre> 1133<p>Key layout file: <code>/system/usr/keylayout/touchyfeely.kl</code>.</p> 1134<pre><code>key 158 BACK 1135key 139 MENU 1136key 102 HOME 1137key 217 SEARCH 1138</code></pre> 1139<p>Key character map file: <code>/system/usr/keychars/touchyfeely.kcm</code>.</p> 1140<pre><code>type SPECIAL_FUNCTION 1141</code></pre> 1142<h2 id="indirect-multi-touch-pointer-gestures">Indirect Multi-touch Pointer Gestures</h2> 1143<p>In pointer mode, the system interprets the following gestures:</p> 1144<ol> 1145<li> 1146<p>Single finger tap: click.</p> 1147</li> 1148<li> 1149<p>Single finger motion: move the pointer.</p> 1150</li> 1151<li> 1152<p>Single finger motion plus button presses: drag the pointer.</p> 1153</li> 1154<li> 1155<p>Two finger motion both fingers moving in the same direction: drag the area under the pointer 1156 in that direction. The pointer itself does not move.</p> 1157</li> 1158<li> 1159<p>Two finger motion both fingers moving towards each other or apart in 1160 different directions: pan/scale/rotate the area surrounding the pointer. 1161 The pointer itself does not move.</p> 1162</li> 1163<li> 1164<p>Multiple finger motion: freeform gesture.</p> 1165</li> 1166</ol> 1167<h2 id="further-reading">Further Reading</h2> 1168<ol> 1169<li><a href="http://www.kernel.org/doc/Documentation/input/multi-touch-protocol.txt">Linux multi-touch protocol</a></li> 1170<li><a href="http://lii-enac.fr/en/architecture/linux-input/multitouch-devices.html">ENAC list of available multitouch devices on Linux</a></li> 1171</ol> 1172