1.. _wheel_scrolling: 2 3============================================================================== 4Wheel scrolling 5============================================================================== 6 7libinput 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 22The events are separate for historical reasons. Both events are 23generated for the same device but are independent event streams. Callers 24must not assume any relation between the two, i.e. there is no guarantee 25that an axis event is sent before or after any specific high-resolution 26event 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 32Both 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------------------------------------------------------------------------------ 57The v120 Wheel API 58------------------------------------------------------------------------------ 59 60The ``v120`` value matches the Windows API for wheel scrolling. Wheel 61movements are normalized into multiples (or fractions) of 120 with each 62multiple of 120 representing one detent of movement. The ``v120`` API is the 63recommended API for callers that do not care about the exact physical 64motion and is the simplest API to handle high-resolution scrolling. 65 66Most wheels provide 24 detents per 360 degree rotation (click angle of 15), 67others provide 18 detents per 360 degree rotation (click angle 20). Mice 68falling outside these two are rare but do exist. Below is a table showing 69the various values for a single event, depending on the click angle of the 70wheel: 71 72+-------------+------------+---------------+------+ 73| Click angle | Axis value | Discrete value| v120 | 74+=============+============+===============+======+ 75| 15 | 15 | 1 | 120 | 76+-------------+------------+---------------+------+ 77| 20 | 20 | 1 | 120 | 78+-------------+------------+---------------+------+ 79 80Fast scrolling may trigger cover than one detent per event and thus each 81event 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 91Scrolling on high-resolution wheels will produce fractions of 120, depending 92on the resolution of the wheel. The example below shows a mouse with click 93angle 15 and a resolution of 3 events per wheel click and a mouse with click 94angle 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------------------------------------------------------------------------------ 105Event sequences for high-resolution wheel mice 106------------------------------------------------------------------------------ 107 108High-resolution scroll wheels provide multiple events for each detent is 109hit. For those mice, an event sequence covering two detents may look like 110this: 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 130The above assumes a click angle of 15 for the physical detents. Note how the 131second set of high-resolution events do **not** add up to a multiple of 132120 before the low-resolution event. A caller must not assume any relation 133between ``LIBINPUT_EVENT_POINTER_SCROLL_WHEEL`` and 134``LIBINPUT_EVENT_POINTER_AXIS``. 135 136Fast-scrolling on a high-resolution mouse may trigger multiple fractions per 137hardware 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 157Note how the first low-resolution event is sent at an accumulated 15 158degrees, the second at an accumulated 20 degrees. The libinput API does not 159specify the smallest fraction a wheel supports. 160 161------------------------------------------------------------------------------ 162Event sequences for regular wheel mice 163------------------------------------------------------------------------------ 164 165``LIBINPUT_EVENT_POINTER_SCROLL_WHEEL`` for low-resolution mice are virtually 166identical to ``LIBINPUT_EVENT_POINTER_AXIS`` events. Note that the discrete 167value 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 181Note that the order of ``LIBINPUT_EVENT_POINTER_AXIS`` vs 182``LIBINPUT_EVENT_POINTER_SCROLL_WHEEL`` events is not guaranteed, as shown in 183the example above. 184