From 174364580d1f8006dba4c8412573f4a8f9d1a447 Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Tue, 23 Dec 2014 09:32:37 +1000 Subject: [PATCH] doc: move the wiki's tapping documentation to here Signed-off-by: Peter Hutterer --- doc/Makefile.am | 3 ++- doc/tapping.dox | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 50 insertions(+), 1 deletion(-) create mode 100644 doc/tapping.dox diff --git a/doc/Makefile.am b/doc/Makefile.am index 5c22d77..746418a 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -13,7 +13,8 @@ header_files = \ $(srcdir)/normalization-of-relative-motion.dox \ $(srcdir)/scrolling.dox \ $(srcdir)/seats.dox \ - $(srcdir)/t440-support.dox + $(srcdir)/t440-support.dox \ + $(srcdir)/tapping.dox diagram_files = \ $(srcdir)/dot/seats-sketch.gv \ diff --git a/doc/tapping.dox b/doc/tapping.dox new file mode 100644 index 0000000..f603b7d --- /dev/null +++ b/doc/tapping.dox @@ -0,0 +1,48 @@ +/** +@page tapping Tap-to-click behaviour + +"Tapping" or "tap-to-click" is the name given to the behavior where a short +finger touch down/up sequence maps into a button click. This is most +commonly used on touchpads, but may be available on other devices. + +libinput implements tapping for one, two, and three fingers, where supported +by the hardware, and maps those taps into a left, right, and middle button +click, respectively. Not all devices support three fingers, libinput will +support tapping up to whatever is supported by the hardware. libinput does +not support four-finger taps or any tapping with more than four fingers, +even though some hardware can distinguish between that many fingers. + +Tapping is **disabled** by default, see [this +commit](http://cgit.freedesktop.org/wayland/libinput/commit/?id=2219c12c3aa45b80f235e761e87c17fb9ec70eae) +because: +- if you don't know that tapping is a thing (or enabled by default), you get + spurious button events that make the desktop feel buggy. +- if you do know what tapping is and you want it, you usually know where to + enable it, or at least you can search for it. + +Tapping can be enabled on a per-device basis. See +libinput_device_config_tap_set_enabled() for details. + +@section tapndrag Tap-and-drag + +libinput also supports "tap-and-drag" where a tap immediately followed by a +finger down and that finger being held down emulates a button press. Moving +the finger around can thus drag the selected item on the screen. Lifting the +finger and putting it back down immediately (i.e. within the timeout) will +continue the dragging process, so that multiple touchpad-widths of distance +can be covered easily. If two-fingers are supported by the hardware, a +second finger can be used to drag while the first is held in-place. + +@section tap_constraints Constraints while tapping + +A couple of constraints apply to the contact to be converted into a press, the most common ones are: +- the touch down and touch up must happen within an implementation-defined timeout +- if a finger moves more than an implementation-defined distance while in contact, it's not a tap +- tapping within @ref clickpad_softbuttons "clickpad software buttons" may not trigger an event +- a tap not meeting required pressure thresholds can be ignored as accidental touch +- a tap exceeding certain pressure thresholds can be ignored (see @ref + palm_detection) +- a tap on the edges of the touchpad can usually be ignored (see @ref + palm_detection) + +*/ -- 2.7.4