Debian Codegraph @

doc/user/faqs.rst

raw
1 .. _faq:
2
3 ==============================================================================
4 FAQs - Frequently Asked Questions
5 ==============================================================================
6
7 Frequently asked questions about libinput.
8
9
10 .. contents::
11 :local:
12 :backlinks: entry
13
14 .. _faq_feature:
15
16 ------------------------------------------------------------------------------
17 Why doesn't libinput support ...?
18 ------------------------------------------------------------------------------
19
20 First, read :ref:`what_is_libinput` If you have a feature that you think
21 libinput needs to support, please file a bug report. See :ref:`reporting_bugs`
22 for more details.
23
24 .. _faq_fast_mouse:
25
26 ------------------------------------------------------------------------------
27 My mouse moves too fast, even at the slowest setting
28 ------------------------------------------------------------------------------
29
30 This is a symptom of high-dpi mice (greater than 1000dpi). These devices
31 need a udev hwdb entry to normalize their motion. See
32 :ref:`motion_normalization` for a detailed explanation.
33
34 .. _faq_fast_trackpoint:
35
36 ------------------------------------------------------------------------------
37 My trackpoint moves too slow or too fast
38 ------------------------------------------------------------------------------
39
40 This is a symptom of an invalid trackpoint multiplier. These devices need
41 :ref:`device-quirks` to specify the range available so libinput can adjust the
42 pointer acceleration accordingly. See :ref:`trackpoint_range` for a detailed
43 explanation.
44
45 .. _faq_pointer_acceleration:
46
47 ------------------------------------------------------------------------------
48 Why is libinput's pointer acceleration worse than synaptics/evdev
49 ------------------------------------------------------------------------------
50
51 This is a known problem affecting some devices and/or use-case but the exact
52 cause is still unknown. It may be a device-specific issue, it may be a bug
53 in libinput's acceleration code, it may be a disagreement about how pointer
54 acceleration should feel. Unfortunately this is something that affected
55 users need to investigate and analyze.
56
57 .. _faq_enable_tapping:
58
59 ------------------------------------------------------------------------------
60 Why isn't touchpad tap-to-click enabled by default
61 ------------------------------------------------------------------------------
62
63 See :ref:`tapping_default`
64
65 .. _faq_touchpad_pressure:
66
67 ------------------------------------------------------------------------------
68 Why does my touchpad lose track of touches
69 ------------------------------------------------------------------------------
70
71 The most common cause for this is an incorrect pressure threshold range.
72 See :ref:`touchpad_pressure` for more info.
73
74 .. _faq_kinetic_scrolling:
75
76 ------------------------------------------------------------------------------
77 Kinetic scrolling does not work
78 ------------------------------------------------------------------------------
79
80 The X.Org synaptics driver implemented kinetic scrolling in the driver. It
81 measures the scroll speed and once the finger leaves the touchpad the driver
82 keeps sending scroll events for a predetermined time. This effectively
83 provides for kinetic scrolling without client support but triggers an
84 unfixable `bug <https://bugs.freedesktop.org/show_bug.cgi?id=38909>`_: the
85 client cannot know that the events are from a kinetic scroll source. Scroll
86 events in X are always sent to the current cursor position, a movement of the
87 cursor after lifting the finger will send the kinetic scroll events to the
88 new client, something the user does not usually expect. A key event during
89 the kinetic scroll procedure causes side-effects such as triggering zoom.
90
91 libinput does not implement kinetic scrolling for touchpads. Instead it
92 provides the **libinput_event_pointer_get_axis_source()** function that enables
93 callers to implement kinetic scrolling on a per-widget basis, see
94 :ref:`scroll_sources`.
95
96 .. _faq_gpl:
97
98 ------------------------------------------------------------------------------
99 Is libinput GPL-licensed?
100 ------------------------------------------------------------------------------
101
102 No, libinput is MIT licensed. The Linux kernel header file linux/input.h in
103 libinput's tree is provided to ensure the same behavior regardless of which
104 kernel version libinput is built on. It does not make libinput GPL-licensed.
105
106 .. _faq_config_options:
107
108 ------------------------------------------------------------------------------
109 Where is the configuration stored?
110 ------------------------------------------------------------------------------
111
112 libinput does not store configuration options, it is up to the caller to
113 manage these and decide which configuration option to apply to each device.
114 This must be done at startup, after a resume and whenever a new device is
115 detected.
116
117 One commonly used way to configure libinput is to have the Wayland
118 compositor expose a compositor-specific configuration option. For example,
119 in a GNOME stack, the gnome-control-center modifies dconf entries. These
120 changes are read by mutter and applied to libinput. Changing these entries
121 via the gsettings commandline tool has the same effect.
122
123 Another commonly used way to configure libinput is to have xorg.conf.d
124 snippets. When libinput is used with the xf86-input-libinput driver in an
125 X.Org stack, these options are read on startup and apply to each device.
126 Changing properties at runtime with the xinput commandline tool has the same
127 effect.
128
129 In both cases, the selection of available options and how they are exposed
130 depends on the libinput caller (e.g. mutter or xf86-input-libinput).
131
132 .. graphviz:: libinput-stack-gnome.gv
133
134 This has an effect on the availability of configuration options: if an
135 option is not exposed by the intermediary, it cannot be configured by the
136 client. Also some configuration options that are provided by the
137 intermediary may not be libinput-specific configuration options.
138
139 .. _faq_configure_wayland:
140
141 ------------------------------------------------------------------------------
142 How do I configure my device on Wayland?
143 ------------------------------------------------------------------------------
144
145 See :ref:`faq_config_options` Use the configuration tool provided by your
146 desktop environment (e.g. gnome-control-center) or direct access to your
147 desktop environment's configuration storage (e.g. gsettings).
148
149 .. _faq_configure_xorg:
150
151 ------------------------------------------------------------------------------
152 How do I configure my device on X?
153 ------------------------------------------------------------------------------
154
155 See :ref:`faq_config_options` If your desktop environment does not provide a
156 graphical configuration tool you can use an
157 `xorg.conf.d snippet <https://www.x.org/archive/current/doc/man/man5/xorg.conf.5.xhtml>`_.
158 Usually, such a snippet looks like this:
159
160 ::
161
162 $> cat /etc/X11/xorg.conf.d/99-libinput-custom-config.conf
163 Section "InputClass"
164 Identifier "something to identify this snippet"
165 MatchDriver "libinput"
166 MatchProduct "substring of the device name"
167 Option "some option name" "the option value"
168 EndSection
169
170
171 The identifier is merely a human-readable string that shows up in the log
172 file. The MatchProduct line should contain the device name or a substring of
173 the device name that the snippet should apply to. For a full list of option
174 names and permitted values, see the
175 `libinput man page <https://www.mankier.com/4/libinput>`_.
176 xorg.conf.d snippets like the above apply to hotplugged devices but can be
177 overwritten at runtime by desktop tools. Multiple snippets may be placed
178 into the same file.
179
180 For run-time configuration and testing, the
181 `xinput <https://www.x.org/archive/X11R7.5/doc/man/man1/xinput.1.html>`_
182 debugging tool can modify a devices' properties. See the
183 `libinput man page <https://www.mankier.com/4/libinput>`_
184 for supported property names and values. Usually, an invocation looks like
185 this:
186
187 ::
188
189 $> xinput set-prop "the device name" "the property name" value [value2] [value3]
190
191
192 .. note:: Changes performed by xinput do not persist across device hotplugs. xinput
193 is considered a debugging and testing tool only and should not be used
194 for permanent configurations.
195
196 .. _faq_configuration:
197
198 ------------------------------------------------------------------------------
199 Can you add a configuration option for $FEATURE?
200 ------------------------------------------------------------------------------
201
202 No. At least that's going to be the initial answer. Read
203 `Why libinput doesn't have a lot of configuration options <http://who-t.blogspot.com/2016/04/why-libinput-doesnt-have-lot-of-config.html>`_
204 first. Configuration options for most features are a signal that we are incapable
205 of handling it correctly. To get to that point, we want to be sure we're
206 truly incapable of doing so. libinput has several features that
207 are handled automatically (and correctly) that users wanted to have
208 configuration options for initially.
209
210 So the answer to this question will almost always be 'no'. A configuration
211 option is, in most cases, a cop-out.
212
213 .. _faq_synclient:
214
215 ------------------------------------------------------------------------------
216 Why don't synclient and syndaemon work with libinput?
217 ------------------------------------------------------------------------------
218
219 Synclient and syndaemon rely on X input device properties that are specific
220 to the xf86-input-synaptics X.Org input driver. Both were written when the
221 synaptics driver was the only common touchpad driver in existence. They
222 assume that if the properties aren't available, no touchpad is available
223 either. The xf86-input-libinput X.Org input driver does not export these
224 driver-specific properties, synclient/syndaemon will thus not detect the
225 touchpad and refuse to work. Other tools that rely on synclient/syndaemon or
226 those same properties also do not work with xf86-input-libinput.
227
228 Most of syndaemon's functionality is built into libinput, see
229 :ref:`disable-while-typing`. synclient is merely a configuration tool, see
230 :ref:`faq_configure_xorg` for similar functionality.
231
232 See also the blog posts
233 `The definitive guide to synclient <http://who-t.blogspot.com.au/2017/01/the-definitive-guide-to-synclient.html>`_ and
234 `The future of xinput, xmodmap, setxkbmap, xsetwacom and other tools under Wayland <http://who-t.blogspot.com.au/2016/12/the-future-of-xinput-xmodmap-setxkbmap.html>`_
235
236 .. _faq_tablets:
237
238 ------------------------------------------------------------------------------
239 Does libinput support non-Wacom tablets?
240 ------------------------------------------------------------------------------
241
242 Yes, though unfortunately many non-Wacom tablets suffer from bad firmware
243 and don't send the required events. But they should all work nonetheless. If
244 you have a tablet that does not work with libinput, please
245 :ref:`file a bug <reporting_bugs>`.
246
247 .. _faq_tablet_capabilities:
248
249 ------------------------------------------------------------------------------
250 My tablet doesn't work
251 ------------------------------------------------------------------------------
252
253 If you see the message
254
255 ::
256
257 libinput bug: device does not meet tablet criteria. Ignoring this device.
258
259
260 or the message
261
262 ::
263
264 missing tablet capabilities [...] Ignoring this device.
265
266
267 your tablet device does not have the required capabilities to be treated as
268 a tablet. This is usually a problem with the device and the kernel driver.
269 See :ref:`tablet-capabilities` for more details.
270
271 .. _faq_hwdb_changes:
272
273 ------------------------------------------------------------------------------
274 How to apply hwdb changes
275 ------------------------------------------------------------------------------
276
277 Sometimes users are asked to test updates to the
278 `udev hwdb <https://www.freedesktop.org/software/systemd/man/hwdb.html>`_
279 or patches that include a change to the hwdb. See :ref:`hwdb` for
280 details on the hwdb and how to modify it locally.
281
282 .. note:: As of libinput 1.12, libinput-specific properties are now stored in
283 the :ref:`device-quirks` system. There are no libinput-specific hwdb
284 entries anymore and any changes to the hwdb must be merged into the
285 systemd repository.
286
287 .. _faq_timer_offset:
288
289 ------------------------------------------------------------------------------
290 What causes the "your system is too slow" warning?
291 ------------------------------------------------------------------------------
292
293 libinput relies on the caller to call **libinput_dispatch()** whenever data is
294 available. **libinput_dispatch()** will process the state of all devices,
295 including some time-sensitive features (e.g. palm detection, tap-to-click,
296 disable-while-typing, etc.).
297
298 If the time between the event and the call to **libinput_dispatch()**
299 is excessive, those features may not work correctly. For example, a delay in
300 touch event processing may cause wrong or missing tap-to-click events or
301 a palm may not be detected correctly.
302
303 When this warning appears, it simply means that too much time has passed
304 between the event occurring and the current time. In almost all cases this
305 is an indication of the caller being overloaded and not handling events as
306 speedily as required.
307
308 The warning has no immediate effect on libinput's behavior but some of the
309 functionality that relies on the timer may be impeded. This is not a bug in
310 libinput. libinput does not control how quickly **libinput_dispatch()** is
311 called.
312
313 .. _faq_wayland:
314
315 ------------------------------------------------------------------------------
316 Is libinput required for Wayland?
317 ------------------------------------------------------------------------------
318
319 Technically - no. But for your use-case - probably.
320
321 Wayland is a display server communication protocol. libinput is a low-level
322 library to simplify handling input devices and their events. They have no
323 direct connection. As a technical analogy, the question is similar to "is
324 glibc required for HTTP", or (stretching the analogy a bit further) "Is a
325 pen required to write English". No, it isn't.
326
327 You can use libinput without a Wayland compositor, you can write a Wayland
328 compositor without libinput. On most major distributions, libinput is the
329 standard input stack used with the X.Org X server through the
330 xf86-input-libinput driver.
331
332 So why "for your use-case - probably"? All general-purpose Wayland
333 compositors use libinput for their input stack. Wayland compositors that
334 are more specialized (e.g. in-vehicle infotainment or IVI) can handle input
335 devices directly but the compositor you want to use
336 on your desktop needs an input stack that is more complex. And right now,
337 libinput is the only input stack that exists for this use-case.
338
339 .. _faq_separate_contexts:
340
341 ------------------------------------------------------------------------------
342 Can I write a program to make libinput do $FOO
343 ------------------------------------------------------------------------------
344
345 A common question is whether it's possible to write a program that can change
346 libinput's behavior - specifically the libinput that is used inside the
347 compositor. This indicates a misunderstanding of how libinput works:
348 libinput is a library that converts kernel events into libinput events, much
349 like ``sed`` reads data in, modifies it, and provides it to stdout.
350
351 .. graphviz:: libinput-contexts.gv
352
353 A libinput context is private to the process and cannot be modified from the
354 outside. To use the ``sed`` analogy again: if ``sed`` is used by a
355 shell-script, that script has full control over how ``sed`` processes data. In
356 this analogy, ``sed`` is libinput and the shell script is the compositor. It is
357 not possible to write a program to modify the behavior of the ``sed`` instance
358 used inside that shell script.
359
360 Writing a program that uses libinput is akin to writing a new script that
361 invoke ``sed``. It will not have any effect on the original ``sed`` instance.
362
363 The only way to modify libinput's behavior is to use the configuration options
364 exposed by the respective compositor. Those affect the libinput context inside
365 the compositor and thus have an effect on the input device behavior.
366
367 .. _faq_debug_events_not_showing_configuration:
368
369 ------------------------------------------------------------------------------
370 Why doesn't libinput debug-events show my configuration
371 ------------------------------------------------------------------------------
372
373 See :ref:`faq_separate_contexts`.
374
375 ------------------------------------------------------------------------------
376 Can I configure scroll speed?
377 ------------------------------------------------------------------------------
378
379 No, or at least, not as a libinput option.
380
381 When using a mouse, libinput notifies callers about physical scroll wheel
382 movement. When using another device, libinput notifies scroll in scroll units.
383
384 It is up to the caller to transform those events into a number of pixels to
385 scroll and, if desired, provide a way to adjust scroll speed.
386
387 This transformation cannot be done in libinput because it may depend on context
388 only known by the caller. For example, a caller may want to scroll faster
389 depending on how many pages a document has or depending on the widget that
390 receives the scroll events.