1===============
2Libinput Driver
3===============
4
5Overview
6--------
7
8Libinput is an input stack for processes that need to provide events from commonly used input devices. That includes mice, keyboards, touchpads,
9touchscreens and graphics tablets. Libinput handles device-specific quirks and provides an easy-to-use API to receive events from devices.
10
11Prerequisites
12-------------
13
14You have the development version of libinput installed (usually ``libinput-dev``). If your input device requires quirks, make sure they are
15installed as well (usually in ``/usr/share/libinput/*.quirks``). To test if your device is set up correctly for use with libinput, you can
16run ``libinput list-devices``.
17
18.. code-block:: console
19
20    $ sudo libinput list-devices
21    ...
22    Device:           ETPS/2 Elantech Touchpad
23    Kernel:           /dev/input/event5
24    Group:            10
25    Seat:             seat0, default
26    Size:             102x74mm
27    Capabilities:     pointer gesture
28    Tap-to-click:     disabled
29    Tap-and-drag:     enabled
30    ...
31
32If your device doesn't show up, you may have to configure udev and the appropriate udev rules to connect it.
33
34Additionally, if you want full keyboard support, including letters and modifiers, you'll need the development version of libxkbcommon
35installed (usually ``libxkbcommon-dev``).
36
37Configuring the driver
38----------------------
39
40Enable the libinput driver support in lv_conf.h, by cmake compiler define or by KConfig.
41
42.. code-block:: c
43
44    #define LV_USE_LIBINPUT    1
45
46Full keyboard support needs to be enabled separately.
47
48.. code-block:: c
49
50    #define LV_LIBINPUT_XKB            1
51    #define LV_LIBINPUT_XKB_KEY_MAP    { .rules = NULL, .model = "pc101", .layout = "us", .variant = NULL, .options = NULL }
52
53To find the right key map values, you may use the ``setxkbmap -query`` command.
54
55Usage
56-----
57
58To set up an input device via the libinput driver, all you need to do is call ``lv_libinput_create`` with the respective device type
59(``LV_INDEV_TYPE_POINTER`` or ``LV_INDEV_TYPE_KEYPAD``) and device node path (e.g. ``/dev/input/event5``).
60
61.. code-block:: c
62
63    lv_indev_t *indev = lv_libinput_create(LV_INDEV_TYPE_POINTER, "/dev/input/event5");
64
65Note that touchscreens are treated as (absolute) pointer devices by the libinput driver and require ``LV_INDEV_TYPE_POINTER``.
66
67Depending on your system, the device node paths might not be stable across reboots. If this is the case, you can use ``lv_libinput_find_dev``
68to find the first device that has a specific capability.
69
70.. code-block:: c
71
72    char *path = lv_libinput_find_dev(LV_LIBINPUT_CAPABILITY_TOUCH, true);
73
74The second argument controls whether or not all devices are rescanned. If you have many devices connected this can get quite slow.
75Therefore, you should only specify ``true`` on the first call when calling this method multiple times in a row. If you want to find
76all devices that have a specific capability, use ``lv_libinput_find_devs``.
77
78If you want to connect a keyboard device to a textarea, create a dedicated input group and set it on both the indev and textarea.
79
80.. code-block:: c
81
82    lv_obj_t *textarea = lv_textarea_create(...);
83    ...
84    lv_group_t *keyboard_input_group = lv_group_create();
85    lv_indev_set_group(indev, keyboard_input_group);
86    lv_group_add_obj(keyboard_input_group, textarea);
87
88