Debian Codegraph @

doc/user/what-is-libinput.rst

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