Debian Codegraph @

doc/user/palm-detection.rst

raw
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.