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:

• a udev backend where notifications about new and removed devices are provided by udev, and
• a path backend where device addition and device removal need to be handled by the caller.

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:

• Keyboard events
• Pointer events
• Touch events
• Gesture events
• Tablet events
• Tablet pad events
• Switch events

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 = {
        .open_restricted = open_restricted,
        .close_restricted = close_restricted,
};
 
 
int main(void) {
        struct libinput *li;
        struct libinput_event *event;
 
        li = libinput_udev_create_context(&interface, NULL, udev);
        libinput_udev_assign_seat(li, "seat0");
        libinput_dispatch(li);
 
        while ((event = libinput_get_event(li)) != NULL) {
 
                // handle the event here
 
                libinput_event_destroy(event);
                libinput_dispatch(li);
        }
 
        libinput_unref(li);
 
        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 d1e49c7b