| 1 |
|
| 2 |
.. _what_is_libinput: |
| 3 |
|
| 4 |
============================================================================== |
| 5 |
What is libinput? |
| 6 |
============================================================================== |
| 7 |
|
| 8 |
This page describes what libinput is, but more importantly it also describes |
| 9 |
what libinput is **not**. |
| 10 |
|
| 11 |
.. _what_libinput_is: |
| 12 |
|
| 13 |
------------------------------------------------------------------------------ |
| 14 |
What libinput is |
| 15 |
------------------------------------------------------------------------------ |
| 16 |
|
| 17 |
libinput is an input stack for processes that need to provide events from |
| 18 |
commonly used input devices. That includes mice, keyboards, touchpads, |
| 19 |
touchscreens and graphics tablets. libinput handles device-specific quirks |
| 20 |
and provides an easy-to-use API to receive events from devices. |
| 21 |
|
| 22 |
libinput is designed to handle all input devices available on a system but |
| 23 |
it is possible to limit which devices libinput has access to. |
| 24 |
For example, the use of xf86-input-libinput depends on xorg.conf snippets |
| 25 |
for specific devices. But libinput works best if it handles all input |
| 26 |
devices as this allows for smarter handling of features that affect multiple |
| 27 |
devices. |
| 28 |
|
| 29 |
libinput restricts device-specific features to those devices that require |
| 30 |
those features. One example for this are the top software buttons on the |
| 31 |
touchpad in the Lenovo T440. While there may be use-cases for providing top |
| 32 |
software buttons on other devices, libinput does not do so. |
| 33 |
|
| 34 |
`This introductory blog post from 2015 |
| 35 |
<https://who-t.blogspot.com/2015/06/libinput-and-lack-of-device-types.html>`_ |
| 36 |
describes some of the motivations. |
| 37 |
|
| 38 |
.. _what_libinput_is_not: |
| 39 |
|
| 40 |
------------------------------------------------------------------------------ |
| 41 |
What libinput is not |
| 42 |
------------------------------------------------------------------------------ |
| 43 |
|
| 44 |
libinput is **not** a project to support experimental devices. Unless a |
| 45 |
device is commonly available off-the-shelf, libinput will not support this |
| 46 |
device. libinput can serve as a useful base for getting experimental devices |
| 47 |
enabled and reduce the amount of boilerplate required. But such support will |
| 48 |
not land in libinput master until the devices are commonly available. |
| 49 |
|
| 50 |
libinput is **not** a box of legos. It does not provide the pieces to |
| 51 |
assemble a selection of features. Many features can be disabled through |
| 52 |
configuration options, but some features are hardcoded and/or only available |
| 53 |
on some devices. There are plenty of use-cases to provide niche features, |
| 54 |
but libinput is not the place to support these. |
| 55 |
|
| 56 |
libinput is **not** a showcase for features. There are a lot of potential |
| 57 |
features that could be provided on input devices. But unless they have |
| 58 |
common usage, libinput is not the place to implement them. Every feature |
| 59 |
multiplies the maintenance effort, any feature that is provided but unused |
| 60 |
is a net drain on the already sparse developer resources libinput has |
| 61 |
available. |
| 62 |
|
| 63 |
libinput is boring. It does not intend to break new grounds on how devices |
| 64 |
are handled. Instead, it takes best practice and the common use-cases and |
| 65 |
provides it in an easy-to-consume package for compositors or other processes |
| 66 |
that need those interactions typically expected by users. |
| 67 |
|
| 68 |
.. _libinput-wayland: |
| 69 |
|
| 70 |
------------------------------------------------------------------------------ |
| 71 |
libinput and Wayland |
| 72 |
------------------------------------------------------------------------------ |
| 73 |
|
| 74 |
libinput is not used directly by Wayland applications, it is an input stack |
| 75 |
used by the compositor. The typical software stack for a system running |
| 76 |
Wayland is: |
| 77 |
|
| 78 |
.. graphviz:: libinput-stack-wayland.gv |
| 79 |
|
| 80 |
The Wayland compositor may be Weston, mutter, KWin, etc. Note that |
| 81 |
Wayland encourages the use of toolkits, so the Wayland client (your |
| 82 |
application) does not usually talk directly to the compositor but rather |
| 83 |
employs a toolkit (e.g. GTK) to do so. The Wayland client does not know |
| 84 |
whether libinput is in use. |
| 85 |
|
| 86 |
libinput is not a requirement for Wayland or even a Wayland compositor. |
| 87 |
There are some specialized compositors that do not need or want libinput. |
| 88 |
|
| 89 |
.. _libinput-xorg: |
| 90 |
|
| 91 |
------------------------------------------------------------------------------ |
| 92 |
libinput and X.Org |
| 93 |
------------------------------------------------------------------------------ |
| 94 |
|
| 95 |
libinput is not used directly by X applications but rather through the |
| 96 |
custom xf86-input-libinput driver. The simplified software stack for a |
| 97 |
system running X.Org is: |
| 98 |
|
| 99 |
.. graphviz:: libinput-stack-xorg.gv |
| 100 |
|
| 101 |
libinput is not employed directly by the X server but by the |
| 102 |
xf86-input-libinput driver instead. That driver is loaded by the server |
| 103 |
on demand, depending on the xorg.conf.d configuration snippets. The X client |
| 104 |
does not know whether libinput is in use. |
| 105 |
|
| 106 |
libinput and xf86-input-libinput are not a requirement, the driver will only |
| 107 |
handle those devices explicitly assigned through an xorg.conf.d snippets. It |
| 108 |
is possible to mix xf86-input-libinput with other X.Org drivers. |
| 109 |
|
| 110 |
------------------------------------------------------------------------------ |
| 111 |
Device types |
| 112 |
------------------------------------------------------------------------------ |
| 113 |
|
| 114 |
libinput handles all common devices used to interact with a desktop system. |
| 115 |
This includes mice, keyboards, touchscreens, touchpads and graphics tablets. |
| 116 |
libinput does not expose the device type to the caller, it solely provides |
| 117 |
capabilities and the attached features (see |
| 118 |
`this blog post <https://who-t.blogspot.com/2015/06/libinput-and-lack-of-device-types.html>`_). |
| 119 |
|
| 120 |
For example, a touchpad in libinput is a device that provides pointer |
| 121 |
events, gestures and has a number of :ref:`config_options` such as |
| 122 |
:ref:`tapping`. A caller may present the device as touchpad to the user, or |
| 123 |
simply as device with a config knob to enable or disable tapping. |
| 124 |
|
| 125 |
.............................................................................. |
| 126 |
Handled device types |
| 127 |
.............................................................................. |
| 128 |
|
| 129 |
- :ref:`Touchpads` |
| 130 |
- Touchscreens |
| 131 |
- Mice |
| 132 |
- Keyboards |
| 133 |
- Virtual absolute pointing devices such as those used by QEMU or VirtualBox |
| 134 |
- Switches (Lid Switch and Tablet Mode switch) |
| 135 |
- Graphics tablets |
| 136 |
- :ref:`Trackpoints` |
| 137 |
|
| 138 |
If a device falls into one of the above categories but does not work as |
| 139 |
expected, please :ref:`file a bug <reporting_bugs>`. |
| 140 |
|
| 141 |
.............................................................................. |
| 142 |
Unhandled device types |
| 143 |
.............................................................................. |
| 144 |
|
| 145 |
libinput does not handle some devices. The primary reason is that these |
| 146 |
device have no clear interaction with a desktop environment. |
| 147 |
|
| 148 |
Joysticks: |
| 149 |
Joysticks have one or more axes and one or more buttons. Beyond that it is |
| 150 |
difficult to find common ground between joysticks and much of the |
| 151 |
interaction is application-specific, not system-specific. libinput does not |
| 152 |
provide support for joysticks for that reason, any abstraction libinput |
| 153 |
would provide for joysticks would be so generic that libinput would |
| 154 |
merely introduce complexity and processing delays for no real benefit. |