path: root/doc/faqs.dox

/**
@page faq FAQs - Frequently Asked Questions

Frequently asked questions about libinput.

@section faq_fast_mouse My mouse moves too fast, even at the slowest setting

This is a symptom of high-dpi mice (greater than 1000dpi). These devices
need a udev hwdb entry to normalize their motion. See @ref
motion_normalization for a detailed explanation.

@section faq_kinetic_scrolling Kinetic scrolling does not work

The X.Org synaptics driver implemented kinetic scrolling in the driver. It
measures the scroll speed and once the finger leaves the touchpad the driver
keeps sending scroll events for a predetermined time. This effectively
provides for kinetic scrolling without client support but triggers an
unfixable [bug](https://bugs.freedesktop.org/show_bug.cgi?id=38909): the
client cannot know that the events are from a kinetic scroll source. Scroll
events in X are always sent to the current cursor position, a movement of the
cursor after lifting the finger will send the kinetic scroll events to the
new client, something the user does not usually expect. A key event during
the kinetic scroll procedure causes side-effects such as triggering zoom.

libinput does not implement kinetic scrolling for touchpads. Instead it
provides the libinput_event_pointer_get_axis_source() function that enables
callers to implement kinetic scrolling on a per-widget basis, see @ref
scroll_sources.

@section faq_gpl Is libinput GPL-licensed?

No, libinput is MIT licensed. The Linux kernel header file linux/input.h in
libinput's tree is provided to ensure the same behavior regardless of which
kernel version libinput is built on. It does not make libinput GPL-licensed.

@section faq_config_options Where is the configuration stored?

libinput does not store configuration options, it is up to the caller to
manage these and decide which configuration option to apply to each device.
This must be done at startup, after a resume and whenever a new device is
detected.

In a GNOME X.Org stack a user would usually toggle an option in
the gnome-control-center which adjusts a gsettings entry. That change is
picked up by gnome-settings-daemon and applied to the device by adjusting
input device properties that the xf86-input-libinput driver provides.
The input device property changes map to the respective libinput
configuration options.

@dotfile libinput-stack-gnome.gv

This has an effect on the availability of configuration options: if an
option is not exposed by the intermediary, it cannot be configured by the
client. Also some configuration options that are provided by the
intermediary may not be libinput-specific configuration options.

@section faq_configure_wayland How do I configure my device on Wayland?

See @ref faq_config_options Use the configuration tool provided by your
desktop environment (e.g. gnome-control-center) or direct access to your
desktop environment's configuration storage (e.g. gsettings).

@section faq_configure_xorg How do I configure my device on X?

See @ref faq_config_options  If your desktop environment does not provide a
graphical configuration tool you can use an
<a href="https://www.x.org/archive/current/doc/man/man5/xorg.conf.5.xhtml">xorg.conf.d snippet</a>.
Usually, such a snippet looks like this:
<pre>
$> cat /etc/X11/xorg.conf.d/99-libinput-custom-config.conf
Section "InputClass"
  Identifier "something to identify this snippet"
  MatchDriver "libinput"
  MatchProduct "substring of the device name"
  Option "some option name" "the option value"
EndSection
</pre>

The identifier is merely a human-readable string that shows up in the log
file. The MatchProduct line should contain the device name or a substring of
the device name that the snippet should apply to. For a full list of option
names and permitted values, see the
<a href="https://www.mankier.com/4/libinput">libinput man page</a>.
xorg.conf.d snippets like the above apply to hotplugged devices but can be
overwritten at runtime by desktop tools. Multiple snippets may be placed
into the same file.

For run-time configuration and testing, the
<a href="https://www.x.org/archive/X11R7.5/doc/man/man1/xinput.1.html">xinput</a>
debugging tool can modify a devices' properties. See the
<a href="https://www.mankier.com/4/libinput">libinput man page</a>
for supported property names and values. Usually, an invocation looks like
this:
<pre>
$> xinput set-prop "the device name" "the property name" value [value2] [value3]
</pre>

@note
Changes performed by xinput do not persist across device hotplugs. xinput is
considered a debugging and testing tool only and should not be used for
permanent configurations.

@section faq_hwdb_changes How to apply hwdb changes

Sometimes users are asked to test updates to the <a
href="https://www.freedesktop.org/software/systemd/man/hwdb.html">udev
hwdb</a> or patches that include a change to the hwdb.

If you are testing a patch with a hwdb update, the file will be installed
in the correct location. User-specific (i.e. user-written) hwdb entries for
testing and debugging must be in `/etc/udev/hwdb.d/99-filename.hwdb`. You
may rename the `filename` portion to something more useful, but make sure
you keep the `.hwdb` suffix. Do not modify files or save files in
`/usr/lib/udev/hwdb.d`.

Figure out the event node name of your device. Run `sudo evemu-describe`
with no arguments to get a list. If your device is `/dev/input/event4`,
your event node name is `event4` and you will need to replace that in the
commands below.

Rebuild the hwdb and load the new set on your device:

    sudo udevadm hwdb --update
    sudo udevadm trigger /sys/class/input/eventX
    sudo udevadm test /sys/class/input/eventX

With the event node matching your device. Make sure the udev property
appears (or does not appear, whichever applies) in the output of the test
command.

Once the output matches expectations, restart X or your Wayland
compositor or reboot.

*/