libinput Documentation

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;
}

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 f8032ba7

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:3318
int libinput_udev_assign_seat(struct libinput *libinput, const char *seat_id)
int libinput_dispatch(struct libinput *libinput)
void(* close_restricted)(int fd, void *user_data)
Close the file descriptor.
Definition: libinput.h:3326
Definition: libinput.h:96
struct libinput * libinput_unref(struct libinput *libinput)
Definition: libinput.h:3306
struct libinput * libinput_udev_create_context(const struct libinput_interface *interface, void *user_data, struct udev *udev)
void libinput_event_destroy(struct libinput_event *event)
struct libinput_event * libinput_get_event(struct libinput *libinput)