1.. _faq: 2 3============================================================================== 4FAQs - Frequently Asked Questions 5============================================================================== 6 7Frequently asked questions about libinput. 8 9 10.. contents:: 11 :local: 12 :backlinks: entry 13 14.. _faq_feature: 15 16------------------------------------------------------------------------------ 17Why doesn't libinput support ...? 18------------------------------------------------------------------------------ 19 20First, read :ref:`what_is_libinput` If you have a feature that you think 21libinput needs to support, please file a bug report. See :ref:`reporting_bugs` 22for more details. 23 24.. _faq_fast_mouse: 25 26------------------------------------------------------------------------------ 27My mouse moves too fast, even at the slowest setting 28------------------------------------------------------------------------------ 29 30This is a symptom of high-dpi mice (greater than 1000dpi). These devices 31need a udev hwdb entry to normalize their motion. See 32:ref:`motion_normalization` for a detailed explanation. 33 34.. _faq_fast_trackpoint: 35 36------------------------------------------------------------------------------ 37My trackpoint moves too slow or too fast 38------------------------------------------------------------------------------ 39 40This 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 42pointer acceleration accordingly. See :ref:`trackpoint_range` for a detailed 43explanation. 44 45.. _faq_pointer_acceleration: 46 47------------------------------------------------------------------------------ 48Why is libinput's pointer acceleration worse than synaptics/evdev 49------------------------------------------------------------------------------ 50 51This is a known problem affecting some devices and/or use-case but the exact 52cause is still unknown. It may be a device-specific issue, it may be a bug 53in libinput's acceleration code, it may be a disagreement about how pointer 54acceleration should feel. Unfortunately this is something that affected 55users need to investigate and analyze. 56 57.. _faq_enable_tapping: 58 59------------------------------------------------------------------------------ 60Why isn't touchpad tap-to-click enabled by default 61------------------------------------------------------------------------------ 62 63See :ref:`tapping_default` 64 65.. _faq_touchpad_pressure: 66 67------------------------------------------------------------------------------ 68Why does my touchpad lose track of touches 69------------------------------------------------------------------------------ 70 71The most common cause for this is an incorrect pressure threshold range. 72See :ref:`touchpad_pressure` for more info. 73 74.. _faq_kinetic_scrolling: 75 76------------------------------------------------------------------------------ 77Kinetic scrolling does not work 78------------------------------------------------------------------------------ 79 80The X.Org synaptics driver implemented kinetic scrolling in the driver. It 81measures the scroll speed and once the finger leaves the touchpad the driver 82keeps sending scroll events for a predetermined time. This effectively 83provides for kinetic scrolling without client support but triggers an 84unfixable `bug <https://bugs.freedesktop.org/show_bug.cgi?id=38909>`_: the 85client cannot know that the events are from a kinetic scroll source. Scroll 86events in X are always sent to the current cursor position, a movement of the 87cursor after lifting the finger will send the kinetic scroll events to the 88new client, something the user does not usually expect. A key event during 89the kinetic scroll procedure causes side-effects such as triggering zoom. 90 91libinput does not implement kinetic scrolling for touchpads. Instead it 92provides the **libinput_event_pointer_get_axis_source()** function that enables 93callers to implement kinetic scrolling on a per-widget basis, see 94:ref:`scroll_sources`. 95 96.. _faq_gpl: 97 98------------------------------------------------------------------------------ 99Is libinput GPL-licensed? 100------------------------------------------------------------------------------ 101 102No, libinput is MIT licensed. The Linux kernel header file linux/input.h in 103libinput's tree is provided to ensure the same behavior regardless of which 104kernel version libinput is built on. It does not make libinput GPL-licensed. 105 106.. _faq_config_options: 107 108------------------------------------------------------------------------------ 109Where is the configuration stored? 110------------------------------------------------------------------------------ 111 112libinput does not store configuration options, it is up to the caller to 113manage these and decide which configuration option to apply to each device. 114This must be done at startup, after a resume and whenever a new device is 115detected. 116 117One commonly used way to configure libinput is to have the Wayland 118compositor expose a compositor-specific configuration option. For example, 119in a GNOME stack, the gnome-control-center modifies dconf entries. These 120changes are read by mutter and applied to libinput. Changing these entries 121via the gsettings commandline tool has the same effect. 122 123Another commonly used way to configure libinput is to have xorg.conf.d 124snippets. When libinput is used with the xf86-input-libinput driver in an 125X.Org stack, these options are read on startup and apply to each device. 126Changing properties at runtime with the xinput commandline tool has the same 127effect. 128 129In both cases, the selection of available options and how they are exposed 130depends on the libinput caller (e.g. mutter or xf86-input-libinput). 131 132.. graphviz:: libinput-stack-gnome.gv 133 134This has an effect on the availability of configuration options: if an 135option is not exposed by the intermediary, it cannot be configured by the 136client. Also some configuration options that are provided by the 137intermediary may not be libinput-specific configuration options. 138 139.. _faq_configure_wayland: 140 141------------------------------------------------------------------------------ 142How do I configure my device on Wayland? 143------------------------------------------------------------------------------ 144 145See :ref:`faq_config_options` Use the configuration tool provided by your 146desktop environment (e.g. gnome-control-center) or direct access to your 147desktop environment's configuration storage (e.g. gsettings). 148 149.. _faq_configure_xorg: 150 151------------------------------------------------------------------------------ 152How do I configure my device on X? 153------------------------------------------------------------------------------ 154 155See :ref:`faq_config_options` If your desktop environment does not provide a 156graphical configuration tool you can use an 157`xorg.conf.d snippet <https://www.x.org/archive/current/doc/man/man5/xorg.conf.5.xhtml>`_. 158Usually, 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 171The identifier is merely a human-readable string that shows up in the log 172file. The MatchProduct line should contain the device name or a substring of 173the device name that the snippet should apply to. For a full list of option 174names and permitted values, see the 175`libinput man page <https://www.mankier.com/4/libinput>`_. 176xorg.conf.d snippets like the above apply to hotplugged devices but can be 177overwritten at runtime by desktop tools. Multiple snippets may be placed 178into the same file. 179 180For run-time configuration and testing, the 181`xinput <https://www.x.org/archive/X11R7.5/doc/man/man1/xinput.1.html>`_ 182debugging tool can modify a devices' properties. See the 183`libinput man page <https://www.mankier.com/4/libinput>`_ 184for supported property names and values. Usually, an invocation looks like 185this: 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------------------------------------------------------------------------------ 199Can you add a configuration option for $FEATURE? 200------------------------------------------------------------------------------ 201 202No. 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>`_ 204first. Configuration options for most features are a signal that we are incapable 205of handling it correctly. To get to that point, we want to be sure we're 206truly incapable of doing so. libinput has several features that 207are handled automatically (and correctly) that users wanted to have 208configuration options for initially. 209 210So the answer to this question will almost always be 'no'. A configuration 211option is, in most cases, a cop-out. 212 213.. _faq_synclient: 214 215------------------------------------------------------------------------------ 216Why don't synclient and syndaemon work with libinput? 217------------------------------------------------------------------------------ 218 219Synclient and syndaemon rely on X input device properties that are specific 220to the xf86-input-synaptics X.Org input driver. Both were written when the 221synaptics driver was the only commmon touchpad driver in existence. They 222assume that if the properties aren't available, no touchpad is available 223either. The xf86-input-libinput X.Org input driver does not export these 224driver-specific properties, synclient/syndaemon will thus not detect the 225touchpad and refuse to work. Other tools that rely on synclient/syndaemon or 226those same properties also do not work with xf86-input-libinput. 227 228Most 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 232See 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------------------------------------------------------------------------------ 239Does libinput support non-Wacom tablets? 240------------------------------------------------------------------------------ 241 242Yes, though unfortunately many non-Wacom tablets suffer from bad firmware 243and don't send the required events. But they should all work nonetheless. If 244you have a tablet that does not work with libinput, please 245:ref:`file a bug <reporting_bugs>`. 246 247.. _faq_tablet_capabilities: 248 249------------------------------------------------------------------------------ 250My tablet doesn't work 251------------------------------------------------------------------------------ 252 253If you see the message 254 255:: 256 257 libinput bug: device does not meet tablet criteria. Ignoring this device. 258 259 260or the message 261 262:: 263 264 missing tablet capabilities [...] Ignoring this device. 265 266 267your tablet device does not have the required capabilities to be treated as 268a tablet. This is usually a problem with the device and the kernel driver. 269See :ref:`tablet-capabilities` for more details. 270 271.. _faq_hwdb_changes: 272 273------------------------------------------------------------------------------ 274How to apply hwdb changes 275------------------------------------------------------------------------------ 276 277Sometimes users are asked to test updates to the 278`udev hwdb <https://www.freedesktop.org/software/systemd/man/hwdb.html>`_ 279or patches that include a change to the hwdb. See :ref:`hwdb` for 280details 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------------------------------------------------------------------------------ 290What causes the "your system is too slow" warning? 291------------------------------------------------------------------------------ 292 293libinput relies on the caller to call **libinput_dispatch()** whenever data is 294available. **libinput_dispatch()** will process the state of all devices, 295including some time-sensitive features (e.g. palm detection, tap-to-click, 296disable-while-typing, etc.). 297 298If the time between the event and the call to **libinput_dispatch()** 299is excessive, those features may not work correctly. For example, a delay in 300touch event processing may cause wrong or missing tap-to-click events or 301a palm may not be detected correctly. 302 303When this warning appears, it simply means that too much time has passed 304between the event occurring and the current time. In almost all cases this 305is an indication of the caller being overloaded and not handling events as 306speedily as required. 307 308The warning has no immediate effect on libinput's behavior but some of the 309functionality that relies on the timer may be impeded. This is not a bug in 310libinput. libinput does not control how quickly **libinput_dispatch()** is 311called. 312 313.. _faq_wayland: 314 315------------------------------------------------------------------------------ 316Is libinput required for Wayland? 317------------------------------------------------------------------------------ 318 319Technically - no. But for your use-case - probably. 320 321Wayland is a display server communication protocol. libinput is a low-level 322library to simplify handling input devices and their events. They have no 323direct connection. As a technical analogy, the question is similar to "is 324glibc required for HTTP", or (stretching the analogy a bit further) "Is a 325pen required to write English". No, it isn't. 326 327You can use libinput without a Wayland compositor, you can write a Wayland 328compositor without libinput. On most major distributions, libinput is the 329standard input stack used with the X.Org X server through the 330xf86-input-libinput driver. 331 332So why "for your use-case - probably"? All general-purpose Wayland 333compositors use libinput for their input stack. Wayland compositors that 334are more specialized (e.g. in-vehicle infotainment or IVI) can handle input 335devices directly but the compositor you want to use 336on your desktop needs an input stack that is more complex. And right now, 337libinput is the only input stack that exists for this use-case. 338