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