1.. _gestures: 2 3============================================================================== 4Gestures 5============================================================================== 6 7libinput supports :ref:`gestures_pinch` and :ref:`gestures_swipe` on most 8modern touchpads and other indirect touch devices. Note that libinput **does 9not** support gestures on touchscreens, see :ref:`gestures_touchscreens`. 10 11.. _gestures_lifetime: 12 13----------------------------------------------------------------------------- 14Lifetime of a gesture 15----------------------------------------------------------------------------- 16 17A gesture starts when the finger position and/or finger motion is 18unambiguous as to what gesture to trigger and continues until the first 19finger belonging to this gesture is lifted. 20 21A single gesture cannot change the finger count. For example, if a user 22puts down a fourth finger during a three-finger swipe gesture, libinput will 23end (cancel) the three-finger gesture and, if applicable, start a 24four-finger swipe gesture. A caller may however decide that those gestures 25are semantically identical and continue the two gestures as one single 26gesture. 27 28.. _gestures_pinch: 29 30------------------------------------------------------------------------------ 31Pinch gestures 32------------------------------------------------------------------------------ 33 34Pinch gestures are executed when two or more fingers are located on the 35touchpad and are either changing the relative distance to each other 36(pinching) or are changing the relative angle (rotate). Pinch gestures may 37change both rotation and distance at the same time. For such gestures, 38libinput calculates a logical center for the gestures and provides the 39caller with the delta x/y coordinates of that center, the relative angle of 40the fingers compared to the previous event, and the absolute scale compared 41to the initial finger position. 42 43.. figure:: pinch-gestures.svg 44 :align: center 45 46 The pinch and rotate gestures 47 48The illustration above shows a basic pinch in the left image and a rotate in 49the right angle. Not shown is a movement of the logical center if the 50fingers move unevenly. Such a movement is supported by libinput, it is 51merely left out of the illustration. 52 53Note that while position and angle is relative to the previous event, the 54scale is always absolute and a multiplier of the initial finger position's 55scale. 56 57.. _gestures_swipe: 58 59------------------------------------------------------------------------------ 60Swipe gestures 61------------------------------------------------------------------------------ 62 63Swipe gestures are executed when three or more fingers are moved 64synchronously in the same direction. libinput provides x and y coordinates 65in the gesture and thus allows swipe gestures in any direction, including 66the tracing of complex paths. It is up to the caller to interpret the 67gesture 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 74The illustration above shows a vertical three-finger swipe. The coordinates 75provided during the gesture are the movements of the logical center. 76 77.. _gestures_hold: 78 79------------------------------------------------------------------------------ 80Hold gestures 81------------------------------------------------------------------------------ 82 83A hold gesture is one where the user places one or more fingers on the 84device without significant movement. The exact conditions when a hold gesture 85transitions to pointer motion, scrolling or other gestures 86are implementation-defined. 87 88The hold gesture is intended to allow for the implementation of two specific 89features: 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 97Hold 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 108For example, a user that puts one finger, then a second finger down and 109releases them later may trigger the following event sequence: 110 111============= ============ ============ 112Action Event Finger count 113============= ============ ============ 114Finger 1 down <no event> 115Finger 2 down **begin** 2 116Finger 2 up **end** 2 117Finger 1 up <no event> 118============= ============ ============ 119 120A hold gesture may by be **cancelled**. This occurs 121when the hold gesture changes into some other interaction and should no 122longer be considered the current hold gesture. A **end(cancelled)** event 123applies to the whole gesture (all fingers). For example, a pointer motion on 124a 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 144A 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 163A 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 186Single-finger hold gestures 187........................... 188 189libinput uses implementation-defined timeouts based on other interactions 190to determine whether a single-finger hold gestures should start. In other 191words, a caller **must not** rely on a hold gesture always being triggered 192as soon as a single finger is placed on the touchpad. This is true for any 193hold gesture but especially so for single-finger hold gestures. 194 195Hold gestures with a single finger are prone to being extremely short-lived. 196On many devices it is impossible to hold a finger still enough for there to 197be no pointer motion events, even if those deltas are miniscule. Changing 198movement thresholds to rely on hold gestures would reduce device 199responsiveness. 200 201It is thus the responsibility of the caller to determine where hold gestures 202transition in and out of other interactions. For example, a two-finger hold 203may 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 219Note how the second hold gesture started with a finger count of 2 - without 220the user ever lifting the first finger. Cancellation of hold gesture does 221not imply the user has lifted a finger. 222 223A hold gesture may start after a previous gesture completed. For example, a 224single finger move-and-hold may trigger different sequences for the same 225user 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 240A caller that wants to use hold gestures must thus be able to infer the same 241interaction based on a stream of pointer motion events with small deltas. 242 243libinput may start a new hold begin gesture once the pointer stops moving. 244The time between the last pointer motion event and the hold begin event is 245implementation-defined. 246 247 248Hold gestures and thumb/palm detection 249...................................... 250 251Thumb and palm detection effectively remove touches from being counted 252towards an interaction, see :ref:`thumb_detection` and 253:ref:`palm_detection` for details. 254 255In the context of hold gestures, thumbs and palms are treated by libinput as 256if the finger was removed from the device. Where other non-thumb/non-palm 257fingers remain on the device, an **hold update** event is sent. Otherwise, 258the hold gesture terminates with a **hold cancel** event. 259 260Notably, libinput's thumb and palm detection is not a simple boolean per 261touch but specific to the state of that touch in the overall context. For 262example, a touch may be a thumb for tapping but not for clickfinger 263interactions. A caller must not infer the number of physical fingers from 264the hold gesture. 265 266Likewise, libinput may classify a finger as thumb in the same hardware event 267as 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 269touch points. 270 271Information to determine whether a touch is a thumb or a palm may not be 272available until some time into an interaction. Thus very short brushes 273of the touchpad by a palm may trigger a **hold begin** followed by an 274immediate **hold end** as libinput lacks sufficient information to identify 275the touch as thumb/palm and send the corresponding **hold cancel** 276event. A caller must not assume that a hold gesture always represents a 277valid finger down. 278 279Hold gestures and tap-to-click 280.............................. 281 282:ref:`tapping` is the feature that enables short-lived touches to trigger 283button presses. 284 285.. warning:: Summary: do not use hold gestures to do your own tap-to-click 286 implementation 287 288In the context of hold gestures, tap-to-click cancels current hold gestures 289and a finger dragging (see :ref:`tapndrag`) does not begin a hold 290gesture. 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 292hold gestures for their own tap-to-click implementation as the data is not 293reliable enough. libinput may change internal timeouts and thresholds 294depending on whether tap-to-click is enabled and the hold gesture event may 295not match touch sequences that a user would expect to be a tap-to-click 296interaction. 297 298.. _gestures_touchscreens: 299 300------------------------------------------------------------------------------ 301Touchscreen gestures 302------------------------------------------------------------------------------ 303 304Touchscreen gestures are **not** interpreted by libinput. Rather, any touch 305point is passed to the caller and any interpretation of gestures is up to 306the caller or, eventually, the X or Wayland client. 307 308Interpreting gestures on a touchscreen requires context that libinput does 309not have, such as the location of windows and other virtual objects on the 310screen 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 317In the above example, the finger movements are identical but in the left 318case both fingers are located within the same window, thus suggesting an 319attempt to zoom. In the right case both fingers are located on a window 320border, thus suggesting a window movement. libinput has no knowledge of the 321window coordinates and thus cannot differentiate the two. 322 323.. _gestures_softbuttons: 324 325------------------------------------------------------------------------------ 326Gestures with enabled software buttons 327------------------------------------------------------------------------------ 328 329If the touchpad device is a :ref:`Clickpad <touchpads_buttons_clickpads>`, it 330is recommended that a caller switches to :ref:`clickfinger`. 331Usually fingers placed in a :ref:`software button area <software_buttons>` 332are not considered for gestures, resulting in some gestures to be 333interpreted 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 340In the example above, the software button area is highlighted in red. The 341user executes a three-finger pinch gesture, with the thumb remaining in the 342software button area. libinput ignores fingers within the software button 343areas, the movement of the remaining fingers is thus interpreted as a 344two-finger scroll motion. 345 346.. _gestures_twofinger_touchpads: 347 348------------------------------------------------------------------------------ 349Gestures on two-finger touchpads 350------------------------------------------------------------------------------ 351 352As of kernel 4.2, many :ref:`touchpads_touch_partial_mt` provide only two 353slots. This affects how gestures can be interpreted. Touchpads with only two 354slots can identify two touches by position but can usually tell that there 355is a third (or fourth) finger down on the touchpad - without providing 356positional information for that finger. 357 358Touchpoints are assigned in sequential order and only the first two touch 359points are trackable. For libinput this produces an ambiguity where it is 360impossible to detect whether a gesture is a pinch gesture or a swipe gesture 361whenever a user puts the index and middle finger down first. Since the third 362finger does not have positional information, it's location cannot be 363determined. 364 365.. figure:: gesture-2fg-ambiguity.svg 366 :align: center 367 368 Ambiguity of three-finger gestures on two-finger touchpads 369 370The image above illustrates this ambiguity. The index and middle finger are 371set down first, the data stream from both finger positions looks identical. 372In this case, libinput assumes the fingers are in a horizontal arrangement 373(the right image above) and use a swipe gesture. 374
