Debian Codegraph @

doc/user/tapping.rst

raw
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`)