| 1 |
.. _tapping: |
| 2 |
|
| 3 |
============================================================================== |
| 4 |
Tap-to-click behaviour |
| 5 |
============================================================================== |
| 6 |
|
| 7 |
"Tapping" or "tap-to-click" is the name given to the behavior where a short |
| 8 |
finger touch down/up sequence maps into a button click. This is most |
| 9 |
commonly used on touchpads, but may be available on other devices. |
| 10 |
|
| 11 |
libinput implements tapping for one, two, and three fingers, where supported by |
| 12 |
the hardware, and maps those taps into a left, right, and middle button click, |
| 13 |
respectively. This mapping can be switched to left, middle and right through |
| 14 |
configuration. Not all devices support three fingers, libinput will support |
| 15 |
tapping up to whatever is supported by the hardware. libinput does not support |
| 16 |
four-finger taps or any tapping with more than four fingers, even though some |
| 17 |
hardware can distinguish between that many fingers. |
| 18 |
|
| 19 |
.. _tapping_default: |
| 20 |
|
| 21 |
------------------------------------------------------------------------------ |
| 22 |
Tap-to-click default setting |
| 23 |
------------------------------------------------------------------------------ |
| 24 |
|
| 25 |
Tapping is **disabled** by default on most devices, see |
| 26 |
:commit:`2219c12c3` because: |
| 27 |
|
| 28 |
- if you don't know that tapping is a thing (or enabled by default), you get |
| 29 |
spurious button events that make the desktop feel buggy. |
| 30 |
- if you do know what tapping is and you want it, you usually know where to |
| 31 |
enable it, or at least you can search for it. |
| 32 |
|
| 33 |
Tapping is **enabled** by default on devices where tapping is the only |
| 34 |
method to trigger button clicks. This includes devices without physical |
| 35 |
buttons such as touch-capable graphics tablets. |
| 36 |
|
| 37 |
.. note:: Unfortunately due to the current API design, devices that require |
| 38 |
tapping effectively prevent us from changing this default. For details see |
| 39 |
`this comment <https://gitlab.freedesktop.org/libinput/libinput/-/issues/926#note_2056476>`_. |
| 40 |
|
| 41 |
Tapping can be enabled/disabled on a per-device basis. See |
| 42 |
**libinput_device_config_tap_set_enabled()** for details. |
| 43 |
|
| 44 |
.. _tapndrag: |
| 45 |
|
| 46 |
------------------------------------------------------------------------------ |
| 47 |
Tap-and-drag |
| 48 |
------------------------------------------------------------------------------ |
| 49 |
|
| 50 |
libinput also supports "tap-and-drag" where a tap immediately followed by a |
| 51 |
finger down and that finger being held down emulates a button press. Moving |
| 52 |
the finger around can thus drag the selected item on the screen. |
| 53 |
Tap-and-drag is optional and can be enabled or disabled with |
| 54 |
**libinput_device_config_tap_set_drag_enabled()**. Most devices have |
| 55 |
tap-and-drag enabled by default. |
| 56 |
|
| 57 |
.. note:: Dragging is always done with one finger. The number of fingers on |
| 58 |
the initial tap decide the type of button click. For example, to |
| 59 |
middle-click drag, tap with three fingers followed by a |
| 60 |
single-finger drag. |
| 61 |
|
| 62 |
Also optional is a feature called "drag lock". With drag lock disabled, lifting |
| 63 |
the finger will stop any drag process. When enabled, the drag |
| 64 |
process continues even after lifting a finger but can be ended |
| 65 |
with an additional tap. If timeout-based drag-locks are enabled |
| 66 |
the drag process will also automatically end once the finger has |
| 67 |
been lifted for an implementation-specific timeout. Drag lock can be |
| 68 |
enabled and disabled with **libinput_device_config_tap_set_drag_lock_enabled()**. |
| 69 |
Note that drag lock only applies if tap-and-drag is enabled. |
| 70 |
|
| 71 |
.. figure:: tap-n-drag.svg |
| 72 |
:align: center |
| 73 |
|
| 74 |
Tap-and-drag process |
| 75 |
|
| 76 |
The above diagram explains the process, a tap (a) followed by a finger held |
| 77 |
down (b) starts the drag process and logically holds the left mouse button |
| 78 |
down. A movement of the finger (c) will drag the selected item until the |
| 79 |
finger is released (e). If needed and drag lock is enabled, the finger's |
| 80 |
position can be reset by lifting and quickly setting it down again on the |
| 81 |
touchpad (d). This will be interpreted as continuing move and is especially |
| 82 |
useful on small touchpads or with slow pointer acceleration. |
| 83 |
If drag lock is enabled, the release of the mouse buttons after the finger |
| 84 |
release (e) is triggered by a timeout. To release the button immediately, |
| 85 |
simply tap again (f). |
| 86 |
|
| 87 |
If drag lock is enabled in sticky mode there is no timeout after |
| 88 |
releasing a finger and an extra tap is required to release the button. |
| 89 |
|
| 90 |
If two fingers are supported by the hardware, a second finger can be used to |
| 91 |
drag while the first is held in-place. |
| 92 |
|
| 93 |
.. _tap_constraints: |
| 94 |
|
| 95 |
------------------------------------------------------------------------------ |
| 96 |
Constraints while tapping |
| 97 |
------------------------------------------------------------------------------ |
| 98 |
|
| 99 |
A couple of constraints apply to the contact to be converted into a press, the most common ones are: |
| 100 |
|
| 101 |
- the touch down and touch up must happen within an implementation-defined timeout |
| 102 |
- if a finger moves more than an implementation-defined distance while in contact, it's not a tap |
| 103 |
- tapping within :ref:`clickpad software buttons <clickpad_softbuttons>` may not trigger an event |
| 104 |
- a tap not meeting required pressure thresholds can be ignored as accidental touch |
| 105 |
- a tap exceeding certain pressure thresholds can be ignored (see :ref:`palm_detection`) |
| 106 |
- a tap on the edges of the touchpad can usually be ignored (see :ref:`palm_detection`) |