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