Debian Codegraph @

doc/user/gestures.rst

raw
1 .. _gestures:
2
3 ==============================================================================
4 Gestures
5 ==============================================================================
6
7 libinput supports :ref:`gestures_pinch` and :ref:`gestures_swipe` on most
8 modern touchpads and other indirect touch devices. Note that libinput **does
9 not** support gestures on touchscreens, see :ref:`gestures_touchscreens`.
10
11 .. _gestures_lifetime:
12
13 -----------------------------------------------------------------------------
14 Lifetime of a gesture
15 -----------------------------------------------------------------------------
16
17 A gesture starts when the finger position and/or finger motion is
18 unambiguous as to what gesture to trigger and continues until the first
19 finger belonging to this gesture is lifted.
20
21 A single gesture cannot change the finger count. For example, if a user
22 puts down a fourth finger during a three-finger swipe gesture, libinput will
23 end (cancel) the three-finger gesture and, if applicable, start a
24 four-finger swipe gesture. A caller may however decide that those gestures
25 are semantically identical and continue the two gestures as one single
26 gesture.
27
28 .. _gestures_pinch:
29
30 ------------------------------------------------------------------------------
31 Pinch gestures
32 ------------------------------------------------------------------------------
33
34 Pinch gestures are executed when two or more fingers are located on the
35 touchpad and are either changing the relative distance to each other
36 (pinching) or are changing the relative angle (rotate). Pinch gestures may
37 change both rotation and distance at the same time. For such gestures,
38 libinput calculates a logical center for the gestures and provides the
39 caller with the delta x/y coordinates of that center, the relative angle of
40 the fingers compared to the previous event, and the absolute scale compared
41 to the initial finger position.
42
43 .. figure:: pinch-gestures.svg
44 :align: center
45
46 The pinch and rotate gestures
47
48 The illustration above shows a basic pinch in the left image and a rotate in
49 the right angle. Not shown is a movement of the logical center if the
50 fingers move unevenly. Such a movement is supported by libinput, it is
51 merely left out of the illustration.
52
53 Note that while position and angle is relative to the previous event, the
54 scale is always absolute and a multiplier of the initial finger position's
55 scale.
56
57 .. _gestures_swipe:
58
59 ------------------------------------------------------------------------------
60 Swipe gestures
61 ------------------------------------------------------------------------------
62
63 Swipe gestures are executed when three or more fingers are moved
64 synchronously in the same direction. libinput provides x and y coordinates
65 in the gesture and thus allows swipe gestures in any direction, including
66 the tracing of complex paths. It is up to the caller to interpret the
67 gesture into an action or limit a gesture to specific directions only.
68
69 .. figure:: swipe-gestures.svg
70 :align: center
71
72 The swipe gestures
73
74 The illustration above shows a vertical three-finger swipe. The coordinates
75 provided during the gesture are the movements of the logical center.
76
77 .. _gestures_hold:
78
79 ------------------------------------------------------------------------------
80 Hold gestures
81 ------------------------------------------------------------------------------
82
83 A hold gesture is one where the user places one or more fingers on the
84 device without significant movement. The exact conditions when a hold gesture
85 transitions to pointer motion, scrolling or other gestures
86 are implementation-defined.
87
88 The hold gesture is intended to allow for the implementation of two specific
89 features:
90
91 - where a two-finger scrolling starts kinetic scrolling in the caller, a
92 subsequent hold gesture can be used to stop that kinetic scroll motion,
93 and
94 - hold-to-trigger interactions where the interaction could be a click, a
95 context menu, or some other context-specific interaction.
96
97 Hold gestures have three potential logical states:
98
99 - **begin**: one or more fingers are placed on the device at the same time
100 - **end**: all fingers are removed and the device enters a neutral logical state
101 - **end(cancelled)**: all fingers are part of a known interaction and the
102 currenthold gesture is no longer active. This may also occurs when
103 switching between hold gestures with different finger counts.
104
105 .. note:: By definition, a hold gesture does not move and thus no coordinate
106 updates are available.
107
108 For example, a user that puts one finger, then a second finger down and
109 releases them later may trigger the following event sequence:
110
111 ============= ============ ============
112 Action Event Finger count
113 ============= ============ ============
114 Finger 1 down <no event>
115 Finger 2 down **begin** 2
116 Finger 2 up **end** 2
117 Finger 1 up <no event>
118 ============= ============ ============
119
120 A hold gesture may by be **cancelled**. This occurs
121 when the hold gesture changes into some other interaction and should no
122 longer be considered the current hold gesture. A **end(cancelled)** event
123 applies to the whole gesture (all fingers). For example, a pointer motion on
124 a touchpad may trigger this sequence:
125
126 +-------------------+-----------------------+
127 | Action | Event |
128 +===================+=======================+
129 | | Finger 1 down | | **hold begin** |
130 +-------------------+-----------------------+
131 | | Finger 1 motion | | **hold cancel** |
132 | | | | **pointer motion** |
133 +-------------------+-----------------------+
134 | | Finger 1 motion | | **pointer motion** |
135 +-------------------+-----------------------+
136 | | Finger 1 up | | *no event* |
137 +-------------------+-----------------------+
138
139 .. note:: Many interactions with a touchpad will start with a hold
140 gesture that is then cancelled as that gesture turns into e.g.
141 pointer motion. A caller **must** handle hold gesture
142 cancellations correctly.
143
144 A two-finger scroll motion on a touchpad may trigger this sequence:
145
146 +------------------------+---------------------+--------------+
147 | Action | Event | Finger count |
148 +========================+=====================+==============+
149 | | Finger 1 down | | **hold begin** | | 1 |
150 +------------------------+---------------------+--------------+
151 | | Finger 2 down | | **hold cancel** | | 1 |
152 | | | | **hold begin** | | 2 |
153 +------------------------+---------------------+--------------+
154 | | Finger 1+2 motion | | **hold cancel** | | 2 |
155 | | | | **pointer axis** | | |
156 +------------------------+---------------------+--------------+
157 | | Finger 1+2 motion | | **pointer axis** | |
158 +------------------------+---------------------+--------------+
159 | | Finger 1 up | | **pointer axis** | |
160 | | Finger 2 up | | (scroll stop) | |
161 +------------------------+---------------------+--------------+
162
163 A three-finger-swipe on a touchpad may trigger this sequence:
164
165 +---------------------+---------------------+--------------+
166 | Action | Event | Finger count |
167 +=====================+=====================+==============+
168 | | Finger 1 down | | **hold begin** | | 1 |
169 +---------------------+---------------------+--------------+
170 | | Finger 2 down | | **hold cancel** | | 1 |
171 | | | | **hold begin** | | 2 |
172 +---------------------+---------------------+--------------+
173 | | Finger 3 down | | **hold cancel** | | 2 |
174 | | | | **hold begin** | | 3 |
175 +---------------------+---------------------+--------------+
176 | | Finger motion | | **hold cancel** | | 3 |
177 | | | | **swipe begin** | | 3 |
178 +---------------------+---------------------+--------------+
179 | | Finger motion | | **swipe update** | | 3 |
180 +---------------------+---------------------+--------------+
181 | | Finger 1 up | | **swipe end** | | 3 |
182 | | Finger 2 up | | | | |
183 | | Finger 3 up | | | | |
184 +---------------------+---------------------+--------------+
185
186 Single-finger hold gestures
187 ...........................
188
189 libinput uses implementation-defined timeouts based on other interactions
190 to determine whether a single-finger hold gestures should start. In other
191 words, a caller **must not** rely on a hold gesture always being triggered
192 as soon as a single finger is placed on the touchpad. This is true for any
193 hold gesture but especially so for single-finger hold gestures.
194
195 Hold gestures with a single finger are prone to being extremely short-lived.
196 On many devices it is impossible to hold a finger still enough for there to
197 be no pointer motion events, even if those deltas are miniscule. Changing
198 movement thresholds to rely on hold gestures would reduce device
199 responsiveness.
200
201 It is thus the responsibility of the caller to determine where hold gestures
202 transition in and out of other interactions. For example, a two-finger hold
203 may produce a cancelled single-finger hold gesture first:
204
205 +--------------------+----------------------+--------------+--------------+
206 | Action | Event | Finger count | Notes |
207 +====================+======================+==============+==============+
208 | | Finger 1 down | | **hold begin** | | 1 | |
209 +--------------------+----------------------+--------------+--------------+
210 | | Finger 1 motion | | **hold cancel** | | 1 | | tiny deltas|
211 | | | | **pointer motion** | | | | |
212 +--------------------+----------------------+--------------+--------------+
213 | | Finger 2 down | | **hold begin** | | 2 | |
214 +--------------------+----------------------+--------------+--------------+
215 | | Finger 1 up | | **hold end** | | | |
216 | | Finger 2 up | | | | | |
217 +--------------------+----------------------+--------------+--------------+
218
219 Note how the second hold gesture started with a finger count of 2 - without
220 the user ever lifting the first finger. Cancellation of hold gesture does
221 not imply the user has lifted a finger.
222
223 A hold gesture may start after a previous gesture completed. For example, a
224 single finger move-and-hold may trigger different sequences for the same
225 user interaction:
226
227 +--------------------+---------------------+-------------------+--------------+
228 | Action | Device 1 | Device 2 | Notes |
229 +====================+=====================+===================+==============+
230 | | Finger 1 down | | **hold begin** | | **hold begin** | |
231 +--------------------+---------------------+-------------------+--------------+
232 | | Finger 1 motion | | **hold cancel** | | | tiny deltas|
233 | | | **pointer motion**| | | |
234 +--------------------+---------------------+-------------------+--------------+
235 | | | **hold begin** | | |
236 +--------------------+---------------------+-------------------+--------------+
237 | | Finger 1 up | | **hold end** | | **hold end** | |
238 +--------------------+---------------------+-------------------+--------------+
239
240 A caller that wants to use hold gestures must thus be able to infer the same
241 interaction based on a stream of pointer motion events with small deltas.
242
243 libinput may start a new hold begin gesture once the pointer stops moving.
244 The time between the last pointer motion event and the hold begin event is
245 implementation-defined.
246
247
248 Hold gestures and thumb/palm detection
249 ......................................
250
251 Thumb and palm detection effectively remove touches from being counted
252 towards an interaction, see :ref:`thumb_detection` and
253 :ref:`palm_detection` for details.
254
255 In the context of hold gestures, thumbs and palms are treated by libinput as
256 if the finger was removed from the device. Where other non-thumb/non-palm
257 fingers remain on the device, an **hold update** event is sent. Otherwise,
258 the hold gesture terminates with a **hold cancel** event.
259
260 Notably, libinput's thumb and palm detection is not a simple boolean per
261 touch but specific to the state of that touch in the overall context. For
262 example, a touch may be a thumb for tapping but not for clickfinger
263 interactions. A caller must not infer the number of physical fingers from
264 the hold gesture.
265
266 Likewise, libinput may classify a finger as thumb in the same hardware event
267 as a new finger is placed on the touchpad. In that case, the hold gesture
268 **may** continue as one-finger gesture despite there being two physical
269 touch points.
270
271 Information to determine whether a touch is a thumb or a palm may not be
272 available until some time into an interaction. Thus very short brushes
273 of the touchpad by a palm may trigger a **hold begin** followed by an
274 immediate **hold end** as libinput lacks sufficient information to identify
275 the touch as thumb/palm and send the corresponding **hold cancel**
276 event. A caller must not assume that a hold gesture always represents a
277 valid finger down.
278
279 Hold gestures and tap-to-click
280 ..............................
281
282 :ref:`tapping` is the feature that enables short-lived touches to trigger
283 button presses.
284
285 .. warning:: Summary: do not use hold gestures to do your own tap-to-click
286 implementation
287
288 In the context of hold gestures, tap-to-click cancels current hold gestures
289 and a finger dragging (see :ref:`tapndrag`) does not begin a hold
290 gesture. Where tap-to-click is disabled a tap-like gesture may create
291 **hold begin** followed by a **hold end** event. Callers **must not** use
292 hold gestures for their own tap-to-click implementation as the data is not
293 reliable enough. libinput may change internal timeouts and thresholds
294 depending on whether tap-to-click is enabled and the hold gesture event may
295 not match touch sequences that a user would expect to be a tap-to-click
296 interaction.
297
298 .. _gestures_touchscreens:
299
300 ------------------------------------------------------------------------------
301 Touchscreen gestures
302 ------------------------------------------------------------------------------
303
304 Touchscreen gestures are **not** interpreted by libinput. Rather, any touch
305 point is passed to the caller and any interpretation of gestures is up to
306 the caller or, eventually, the X or Wayland client.
307
308 Interpreting gestures on a touchscreen requires context that libinput does
309 not have, such as the location of windows and other virtual objects on the
310 screen as well as the context of those virtual objects:
311
312 .. figure:: touchscreen-gestures.svg
313 :align: center
314
315 Context-sensitivity of touchscreen gestures
316
317 In the above example, the finger movements are identical but in the left
318 case both fingers are located within the same window, thus suggesting an
319 attempt to zoom. In the right case both fingers are located on a window
320 border, thus suggesting a window movement. libinput has no knowledge of the
321 window coordinates and thus cannot differentiate the two.
322
323 .. _gestures_softbuttons:
324
325 ------------------------------------------------------------------------------
326 Gestures with enabled software buttons
327 ------------------------------------------------------------------------------
328
329 If the touchpad device is a :ref:`Clickpad <touchpads_buttons_clickpads>`, it
330 is recommended that a caller switches to :ref:`clickfinger`.
331 Usually fingers placed in a :ref:`software button area <software_buttons>`
332 are not considered for gestures, resulting in some gestures to be
333 interpreted as pointer motion or two-finger scroll events.
334
335 .. figure:: pinch-gestures-softbuttons.svg
336 :align: center
337
338 Interference of software buttons and pinch gestures
339
340 In the example above, the software button area is highlighted in red. The
341 user executes a three-finger pinch gesture, with the thumb remaining in the
342 software button area. libinput ignores fingers within the software button
343 areas, the movement of the remaining fingers is thus interpreted as a
344 two-finger scroll motion.
345
346 .. _gestures_twofinger_touchpads:
347
348 ------------------------------------------------------------------------------
349 Gestures on two-finger touchpads
350 ------------------------------------------------------------------------------
351
352 As of kernel 4.2, many :ref:`touchpads_touch_partial_mt` provide only two
353 slots. This affects how gestures can be interpreted. Touchpads with only two
354 slots can identify two touches by position but can usually tell that there
355 is a third (or fourth) finger down on the touchpad - without providing
356 positional information for that finger.
357
358 Touchpoints are assigned in sequential order and only the first two touch
359 points are trackable. For libinput this produces an ambiguity where it is
360 impossible to detect whether a gesture is a pinch gesture or a swipe gesture
361 whenever a user puts the index and middle finger down first. Since the third
362 finger does not have positional information, it's location cannot be
363 determined.
364
365 .. figure:: gesture-2fg-ambiguity.svg
366 :align: center
367
368 Ambiguity of three-finger gestures on two-finger touchpads
369
370 The image above illustrates this ambiguity. The index and middle finger are
371 set down first, the data stream from both finger positions looks identical.
372 In this case, libinput assumes the fingers are in a horizontal arrangement
373 (the right image above) and use a swipe gesture.