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 52.. note:: Dragging is always done with one finger. The number of fingers on 53 the initial tap decide the type of button click. For example, to 54 middle-click drag, tap with three fingers followed by a 55 single-finger drag. 56 57Also optional is a feature called "drag lock". With drag lock disabled, lifting 58the finger will stop any drag process. When enabled, libinput will ignore a 59finger up event during a drag process, provided the finger is set down again 60within a implementation-specific timeout. Drag lock can be enabled and 61disabled with **libinput_device_config_tap_set_drag_lock_enabled()**. 62Note that drag lock only applies if tap-and-drag is be enabled. 63 64.. figure:: tap-n-drag.svg 65 :align: center 66 67 Tap-and-drag process 68 69The above diagram explains the process, a tap (a) followed by a finger held 70down (b) starts the drag process and logically holds the left mouse button 71down. A movement of the finger (c) will drag the selected item until the 72finger is released (e). If needed and drag lock is enabled, the finger's 73position can be reset by lifting and quickly setting it down again on the 74touchpad (d). This will be interpreted as continuing move and is especially 75useful on small touchpads or with slow pointer acceleration. 76If drag lock is enabled, the release of the mouse buttons after the finger 77release (e) is triggered by a timeout. To release the button immediately, 78simply tap again (f). 79 80If two fingers are supported by the hardware, a second finger can be used to 81drag while the first is held in-place. 82 83.. _tap_constraints: 84 85------------------------------------------------------------------------------ 86Constraints while tapping 87------------------------------------------------------------------------------ 88 89A couple of constraints apply to the contact to be converted into a press, the most common ones are: 90 91- the touch down and touch up must happen within an implementation-defined timeout 92- if a finger moves more than an implementation-defined distance while in contact, it's not a tap 93- tapping within :ref:`clickpad software buttons <clickpad_softbuttons>` may not trigger an event 94- a tap not meeting required pressure thresholds can be ignored as accidental touch 95- a tap exceeding certain pressure thresholds can be ignored (see :ref:`palm_detection`) 96- a tap on the edges of the touchpad can usually be ignored (see :ref:`palm_detection`) 97
