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