Debian Codegraph @

doc/user/scrolling.rst

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