From 0021600ab93d25ed43d9037cfae5c3e23f44fbfe Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Thu, 5 Mar 2015 14:14:07 +1000 Subject: [PATCH] doc: document recommended handling of fake proximity events in the caller 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 Reviewed-by: Benjamin Tissoires --- doc/Makefile.am | 1 + doc/tablet-support.dox | 49 ++++++++++++++++++++++++++++++++++++++++++ src/libinput.h | 2 ++ 3 files changed, 52 insertions(+) create mode 100644 doc/tablet-support.dox diff --git a/doc/Makefile.am b/doc/Makefile.am index f66b47f1..271960e3 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 00000000..fb8ea323 --- /dev/null +++ b/doc/tablet-support.dox @@ -0,0 +1,49 @@ +/** +@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. + +@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: + +@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; +} +@endcode + +*/ diff --git a/src/libinput.h b/src/libinput.h index 204f4909..416aa589 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. */