| 1 |
.. _palm_detection: |
| 2 |
|
| 3 |
============================================================================== |
| 4 |
Palm detection |
| 5 |
============================================================================== |
| 6 |
|
| 7 |
Palm detection tries to identify accidental touches while typing, while |
| 8 |
using the trackpoint and/or during general use of the touchpad area. |
| 9 |
|
| 10 |
On most laptops typing on the keyboard generates accidental touches on the |
| 11 |
touchpad with the palm (usually the area below the thumb). This can lead to |
| 12 |
cursor jumps or accidental clicks. On large touchpads, the palm may also |
| 13 |
touch the bottom edges of the touchpad during normal interaction. |
| 14 |
|
| 15 |
Interference from a palm depends on the size of the touchpad and the position |
| 16 |
of the user's hand. Data from touchpads showed that almost all palm events |
| 17 |
during tying on a Lenovo T440 happened in the left-most and right-most 5% of |
| 18 |
the touchpad. The T440 series has one of the largest touchpads, other |
| 19 |
touchpads are less affected by palm touches. |
| 20 |
|
| 21 |
libinput has multiple ways of detecting a palm, each of which depends on |
| 22 |
hardware-specific capabilities. |
| 23 |
|
| 24 |
- :ref:`palm_tool` |
| 25 |
- :ref:`palm_pressure` |
| 26 |
- :ref:`palm_touch_size` |
| 27 |
- :ref:`palm_exclusion_zones` |
| 28 |
- :ref:`trackpoint-disabling` |
| 29 |
- :ref:`disable-while-typing` |
| 30 |
- :ref:`disable-while-trackpointing` |
| 31 |
- :ref:`stylus-touch-arbitration` |
| 32 |
|
| 33 |
Palm detection is always enabled, with the exception of |
| 34 |
disable-while-typing. |
| 35 |
|
| 36 |
.. _palm_tool: |
| 37 |
|
| 38 |
------------------------------------------------------------------------------ |
| 39 |
Palm detection based on firmware labelling |
| 40 |
------------------------------------------------------------------------------ |
| 41 |
|
| 42 |
Some devices provide palm detection in the firmware, forwarded by the kernel |
| 43 |
as the ``EV_ABS/ABS_MT_TOOL`` axis with a value of ``MT_TOOL_PALM`` |
| 44 |
(whenever a palm is detected). libinput honors that value and switches that |
| 45 |
touch to a palm. |
| 46 |
|
| 47 |
.. _palm_pressure: |
| 48 |
|
| 49 |
------------------------------------------------------------------------------ |
| 50 |
Palm detection based on pressure |
| 51 |
------------------------------------------------------------------------------ |
| 52 |
|
| 53 |
The simplest form of palm detection labels a touch as palm when the pressure |
| 54 |
value goes above a certain threshold. This threshold is usually high enough |
| 55 |
that it cannot be triggered by a finger movement. One a touch is labelled as |
| 56 |
palm based on pressure, it will remain so even if the pressure drops below |
| 57 |
the threshold again. This ensures that a palm remains a palm even when the |
| 58 |
pressure changes as the user is typing. |
| 59 |
|
| 60 |
For some information on how to detect pressure on a touch and debug the |
| 61 |
pressure ranges, see :ref:`touchpad_pressure`. |
| 62 |
|
| 63 |
.. _palm_touch_size: |
| 64 |
|
| 65 |
------------------------------------------------------------------------------ |
| 66 |
Palm detection based on touch size |
| 67 |
------------------------------------------------------------------------------ |
| 68 |
|
| 69 |
On touchpads that support the ``ABS_MT_TOUCH_MAJOR`` axes, libinput can perform |
| 70 |
palm detection based on the size of the touch ellipse. This works similar to |
| 71 |
the pressure-based palm detection in that a touch is labelled as palm when |
| 72 |
it exceeds the (device-specific) touch size threshold. |
| 73 |
|
| 74 |
For some information on how to detect the size of a touch and debug the |
| 75 |
touch size ranges, see :ref:`touchpad_pressure`. |
| 76 |
|
| 77 |
.. _palm_exclusion_zones: |
| 78 |
|
| 79 |
------------------------------------------------------------------------------ |
| 80 |
Palm exclusion zones |
| 81 |
------------------------------------------------------------------------------ |
| 82 |
|
| 83 |
libinput enables palm detection on the left, right and top edges of the |
| 84 |
touchpad. Two exclusion zones are defined on the left and right edge of the |
| 85 |
touchpad. If a touch starts in the exclusion zone, it is considered a palm |
| 86 |
and the touch point is ignored. However, for fast cursor movements across |
| 87 |
the screen, it is common for a finger to start inside an exclusion zone and |
| 88 |
move rapidly across the touchpad. libinput detects such movements and avoids |
| 89 |
palm detection on such touch sequences. |
| 90 |
|
| 91 |
Another exclusion zone is defined on the top edge of the touchpad. As with |
| 92 |
the edge zones, libinput detects vertical movements out of the edge zone and |
| 93 |
avoids palm detection on such touch sequences. |
| 94 |
|
| 95 |
A touch starting in the exclusion zone does not trigger a tap (see |
| 96 |
:ref:`tapping`). |
| 97 |
|
| 98 |
In the diagram below, the exclusion zones are painted red. |
| 99 |
Touch 'A' starts inside the exclusion zone and moves |
| 100 |
almost vertically. It is considered a palm and ignored for cursor movement, |
| 101 |
despite moving out of the exclusion zone. |
| 102 |
|
| 103 |
Touch 'B' starts inside the exclusion zone but moves horizontally out of the |
| 104 |
zone. It is considered a valid touch and controls the cursor. |
| 105 |
|
| 106 |
Touch 'C' occurs in the exclusion zone. Despite being a tapping motion, it does |
| 107 |
not generate an emulated button event. |
| 108 |
|
| 109 |
.. figure:: palm-detection.svg |
| 110 |
:align: center |
| 111 |
|
| 112 |
.. _trackpoint-disabling: |
| 113 |
|
| 114 |
------------------------------------------------------------------------------ |
| 115 |
Palm detection during trackpoint use |
| 116 |
------------------------------------------------------------------------------ |
| 117 |
|
| 118 |
If a device provides a |
| 119 |
`trackpoint <http://en.wikipedia.org/wiki/Pointing_stick>`_, it is |
| 120 |
usually located above the touchpad. This increases the likelihood of |
| 121 |
accidental touches whenever the trackpoint is used. |
| 122 |
|
| 123 |
libinput disables the touchpad whenever it detects trackpoint activity for a |
| 124 |
certain timeout until after trackpoint activity stops. Touches generated |
| 125 |
during this timeout will not move the pointer, and touches started during |
| 126 |
this timeout will likewise not move the pointer (allowing for a user to rest |
| 127 |
the palm on the touchpad while using the trackstick). |
| 128 |
If the touchpad is disabled, the :ref:`top software buttons <t440_support>` |
| 129 |
remain enabled. |
| 130 |
|
| 131 |
.. _disable-while-typing: |
| 132 |
|
| 133 |
------------------------------------------------------------------------------ |
| 134 |
Disable-while-typing |
| 135 |
------------------------------------------------------------------------------ |
| 136 |
|
| 137 |
libinput automatically disables the touchpad for a timeout after a key |
| 138 |
press, a feature traditionally referred to as "disable while typing" and |
| 139 |
previously available through the |
| 140 |
`syndaemon(1) <http://linux.die.net/man/1/syndaemon>`_ command. libinput does |
| 141 |
not require an external command and the feature is currently enabled for all |
| 142 |
touchpads but will be reduced in the future to only apply to touchpads where |
| 143 |
finger width or pressure data is unreliable. |
| 144 |
|
| 145 |
Notable behaviors of libinput's disable-while-typing feature: |
| 146 |
|
| 147 |
- Two different timeouts are used, after a single key press the timeout is |
| 148 |
short to ensure responsiveness. After multiple key events, the timeout is |
| 149 |
longer to avoid accidental pointer manipulation while typing. |
| 150 |
- Some keys do not trigger the timeout, specifically some modifier keys |
| 151 |
(Ctrl, Alt, Shift, and Fn). Actions such as Ctrl + click thus stay |
| 152 |
responsive. |
| 153 |
- Touches started while typing do not control the cursor even after typing |
| 154 |
has stopped, it is thus possible to rest the palm on the touchpad while |
| 155 |
typing. |
| 156 |
- Physical buttons work even while the touchpad is disabled. This includes |
| 157 |
:ref:`software-emulated buttons <t440_support>`. |
| 158 |
- libinput pairs touchpads and keyboards for the disable-while-typing |
| 159 |
feature. In the most common case, the internal touchpad is paired only |
| 160 |
with the internal keyboard. Typing on an external keyboard will thus not |
| 161 |
disable the touchpad. Some devices require a :ref:`quirk <device-quirks>` |
| 162 |
to be correctly paired. |
| 163 |
|
| 164 |
Disable-while-typing can be enabled and disabled by calling |
| 165 |
**libinput_device_config_dwt_set_enabled()**. |
| 166 |
|
| 167 |
.. _disable-while-trackpointing: |
| 168 |
|
| 169 |
------------------------------------------------------------------------------ |
| 170 |
Disable-while-trackpointing |
| 171 |
------------------------------------------------------------------------------ |
| 172 |
|
| 173 |
libinput automatically disables the touchpad for a timeout after the trackpoint |
| 174 |
is moved, a feature referred to as "disable while trackpointing". libinput does |
| 175 |
not require an external command and the feature is currently enabled for all |
| 176 |
touchpads. |
| 177 |
|
| 178 |
Disable-while-trackpointing can be enabled and disabled by calling |
| 179 |
**libinput_device_config_dwtp_set_enabled()**. |
| 180 |
|
| 181 |
.. _stylus-touch-arbitration: |
| 182 |
|
| 183 |
------------------------------------------------------------------------------ |
| 184 |
Stylus-touch arbitration |
| 185 |
------------------------------------------------------------------------------ |
| 186 |
|
| 187 |
A special case of palm detection is touch arbitration on devices that |
| 188 |
support styli. When interacting with a stylus on the screen, parts of the |
| 189 |
hand may touch the surface and trigger touches. As the user is currently |
| 190 |
interacting with the stylus, these touches would interfer with the correct |
| 191 |
working of the stylus. |
| 192 |
|
| 193 |
libinput employs a method similar to :ref:`disable-while-typing` to detect |
| 194 |
these touches and disables the touchpad accordingly. |
| 195 |
|
| 196 |
.. _thumb-detection: |
| 197 |
|
| 198 |
------------------------------------------------------------------------------ |
| 199 |
Thumb detection |
| 200 |
------------------------------------------------------------------------------ |
| 201 |
|
| 202 |
Many users rest their thumb on the touchpad while using the index finger to |
| 203 |
move the finger around. For clicks, often the thumb is used rather than the |
| 204 |
finger. The thumb should otherwise be ignored as a touch, i.e. it should not |
| 205 |
count towards :ref:`clickfinger` and it should not cause a single-finger |
| 206 |
movement to trigger :ref:`twofinger_scrolling`. |
| 207 |
|
| 208 |
libinput uses two triggers for thumb detection: pressure and |
| 209 |
location. A touch exceeding a pressure threshold is considered a thumb if it |
| 210 |
is within the thumb detection zone. |
| 211 |
|
| 212 |
.. note:: "Pressure" on touchpads is synonymous with "contact area." A large touch |
| 213 |
surface area has a higher pressure and thus hints at a thumb or palm |
| 214 |
touching the surface. |
| 215 |
|
| 216 |
Pressure readings are unreliable at the far bottom of the touchpad as a |
| 217 |
thumb hanging mostly off the touchpad will have a small surface area. |
| 218 |
libinput has a definitive thumb zone where any touch is considered a resting |
| 219 |
thumb. |
| 220 |
|
| 221 |
.. figure:: thumb-detection.svg |
| 222 |
:align: center |
| 223 |
|
| 224 |
The picture above shows the two detection areas. In the larger (light red) |
| 225 |
area, a touch is labelled as thumb when it exceeds a device-specific |
| 226 |
pressure threshold. In the lower (dark red) area, a touch is labelled as |
| 227 |
thumb if it remains in that area for a time without moving outside. |