Debian Codegraph @

doc/api/mainpage.dox

raw
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 */