doc: move the wiki's tapping documentation to here

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 5c22d776e04128361eb5f25fa72d6baa08b0c7b8..746418a6b127ccec0682a6c41286f000477e51e9 100644 (file)
--- 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 (file)
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)
+
+*/