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.hutte...@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 @@ +/** +@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 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 _______________________________________________ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel