[PATCH libinput 2/2] doc: document recommended handling of fake proximity events in the caller

[Peter Hutterer]

Fake proximity events are context dependent and libinput doesn't have access
to the context. For example, fake proximity on the Wacom mouse is only required
in relative mode - but whether to use relative or absolute events is decided
in the caller.

Document what the recommended approach is since it's a bit quirky and leave it
at that.

Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
---
 doc/Makefile.am        |  1 +
 doc/tablet-support.dox | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 src/libinput.h         |  2 ++
 3 files changed, 53 insertions(+)
 create mode 100644 doc/tablet-support.dox

diff --git a/doc/Makefile.am b/doc/Makefile.am
index f66b47f..271960e 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -15,6 +15,7 @@ header_files = \
 	$(srcdir)/scrolling.dox \
 	$(srcdir)/seats.dox \
 	$(srcdir)/t440-support.dox \
+	$(srcdir)/tablet-support.dox \
 	$(srcdir)/tapping.dox
 
 diagram_files = \
diff --git a/doc/tablet-support.dox b/doc/tablet-support.dox
new file mode 100644
index 0000000..aeb2f64
--- /dev/null
+++ b/doc/tablet-support.dox
@@ -0,0 +1,50 @@
+/**
+ at page tablet-support Tablet support
+
+This page provides details about the graphics tablet
+support in libinput. Note that the term "tablet" in libinput refers to
+graphics tablets only (e.g. Wacom Intuos), not to tablet devices like the
+Apple iPad.
+
+ at section fake-proximity Handling of proximity events 
+
+libinput's @ref LIBINPUT_EVENT_TABLET_PROXIMITY events represent the
+physical proximity limits of the device. In some cases the caller should
+emulate proximity based on the distance events. For example, the Wacom mouse
+and lens cursor tools are usually used in relative mode, lying flat on the
+tablet. A user typically expects that lifting the tool off the tablet to a
+different location has the same effect as with a normal mouse. The proximity
+detection on Wacom tablets however extends further than the user may lift
+the mouse, i.e. the tool may not be lifted out of physical proximity.
+
+To enable normal use as a mouse it is recommended that the caller treats
+proximity separate from libinput's proximity events. There is no simple way
+to detect the proximity motion threshold, it is different on each tablet and
+differs between tools. The recommended algorithm is to remember the minimum
+distance value seen on the tool and assume a proximity out when the distance
+exceeds a threshold above this minimum value. In pseudo-code:
+
+ at code
+const double threshold = ...;
+static double min;
+static bool in_proximity;
+
+double value;
+
+value = libinput_event_pointer_get_axis_value(device,
+					      LIBINPUT_TABLET_AXIS_DISTANCE);
+
+if (value < min) {
+	min = value;
+	return;
+} else if (in_proximity &&
+	   value > min + threshold) {
+	   in_proximity = false;
+} else if (!in_proximity &&
+	   value < min + threshold) {
+	   in_proximity = true;
+}
+ at endcode
+
+*/
+
diff --git a/src/libinput.h b/src/libinput.h
index 204f490..416aa58 100644
--- a/src/libinput.h
+++ b/src/libinput.h
@@ -1185,6 +1185,8 @@ libinput_event_tablet_get_tool(struct libinput_event_tablet *event);
  * Used to check whether or not a tool came in or out of proximity during an
  * event of type @ref LIBINPUT_EVENT_TABLET_PROXIMITY.
  *
+ * See @ref fake-proximity for recommendations on proximity handling.
+ *
  * @param event The libinput tablet event
  * @return The new proximity state of the tool from the event.
  */
-- 
2.1.0