From: Peter Hutterer Date: Wed, 10 Jul 2019 04:06:07 +0000 (+1000) Subject: doc/user: add documentation for the new thumb detection X-Git-Tag: 1.13.901~1^2~2 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=94a7cd4959b8e24e095d00b2afcdabe756c71224;p=platform%2Fupstream%2Flibinput.git doc/user: add documentation for the new thumb detection Signed-off-by: Peter Hutterer --- diff --git a/doc/user/features.rst b/doc/user/features.rst index 6e644a8..55c9cbb 100644 --- a/doc/user/features.rst +++ b/doc/user/features.rst @@ -18,6 +18,7 @@ to be useful. gestures.rst middle-button-emulation.rst palm-detection.rst + touchpad-thumb-detection.rst scrolling.rst t440-support.rst tapping.rst diff --git a/doc/user/meson.build b/doc/user/meson.build index fce6ec1..7d81bcf 100644 --- a/doc/user/meson.build +++ b/doc/user/meson.build @@ -159,6 +159,7 @@ src_rst = files( 'touchpad-pressure.rst', 'touchpad-pressure-debugging.rst', 'touchpad-jitter.rst', + 'touchpad-thumb-detection.rst', 'touchpads.rst', 'trackpoints.rst', 'trackpoint-configuration.rst', diff --git a/doc/user/touchpad-thumb-detection.rst b/doc/user/touchpad-thumb-detection.rst new file mode 100644 index 0000000..caf26dc --- /dev/null +++ b/doc/user/touchpad-thumb-detection.rst @@ -0,0 +1,89 @@ +.. _thumb_detection: + +============================================================================== +Thumb detection +============================================================================== + +Thumb detection tries to identify touches triggered by a thumb rather than a +pointer-moving finger. This is necessary on :ref:`touchpads_buttons_clickpads` +as a finger pressing a button always creates a new touch, causing +misinterpretation of gestures. Click-and-drag with two fingers (one holding +the button, one moving) would be interpreted as two-finger scrolling without +working thumb detection. + +libinput has built-in thumb detection, partially dependent on +hardware-specific capabilities. + +- :ref:`thumb_pressure` +- :ref:`thumb_areas` +- :ref:`thumb_speed` + +Thumb detection uses multiple approaches and the final decision on whether +to ignore a thumb depends on the interaction at the time. + +.. _thumb_pressure: + +------------------------------------------------------------------------------ +Thumb detection based on pressure or size +------------------------------------------------------------------------------ + +The simplest form of thumb detection identifies a touch as thumb when the +pressure value goes above a certain threshold. This threshold is usually +high enough that it cannot be triggered by a finger movement. + +On touchpads that support the ``ABS_MT_TOUCH_MAJOR`` axes, libinput can perform +thumb detection based on the size of the touch ellipse. This works similar to +the pressure-based palm detection in that a touch is labelled as palm when +it exceeds the (device-specific) touch size threshold. + +Pressure- and size-based thumb detection depends on the location of the +thumb and usually only applies within the :ref:`thumb_areas`. + +For some information on how to detect pressure on a touch and debug the +pressure ranges, see :ref:`touchpad_pressure`. Pressure- and size-based +thumb detection require thresholds set in the :ref:`device-quirks`. + +.. _thumb_areas: + +------------------------------------------------------------------------------ +Thumb detection areas +------------------------------------------------------------------------------ + +Pressure and size readings are unreliable at the far bottom of the touchpad. +A thumb hanging mostly off the touchpad will have a small surface area. +libinput has a definitive thumb zone where any touch is considered a +thumb. Immediately above that area is the area where libinput will label a +thumb as such if the pressure or size thresholds are exceeded. + + +.. figure:: thumb-detection.svg + :align: center + +The picture above shows the two detection areas. In the larger (light red) +area, a touch is labelled as thumb when it exceeds a device-specific +pressure threshold. In the lower (dark red) area, a touch is always labelled +as thumb. + +Moving outside the areas generally releases the thumb from being a thumb. + +.. _thumb_speed: + +------------------------------------------------------------------------------ +Thumb movement based on speed +------------------------------------------------------------------------------ + +Regular interactions with thumbs do not usually move the thumb. When fingers +are moving across the touchpad and a thumb is dropped, this can cause +erroneous scroll motion or similar issues. libinput observes the finger +motion speed for all touches - where a finger has been moving a newly +dropped finger is more likely to be labeled as thumb. + +------------------------------------------------------------------------------ +Thumb detection based on finger positions +------------------------------------------------------------------------------ + +The shape of the human hand and the interactions that usually involve a +thumb imply that a thumb is situated in a specific position relative to +other fingers (usually to the side and below). This is used by libinput to +detect thumbs during some interactions that do not implicitly require a +thumb (e.g. pinch-and-rotate).