doc: move the wiki's palm detection docs to here

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

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 746418a..b4b5d54 100644 (file)
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -11,6 +11,7 @@ header_files = \
        $(srcdir)/clickpad-softbuttons.dox \
        $(srcdir)/device-configuration-via-udev.dox \
        $(srcdir)/normalization-of-relative-motion.dox \
+       $(srcdir)/palm-detection.dox \
        $(srcdir)/scrolling.dox \
        $(srcdir)/seats.dox \
        $(srcdir)/t440-support.dox \
@@ -21,6 +22,7 @@ diagram_files = \
        $(srcdir)/dot/seats-sketch-libinput.gv \
        $(srcdir)/svg/button-scrolling.svg \
        $(srcdir)/svg/edge-scrolling.svg \
+       $(srcdir)/svg/palm-detection.svg \
        $(srcdir)/svg/twofinger-scrolling.svg
 
 html/index.html: libinput.doxygen $(header_files) $(diagram_files)

diff --git a/doc/palm-detection.dox b/doc/palm-detection.dox
new file mode 100644 (file)
index 0000000..4e839e6
--- /dev/null
+++ b/doc/palm-detection.dox
@@ -0,0 +1,52 @@
+/**
+@page palm_detection Palm detection
+
+Palm detection tries to identify accidental touches while typing.
+
+On most laptops typing on the keyboard generates accidental touches on the
+touchpad with the palm (usually the area below the thumb). This can lead to
+cursor jumps or accidental clicks.
+
+Interference from a palm depends on the size of the touchpad and the position
+of the user's hand. Data from touchpads showed that almost all palm events on a
+Lenovo T440 happened in the left-most and right-most 5% of the touchpad. The
+T440 series has one of the largest touchpads, other touchpads are less
+affected by palm touches.
+
+@section palm_exclusion_zones Palm exclusion zones
+
+libinput enables palm detection on the edge of the touchpad. Two exclusion
+zones are defined  on the left and right edge of the touchpad.
+If a touch starts in the exclusion zone, it is considered a palm and the
+touch point is ignored. However, for fast cursor movements across the
+screen, it is common for a finger to start inside an exclusion zone and move
+rapidly across the touchpad. libinput detects such movements and avoids palm
+detection on such touch sequences.
+
+In the diagram below, the exclusion zones are painted red.
+Touch 'A' starts inside the exclusion zone and moves
+almost vertically. It is considered a palm and ignored for cursor movement,
+despite moving out of the exclusion zone.
+
+Touch 'B' starts inside the exclusion zone but moves horizontally out of the
+zone. It is considered a valid touch and controls the cursor.
+
+@image html palm-detection.svg
+
+@section trackpoint-disabling Palm detection during trackpoint use
+
+If a device provides a <a
+href="http://en.wikipedia.org/wiki/Pointing_stick">trackpoint</a>, it is
+usually located above the touchpad. This increases the likelyhood of
+accidental touches whenever the trackpoint is used.
+
+libinput disables the touchpad whenver it detects trackpoint activity for a
+certain timeout until after trackpoint activity stops. Touches generated
+during this timeout will not move the pointer, and touches started during
+this timeout will likewise not move the pointer (allowing for a user to rest
+the palm on the touchpad while using the trackstick).
+If the touchpad is disabled, the @ref t440_support "top software buttons"
+remain enabled.
+
+
+*/

