libinput

This is the libinput API reference.

This documentation is aimed at developers of Wayland compositors. User documentation is available here.

Concepts

Initialization of a libinput context

libinput provides two different backends:

See section Initialization and manipulation of libinput contexts for information about initializing a libinput context.

Monitoring for events

libinput exposes a single file descriptor to the caller. This file descriptor should be monitored by the caller, whenever data is available the caller must immediately call libinput_dispatch(). Failure to do so will result in erroneous behavior.

libinput_dispatch() may result in one or more events being available to the caller. After libinput_dispatch() a caller should call libinput_get_event() to retrieve and process this event. Whenever libinput_get_event() returns NULL, no further events are available.

See section Accessing and destruction of events for more information about events.

Device grouping into seats

All devices are grouped into physical and logical seats. Button and key states are available per-device and per-seat. See Initialization and manipulation of seats for more information.

Device capabilities

libinput does not use device types. All devices have capabilities that define which events may be generated. See Initialization and manipulation of input devices for more information about devices.

Specific event types include:

Device configuration

libinput relies on the caller for device configuration. See Device configuration for more information.

An example libinput program

The simplest libinput program looks like this:

static int open_restricted(const char *path, int flags, void *user_data)
{
int fd = open(path, flags);
return fd < 0 ? -errno : fd;
}
static void close_restricted(int fd, void *user_data)
{
close(fd);
}
const static struct libinput_interface interface = {
.close_restricted = close_restricted,
};
int main(void) {
struct libinput *li;
struct libinput_event *event;
li = libinput_udev_create_context(&interface, NULL, udev);
while ((event = libinput_get_event(li)) != NULL) {
// handle the event here
}
return 0;
}
int libinput_dispatch(struct libinput *libinput)
Main event dispatchment function.
struct libinput_event * libinput_get_event(struct libinput *libinput)
Retrieve the next event from libinput's internal event queue.
struct libinput * libinput_udev_create_context(const struct libinput_interface *interface, void *user_data, struct udev *udev)
Create a new libinput context from udev.
int libinput_udev_assign_seat(struct libinput *libinput, const char *seat_id)
Assign a seat to this libinput context.
struct libinput * libinput_unref(struct libinput *libinput)
Dereference the libinput context.
void libinput_event_destroy(struct libinput_event *event)
Destroy the event, freeing all associated resources.
The base event type.
libinput does not open file descriptors to devices directly, instead open_restricted() and close_rest...
Definition: libinput.h:3501
int(* open_restricted)(const char *path, int flags, void *user_data)
Open the device at the given path with the flags provided and return the fd.
Definition: libinput.h:3513
void(* close_restricted)(int fd, void *user_data)
Close the file descriptor.
Definition: libinput.h:3521
A handle for accessing libinput.

Building against libinput

libinput provides a pkg-config file. Software that uses libinput should use pkg-config and the PKG_CHECK_MODULES autoconf macro. Otherwise, the most rudimentary way to compile and link a program against libinput is:

    gcc -o myprogram myprogram.c `pkg-config --cflags --libs libinput`

For further information on using pkgconfig see the pkg-config documentation.

Backwards-compatibility

libinput promises backwards-compatibility across all the 1.x.y version. An application built against libinput 1.x.y will work with any future 1.*.* release.

About

Documentation generated from git commit 1680f2fb