1.. _scrolling: 2 3============================================================================== 4Scrolling 5============================================================================== 6 7libinput supports three different types of scrolling methods: 8:ref:`twofinger_scrolling`, :ref:`edge_scrolling` and 9:ref:`button_scrolling`. Some devices support multiple methods, though only 10one can be enabled at a time. As a general overview: 11 12- touchpad devices with physical buttons below the touchpad support edge and 13 two-finger scrolling 14- touchpad devices without physical buttons (:ref:`ClickPads <clickpad_softbuttons>`) 15 support two-finger scrolling only 16- pointing sticks provide on-button scrolling by default 17- mice and other pointing devices support on-button scrolling but it is not 18 enabled by default 19 20A device may differ from the above based on its capabilities. See 21**libinput_device_config_scroll_set_method()** for documentation on how to 22switch methods and **libinput_device_config_scroll_get_methods()** for 23documentation on how to query a device for available scroll methods. 24 25.. _horizontal_scrolling: 26 27------------------------------------------------------------------------------ 28Horizontal scrolling 29------------------------------------------------------------------------------ 30 31Scroll movements provide vertical and horizontal directions, each 32scroll event contains both directions where applicable, see 33**libinput_event_pointer_get_axis_value()**. libinput does not provide separate 34toggles to enable or disable horizontal scrolling. Instead, horizontal 35scrolling is always enabled. This is intentional, libinput does not have 36enough context to know when horizontal scrolling is appropriate for a given 37widget. The task of filtering horizontal movements is up to the caller. 38 39.. _twofinger_scrolling: 40 41------------------------------------------------------------------------------ 42Two-finger scrolling 43------------------------------------------------------------------------------ 44 45The default on two-finger capable touchpads (almost all modern touchpads are 46capable of detecting two fingers). Scrolling is triggered by two fingers 47being placed on the surface of the touchpad, then moving those fingers 48vertically or horizontally. 49 50.. figure:: twofinger-scrolling.svg 51 :align: center 52 53 Vertical and horizontal two-finger scrolling 54 55For scrolling to trigger, a built-in distance threshold has to be met, but once 56engaged, any movement will scroll. In other words: to start scrolling, a 57sufficiently large movement is required; once scrolling, tiny amounts of 58movements will translate into tiny scroll movements. 59Scrolling in both directions at once is possible by meeting the required 60distance thresholds to enable each direction separately. 61 62When a scroll gesture remains close to perfectly straight, it will be held to 63exact 90-degree angles; but if the gesture moves diagonally, it is free to 64scroll in any direction. 65 66Two-finger scrolling requires the touchpad to track both touch points with 67reasonable precision. Unfortunately, some so-called "semi-mt" touchpads can 68only track the bounding box of the two fingers rather than the actual 69position of each finger. In addition, that bounding box usually suffers from 70a low resolution, causing jumpy movement during two-finger scrolling. 71libinput does not provide two-finger scrolling on those touchpads. 72 73.. _edge_scrolling: 74 75------------------------------------------------------------------------------ 76Edge scrolling 77------------------------------------------------------------------------------ 78 79On some touchpads, edge scrolling is available, triggered by moving a single 80finger along the right edge (vertical scroll) or bottom edge (horizontal 81scroll). 82 83.. figure:: edge-scrolling.svg 84 :align: center 85 86 Vertical and horizontal edge scrolling 87 88Due to the layout of the edges, diagonal scrolling is not possible. The 89behavior of edge scrolling using both edges at the same time is undefined. 90 91Edge scrolling overlaps with :ref:`clickpad_softbuttons`. A physical click on 92a clickpad ends scrolling. 93 94.. _button_scrolling: 95 96------------------------------------------------------------------------------ 97On-Button scrolling 98------------------------------------------------------------------------------ 99 100On-button scrolling converts the motion of a device into scroll events while 101a designated button is held down. For example, Lenovo devices provide a 102`pointing stick <http://en.wikipedia.org/wiki/Pointing_stick>`_ that emulates 103scroll events when the trackstick's middle mouse button is held down. 104 105.. note:: On-button scrolling is enabled by default for pointing sticks. This 106 prevents middle-button dragging; all motion events while the middle 107 button is down are converted to scroll events. 108 109.. figure:: button-scrolling.svg 110 :align: center 111 112 Button scrolling 113 114The button may be changed with 115**libinput_device_config_scroll_set_button()** but must be on the same device as 116the motion events. Cross-device scrolling is not supported but 117for one exception: libinput's :ref:`t440_support` enables the use of the middle 118button for button scrolling (even when the touchpad is disabled). 119 120If the scroll button lock is enabled (see 121**libinput_device_config_scroll_set_button_lock()**), the button does not 122need to be held down. Pressing and releasing the button once enables the 123button lock, the button is now considered logically held down. Pressing and 124releasing the button a second time logically releases the button. While the 125button is logically held down, motion events are converted to scroll events. 126 127.. _scroll_sources: 128 129------------------------------------------------------------------------------ 130Scroll sources 131------------------------------------------------------------------------------ 132 133.. note:: Scroll sources are deprecated with libinput 1.19. The scroll 134 source is now encoded in the event type. 135 136libinput provides a pointer axis *source* for each scroll event. The 137source can be obtained with the **libinput_event_pointer_get_axis_source()** 138function and is one of **wheel**, **finger**, or **continuous**. The source 139information lets a caller decide when to implement kinetic scrolling. 140Usually, a caller will process events of source wheel as they come in. 141For events of source finger a caller should calculate the velocity of the 142scroll motion and upon finger release start a kinetic scrolling motion (i.e. 143continue executing a scroll according to some friction factor). 144libinput expects the caller to be in charge of widget handling, the source 145information is thus enough to provide kinetic scrolling on a per-widget 146basis. A caller should cancel kinetic scrolling when the pointer leaves the 147current widget or when a key is pressed. 148 149See the **libinput_event_pointer_get_axis_source()** for details on the 150behavior of each scroll source. 151 152See also http://who-t.blogspot.com.au/2015/03/libinput-scroll-sources.html 153
