| 1 |
/** |
| 2 |
@mainpage |
| 3 |
|
| 4 |
This is the libinput API reference. |
| 5 |
|
| 6 |
This documentation is aimed at developers of Wayland compositors. User |
| 7 |
documentation 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 |
|
| 14 |
libinput 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 |
|
| 22 |
See section @ref base for information about initializing a libinput context. |
| 23 |
|
| 24 |
@subsection concepts_events Monitoring for events |
| 25 |
|
| 26 |
libinput exposes a single @ref libinput_get_fd "file descriptor" to the |
| 27 |
caller. This file descriptor should be monitored by the caller, whenever |
| 28 |
data is available the caller **must** immediately call libinput_dispatch(). |
| 29 |
Failure to do so will result in erroneous behavior. |
| 30 |
|
| 31 |
libinput_dispatch() may result in one or more events being available to the |
| 32 |
caller. After libinput_dispatch() a caller **should** call |
| 33 |
libinput_get_event() to retrieve and process this event. Whenever |
| 34 |
libinput_get_event() returns `NULL`, no further events are available. |
| 35 |
|
| 36 |
See section @ref event for more information about events. |
| 37 |
|
| 38 |
@subsection concepts_seats Device grouping into seats |
| 39 |
|
| 40 |
All devices are grouped into physical and logical seats. Button and key |
| 41 |
states are available per-device and per-seat. See @ref seat for more |
| 42 |
information. |
| 43 |
|
| 44 |
@subsection concepts_devices Device capabilities |
| 45 |
|
| 46 |
libinput does not use device types. All devices have @ref |
| 47 |
libinput_device_has_capability "capabilities" that define which events may |
| 48 |
be generated. See @ref device for more information about devices. |
| 49 |
|
| 50 |
Specific 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 |
|
| 62 |
libinput relies on the caller for device configuration. See |
| 63 |
@ref config for more information. |
| 64 |
|
| 65 |
@subsection example An example libinput program |
| 66 |
|
| 67 |
The simplest libinput program looks like this: |
| 68 |
|
| 69 |
@code |
| 70 |
static 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 |
|
| 76 |
static void close_restricted(int fd, void *user_data) |
| 77 |
{ |
| 78 |
close(fd); |
| 79 |
} |
| 80 |
|
| 81 |
const static struct libinput_interface interface = { |
| 82 |
.open_restricted = open_restricted, |
| 83 |
.close_restricted = close_restricted, |
| 84 |
}; |
| 85 |
|
| 86 |
|
| 87 |
int 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 |
|
| 112 |
libinput provides a |
| 113 |
[pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/) file. |
| 114 |
Software that uses libinput should use pkg-config and the |
| 115 |
`PKG_CHECK_MODULES` autoconf macro. |
| 116 |
Otherwise, the most rudimentary way to compile and link a program against |
| 117 |
libinput is: |
| 118 |
|
| 119 |
@verbatim |
| 120 |
gcc -o myprogram myprogram.c `pkg-config --cflags --libs libinput` |
| 121 |
@endverbatim |
| 122 |
|
| 123 |
For further information on using pkgconfig see the pkg-config documentation. |
| 124 |
|
| 125 |
@section stability Backwards-compatibility |
| 126 |
|
| 127 |
libinput promises backwards-compatibility across all the 1.x.y version. An |
| 128 |
application built against libinput 1.x.y will work with any future 1.*.* |
| 129 |
release. |
| 130 |
|
| 131 |
@section About |
| 132 |
|
| 133 |
Documentation generated from git commit [__GIT_VERSION__](https://gitlab.freedesktop.org/libinput/libinput/commit/__GIT_VERSION__) |
| 134 |
|
| 135 |
*/ |