From 2af226f8930865a5e4294091fd63e6b3b89f8eea Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Thu, 28 May 2015 08:53:00 +1000 Subject: [PATCH] doc: add a blurb about scroll sources to the scrolling docs Signed-off-by: Peter Hutterer --- doc/scrolling.dox | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/doc/scrolling.dox b/doc/scrolling.dox index b5a01cf8..94aa8158 100644 --- a/doc/scrolling.dox +++ b/doc/scrolling.dox @@ -63,4 +63,23 @@ the motion events. Cross-device scrolling is not supported but for one exception: libinput's @ref t440_support enables the use of the middle button for button scrolling (even when the touchpad is disabled). +@section scroll_sources Scroll sources + +libinput provides a pointer axis *source* for each scroll event. The +source can be obtained with the libinput_event_pointer_get_axis_source() +function and is one of **wheel**, **finger**, or **continuous**. The source +information lets a caller decide when to implement kinetic scrolling. +Usually, a caller will process events of source wheel as they come in. +For events of source finger a caller should calculate the velocity of the +scroll motion and upon finger release start a kinetic scrolling motion (i.e. +continue executing a scroll according to some friction factor). +libinput expects the caller to be in charge of widget handling, the source +information is thus enough to provide kinetic scrolling on a per-widget +basis. A caller should cancel kinetic scrolling when the pointer leaves the +current widget or when a key is pressed. + +See the libinput_event_pointer_get_axis_source() for details on the +behavior of each scroll source. + +See also http://who-t.blogspot.com.au/2015/03/libinput-scroll-sources.html */