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 the three-finger gesture and, if applicable, start a four-finger swipe 24gesture. A caller may however decide that those gestures are semantically 25identical and continue the two gestures as one single gesture. 26 27.. _gestures_pinch: 28 29------------------------------------------------------------------------------ 30Pinch gestures 31------------------------------------------------------------------------------ 32 33Pinch gestures are executed when two or more fingers are located on the 34touchpad and are either changing the relative distance to each other 35(pinching) or are changing the relative angle (rotate). Pinch gestures may 36change both rotation and distance at the same time. For such gestures, 37libinput calculates a logical center for the gestures and provides the 38caller with the delta x/y coordinates of that center, the relative angle of 39the fingers compared to the previous event, and the absolute scale compared 40to the initial finger position. 41 42.. figure:: pinch-gestures.svg 43 :align: center 44 45 The pinch and rotate gestures 46 47The illustration above shows a basic pinch in the left image and a rotate in 48the right angle. Not shown is a movement of the logical center if the 49fingers move unevenly. Such a movement is supported by libinput, it is 50merely left out of the illustration. 51 52Note that while position and angle is relative to the previous event, the 53scale is always absolute and a multiplier of the initial finger position's 54scale. 55 56.. _gestures_swipe: 57 58------------------------------------------------------------------------------ 59Swipe gestures 60------------------------------------------------------------------------------ 61 62Swipe gestures are executed when three or more fingers are moved 63synchronously in the same direction. libinput provides x and y coordinates 64in the gesture and thus allows swipe gestures in any direction, including 65the tracing of complex paths. It is up to the caller to interpret the 66gesture into an action or limit a gesture to specific directions only. 67 68.. figure:: swipe-gestures.svg 69 :align: center 70 71 The swipe gestures 72 73The illustration above shows a vertical three-finger swipe. The coordinates 74provided during the gesture are the movements of the logical center. 75 76.. _gestures_touchscreens: 77 78------------------------------------------------------------------------------ 79Touchscreen gestures 80------------------------------------------------------------------------------ 81 82Touchscreen gestures are **not** interpreted by libinput. Rather, any touch 83point is passed to the caller and any interpretation of gestures is up to 84the caller or, eventually, the X or Wayland client. 85 86Interpreting gestures on a touchscreen requires context that libinput does 87not have, such as the location of windows and other virtual objects on the 88screen as well as the context of those virtual objects: 89 90.. figure:: touchscreen-gestures.svg 91 :align: center 92 93 Context-sensitivity of touchscreen gestures 94 95In the above example, the finger movements are identical but in the left 96case both fingers are located within the same window, thus suggesting an 97attempt to zoom. In the right case both fingers are located on a window 98border, thus suggesting a window movement. libinput has no knowledge of the 99window coordinates and thus cannot differentiate the two. 100 101.. _gestures_softbuttons: 102 103------------------------------------------------------------------------------ 104Gestures with enabled software buttons 105------------------------------------------------------------------------------ 106 107If the touchpad device is a :ref:`Clickpad <touchpads_buttons_clickpads>`, it 108is recommended that a caller switches to :ref:`clickfinger`. 109Usually fingers placed in a :ref:`software button area <software_buttons>` 110are not considered for gestures, resulting in some gestures to be 111interpreted as pointer motion or two-finger scroll events. 112 113.. figure:: pinch-gestures-softbuttons.svg 114 :align: center 115 116 Interference of software buttons and pinch gestures 117 118In the example above, the software button area is highlighted in red. The 119user executes a three-finger pinch gesture, with the thumb remaining in the 120software button area. libinput ignores fingers within the software button 121areas, the movement of the remaining fingers is thus interpreted as a 122two-finger scroll motion. 123 124.. _gestures_twofinger_touchpads: 125 126------------------------------------------------------------------------------ 127Gestures on two-finger touchpads 128------------------------------------------------------------------------------ 129 130As of kernel 4.2, many :ref:`touchpads_touch_partial_mt` provide only two 131slots. This affects how gestures can be interpreted. Touchpads with only two 132slots can identify two touches by position but can usually tell that there 133is a third (or fourth) finger down on the touchpad - without providing 134positional information for that finger. 135 136Touchpoints are assigned in sequential order and only the first two touch 137points are trackable. For libinput this produces an ambiguity where it is 138impossible to detect whether a gesture is a pinch gesture or a swipe gesture 139whenever a user puts the index and middle finger down first. Since the third 140finger does not have positional information, it's location cannot be 141determined. 142 143.. figure:: gesture-2fg-ambiguity.svg 144 :align: center 145 146 Ambiguity of three-finger gestures on two-finger touchpads 147 148The image above illustrates this ambiguity. The index and middle finger are 149set down first, the data stream from both finger positions looks identical. 150In this case, libinput assumes the fingers are in a horizontal arrangement 151(the right image above) and use a swipe gesture. 152
