| 1 |
.. _wheel_scrolling: |
| 2 |
|
| 3 |
============================================================================== |
| 4 |
Wheel scrolling |
| 5 |
============================================================================== |
| 6 |
|
| 7 |
libinput provides two events to handle wheel scrolling: |
| 8 |
|
| 9 |
- ``LIBINPUT_EVENT_POINTER_AXIS`` events are sent for regular wheel clicks, |
| 10 |
usually those representing one detent on the device. These wheel clicks |
| 11 |
usually require a rotation of 15 or 20 degrees. |
| 12 |
**This event is deprecated as of libinput 1.19.** |
| 13 |
|
| 14 |
- ``LIBINPUT_EVENT_POINTER_SCROLL_WHEEL`` events are sent for regular and/or |
| 15 |
high resolution wheel movements. High-resolution events are often 4 or 8 |
| 16 |
times more frequent than wheel clicks and require the device to be switched |
| 17 |
into high-resolution mode (Linux kernel 5.0 and later). Where |
| 18 |
high-resolution wheels are not provided by the kernel, libinput emulates |
| 19 |
these events for regular wheel clicks. |
| 20 |
**This event is available since libinput 1.19.** |
| 21 |
|
| 22 |
The events are separate for historical reasons. Both events are |
| 23 |
generated for the same device but are independent event streams. Callers |
| 24 |
must not assume any relation between the two, i.e. there is no guarantee |
| 25 |
that an axis event is sent before or after any specific high-resolution |
| 26 |
event and vice versa. Callers should not handle both events. |
| 27 |
|
| 28 |
.. warning:: do not handle both ``LIBINPUT_EVENT_POINTER_AXIS`` and |
| 29 |
``LIBINPUT_EVENT_POINTER_SCROLL_WHEEL``. Always use the latter where |
| 30 |
possible, otherwise only use the former. |
| 31 |
|
| 32 |
Both events have their own set of APIs to access the data within: |
| 33 |
|
| 34 |
- ``LIBINPUT_EVENT_POINTER_AXIS``: Deprecated as of libinput 1.19, where |
| 35 |
possible it is recommended to handle **only** |
| 36 |
``LIBINPUT_EVENT_POINTER_SCROLL_WHEEL``. |
| 37 |
|
| 38 |
* ``libinput_event_pointer_get_axis_value()`` returns the angle of movement |
| 39 |
in degrees. |
| 40 |
* ``libinput_event_pointer_get_axis_source()`` returns the source of the |
| 41 |
event: wheel, finger or continuous. |
| 42 |
* ``libinput_event_pointer_get_axis_value_discrete()`` returns the number of |
| 43 |
logical wheel clicks. |
| 44 |
|
| 45 |
- ``LIBINPUT_EVENT_POINTER_SCROLL_WHEEL`` available since libinput 1.19. |
| 46 |
|
| 47 |
* ``libinput_event_pointer_get_scroll_value_v120()`` returns a value |
| 48 |
normalized into the 0..120 range, see below. Any multiple of 120 should |
| 49 |
be treated as one full wheel click. |
| 50 |
|
| 51 |
.. note:: Where possible, the ``libinput_event_pointer_get_axis_value()``, |
| 52 |
``libinput_event_pointer_get_axis_source()`` and |
| 53 |
``libinput_event_pointer_get_axis_value_discrete()`` API should be |
| 54 |
avoided. |
| 55 |
|
| 56 |
------------------------------------------------------------------------------ |
| 57 |
The v120 Wheel API |
| 58 |
------------------------------------------------------------------------------ |
| 59 |
|
| 60 |
The ``v120`` value matches the Windows API for wheel scrolling. Wheel |
| 61 |
movements are normalized into multiples (or fractions) of 120 with each |
| 62 |
multiple of 120 representing one detent of movement. The ``v120`` API is the |
| 63 |
recommended API for callers that do not care about the exact physical |
| 64 |
motion and is the simplest API to handle high-resolution scrolling. |
| 65 |
|
| 66 |
Most wheels provide 24 detents per 360 degree rotation (click angle of 15), |
| 67 |
others provide 18 detents per 360 degree rotation (click angle 20). Mice |
| 68 |
falling outside these two are rare but do exist. Below is a table showing |
| 69 |
the various values for a single event, depending on the click angle of the |
| 70 |
wheel: |
| 71 |
|
| 72 |
+-------------+------------+---------------+------+ |
| 73 |
| Click angle | Axis value | Discrete value| v120 | |
| 74 |
+=============+============+===============+======+ |
| 75 |
| 15 | 15 | 1 | 120 | |
| 76 |
+-------------+------------+---------------+------+ |
| 77 |
| 20 | 20 | 1 | 120 | |
| 78 |
+-------------+------------+---------------+------+ |
| 79 |
|
| 80 |
Fast scrolling may trigger cover than one detent per event and thus each |
| 81 |
event may contain multiples of the value, discrete or v120 value: |
| 82 |
|
| 83 |
+-------------+------------+---------------+------+ |
| 84 |
| Click angle | Axis value | Discrete value| v120 | |
| 85 |
+=============+============+===============+======+ |
| 86 |
| 15 | 30 | 2 | 240 | |
| 87 |
+-------------+------------+---------------+------+ |
| 88 |
| 20 | 60 | 3 | 360 | |
| 89 |
+-------------+------------+---------------+------+ |
| 90 |
|
| 91 |
Scrolling on high-resolution wheels will produce fractions of 120, depending |
| 92 |
on the resolution of the wheel. The example below shows a mouse with click |
| 93 |
angle 15 and a resolution of 3 events per wheel click and a mouse with click |
| 94 |
angle 20 and a resolution of 2 events per wheel click. |
| 95 |
|
| 96 |
+-------------+------------+---------------+------+ |
| 97 |
| Click angle | Axis value | Discrete value| v120 | |
| 98 |
+=============+============+===============+======+ |
| 99 |
| 15 | 5 | 0 | 40 | |
| 100 |
+-------------+------------+---------------+------+ |
| 101 |
| 20 | 10 | 0 | 60 | |
| 102 |
+-------------+------------+---------------+------+ |
| 103 |
|
| 104 |
------------------------------------------------------------------------------ |
| 105 |
Event sequences for high-resolution wheel mice |
| 106 |
------------------------------------------------------------------------------ |
| 107 |
|
| 108 |
High-resolution scroll wheels provide multiple events for each detent is |
| 109 |
hit. For those mice, an event sequence covering two detents may look like |
| 110 |
this: |
| 111 |
|
| 112 |
+--------------+---------+------------+---------------+------+ |
| 113 |
| Event number | Type | Axis value | Discrete value| v120 | |
| 114 |
+==============+=========+============+===============+======+ |
| 115 |
| 1 | WHEEL | 5 | n/a | 40 | |
| 116 |
+--------------+---------+------------+---------------+------+ |
| 117 |
| 2 | WHEEL | 5 | n/a | 40 | |
| 118 |
+--------------+---------+------------+---------------+------+ |
| 119 |
| 3 | WHEEL | 5 | n/a | 40 | |
| 120 |
+--------------+---------+------------+---------------+------+ |
| 121 |
| 4 | AXIS | 15 | 1 | 120 | |
| 122 |
+--------------+---------+------------+---------------+------+ |
| 123 |
| 5 | WHEEL | 5 | n/a | 40 | |
| 124 |
+--------------+---------+------------+---------------+------+ |
| 125 |
| 6 | WHEEL | 5 | n/a | 40 | |
| 126 |
+--------------+---------+------------+---------------+------+ |
| 127 |
| 7 | AXIS | 15 | 1 | 120 | |
| 128 |
+--------------+---------+------------+---------------+------+ |
| 129 |
|
| 130 |
The above assumes a click angle of 15 for the physical detents. Note how the |
| 131 |
second set of high-resolution events do **not** add up to a multiple of |
| 132 |
120 before the low-resolution event. A caller must not assume any relation |
| 133 |
between ``LIBINPUT_EVENT_POINTER_SCROLL_WHEEL`` and |
| 134 |
``LIBINPUT_EVENT_POINTER_AXIS``. |
| 135 |
|
| 136 |
Fast-scrolling on a high-resolution mouse may trigger multiple fractions per |
| 137 |
hardware scanout cycle and result in an event sequence like this: |
| 138 |
|
| 139 |
+---------------+---------+------------+---------------+------+ |
| 140 |
| Event number | Type | Axis value | Discrete value| v120 | |
| 141 |
+===============+=========+============+===============+======+ |
| 142 |
| 1 | WHEEL | 5 | n/a | 40 | |
| 143 |
+---------------+---------+------------+---------------+------+ |
| 144 |
| 2 | WHEEL | 10 | n/a | 80 | |
| 145 |
+---------------+---------+------------+---------------+------+ |
| 146 |
| 3 | AXIS | 15 | 1 | 120 | |
| 147 |
+---------------+---------+------------+---------------+------+ |
| 148 |
| 4 | WHEEL | 10 | n/a | 80 | |
| 149 |
+---------------+---------+------------+---------------+------+ |
| 150 |
| 5 | WHEEL | 10 | n/a | 80 | |
| 151 |
+---------------+---------+------------+---------------+------+ |
| 152 |
| 6 | AXIS | 15 | 1 | 120 | |
| 153 |
+---------------+---------+------------+---------------+------+ |
| 154 |
| 7 | WHEEL | 5 | n/a | 40 | |
| 155 |
+---------------+---------+------------+---------------+------+ |
| 156 |
|
| 157 |
Note how the first low-resolution event is sent at an accumulated 15 |
| 158 |
degrees, the second at an accumulated 20 degrees. The libinput API does not |
| 159 |
specify the smallest fraction a wheel supports. |
| 160 |
|
| 161 |
------------------------------------------------------------------------------ |
| 162 |
Event sequences for regular wheel mice |
| 163 |
------------------------------------------------------------------------------ |
| 164 |
|
| 165 |
``LIBINPUT_EVENT_POINTER_SCROLL_WHEEL`` for low-resolution mice are virtually |
| 166 |
identical to ``LIBINPUT_EVENT_POINTER_AXIS`` events. Note that the discrete |
| 167 |
value is always 0 for ``LIBINPUT_EVENT_POINTER_SCROLL_WHEEL``. |
| 168 |
|
| 169 |
+--------------+---------+------------+---------------+------+ |
| 170 |
| Event number | Type | Axis value | Discrete value| v120 | |
| 171 |
+==============+=========+============+===============+======+ |
| 172 |
| 1 | AXIS | 15 | 1 | 120 | |
| 173 |
+--------------+---------+------------+---------------+------+ |
| 174 |
| 2 | WHEEL | 15 | n/a | 120 | |
| 175 |
+--------------+---------+------------+---------------+------+ |
| 176 |
| 3 | WHEEL | 15 | n/a | 120 | |
| 177 |
+--------------+---------+------------+---------------+------+ |
| 178 |
| 4 | AXIS | 15 | 1 | 120 | |
| 179 |
+--------------+---------+------------+---------------+------+ |
| 180 |
|
| 181 |
Note that the order of ``LIBINPUT_EVENT_POINTER_AXIS`` vs |
| 182 |
``LIBINPUT_EVENT_POINTER_SCROLL_WHEEL`` events is not guaranteed, as shown in |
| 183 |
the example above. |