libinput supports basic gestures on touchpads and other indirect input devices.
Two types of gestures are supported: Pinch gestures and Swipe gestures. Support for gestures depends on the hardware device, most touchpads support both gestures and any device that may send gesture events has the LIBINPUT_DEVICE_CAP_GESTURE capability set.
Note that libinput does not support gestures on touchscreens, see Touchscreen gestures.
Lifetime of a gesture
A gesture's lifetime has three distinct stages: begin, update and end, each with their own event types. Begin is sent when the fingers are first set down or libinput decides that the gesture begins. For Pinch gestures this sets the initial scale. Any events changing properties of the gesture are sent as update events. On termination of the gesture, an end event is sent.
A gesture includes the finger count (see libinput_event_gesture_get_finger_count()) and that finger count remains the same for the lifetime of a gesture. Thus, if a user puts down a fourth finger during a three-finger swipe gesture, libinput will end the three-finger gesture and, if applicable, start a four-finger swipe gesture. A caller may decide that those gestures are semantically identical and continue the two gestures as one single gesture.
- See also
- LIBINPUT_EVENT_GESTURE_PINCH_BEGIN
- LIBINPUT_EVENT_GESTURE_PINCH_UPDATE
- LIBINPUT_EVENT_GESTURE_PINCH_END
- LIBINPUT_EVENT_GESTURE_PINCH_BEGIN
- LIBINPUT_EVENT_GESTURE_SWIPE_UPDATE
- LIBINPUT_EVENT_GESTURE_SWIPE_END
Pinch gestures
Pinch gestures are executed when two or more fingers are located on the touchpad and are either changing the relative distance to each other (pinching) or are changing the relative angle (rotate). Pinch gestures may change both rotation and distance at the same time. For such gestures, libinput calculates a logical center for the gestures and provides the caller with the delta x/y coordinates of that center, the relative angle of the fingers compared to the previous event, and the absolute scale compared to the initial finger position.
The illustration above shows a basic pinch in the left image and a rotate in the right angle. Not shown is a movement of the logical center if the fingers move unevenly. Such a movement is supported by libinput, it is merely left out of the illustration.
Note that while position and angle is relative to the previous event, the scale is always absolute and a multiplier of the initial finger position's scale.
Swipe gestures
Swipe gestures are executed when three or more fingers are moved synchronously in the same direction. libinput provides x and y coordinates in the gesture and thus allows swipe gestures in any direction, including the tracing of complex paths. It is up to the caller to interpret the gesture into an action or limit a gesture to specific directions only.
The illustration above shows a vertical three-finger swipe. The coordinates provided during the gesture are the movements of the logical center.
Touchscreen gestures
Touchscreen gestures are not interpreted by libinput. Rather, any touch point is passed to the caller and any interpretation of gestures is up to the caller or, eventually, the X or Wayland client.
Interpreting gestures on a touchscreen requires context that libinput does not have, such as the location of windows and other virtual objects on the screen as well as the context of those virtual objects:
In this example, the finger movements are identical but in the left case both fingers are located within the same window, thus suggesting an attempt to zoom. In the right case both fingers are located on a window border, thus suggesting a window movement. libinput only has knowledge of the finger coordinates (and even then only in device coordinates, not in screen coordinates) and thus cannot differentiate the two.
