1/** 2@mainpage 3 4This is the libinput API reference. 5 6This documentation is aimed at developers of Wayland compositors. User 7documentation is available 8[here](https://wayland.freedesktop.org/libinput/doc/latest). 9 10@section concepts Concepts 11 12@subsection concepts_initialization Initialization of a libinput context 13 14libinput provides two different backends: 15- a @ref libinput_udev_create_context "udev backend" where notifications 16 about new and removed devices are provided by udev, and 17- a @ref libinput_path_create_context "path backend" where 18 @ref libinput_path_add_device "device addition" and 19 @ref libinput_path_remove_device "device removal" need to be handled by 20 the caller. 21 22See section @ref base for information about initializing a libinput context. 23 24@subsection concepts_events Monitoring for events 25 26libinput exposes a single @ref libinput_get_fd "file descriptor" to the 27caller. This file descriptor should be monitored by the caller, whenever 28data is available the caller **must** immediately call libinput_dispatch(). 29Failure to do so will result in erroneous behavior. 30 31libinput_dispatch() may result in one or more events being available to the 32caller. After libinput_dispatch() a caller **should** call 33libinput_get_event() to retrieve and process this event. Whenever 34libinput_get_event() returns `NULL`, no further events are available. 35 36See section @ref event for more information about events. 37 38@subsection concepts_seats Device grouping into seats 39 40All devices are grouped into physical and logical seats. Button and key 41states are available per-device and per-seat. See @ref seat for more 42information. 43 44@subsection concepts_devices Device capabilities 45 46libinput does not use device types. All devices have @ref 47libinput_device_has_capability "capabilities" that define which events may 48be generated. See @ref device for more information about devices. 49 50Specific event types include: 51- @ref event_keyboard 52- @ref event_pointer 53- @ref event_touch 54- @ref event_gesture 55- @ref event_tablet 56- @ref event_tablet_pad 57- @ref event_switch 58 59 60@subsection concepts_configuration Device configuration 61 62libinput relies on the caller for device configuration. See 63@ref config for more information. 64 65@subsection example An example libinput program 66 67The simplest libinput program looks like this: 68 69@code 70static int open_restricted(const char *path, int flags, void *user_data) 71{ 72 int fd = open(path, flags); 73 return fd < 0 ? -errno : fd; 74} 75 76static void close_restricted(int fd, void *user_data) 77{ 78 close(fd); 79} 80 81const static struct libinput_interface interface = { 82 .open_restricted = open_restricted, 83 .close_restricted = close_restricted, 84}; 85 86 87int main(void) { 88 struct libinput *li; 89 struct libinput_event *event; 90 91 li = libinput_udev_create_context(&interface, NULL, udev); 92 libinput_udev_assign_seat(li, "seat0"); 93 libinput_dispatch(li); 94 95 while ((event = libinput_get_event(li)) != NULL) { 96 97 // handle the event here 98 99 libinput_event_destroy(event); 100 libinput_dispatch(li); 101 } 102 103 libinput_unref(li); 104 105 return 0; 106} 107 108@endcode 109 110@section building_against Building against libinput 111 112libinput provides a 113[pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/) file. 114Software that uses libinput should use pkg-config and the 115`PKG_CHECK_MODULES` autoconf macro. 116Otherwise, the most rudimentary way to compile and link a program against 117libinput is: 118 119@verbatim 120 gcc -o myprogram myprogram.c `pkg-config --cflags --libs libinput` 121@endverbatim 122 123For further information on using pkgconfig see the pkg-config documentation. 124 125@section stability Backwards-compatibility 126 127libinput promises backwards-compatibility across all the 1.x.y version. An 128application built against libinput 1.x.y will work with any future 1.*.* 129release. 130 131@section About 132 133Documentation generated from git commit [__GIT_VERSION__](https://gitlab.freedesktop.org/libinput/libinput/commit/__GIT_VERSION__) 134 135*/ 136