| 1 |
.. _lua_plugins: |
| 2 |
|
| 3 |
============================================================================== |
| 4 |
Lua Plugins |
| 5 |
============================================================================== |
| 6 |
|
| 7 |
libinput provides a plugin system that allows users to modify the behavior |
| 8 |
of devices. For example, a plugin may add or remove axes and/or buttons on a |
| 9 |
device and/or modify the event stream seen by this device before it is passed |
| 10 |
to libinput. |
| 11 |
|
| 12 |
Plugins are implemented in `Lua <https://www.lua.org/>`_ (version 5.4) |
| 13 |
and are typically loaded from the following paths: |
| 14 |
|
| 15 |
- ``/etc/libinput/plugins/*.lua``, and |
| 16 |
- ``/usr/lib{64}/libinput/plugins/*.lua`` |
| 17 |
|
| 18 |
Plugins are loaded in alphabetical order and where |
| 19 |
multiple plugins share the same file name, the one in the highest precedence |
| 20 |
directory is used. Plugins in ``/etc`` take precedence over |
| 21 |
plugins in ``/usr``. |
| 22 |
|
| 23 |
.. note:: Plugins lookup paths and their order are decided by the compositor. |
| 24 |
Some compositors may support more/fewer/other lookup paths than the |
| 25 |
above defaults. |
| 26 |
|
| 27 |
Plugins are run sequentially in ascending sort-order (i.e. ``00-foo.lua`` runs |
| 28 |
before ``10-bar.lua``) and each plugin sees the state left by any previous |
| 29 |
plugins. For example if ``00-foo.lua`` changes all left button events to right |
| 30 |
button events, ``10-bar.lua`` only ever sees right button events. |
| 31 |
|
| 32 |
See the `Lua Reference manual <https://www.lua.org/manual/5.4/manual.html>`_ for |
| 33 |
details on the Lua language. |
| 34 |
|
| 35 |
.. note:: Plugins are **not** loaded by default, it is up to the compositor |
| 36 |
whether to allow plugins. An explicit call to |
| 37 |
``libinput_plugin_system_load_plugins()`` is required. |
| 38 |
|
| 39 |
------------------------------------------------------------------------------ |
| 40 |
Limitations |
| 41 |
------------------------------------------------------------------------------ |
| 42 |
|
| 43 |
Each script runs in its own sandbox and cannot communicate or share state with |
| 44 |
other scripts. |
| 45 |
|
| 46 |
Tables that hold API methods are not writable, i.e. it is not possible |
| 47 |
to overwrite the default functionality of those APIs. |
| 48 |
|
| 49 |
The Lua API available to plugins is limited to the following calls:: |
| 50 |
|
| 51 |
assert error ipairs next pairs tonumber |
| 52 |
pcall select print tostring type xpcall |
| 53 |
table string math _VERSION |
| 54 |
|
| 55 |
It is not possible to e.g. use the ``io`` module from a script. |
| 56 |
|
| 57 |
To use methods on instantiated objects, the ``object:method`` method call |
| 58 |
syntax must be used. For example: |
| 59 |
|
| 60 |
.. code-block:: lua |
| 61 |
|
| 62 |
libinput:register() |
| 63 |
libinput.register() -- this will fail |
| 64 |
|
| 65 |
------------------------------------------------------------------------------ |
| 66 |
When to use plugins |
| 67 |
------------------------------------------------------------------------------ |
| 68 |
|
| 69 |
libinput plugins are a relatively niche use-case that typically need to |
| 70 |
address either once-off issues (e.g. those caused by worn-out hardware) or |
| 71 |
user preferences that libinput does not and will not cater for. |
| 72 |
|
| 73 |
Plugins should not be used for issues that can be fixed generically, for |
| 74 |
example via :ref:`device-quirks`. |
| 75 |
|
| 76 |
As a rule of thumb: a plugin should be a once-off that only works for one |
| 77 |
user's hardware. If a plugin can be shared with many users then the plugin |
| 78 |
implements functionality that should be integrated into libinput proper. |
| 79 |
|
| 80 |
------------------------------------------------------------------------------ |
| 81 |
Testing plugins |
| 82 |
------------------------------------------------------------------------------ |
| 83 |
|
| 84 |
Our :ref:`tools` support plugins if passed the ``--enable-plugins`` commandline |
| 85 |
option. For implementing and testing plugins the easiest commands to test are |
| 86 |
|
| 87 |
- ``libinput debug-events --enable-plugins`` (see :ref:`libinput-debug-events` docs) |
| 88 |
- ``libinput debug-gui --enable-plugins`` (see :ref:`libinput-debug-gui` docs) |
| 89 |
|
| 90 |
Where libinput is built and run from git, the tools will also look for plugins |
| 91 |
in the meson build directory. See the ``plugins/meson.build`` file for details. |
| 92 |
|
| 93 |
.. _plugins_api_lua: |
| 94 |
|
| 95 |
-------------------------------------------------------------------------------- |
| 96 |
Lua Plugin API |
| 97 |
-------------------------------------------------------------------------------- |
| 98 |
|
| 99 |
Lua plugins sit effectively below libinput and the API is not a |
| 100 |
representation of the libinput API. Plugins modify the evdev event stream |
| 101 |
received from the kernel. |
| 102 |
|
| 103 |
.. graphviz:: plugin-stack.gv |
| 104 |
|
| 105 |
The API revolves around two types: ``libinput`` and ``EvdevDevice``. The |
| 106 |
``libinput`` type is used to register a plugin from a script, the |
| 107 |
``EvdevDevice`` represents one device that is present in the system (but may |
| 108 |
not have yet been added by libinput). |
| 109 |
|
| 110 |
Typically a script does the following steps: |
| 111 |
|
| 112 |
- register with libinput via ``libinput:register({versions})`` |
| 113 |
- connect to the ``"new-evdev-device"`` event |
| 114 |
- receive an ``EvdevDevice`` object in the ``"new-evdev-device"`` callback |
| 115 |
|
| 116 |
- check and/or modify the evdev event codes on the device |
| 117 |
- connect to the device's ``"evdev-frame"`` event |
| 118 |
|
| 119 |
- receive an :ref:`evdev frame <plugins_api_evdev_frame>` in the device's |
| 120 |
``"evdev-frame"`` callback |
| 121 |
|
| 122 |
- check and/or modify the events in that frame |
| 123 |
|
| 124 |
Where multiple plugins are active, the evdev frame passed to the callback is |
| 125 |
the combined frame as processed by all previous plugins in ascending sort order. |
| 126 |
For example, if one plugin discards all button events subsequent plugins will |
| 127 |
never see those button events in the frame. |
| 128 |
|
| 129 |
.. _plugins_api_version_stability: |
| 130 |
|
| 131 |
.............................................................................. |
| 132 |
Plugin version stability |
| 133 |
.............................................................................. |
| 134 |
|
| 135 |
Plugin API version stability is provided on a best effort basis. We aim to provide |
| 136 |
stable plugin versions for as long as feasible but may need to retire some older |
| 137 |
versions over time. For this reason a plugin can select multiple versions it |
| 138 |
implements, libinput will pick one supported version and adjust the plugin |
| 139 |
behavior to match that version. See the ``libinput:register()`` call for details. |
| 140 |
|
| 141 |
-------------------------------------------------------------------------------- |
| 142 |
Lua Plugin API Reference |
| 143 |
-------------------------------------------------------------------------------- |
| 144 |
|
| 145 |
|
| 146 |
libinput provides the following globals and types: |
| 147 |
|
| 148 |
.. _plugins_api_evdev_usage: |
| 149 |
|
| 150 |
................................................................................ |
| 151 |
Evdev Usages |
| 152 |
................................................................................ |
| 153 |
|
| 154 |
Evdev usages are a libinput-specific wrapper around the ``linux/input-event-codes.h`` |
| 155 |
evdev types and codes. They are used by libinput internally and are a 32-bit |
| 156 |
combination of ``type << 16 | code``. Each usage carries the type and code and |
| 157 |
is thus simpler to pass around and less prone to type confusion. |
| 158 |
|
| 159 |
The :ref:`evdev global <plugins_api_evdev_global>` attempts to provide all |
| 160 |
available usages but for the niche cases where it does not provide a named constant |
| 161 |
the value can be crafted manually: |
| 162 |
|
| 163 |
.. code-block:: lua |
| 164 |
|
| 165 |
evdev_type = 0x3 -- EV_REL |
| 166 |
evdev_code = 0x1 -- REL_Y |
| 167 |
evdev_usage = (evdev_type << 16) | evdev_code |
| 168 |
|
| 169 |
assert(usage == evdev.REL_Y) |
| 170 |
|
| 171 |
.. _plugins_api_evdev_global: |
| 172 |
|
| 173 |
................................................................................ |
| 174 |
The ``evdev`` global |
| 175 |
................................................................................ |
| 176 |
|
| 177 |
The ``evdev`` global represents all known :ref:`plugins_api_evdev_usage`, |
| 178 |
effectively in the form: |
| 179 |
|
| 180 |
.. code-block:: lua |
| 181 |
|
| 182 |
evdev = { |
| 183 |
ABS_X = (3 << 16) | 0, |
| 184 |
ABS_Y = (3 << 16) | 1, |
| 185 |
... |
| 186 |
REL_X = (2 << 16) | 0, |
| 187 |
REL_Y = (2 << 16) | 1, |
| 188 |
... |
| 189 |
} |
| 190 |
|
| 191 |
|
| 192 |
This global is provided for convenience to improve readability in the code. |
| 193 |
Note that the name uses the event code name only (e.g. ``evdev.ABS_Y``) but the |
| 194 |
value is an :ref:`Evdev Usage <plugins_api_evdev_usage>` (type and code). |
| 195 |
|
| 196 |
See the ``linux/input-event-codes.h`` header file provided by your kernel |
| 197 |
for a list of all evdev types and codes. |
| 198 |
|
| 199 |
The evdev global also provides the bus type constants, e.g. ``evdev.BUS_USB``. |
| 200 |
See the ``linux/input.h`` header file provided by your kernel |
| 201 |
for a list of bus types. |
| 202 |
|
| 203 |
|
| 204 |
.. _plugins_api_evdev_frame: |
| 205 |
|
| 206 |
................................................................................ |
| 207 |
Evdev frames |
| 208 |
................................................................................ |
| 209 |
|
| 210 |
Evdev frames represent a single frame of evdev events for a device. A frame |
| 211 |
is a group of events that occurred at the same time. The frame usually only |
| 212 |
contains state that has changed compared to the previous frame. |
| 213 |
|
| 214 |
In our API a frame is exposed as a nested table with the following structure: |
| 215 |
|
| 216 |
.. code-block:: lua |
| 217 |
|
| 218 |
frame1 = { |
| 219 |
{ usage = evdev.ABS_X, value = 123 }, |
| 220 |
{ usage = evdev.ABS_Y, value = 456 }, |
| 221 |
{ usage = evdev.BTN_LEFT, value = 1 }, |
| 222 |
} |
| 223 |
frame2 = { |
| 224 |
{ usage = evdev.ABS_Y, value = 457 }, |
| 225 |
} |
| 226 |
frame3 = { |
| 227 |
{ usage = evdev.ABS_X, value = 124 }, |
| 228 |
{ usage = evdev.BTN_LEFT, value = 0 }, |
| 229 |
} |
| 230 |
|
| 231 |
.. note:: This API does not use ``SYN_REPORT`` events, it is implied at the |
| 232 |
end of the table. Where a plugin writes a ``SYN_REPORT`` into the |
| 233 |
list of events, that ``SYN_REPORT`` terminates the event frame |
| 234 |
(similar to writing a ``\0`` into the middle of a C string). |
| 235 |
A frame containing only a ``SYN_REPORT`` is functionally equivalent |
| 236 |
to an empty frame. |
| 237 |
|
| 238 |
Events or frames do not have a timestamp. Where a timestamp is required, that |
| 239 |
timestamp is passed as additional argument to the function or return value. |
| 240 |
|
| 241 |
See :ref:`plugins_api_evdev_global` for a list of known usages. |
| 242 |
|
| 243 |
.. warning:: Evdev frames have an implementation-defined size limit of how many |
| 244 |
events can be added to a single frame. This limit should never be |
| 245 |
hit by valid plugins. |
| 246 |
|
| 247 |
.. _plugins_api_libinputglobal: |
| 248 |
|
| 249 |
................................................................................ |
| 250 |
The ``libinput`` global object |
| 251 |
................................................................................ |
| 252 |
|
| 253 |
The core of our plugin API is the ``libinput`` global object. A script must |
| 254 |
immediately ``register()`` to be active, otherwise it is unloaded immediately. |
| 255 |
|
| 256 |
All libinput-specific APIs can be accessed through the ``libinput`` object. |
| 257 |
|
| 258 |
.. function:: libinput:register({1, 2, ...}) |
| 259 |
|
| 260 |
Register this plugin with the given table of supported version numbers and |
| 261 |
returns the version number selected by libinput for this plugin. See |
| 262 |
:ref:`plugins_api_version_stability` for details. |
| 263 |
|
| 264 |
.. code-block:: lua |
| 265 |
|
| 266 |
-- this plugin can support versions 1, 4 and 5 |
| 267 |
version = libinput:register({1, 4, 5}) |
| 268 |
if version == 1 then |
| 269 |
... |
| 270 |
|
| 271 |
This function must be the first function called. |
| 272 |
If the plugin calls any other functions before ``register()``, those functions |
| 273 |
return the default zero value for the return type (``nil``, ``0``, an empty |
| 274 |
table, etc.). |
| 275 |
|
| 276 |
If the plugin does not call ``register()`` it will be removed immediately. |
| 277 |
Once registered, any connected callbacks will be invoked whenever libinput |
| 278 |
detects new devices, removes devices, etc. |
| 279 |
|
| 280 |
This function must only be called once. |
| 281 |
|
| 282 |
.. function:: libinput:unregister() |
| 283 |
|
| 284 |
Unregister this plugin. This removes the plugin from libinput and releases |
| 285 |
any resources associated with this plugin. This call must be the last call |
| 286 |
in your plugin, it is effectively equivalent to Lua's |
| 287 |
`os.exit() <https://www.lua.org/manual/5.4/manual.html#pdf-os.exit>`_. |
| 288 |
|
| 289 |
.. function:: libinput:log_debug(message) |
| 290 |
|
| 291 |
Log a message at the libinput debug log priority. See |
| 292 |
``libinput:log_error()`` for details. |
| 293 |
|
| 294 |
.. function:: libinput:log_info(message) |
| 295 |
|
| 296 |
Log a message at the libinput info log priority. See |
| 297 |
``libinput:log_error()`` for details. |
| 298 |
|
| 299 |
.. function:: libinput:log_error(message) |
| 300 |
|
| 301 |
Log a message at the libinput error log priority. Whether a message is |
| 302 |
displayed in the log depends on libinput's log priority, set by the caller. |
| 303 |
|
| 304 |
A compositor may disable stdout and stderr. Log messages should be preferred |
| 305 |
over Lua's ``print()`` function to ensure the messages end up in the same |
| 306 |
location as other libinput log messages and are not discarded. |
| 307 |
|
| 308 |
.. function:: libinput:now() |
| 309 |
|
| 310 |
Returns the current time in microseconds in ``CLOCK_MONOTONIC``. This is |
| 311 |
the timestamp libinput uses internally. This timestamp cannot be mapped |
| 312 |
to any particular time of day, see the |
| 313 |
`clock_gettime() man page <https://man7.org/linux/man-pages/man3/clock_gettime.3.html>`_ |
| 314 |
for details. |
| 315 |
|
| 316 |
.. function:: libinput:version() |
| 317 |
|
| 318 |
Returns the agreed-on version of the plugin, see ``libinput:register()``. |
| 319 |
If called before ``libinput:register()`` this function returns ``0``. |
| 320 |
|
| 321 |
.. function:: libinput:connect(name, function) |
| 322 |
|
| 323 |
Set the callback to the given event name. Only one callback |
| 324 |
may be set for an event name at any time, subsequent callbacks |
| 325 |
will replace any earlier callbacks for the same name. |
| 326 |
|
| 327 |
Version 1 of the plugin API supports the following events and callback arguments: |
| 328 |
|
| 329 |
- ``"new-evdev-device"``: A new :ref:`EvdevDevice <plugins_api_evdevdevice>` |
| 330 |
has been seen by libinput but not yet added. |
| 331 |
|
| 332 |
.. code-block:: lua |
| 333 |
|
| 334 |
libinput:connect("new-evdev-device", function (device) ... end) |
| 335 |
|
| 336 |
- ``"timer-expired"``: The timer for this plugin has expired. This event is |
| 337 |
only sent if the plugin has set a timer with ``timer_set()``. |
| 338 |
|
| 339 |
.. code-block:: lua |
| 340 |
|
| 341 |
libinput:connect("timer-expired", function (now) ... end) |
| 342 |
|
| 343 |
The ``now`` argument is the current time in microseconds in |
| 344 |
``CLOCK_MONOTONIC`` (see ``libinput:now()``). |
| 345 |
|
| 346 |
.. function:: libinput:timer_cancel() |
| 347 |
|
| 348 |
Cancel the timer for this plugin. This is a no-op if the timer |
| 349 |
has not been set or has already expired. |
| 350 |
|
| 351 |
.. function:: libinput:timer_set_absolute(time) |
| 352 |
|
| 353 |
Set a timer for this plugin, with the given time in microseconds. |
| 354 |
The timeout specifies an absolute time in microseconds (see |
| 355 |
``libinput:now()``) The timer will expire once and then call the |
| 356 |
``"timer-expired"`` event handler (if any). |
| 357 |
|
| 358 |
See ``libinput:timer_set_relative()`` for a relative timer. |
| 359 |
|
| 360 |
The following two lines of code are equivalent: |
| 361 |
|
| 362 |
.. code-block:: lua |
| 363 |
|
| 364 |
libinput:timer_set_relative(1000000) -- 1 second from now |
| 365 |
libinput:timer_set_absolute(libinput:now() + 1000000) -- 1 second from now |
| 366 |
|
| 367 |
Calling this function will cancel any existing (relative or absolute) timer. |
| 368 |
|
| 369 |
.. function:: libinput:timer_set_relative(timeout) |
| 370 |
|
| 371 |
Set a timer for this plugin, with the given timeout in microseconds from |
| 372 |
the current time. The timer will expire once and then call the |
| 373 |
``"timer-expired"`` event handler (if any). |
| 374 |
|
| 375 |
See ``libinput:timer_set_absolute()`` for an absolute timer. |
| 376 |
|
| 377 |
The following two lines of code are equivalent: |
| 378 |
|
| 379 |
.. code-block:: lua |
| 380 |
|
| 381 |
libinput:timer_set_relative(1000000) -- 1 second from now |
| 382 |
libinput:timer_set_absolute(libinput:now() + 1000000) -- 1 second from now |
| 383 |
|
| 384 |
Calling this function will cancel any existing (relative or absolute) timer. |
| 385 |
|
| 386 |
.. _plugins_api_evdevdevice: |
| 387 |
|
| 388 |
................................................................................ |
| 389 |
The ``EvdevDevice`` type |
| 390 |
................................................................................ |
| 391 |
|
| 392 |
The ``EvdevDevice`` type represents a device available in the system |
| 393 |
but not (yet) added by libinput. This device may be used to modify |
| 394 |
a device's capabilities before the device is processed by libinput. |
| 395 |
|
| 396 |
A plugin should always ``connect()`` to the ``"device-removed"`` callback |
| 397 |
to be notified when a device is removed. If the plugin keeps a reference |
| 398 |
to this device but the device is discarded by libinput, the device's query |
| 399 |
methods will return zero values (e.g. ``nil``, ``0``, an empty table) and |
| 400 |
methods will be noops. |
| 401 |
|
| 402 |
.. function:: EvdevDevice:info() |
| 403 |
|
| 404 |
A table containing static information about the device, e.g. |
| 405 |
|
| 406 |
.. code-block:: lua |
| 407 |
|
| 408 |
{ |
| 409 |
bustype = evdev.BUS_USB, |
| 410 |
vid = 0x1234, |
| 411 |
pid = 0x5678, |
| 412 |
} |
| 413 |
|
| 414 |
A plugin must ignore keys it does not know about. |
| 415 |
|
| 416 |
Version 1 of the plugin API supports the following keys and values: |
| 417 |
|
| 418 |
- ``bustype``: The numeric bustype of the device. See the |
| 419 |
``BUS_*`` defines in ``linux/input.h`` for the list of possible values. |
| 420 |
- ``vid``: The 16-bit vendor ID of the device |
| 421 |
- ``pid``: The 16-bit product ID of the device |
| 422 |
|
| 423 |
If the device has since been discarded by libinput, this function returns an |
| 424 |
empty table. |
| 425 |
|
| 426 |
.. function:: EvdevDevice:name() |
| 427 |
|
| 428 |
The device name as set by the kernel |
| 429 |
|
| 430 |
.. function:: EvdevDevice:usages() |
| 431 |
|
| 432 |
Returns a table of all usages that are currently enabled for this |
| 433 |
device. Any type that exists on the device has a table assigned and in this |
| 434 |
table any code that exists on the device is a boolean true. |
| 435 |
For example: |
| 436 |
|
| 437 |
.. code-block:: lua |
| 438 |
|
| 439 |
{ |
| 440 |
evdev.REL_X = true, |
| 441 |
evdev.REL_Y = true, |
| 442 |
evdev.BTN_LEFT = true, |
| 443 |
} |
| 444 |
|
| 445 |
All other usages are ``nil``, so that the following code is possible: |
| 446 |
|
| 447 |
.. code-block:: lua |
| 448 |
|
| 449 |
local usages = device:usages() |
| 450 |
if usages[evdev.REL_X] then |
| 451 |
-- do something |
| 452 |
end |
| 453 |
|
| 454 |
|
| 455 |
If the device has since been discarded by libinput, this function returns an |
| 456 |
empty table. |
| 457 |
|
| 458 |
.. function:: EvdevDevice:absinfos() |
| 459 |
|
| 460 |
Returns a table of all ``EV_ABS`` codes that are currently enabled for this device. |
| 461 |
The event code is the key, each value is a table containing the following keys: |
| 462 |
``minimum``, ``maximum``, ``fuzz``, ``flat``, ``resolution``. |
| 463 |
|
| 464 |
.. code-block:: lua |
| 465 |
|
| 466 |
{ |
| 467 |
evdev.ABS_X = { |
| 468 |
minimum = 0, |
| 469 |
maximum = 1234, |
| 470 |
fuzz = 0, |
| 471 |
flat = 0, |
| 472 |
resolution = 45, |
| 473 |
}, |
| 474 |
} |
| 475 |
|
| 476 |
If the device has since been discarded by libinput, this function returns an |
| 477 |
empty table. |
| 478 |
|
| 479 |
.. function:: EvdevDevice:udev_properties() |
| 480 |
|
| 481 |
Returns a table containing a filtered list of udev properties available on this device |
| 482 |
in the form ``{ property_name = property_value, ... }``. |
| 483 |
udev properties used as a boolean (e.g. ``ID_INPUT``) are only present if their |
| 484 |
value is a logical true. |
| 485 |
|
| 486 |
Version 1 of the plugin API supports the following udev properties: |
| 487 |
|
| 488 |
- ``ID_INPUT`` and all of ``ID_INPUT_*`` that denote the device type as assigned |
| 489 |
by udev. This information is usually used by libinput to determine a |
| 490 |
device type. Note that for historical reasons these properties have |
| 491 |
varying rules - some properties may be mutually exclusive, others are |
| 492 |
independent, others may only be set if another property is set. Refer to |
| 493 |
the udev documentation (if any) for details. ``ID_INPUT_WIDTH_MM`` and |
| 494 |
``ID_INPUT_HEIGHT_MM`` are excluded from this set. |
| 495 |
|
| 496 |
If the device has since been discarded by libinput, this function returns an |
| 497 |
empty table. |
| 498 |
|
| 499 |
.. function:: EvdevDevice:enable_evdev_usage(usage) |
| 500 |
|
| 501 |
Enable the given :ref:`evdev usage <plugins_api_evdev_usage>` for this device. |
| 502 |
Use :ref:`plugins_api_evdev_global` for better readability, |
| 503 |
e.g. ``device:enable_evdev_usage(evdev.REL_X)``. |
| 504 |
This function must not be used for ``ABS_*`` events, use ``set_absinfo()`` |
| 505 |
instead. |
| 506 |
|
| 507 |
Once a usage is enabled, events for that usage may be added to a device's |
| 508 |
frame. |
| 509 |
|
| 510 |
If the device has since been discarded by libinput, this function does nothing. |
| 511 |
|
| 512 |
.. function:: EvdevDevice:disable_evdev_usage(usage) |
| 513 |
|
| 514 |
Disable the given :ref:`evdev usage <plugins_api_evdev_usage>` for this device. |
| 515 |
Use :ref:`plugins_api_evdev_global` for better readability, |
| 516 |
e.g. ``device:disable_evdev_usage(evdev.REL_X)``. |
| 517 |
|
| 518 |
Once a usage is disabled, events for that usage are discarded from any |
| 519 |
device frame. |
| 520 |
|
| 521 |
If the device has since been discarded by libinput, this function does nothing. |
| 522 |
|
| 523 |
.. function:: EvdevDevice:set_absinfo(usage, absinfo) |
| 524 |
|
| 525 |
Set the absolute axis information for the given :ref:`evdev usage <plugins_api_evdev_usage>` |
| 526 |
and enable it if it does not yet exist on the device. The ``absinfo`` argument is a table |
| 527 |
containing zero or more of the following keys: ``minimum``, ``maximum``, ``fuzz``, |
| 528 |
``flat``, ``resolution``. Any missing key defaults the corresponding |
| 529 |
value from the device if the device already has this event usage or zero otherwise. |
| 530 |
For example, the following code changes the resolution but leaves everything |
| 531 |
else as-is: |
| 532 |
|
| 533 |
.. code-block:: lua |
| 534 |
|
| 535 |
local absinfo = { |
| 536 |
resolution = 40, |
| 537 |
} |
| 538 |
device:set_absinfo(evdev.ABS_X, absinfo) |
| 539 |
device:set_absinfo(evdev.ABS_Y, absinfo) |
| 540 |
|
| 541 |
Use :ref:`plugins_api_evdev_global` for better readability as shown in the |
| 542 |
example above. |
| 543 |
|
| 544 |
If the device has since been discarded by libinput, this function does nothing. |
| 545 |
|
| 546 |
.. note:: Overriding the absinfo values often indicates buggy firmware. This should |
| 547 |
typically be fixed with an entry in the |
| 548 |
`60-evdev.hwdb <https://github.com/systemd/systemd/blob/main/hwdb.d/60-evdev.hwdb>`_ |
| 549 |
or :ref:`device-quirks` instead of a plugin so all users of that |
| 550 |
device can benefit from the fix. |
| 551 |
|
| 552 |
.. function:: EvdevDevice:connect(name, function) |
| 553 |
|
| 554 |
Set the callback to the given event name. Only one callback |
| 555 |
may be set for an event name at any time, subsequent callbacks |
| 556 |
will overwrite any earlier callbacks for the same name. |
| 557 |
|
| 558 |
If the device has since been discarded by libinput, this function does nothing. |
| 559 |
|
| 560 |
Version 1 of the plugin API supports the following events and callback arguments: |
| 561 |
|
| 562 |
- ``"evdev-frame"``: A new :ref:`evdev frame <plugins_api_evdev_frame>` has |
| 563 |
started for this device. If the callback returns a value other than |
| 564 |
``nil``, that value is the frame with any modified events. |
| 565 |
An empty frame (``{}``) causes libinput to drop the current event frame. |
| 566 |
|
| 567 |
.. code-block:: lua |
| 568 |
|
| 569 |
device:connect("evdev-frame", function (device, frame, timestamp) |
| 570 |
-- change any event into a movement left by 1 pixel |
| 571 |
move_left = { |
| 572 |
{ usage = evdev.REL_X, value = -1, }, |
| 573 |
} |
| 574 |
return move_left |
| 575 |
end |
| 576 |
|
| 577 |
The timestamp of an event frame is in microseconds in ``CLOCK_MONOTONIC``, see |
| 578 |
``libinput:now()`` for details. |
| 579 |
|
| 580 |
For performance reasons plugins that do not modify the event frame should |
| 581 |
return ``nil`` (or nothing) instead of the event frame that was passed |
| 582 |
as argument. |
| 583 |
|
| 584 |
- ``"device-removed"``: This device was removed by libinput. This may happen |
| 585 |
without the device ever becoming a libinput device as seen by libinput's |
| 586 |
public API (e.g. if the device does not meet the requirements to be |
| 587 |
added). Once this callback is invoked, the plugin should remove any |
| 588 |
references to this device and stop using it. |
| 589 |
|
| 590 |
.. code-block:: lua |
| 591 |
|
| 592 |
device:connect("device-removed", function (device) ... end) |
| 593 |
|
| 594 |
Functions to query the device's capabilities (e.g. ``usages()``) will |
| 595 |
return an empty table. |
| 596 |
|
| 597 |
.. function:: EvdevDevice:disconnect(name) |
| 598 |
|
| 599 |
Disconnect the existing callback (if any) for the given event name. See |
| 600 |
``EvdevDevice:connect()`` for a list of supported names. |
| 601 |
|
| 602 |
.. function:: EvdevDevice:prepend_frame(frame) |
| 603 |
|
| 604 |
Prepend an :ref:`evdev frame <plugins_api_evdev_frame>` for this device |
| 605 |
**before** the current frame (if any). The **next** plugin will see the |
| 606 |
prepended frame first followed by the current frame. |
| 607 |
|
| 608 |
This function can only be called from within a device's ``"evdev-frame"`` |
| 609 |
handler or from within the plugin's timer callback function. |
| 610 |
|
| 611 |
For example, to change a single event into a drag, prepend a button |
| 612 |
down and append a button up before each event: |
| 613 |
|
| 614 |
.. code:: lua |
| 615 |
|
| 616 |
function frame_handler(device, frame, timestamp) |
| 617 |
device:prepend_frame({ |
| 618 |
{ usage = evdev.BTN_LEFT, value = 1} |
| 619 |
}) |
| 620 |
device:append_frame({ |
| 621 |
{ usage = evdev.BTN_LEFT, value = 0} |
| 622 |
}) |
| 623 |
return nil -- return the current frame unmodified |
| 624 |
|
| 625 |
-- The next plugin sees the event sequence: |
| 626 |
-- button down, frame, button up |
| 627 |
end |
| 628 |
|
| 629 |
If called from within the plugin's timer there is no current frame and this |
| 630 |
function is identical to ``append_frame()``. |
| 631 |
|
| 632 |
.. function:: EvdevDevice:append_frame(frame) |
| 633 |
|
| 634 |
Appends an :ref:`evdev frame <plugins_api_evdev_frame>` for this device |
| 635 |
**after** the current frame (if any). This function can only be called from |
| 636 |
within a device's ``"evdev-frame"`` handler or from within the plugin's timer |
| 637 |
callback function. |
| 638 |
|
| 639 |
If called from within the plugin's timer there is no current frame and this |
| 640 |
function is identical to ``prepend_frame()``. |
| 641 |
|
| 642 |
See ``prepend_frame()`` for more details. |
| 643 |
|
| 644 |
.. function:: EvdevDevice:disable_feature(feature_name) |
| 645 |
|
| 646 |
Disable the given libinput-internal feature for this device. This should be used |
| 647 |
by plugins that replace that feature with a custom implementation for this device. |
| 648 |
|
| 649 |
libinput may have multiple internal implementations for any given feature, disabling |
| 650 |
it via this API disables any and all of those implementations, causing the feature to |
| 651 |
no longer work at all. It is up to the plugin implementation to re-implement that |
| 652 |
feature to match the user's expectation. |
| 653 |
|
| 654 |
Version 1 of the plugin API supports the following features: |
| 655 |
|
| 656 |
- ``"button-debouncing"``: see :ref:`button_debouncing` |
| 657 |
- ``"touchpad-hysteresis"``: see :ref:`touchpad_jitter` |
| 658 |
- ``"touchpad-jump-detection"``: see :ref:`touchpad_jumping_cursor` |
| 659 |
- ``"touchpad-palm-detection"``: see :ref:`palm_detection` |
| 660 |
- ``"wheel-debouncing"``: some high-resolution mouse wheel movements inside libinput |
| 661 |
are delayed and/or modified |