diff --git a/doc/svg/palm-detection.svg b/doc/svg/palm-detection.svg
new file mode 100644 (file)
index 0000000..9fb6077
--- /dev/null
+++ b/doc/svg/palm-detection.svg
@@ -0,0 +1,122 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   version="1.1"
+   width="393.62857"
+   height="268.62857"
+   id="svg2">
+  <defs
+     id="defs4">
+    <marker
+       refX="0"
+       refY="0"
+       orient="auto"
+       id="Arrow1Lend"
+       style="overflow:visible">
+      <path
+         d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+         transform="matrix(-0.8,0,0,-0.8,-10,0)"
+         id="path3710"
+         style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" />
+    </marker>
+    <marker
+       refX="0"
+       refY="0"
+       orient="auto"
+       id="Arrow1Lstart"
+       style="overflow:visible">
+      <path
+         d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+         transform="matrix(0.8,0,0,0.8,10,0)"
+         id="path3707"
+         style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" />
+    </marker>
+    <marker
+       refX="0"
+       refY="0"
+       orient="auto"
+       id="Arrow1Lstart-4"
+       style="overflow:visible">
+      <path
+         d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+         transform="matrix(0.8,0,0,0.8,10,0)"
+         id="path3707-7"
+         style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" />
+    </marker>
+    <marker
+       refX="0"
+       refY="0"
+       orient="auto"
+       id="Arrow1Lend-2"
+       style="overflow:visible">
+      <path
+         d="M 0,0 5,-5 -12.5,0 5,5 0,0 z"
+         transform="matrix(-0.8,0,0,-0.8,-10,0)"
+         id="path3710-3"
+         style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" />
+    </marker>
+  </defs>
+  <g
+     transform="translate(343.95712,-527.33359)"
+     id="layer3"
+     style="display:inline">
+    <rect
+       width="386.42856"
+       height="261.42856"
+       x="-340.35712"
+       y="530.93359"
+       id="rect2858-0"
+       style="color:#000000;fill:#b3b3b3;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:7.20000076;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker:none;visibility:visible;display:inline;overflow:visible;enable-background:accumulate" />
+    <rect
+       width="65.281105"
+       height="254.3844"
+       x="-336.88608"
+       y="534.46918"
+       id="rect12924"
+       style="color:#000000;fill:#ff0000;fill-opacity:0.32017547;fill-rule:nonzero;stroke:none;stroke-width:3.5;marker:none;visibility:visible;display:inline;overflow:visible;enable-background:accumulate" />
+    <rect
+       width="65.281105"
+       height="254.3844"
+       x="-22.72864"
+       y="534.21661"
+       id="rect13482"
+       style="color:#000000;fill:#ff0000;fill-opacity:0.32017547;fill-rule:nonzero;stroke:none;stroke-width:3.5;marker:none;visibility:visible;display:inline;overflow:visible;enable-background:accumulate" />
+    <path
+       d="m 38.928571,67.914286 c 0,0 3.508205,24.810617 9.642857,57.857144 6.134651,33.04652 23.277202,79.68584 89.642852,90.35714"
+       transform="translate(-343.95712,527.33359)"
+       id="path13492"
+       style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:6, 1;stroke-dashoffset:0;marker-mid:none;marker-end:url(#Arrow1Lend-2)" />
+    <text
+       x="-310.74283"
+       y="590.96222"
+       id="text13874"
+       xml:space="preserve"
+       style="font-size:12px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:100%;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Utopia;-inkscape-font-specification:Utopia"><tspan
+         x="-310.74283"
+         y="590.96222"
+         id="tspan13876"
+         style="font-size:18px;font-family:Arial;-inkscape-font-specification:Arial">A</tspan></text>
+    <text
+       x="7.8971062"
+       y="626.08258"
+       id="text13874-8"
+       xml:space="preserve"
+       style="font-size:12px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:100%;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;display:inline;font-family:Utopia;-inkscape-font-specification:Utopia"><tspan
+         x="7.8971062"
+         y="626.08258"
+         id="tspan13876-7"
+         style="font-size:18px;font-family:Arial;-inkscape-font-specification:Arial">B</tspan></text>
+    <path
+       d="m 347.5,90.414286 c 0,0 -28.20972,-6.408104 -85,-6.071429 -22.06971,0.130838 -66.07143,4.285715 -66.07143,4.285715"
+       transform="translate(-343.95712,527.33359)"
+       id="path13903"
+       style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow1Lend-2)" />
+  </g>
+  <g
+     transform="translate(343.95712,-527.33359)"
+     id="layer1"
+     style="display:inline" />
+</svg>