| 1 |
.. _tablet-support: |
| 2 |
|
| 3 |
============================================================================== |
| 4 |
Tablet support |
| 5 |
============================================================================== |
| 6 |
|
| 7 |
This page provides details about the graphics tablet |
| 8 |
support in libinput. Note that the term "tablet" in libinput refers to |
| 9 |
graphics tablets only (e.g. Wacom Intuos), not to tablet devices like the |
| 10 |
Apple iPad. |
| 11 |
|
| 12 |
.. figure:: tablet.svg |
| 13 |
:align: center |
| 14 |
|
| 15 |
Illustration of a graphics tablet |
| 16 |
|
| 17 |
.. _tablet-tools: |
| 18 |
|
| 19 |
------------------------------------------------------------------------------ |
| 20 |
Pad buttons vs. tablet tools |
| 21 |
------------------------------------------------------------------------------ |
| 22 |
|
| 23 |
Most tablets provide two types of devices. The physical tablet often |
| 24 |
provides a number of buttons and a touch ring or strip. Interaction on the |
| 25 |
drawing surface of the tablet requires a tool, usually in the shape of a |
| 26 |
stylus. The libinput interface exposed by devices with the |
| 27 |
**LIBINPUT_DEVICE_CAP_TABLET_TOOL** capability applies only to events generated |
| 28 |
by tools. |
| 29 |
|
| 30 |
Buttons, rings or strips on the physical tablet hardware (the "pad") are |
| 31 |
exposed by devices with the **LIBINPUT_DEVICE_CAP_TABLET_PAD** capability. |
| 32 |
Pad events do not require a tool to be in proximity. Note that both |
| 33 |
capabilities may exist on the same device though usually they are split |
| 34 |
across multiple kernel devices. |
| 35 |
|
| 36 |
.. figure:: tablet-interfaces.svg |
| 37 |
:align: center |
| 38 |
|
| 39 |
Difference between Pad and Tool buttons |
| 40 |
|
| 41 |
Touch events on the tablet integrated into a screen itself are exposed |
| 42 |
through the **LIBINPUT_DEVICE_CAP_TOUCH** capability. Touch events on a |
| 43 |
standalone tablet are exposed through the **LIBINPUT_DEVICE_CAP_POINTER** |
| 44 |
capability. In both cases, the kernel usually provides a separate event |
| 45 |
node for the touch device, resulting in a separate libinput device. |
| 46 |
See **libinput_device_get_device_group()** for information on how to associate |
| 47 |
the touch part with other devices exposed by the same physical hardware. |
| 48 |
|
| 49 |
.. _tablet-tip: |
| 50 |
|
| 51 |
------------------------------------------------------------------------------ |
| 52 |
Tool tip events vs. tool button events |
| 53 |
------------------------------------------------------------------------------ |
| 54 |
|
| 55 |
The primary use of a tablet tool is to draw on the surface of the tablet. |
| 56 |
When the tool tip comes into contact with the surface, libinput sends an |
| 57 |
event of type **LIBINPUT_EVENT_TABLET_TOOL_TIP**, and again when the tip |
| 58 |
ceases contact with the surface. |
| 59 |
|
| 60 |
Tablet tools may send button events; these are exclusively for extra buttons |
| 61 |
unrelated to the tip. A button event is independent of the tip and can while |
| 62 |
the tip is down or up. |
| 63 |
|
| 64 |
Some tablet tools' pressure detection is too sensitive, causing phantom |
| 65 |
touches when the user only slightly brushes the surfaces. For example, some |
| 66 |
tools are capable of detecting 1 gram of pressure. |
| 67 |
|
| 68 |
libinput uses a device-specific pressure threshold to determine when the tip |
| 69 |
is considered logically down. As a result, libinput may send a nonzero |
| 70 |
pressure value while the tip is logically up. Most application can and |
| 71 |
should ignore pressure information until they receive the event of type |
| 72 |
**LIBINPUT_EVENT_TABLET_TOOL_TIP**. Applications that require extremely |
| 73 |
fine-grained pressure sensitivity should use the pressure data instead of |
| 74 |
the tip events to determine a logical tip down state and treat the tip |
| 75 |
events like axis events otherwise. |
| 76 |
|
| 77 |
Note that the pressure threshold to trigger a logical tip event may be zero |
| 78 |
on some devices. On tools without pressure sensitivity, determining when a |
| 79 |
tip is down is device-specific. |
| 80 |
|
| 81 |
.. _tablet-relative-motion: |
| 82 |
|
| 83 |
------------------------------------------------------------------------------ |
| 84 |
Relative motion for tablet tools |
| 85 |
------------------------------------------------------------------------------ |
| 86 |
|
| 87 |
libinput calculates the relative motion vector for each event and converts |
| 88 |
it to the same coordinate space that a normal mouse device would use. For |
| 89 |
the caller, this means that the delta coordinates returned by |
| 90 |
**libinput_event_tablet_tool_get_dx()** and |
| 91 |
**libinput_event_tablet_tool_get_dy()** can be used identical to the delta |
| 92 |
coordinates from any other pointer event. Any resolution differences between |
| 93 |
the x and y axes are accommodated for, a delta of N/N represents a 45 degree |
| 94 |
diagonal move on the tablet. |
| 95 |
|
| 96 |
The delta coordinates are available for all tablet events, it is up to the |
| 97 |
caller to decide when a tool should be used in relative mode. It is |
| 98 |
recommended that mouse and lens cursor tool default to relative mode and |
| 99 |
all pen-like tools to absolute mode. |
| 100 |
|
| 101 |
If a tool in relative mode must not use pointer acceleration, callers |
| 102 |
should use the absolute coordinates returned by |
| 103 |
**libinput_event_tablet_tool_get_x()** and libinput_event_tablet_tool_get_y() |
| 104 |
and calculate the delta themselves. Callers that require exact physical |
| 105 |
distance should also use these functions to calculate delta movements. |
| 106 |
|
| 107 |
.. _tablet-axes: |
| 108 |
|
| 109 |
------------------------------------------------------------------------------ |
| 110 |
Special axes on tablet tools |
| 111 |
------------------------------------------------------------------------------ |
| 112 |
|
| 113 |
A tablet tool usually provides additional information beyond x/y positional |
| 114 |
information and the tip state. A tool may provide the distance to the tablet |
| 115 |
surface and the pressure exerted on the tip when in contact. Some tablets |
| 116 |
additionally provide tilt information along the x and y axis. |
| 117 |
|
| 118 |
.. figure:: tablet-axes.svg |
| 119 |
:align: center |
| 120 |
|
| 121 |
Illustration of the distance, pressure and tilt axes |
| 122 |
|
| 123 |
The granularity and precision of the distance and pressure axes varies |
| 124 |
between tablet devices and cannot usually be mapped into a physical unit. |
| 125 |
libinput normalizes distance and pressure into the [0, 1] range. |
| 126 |
|
| 127 |
While the normalization range is identical for these axes, a caller should |
| 128 |
not interpret identical values as identical across axes, i.e. a value v1 on |
| 129 |
the distance axis has no relation to the same value v1 on the pressure axis. |
| 130 |
|
| 131 |
The tilt axes provide the angle in degrees between a vertical line out of |
| 132 |
the tablet and the top of the stylus. The angle is measured along the x and |
| 133 |
y axis, respectively, a positive tilt angle thus means that the stylus' top |
| 134 |
is tilted towards the logical right and/or bottom of the tablet. |
| 135 |
|
| 136 |
.. _tablet-fake-proximity: |
| 137 |
|
| 138 |
------------------------------------------------------------------------------ |
| 139 |
Handling of proximity events |
| 140 |
------------------------------------------------------------------------------ |
| 141 |
|
| 142 |
libinput's **LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY** events notify a caller |
| 143 |
when a tool comes into sensor range or leaves the sensor range. On some |
| 144 |
tools this range does not represent the physical range but a reduced |
| 145 |
tool-specific logical range. If the range is reduced, this is done |
| 146 |
transparent to the caller. |
| 147 |
|
| 148 |
For example, the Wacom mouse and lens cursor tools are usually |
| 149 |
used in relative mode, lying flat on the tablet. Movement typically follows |
| 150 |
the interaction normal mouse movements have, i.e. slightly lift the tool and |
| 151 |
place it in a separate location. The proximity detection on Wacom |
| 152 |
tablets however extends further than the user may lift the mouse, i.e. the |
| 153 |
tool may not be lifted out of physical proximity. For such tools, libinput |
| 154 |
provides software-emulated proximity. |
| 155 |
|
| 156 |
Events from the pad do not require proximity, they may be sent any time. |
| 157 |
|
| 158 |
.. _tablet-pressure-offset: |
| 159 |
|
| 160 |
------------------------------------------------------------------------------ |
| 161 |
Pressure offset on worn-out tools |
| 162 |
------------------------------------------------------------------------------ |
| 163 |
|
| 164 |
When a tool is used for an extended period it can wear down physically. A |
| 165 |
worn-down tool may never return a zero pressure value. Even when hovering |
| 166 |
above the surface, the pressure value returned by the tool is nonzero, |
| 167 |
creating a fake surface touch and making interaction with the tablet less |
| 168 |
predictable. |
| 169 |
|
| 170 |
libinput automatically detects pressure offsets and rescales the remaining |
| 171 |
pressure range into the available range, making pressure-offsets transparent |
| 172 |
to the caller. A tool with a pressure offset will thus send a 0 pressure |
| 173 |
value for the detected offset and nonzero pressure values for values higher |
| 174 |
than that offset. |
| 175 |
|
| 176 |
Some limitations apply to avoid misdetection of pressure offsets, |
| 177 |
specifically: |
| 178 |
|
| 179 |
- pressure offset is only detected on proximity in, and if a device is |
| 180 |
capable of detection distances, |
| 181 |
- pressure offset is only detected if the distance between the tool and the |
| 182 |
tablet is high enough, |
| 183 |
- pressure offset is only used if it is 50% or less of the pressure range |
| 184 |
available to the tool. A pressure offset higher than 50% indicates either |
| 185 |
a misdetection or a tool that should be replaced, and |
| 186 |
- if a pressure value less than the current pressure offset is seen, the |
| 187 |
offset resets to that value. |
| 188 |
|
| 189 |
Pressure offsets are not detected on **LIBINPUT_TABLET_TOOL_TYPE_MOUSE** |
| 190 |
and **LIBINPUT_TABLET_TOOL_TYPE_LENS** tools. |
| 191 |
|
| 192 |
|
| 193 |
.. _tablet-pressure-range: |
| 194 |
|
| 195 |
------------------------------------------------------------------------------ |
| 196 |
Custom tablet tool pressure ranges |
| 197 |
------------------------------------------------------------------------------ |
| 198 |
|
| 199 |
On tablets supporting pressure, libinput provides that hardware pressure as |
| 200 |
a logical range of ``0.0`` up to ``1.0`` for the maximum supported pressure. |
| 201 |
By default, the hardware range thus maps into the following logical range:: |
| 202 |
|
| 203 |
|
| 204 |
hw minimum hw maximum |
| 205 |
hw range: |------|-----------------------------------| |
| 206 |
logical range: |----|-----------------------------------| |
| 207 |
0.0 | 1.0 |
| 208 |
Tip |
| 209 |
|
| 210 |
Note that libinput always has some built-in thresholds to filter out erroneous |
| 211 |
touches with near-zero pressure but otherwise the hardware range maps as-is |
| 212 |
into the logical range. The :ref:`tip event <tablet-tip>` threshold is defined |
| 213 |
within this range. |
| 214 |
|
| 215 |
For some use-cases the full hardware range is not suitable, it may require either |
| 216 |
too light a pressure for the user to interact or it may require too hard a |
| 217 |
pressure before the logical maximum is reached. libinput provides |
| 218 |
the **libinput_tablet_tool_config_pressure_range_set()** function that allows |
| 219 |
reducing the usable range of the tablet:: |
| 220 |
|
| 221 |
hw minimum hw maximum |
| 222 |
hw range: |----------|-------------------------------| |
| 223 |
adjusted range: |------|---------------------| |
| 224 |
logical range: |----|---------------------| |
| 225 |
0.0 | 1.0 |
| 226 |
Tip |
| 227 |
|
| 228 |
A reduced range as shown above will result in |
| 229 |
|
| 230 |
- all hw pressure below the new minimum to register as logical pressure ``0.0`` |
| 231 |
- all hw pressure above the new maximum to register as logical pressure ``1.0`` |
| 232 |
- the tip event threshold to be relative to the new minimum |
| 233 |
|
| 234 |
In other words, adjusting the pressure range of a tablet tool is equivalent to |
| 235 |
reducing the hardware range of said tool. Note that where a custom pressure |
| 236 |
range is set, detection of :ref:`tablet-pressure-offset` is disabled. |
| 237 |
|
| 238 |
.. _tablet-serial-numbers: |
| 239 |
|
| 240 |
------------------------------------------------------------------------------ |
| 241 |
Tracking unique tools |
| 242 |
------------------------------------------------------------------------------ |
| 243 |
|
| 244 |
Some tools provide hardware information that enables libinput to uniquely |
| 245 |
identify the physical device. For example, tools compatible with the Wacom |
| 246 |
Intuos 4, Intuos 5, Intuos Pro and Cintiq series are uniquely identifiable |
| 247 |
through a serial number. libinput does not specify how a tool can be |
| 248 |
identified uniquely, a caller should use **libinput_tablet_tool_is_unique()** to |
| 249 |
check if the tool is unique. |
| 250 |
|
| 251 |
libinput creates a struct libinput_tablet_tool on the first proximity in of |
| 252 |
this tool. By default, this struct is destroyed on proximity out and |
| 253 |
re-initialized on the next proximity in. If a caller keeps a reference to |
| 254 |
the tool by using **libinput_tablet_tool_ref()** libinput re-uses this struct |
| 255 |
whenever that same physical tool comes into proximity on any tablet |
| 256 |
recognized by libinput. It is possible to attach tool-specific virtual state |
| 257 |
to the tool. For example, a graphics program such as the GIMP may assign a |
| 258 |
specific color to each tool, allowing the artist to use the tools like |
| 259 |
physical pens of different color. In multi-tablet setups it is also |
| 260 |
possible to track the tool across devices. |
| 261 |
|
| 262 |
If the tool does not have a unique identifier, libinput creates a single |
| 263 |
struct libinput_tablet_tool per tool type on each tablet the tool is used |
| 264 |
on. |
| 265 |
|
| 266 |
.. _tablet-tool-types: |
| 267 |
|
| 268 |
------------------------------------------------------------------------------ |
| 269 |
Vendor-specific tablet tool types |
| 270 |
------------------------------------------------------------------------------ |
| 271 |
|
| 272 |
libinput supports a number of high-level tool types that describe the |
| 273 |
general interaction expected with the tool. For example, a user would expect |
| 274 |
a tool of type **LIBINPUT_TABLET_TOOL_TYPE_PEN** to interact with a |
| 275 |
graphics application taking pressure and tilt into account. The default |
| 276 |
virtual tool assigned should be a drawing tool, e.g. a virtual pen or brush. |
| 277 |
A tool of type **LIBINPUT_TABLET_TOOL_TYPE_ERASER** would normally be |
| 278 |
mapped to an eraser-like virtual tool. See **libinput_tablet_tool_type** |
| 279 |
for the list of all available tools. |
| 280 |
|
| 281 |
Vendors may provide more fine-grained information about the tool in use by |
| 282 |
adding a hardware-specific tool ID. libinput provides this ID to the caller |
| 283 |
with **libinput_tablet_tool_get_tool_id()** but makes no promises about the |
| 284 |
content or format of the ID. |
| 285 |
|
| 286 |
libinput currently supports Wacom-style tool IDs as provided on the Wacom |
| 287 |
Intuos 3, 4, 5, Wacon Cintiq and Wacom Intuos Pro series. The tool ID can |
| 288 |
be used to distinguish between e.g. a Wacom Classic Pen or a Wacom Pro Pen. |
| 289 |
It is the caller's responsibility to interpret the tool ID. |
| 290 |
|
| 291 |
.. _tablet-bounds: |
| 292 |
|
| 293 |
------------------------------------------------------------------------------ |
| 294 |
Out-of-bounds motion events |
| 295 |
------------------------------------------------------------------------------ |
| 296 |
|
| 297 |
Some tablets integrated into a screen (e.g. Wacom Cintiq 24HD, 27QHD and |
| 298 |
13HD series, etc.) have a sensor larger than the display area. libinput uses |
| 299 |
the range advertised by the kernel as the valid range unless device-specific |
| 300 |
quirks are present. Events outside this range will produce coordinates that |
| 301 |
may be negative or larger than the tablet's width and/or height. It is up to |
| 302 |
the caller to ignore these events. |
| 303 |
|
| 304 |
.. figure:: tablet-out-of-bounds.svg |
| 305 |
:align: center |
| 306 |
|
| 307 |
Illustration of the out-of-bounds area on a tablet |
| 308 |
|
| 309 |
In the image above, the display area is shown in black. The red area around |
| 310 |
the display illustrates the sensor area that generates input events. Events |
| 311 |
within this area will have negative coordinate or coordinates larger than |
| 312 |
the width/height of the tablet. |
| 313 |
|
| 314 |
If events outside the logical bounds of the input area are scaled into a |
| 315 |
custom range with **libinput_event_tablet_tool_get_x_transformed()** and |
| 316 |
**libinput_event_tablet_tool_get_y_transformed()** the resulting value may be |
| 317 |
less than 0 or larger than the upper range provided. It is up to the caller |
| 318 |
to test for this and handle or ignore these events accordingly. |
| 319 |
|
| 320 |
.. _tablet-pad-buttons: |
| 321 |
|
| 322 |
------------------------------------------------------------------------------ |
| 323 |
Tablet pad button numbers |
| 324 |
------------------------------------------------------------------------------ |
| 325 |
|
| 326 |
Tablet Pad buttons are numbered sequentially, starting with button 0. Thus |
| 327 |
button numbers returned by **libinput_event_tablet_pad_get_button_number()** |
| 328 |
have no semantic meaning, a notable difference to the button codes returned |
| 329 |
by other libinput interfaces (e.g. **libinput_event_tablet_tool_get_button()**). |
| 330 |
|
| 331 |
The Linux kernel requires all input events to have semantic event codes, |
| 332 |
but generic buttons like those on a pad cannot easily be assigned semantic |
| 333 |
codes. The kernel supports generic codes in the form of BTN_0 through to |
| 334 |
BTN_9 and additional unnamed space up until code 0x10f. Additional generic |
| 335 |
buttons are available as BTN_A in the range dedicated for gamepads and |
| 336 |
joysticks. Thus, tablet with a large number of buttons have to map across |
| 337 |
two semantic ranges, have to use unnamed kernel button codes or risk leaking |
| 338 |
into an unrelated range. libinput transparently maps the kernel event codes |
| 339 |
into a sequential button range on the pad. Callers should use external |
| 340 |
sources like libwacom to associate button numbers to their position on the |
| 341 |
tablet. |
| 342 |
|
| 343 |
Some buttons may have expected default behaviors. For example, on Wacom |
| 344 |
Intuos Pro series tablets, the button inside the touch ring is expected to |
| 345 |
switch between modes, see :ref:`tablet-pad-modes`. Callers should use |
| 346 |
external sources like libwacom to identify which buttons have semantic |
| 347 |
behaviors. |
| 348 |
|
| 349 |
.. _tablet-left-handed: |
| 350 |
|
| 351 |
------------------------------------------------------------------------------ |
| 352 |
Tablets in left-handed mode |
| 353 |
------------------------------------------------------------------------------ |
| 354 |
|
| 355 |
Left-handed mode on tablet devices usually means rotating the physical |
| 356 |
tablet by 180 degrees to move the tablet pad button area to right side of |
| 357 |
the tablet. When left-handed mode is enabled on a tablet device (see |
| 358 |
**libinput_device_config_left_handed_set()**) the tablet tool and tablet pad |
| 359 |
behavior changes. In left-handed mode, the tools' axes are adjusted |
| 360 |
so that the origin of each axis remains the logical north-east of |
| 361 |
the physical tablet. For example, the x and y axes are inverted and the |
| 362 |
positive x/y coordinates are down/right of the top-left corner of the tablet |
| 363 |
in its current orientation. On a tablet pad, the ring and strip are |
| 364 |
similarly adjusted. The origin of the ring and strips remain the top-most |
| 365 |
point. |
| 366 |
|
| 367 |
.. figure:: tablet-left-handed.svg |
| 368 |
:align: center |
| 369 |
|
| 370 |
Tablet axes in right- and left-handed mode |
| 371 |
|
| 372 |
Pad buttons are not affected by left-handed mode; the number of each button |
| 373 |
remains the same even when the perceived physical location of the button |
| 374 |
changes. This is a conscious design decision: |
| 375 |
|
| 376 |
- Tablet pad buttons do not have intrinsic semantic meanings. Re-ordering |
| 377 |
the button numbers would not change any functionality. |
| 378 |
- Button numbers should not be exposed directly to the user but handled in |
| 379 |
the intermediate layers. Re-ordering button numbers thus has no |
| 380 |
user-visible effect. |
| 381 |
- Re-ordering button numbers may complicate the intermediate layers. |
| 382 |
|
| 383 |
Left-handed mode is only available on some tablets, some tablets are |
| 384 |
symmetric and thus do not support left-handed mode. libinput requires |
| 385 |
libwacom to determine if a tablet is capable of being switched to |
| 386 |
left-handed mode. |
| 387 |
|
| 388 |
.. _tablet-pad-modes: |
| 389 |
|
| 390 |
------------------------------------------------------------------------------ |
| 391 |
Tablet pad modes |
| 392 |
------------------------------------------------------------------------------ |
| 393 |
|
| 394 |
Tablet pad modes are virtual groupings of button, ring and strip |
| 395 |
functionality. A caller may assign different functionalities depending on |
| 396 |
the mode the tablet is in. For example, in mode 0 the touch ring may emulate |
| 397 |
scrolling, in mode 1 the touch ring may emulate zooming, etc. libinput |
| 398 |
handles the modes and mode switching but does not assign specific |
| 399 |
functionality to buttons, rings or strips based on the mode. It is up to the |
| 400 |
caller to decide whether the mode only applies to buttons, rings and strips |
| 401 |
or only to rings and strips (this is the case with the Wacom OS X and |
| 402 |
Windows driver). |
| 403 |
|
| 404 |
The availability of modes on a touchpad usually depends on visual feedback |
| 405 |
such as LEDs around the touch ring. If no visual feedback is available, only |
| 406 |
one mode may be available. |
| 407 |
|
| 408 |
Mode switching is controlled by libinput and usually toggled by one or |
| 409 |
more buttons on the device. For example, on the Wacom Intuos 4, 5, and |
| 410 |
Pro series tablets the mode button is the button centered in the touch |
| 411 |
ring and toggles the modes sequentially. On the Wacom Cintiq 24HD the |
| 412 |
three buttons next to each touch ring allow for directly changing the |
| 413 |
mode to the desired setting. |
| 414 |
|
| 415 |
Multiple modes may exist on the tablet, libinput uses the term "mode group" |
| 416 |
for such groupings of buttons that share a mode and mode toggle. For |
| 417 |
example, the Wacom Cintiq 24HD has two separate mode groups, one for the |
| 418 |
left set of buttons, strips, and touch rings and one for the right set. |
| 419 |
libinput handles the mode groups independently and returns the mode for each |
| 420 |
button as appropriate. The mode group is static for the lifetime of the |
| 421 |
device. |
| 422 |
|
| 423 |
.. figure:: tablet-intuos-modes.svg |
| 424 |
:align: center |
| 425 |
|
| 426 |
Modes on an Intuos Pro-like tablet |
| 427 |
|
| 428 |
In the image above, the Intuos Pro-like tablet provides 4 LEDs to indicate |
| 429 |
the currently active modes. The button inside the touch ring cycles through |
| 430 |
the modes in a clockwise fashion. The upper-right LED indicates that the |
| 431 |
currently active mode is 1, based on 0-indexed mode numbering. |
| 432 |
**libinput_event_tablet_pad_get_mode()** would thus return 1 for all button and |
| 433 |
ring events on this tablet. When the center button is pressed, the mode |
| 434 |
switches to mode 2, the LED changes to the bottom-right and |
| 435 |
**libinput_event_tablet_pad_get_mode()** returns 2 for the center button event |
| 436 |
and all subsequent events. |
| 437 |
|
| 438 |
.. figure:: tablet-cintiq24hd-modes.svg |
| 439 |
:align: center |
| 440 |
|
| 441 |
Modes on an Cintiq 24HD-like tablet |
| 442 |
|
| 443 |
In the image above, the Cintiq 24HD-like tablet provides 3 LEDs on each side |
| 444 |
of the tablet to indicate the currently active mode for that group of |
| 445 |
buttons and the respective ring. The buttons next to the touch ring select |
| 446 |
the mode directly. The two LEDs indicate that the mode for the left set of |
| 447 |
buttons is currently 0, the mode for the right set of buttons is currently |
| 448 |
1, based on 0-indexed mode numbering. **libinput_event_tablet_pad_get_mode()** |
| 449 |
would thus return 0 for all button and ring events on the left and 1 for all |
| 450 |
button and ring events on the right. When one of the three mode toggle |
| 451 |
buttons on the right is pressed, the right mode switches to that button's |
| 452 |
mode but the left mode remains unchanged. |
| 453 |
|
| 454 |
.. _tablet-touch-arbitration: |
| 455 |
|
| 456 |
------------------------------------------------------------------------------ |
| 457 |
Tablet touch arbitration |
| 458 |
------------------------------------------------------------------------------ |
| 459 |
|
| 460 |
"Touch arbitration" is the terminology used when touch events are suppressed |
| 461 |
while the pen is in proximity. Since it is almost impossible to use a stylus |
| 462 |
or other tool without triggering touches with the hand holding the tool, |
| 463 |
touch arbitration serves to reduce the number of accidental inputs. |
| 464 |
The wacom kernel driver currently provides touch arbitration but for other |
| 465 |
devices arbitration has to be done in userspace. |
| 466 |
|
| 467 |
libinput uses the **libinput_device_group** to decide on touch arbitration |
| 468 |
and automatically discards touch events whenever a tool is in proximity. |
| 469 |
The exact behavior is device-dependent. |
| 470 |
|
| 471 |
.. _tablet-area: |
| 472 |
|
| 473 |
------------------------------------------------------------------------------ |
| 474 |
Tablet area |
| 475 |
------------------------------------------------------------------------------ |
| 476 |
|
| 477 |
External tablet devices such as e.g. the Wacom Intuos series can be configured |
| 478 |
to reduce the available logical input area. Typically the logical input area |
| 479 |
is equivalent to the physical input area but it can be reduced with the |
| 480 |
**libinput_device_config_area_set_rectangle()** call. Once reduced, input |
| 481 |
events outside the logical input area are ignored and the logical input area |
| 482 |
acts as if it represented the extents of the physical tablet. |
| 483 |
|
| 484 |
.. figure:: tablet-area.svg |
| 485 |
:align: center |
| 486 |
|
| 487 |
Tablet area configuration example |
| 488 |
|
| 489 |
In the image above, the area is set to the rectangle 0.25/0.25 to 0.5/0.75. |
| 490 |
Even though the tool is roughly at the physical position ``0.5 * width`` and |
| 491 |
``0.75 * height``, the return values of |
| 492 |
**libinput_event_tablet_tool_get_x_transformed()** and |
| 493 |
**libinput_event_tablet_tool_get_y_transformed()** would be close to the |
| 494 |
maximum provided in this call. |
| 495 |
|
| 496 |
The size of the tablet reported by **libinput_device_get_size()** always reflects |
| 497 |
the physical area, not the logical area. |
| 498 |
|
| 499 |
.. _tablet-eraser-button: |
| 500 |
|
| 501 |
------------------------------------------------------------------------------ |
| 502 |
Tablet eraser buttons |
| 503 |
------------------------------------------------------------------------------ |
| 504 |
|
| 505 |
Tablet tools come in a variety of forms but the most common one is a |
| 506 |
pen-like tool. Some of these pen-like tools have a virtual eraser at the |
| 507 |
tip of the tool - inverting the tool brings the eraser into proximity. |
| 508 |
|
| 509 |
.. figure:: tablet-eraser-invert.svg |
| 510 |
:align: center |
| 511 |
|
| 512 |
An pen-like tool used as pen and as eraser by inverting it |
| 513 |
|
| 514 |
Having an eraser as a separate tool is beneficial in many applications as the |
| 515 |
eraser tool can be assigned different functionality (colors, paint tools, etc.) |
| 516 |
that is easily available. |
| 517 |
|
| 518 |
However, a large proportion of tablet pens have an "eraser button". By |
| 519 |
pressing the button the pen switches to be an eraser tool. |
| 520 |
On the data level this is not done via a button event, instead the firmware |
| 521 |
will pretend the pen tool going out of proximity and the eraser coming |
| 522 |
into proximity immediately after - as if the tool was physically inverted. |
| 523 |
|
| 524 |
.. figure:: tablet-eraser-button.svg |
| 525 |
:align: center |
| 526 |
|
| 527 |
An pen-like tool used as pen and as eraser by pressing the eraser button |
| 528 |
|
| 529 |
Microsoft mandates this behavior (see |
| 530 |
`Windows Pen States <https://learn.microsoft.com/en-us/windows-hardware/design/component-guidelines/windows-pen-states>`_ |
| 531 |
for details) and thus the overwhelming majority of devices will have |
| 532 |
an eraser button that virtually inverts the pen. |
| 533 |
|
| 534 |
Enforcing an eraser button means that users have one button less on the |
| 535 |
stylus that they would have otherwise. For some users the eraser button |
| 536 |
is in an inconvenient location, others don't want an eraser button at all. |
| 537 |
|
| 538 |
libinput provides an eraser button configuration that allows disabling the |
| 539 |
eraser button and turning it into a normal button event. If the eraser button |
| 540 |
is disabled, pressing that button will generate a normal tablet tool button |
| 541 |
event. |
| 542 |
|
| 543 |
This configuration is only available on pens with an eraser button, not on |
| 544 |
with an invert-type eraser. |