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