libinput/doc/gestures.dox

/**
@page gestures Gestures

libinput supports basic gestures on touchpads and other indirect input
devices. Two types of gestures are supported: @ref gestures_pinch and @ref
gestures_swipe. Support for gestures depends on the hardware device, most
touchpads support both gestures and any device that may send gesture events
has the @ref LIBINPUT_DEVICE_CAP_GESTURE capability set.

Note that libinput **does not** support gestures on touchscreens, see
@ref gestures_touchscreens.

@section gestures_lifetime 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 @ref gestures_pinch
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 LIBINPUT_EVENT_GESTURE_PINCH_BEGIN
@see LIBINPUT_EVENT_GESTURE_PINCH_UPDATE
@see LIBINPUT_EVENT_GESTURE_PINCH_END
@see LIBINPUT_EVENT_GESTURE_PINCH_BEGIN
@see LIBINPUT_EVENT_GESTURE_SWIPE_UPDATE
@see LIBINPUT_EVENT_GESTURE_SWIPE_END

@section gestures_pinch 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.

@image html pinch-gestures.svg "The pinch and rotate gestures"

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.

@section gestures_swipe 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.

@image html swipe-gestures.svg "The swipe gestures"

The illustration above shows a vertical three-finger swipe. The coordinates
provided during the gesture are the movements of the logical center.

@section gestures_touchscreens 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:

@image html touchscreen-gestures.svg "Context-sensitivity of touchscreen gestures"

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.

@section gestures_softbuttons Gestures with enabled software buttons

If the touchpad device is a @ref touchpads_buttons_clickpads "Clickpad", it
is recommended that a caller switches to @ref clickfinger.
Usually fingers placed in a @ref software_buttons "software button area" is not
considered for gestures, resulting in some gestures to be interpreted as
pointer motion or two-finger scroll events.

@image html pinch-gestures-softbuttons.svg "Interference of software buttons and pinch gestures"

In the example above, the software button area is highlighted in red. The
user executes a three-finger pinch gesture, with the thumb remaining in the
software button area. libinput ignores fingers within the software button
areas, the movement of the remaining fingers is thus interpreted as a
two-finger scroll motion.

@section gestures_twofinger_touchpads Gestures on two-finger touchpads

As of kernel 4.2, many @ref touchpads_touch_partial_mt provide only two
slots. This affects how gestures can be interpreted. Touchpads with only two
slots can identify two touches by position but can usually tell that there
is a third (or fourth) finger down on the touchpad - without providing
positional information for that finger.

Touchpoints are assigned in sequential order and only the first two touch
points are trackable. For libinput this produces an ambiguity where it is
impossible to detect whether a gesture is a pinch gesture or a swipe gesture
whenever a user puts the index and middle finger down first. Since the third
finger does not have positional information, it's location cannot be
determined.

@image html gesture-2fg-ambiguity.svg "Ambiguity of three-finger gestures on two-finger touchpads"

The image above illustrates this ambiguity. The index and middle finger are
set down first, the data stream from both finger positions looks identical.
In this case, libinput assumes the fingers are in a horizontal arrangement
(the right image above) and use a swipe gesture.

*/