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.
+
+.. _gestures_hold:
+
+------------------------------------------------------------------------------
+Hold gestures
+------------------------------------------------------------------------------
+
+A hold gesture is one where the user places one or more fingers on the
+device without significant movement. The exact conditions when a hold gesture
+transitions to pointer motion, scrolling or other gestures
+are implementation-defined.
+
+The hold gesture is intended to allow for the implementation of two specific
+features:
+
+- where a two-finger scrolling starts kinetic scrolling in the caller, a
+ subsequent hold gesture can be used to stop that kinetic scroll motion,
+ and
+- hold-to-trigger interactions where the interaction could be a click, a
+ context menu, or some other context-specific interaction.
+
+Hold gestures have three potential logical states:
+
+- **begin**: one or more fingers are placed on the device at the same time
+- **end**: all fingers are removed and the device enters a neutral logical state
+- **end(cancelled)**: all fingers are part of a known interaction and the
+ currenthold gesture is no longer active. This may also occurs when
+ switching between hold gestures with different finger counts.
+
+.. note:: By definition, a hold gesture does not move and thus no coordinate
+ updates are available.
+
+For example, a user that puts one finger, then a second finger down and
+releases them later may trigger the following event sequence:
+
+============= ============ ============
+Action Event Finger count
+============= ============ ============
+Finger 1 down <no event>
+Finger 2 down **begin** 2
+Finger 2 up **end** 2
+Finger 1 up <no event>
+============= ============ ============
+
+A hold gesture may by be **cancelled**. This occurs
+when the hold gesture changes into some other interaction and should no
+longer be considered the current hold gesture. A **end(cancelled)** event
+applies to the whole gesture (all fingers). For example, a pointer motion on
+a touchpad may trigger this sequence:
+
++----------------+---------------------+
+| Action | Event |
++================+=====================+
+|Finger 1 down | **hold begin** |
++----------------+---------------------+
+|Finger 1 motion | | **hold cancel** |
+| | | **pointer motion**|
+| | |
++----------------+---------------------+
+|Finger 1 motion | **pointer motion** |
++----------------+---------------------+
+|Finger 1 up | *no event* |
++----------------+---------------------+
+
+.. note:: Many interactions with a touchpad will start with a hold
+ gesture that is then cancelled as that gesture turns into e.g.
+ pointer motion. A caller **must** handle hold gesture
+ cancellations correctly.
+
+A two-finger scroll motion on a touchpad may trigger this sequence:
+
++------------------+---------------------+--------------+
+| Action | Event | Finger count |
++==================+=====================+==============+
+|Finger 1 down | **hold begin** | 1 |
++------------------+---------------------+--------------+
+|Finger 2 down | **hold cancel** | 1 |
+| | **hold begin** | 2 |
++------------------+---------------------+--------------+
+|Finger 1+2 motion | | **hold cancel** | 2 |
+| | | **pointer axis** | |
+| | | |
++------------------+---------------------+--------------+
+|Finger 1+2 motion | **pointer axis** | |
++------------------+---------------------+--------------+
+| | Finger 1 up | **pointer axis** | |
+| | Finger 2 up | (scroll stop) | |
+| | | |
++------------------+---------------------+--------------+
+
+A three-finger-swipe on a touchpad may trigger this sequence:
+
++------------------+---------------------+--------------+
+| Action | Event | Finger count |
++==================+=====================+==============+
+|Finger 1 down | **hold begin** | 1 |
++------------------+---------------------+--------------+
+|Finger 2 down | **hold cancel** | 1 |
+| | **hold begin** | 2 |
++------------------+---------------------+--------------+
+|Finger 3 down | **hold cancel** | 2 |
+| | **hold begin** | 3 |
++------------------+---------------------+--------------+
+|Finger motion | | **hold cancel** | 3 |
+| | | **swipe begin** | 3 |
+| | | |
++------------------+---------------------+--------------|
+|Finger motion | **swipe update** | 3 |
++------------------+---------------------+--------------+
+| | Finger 1 up | **swipe end** | 3 |
+| | Finger 2 up | | |
+| | Finger 3 up | | |
+| | | |
++------------------+---------------------+--------------+
+
+Single-finger hold gestures
+...........................
+
+libinput uses implementation-defined timeouts based on other interactions
+to determine whether a single-finger hold gestures should start. In other
+words, a caller **must not** rely on a hold gesture always being triggered
+as soon as a single finger is placed on the touchpad. This is true for any
+hold gesture but especially so for single-finger hold gestures.
+
+Hold gestures with a single finger are prone to being extremely short-lived.
+On many devices it is impossible to hold a finger still enough for there to
+be no pointer motion events, even if those deltas are miniscule. Changing
+movement thresholds to rely on hold gestures would reduce device
+responsiveness.
+
+It is thus the responsibility of the caller to determine where hold gestures
+transition in and out of other interactions. For example, a two-finger hold
+may produce a cancelled single-finger hold gesture first:
+
++----------------+---------------------+--------------+--------------+
+| Action | Event | Finger count | Notes |
++================+=====================+==============+==============+
+|Finger 1 down | **hold begin** | 1 | |
++----------------+---------------------+--------------+--------------+
+|Finger 1 motion | | **hold cancel** | 1 | tiny deltas |
+| | | **pointer motion**| | |
+| | | | |
++----------------+---------------------+--------------+--------------+
+|Finger 2 down | **hold begin** | 2 | |
++----------------+---------------------+--------------+--------------+
+| | Finger 1 up | **hold end** | | |
+| | Finger 2 up | | | |
+| | | | |
++----------------+---------------------+--------------+--------------+
+
+Note how the second hold gesture started with a finger count of 2 - without
+the user ever lifting the first finger. Cancellation of hold gesture does
+not imply the user has lifted a finger.
+
+A hold gesture may start after a previous gesture completed. For example, a
+single finger move-and-hold may trigger different sequences for the same
+user interaction:
+
++----------------+---------------------+----------------+--------------+
+| Action | Device 1 | Device 2 | Notes |
++================+=====================+================+==============+
+|Finger 1 down | **hold begin** | **hold begin** | |
++----------------+---------------------+----------------+--------------+
+|Finger 1 motion | | **hold cancel** | | tiny deltas |
+| | | **pointer motion**| | |
+| | | | |
++----------------+---------------------+----------------+--------------+
+| | **hold begin** | | |
++----------------+---------------------+----------------+--------------+
+| Finger 1 up | **hold end** | **hold end** | |
++----------------+---------------------+----------------+--------------+
+
+A caller that wants to use hold gestures must thus be able to infer the same
+interaction based on a stream of pointer motion events with small deltas.
+
+libinput may start a new hold begin gesture once the pointer stops moving.
+The time between the last pointer motion event and the hold begin event is
+implementation-defined.
+
+
+Hold gestures and thumb/palm detection
+......................................
+
+Thumb and palm detection effectively remove touches from being counted
+towards an interaction, see :ref:`thumb_detection` and
+:ref:`palm_detection` for details.
+
+In the context of hold gestures, thumbs and palms are treated by libinput as
+if the finger was removed from the device. Where other non-thumb/non-palm
+fingers remain on the device, an **hold update** event is sent. Otherwise,
+the hold gesture terminates with a **hold cancel** event.
+
+Notably, libinput's thumb and palm detection is not a simple boolean per
+touch but specific to the state of that touch in the overall context. For
+example, a touch may be a thumb for tapping but not for clickfinger
+interactions. A caller must not infer the number of physical fingers from
+the hold gesture.
+
+Likewise, libinput may classify a finger as thumb in the same hardware event
+as a new finger is placed on the touchpad. In that case, the hold gesture
+**may** continue as one-finger gesture despite there being two physical
+touch points.
+
+Information to determine whether a touch is a thumb or a palm may not be
+available until some time into an interaction. Thus very short brushes
+of the touchpad by a palm may trigger a **hold begin** followed by an
+immediate **hold end** as libinput lacks sufficient information to identify
+the touch as thumb/palm and send the corresponding **hold cancel**
+event. A caller must not assume that a hold gesture always represents a
+valid finger down.
+
+Hold gestures and tap-to-click
+..............................
+
+:ref:`tapping` is the feature that enables short-lived touches to trigger
+button presses.
+
+.. warning:: Summary: do not use hold gestures to do your own tap-to-click
+ implementation
+
+In the context of hold gestures, tap-to-click cancels current hold gestures
+and a finger dragging (see :ref:`tapndrag`) does not begin a hold
+gesture. Where tap-to-click is disabled a tap-like gesture may create
+**hold begin** followed by a **hold end** event. Callers **must not** use
+hold gestures for their own tap-to-click implementation as the data is not
+reliable enough. libinput may change internal timeouts and thresholds
+depending on whether tap-to-click is enabled and the hold gesture event may
+not match touch sequences that a user would expect to be a tap-to-click
+interaction.
projects / platform / upstream / libinput.git / commitdiff