From: Peter Hutterer Date: Mon, 22 Dec 2014 23:32:37 +0000 (+1000) Subject: doc: move the wiki's tapping documentation to here X-Git-Tag: 0.8.0~42 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=174364580d1f8006dba4c8412573f4a8f9d1a447;p=platform%2Fupstream%2Flibinput.git doc: move the wiki's tapping documentation to here Signed-off-by: Peter Hutterer --- diff --git a/doc/Makefile.am b/doc/Makefile.am index 5c22d776..746418a6 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 00000000..f603b7d5 --- /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) + +*/