Debian Codegraph @

doc/user/wheel-api.rst

raw
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.