1=========================
2X11 Display/Inputs driver
3=========================
4
5Overview
6--------
7
8| The **X11** display/input `driver <https://github.com/lvgl/lvgl/src/drivers/x11>`__ offers support for simulating the LVGL display and keyboard/mouse inputs in an X11 desktop window.
9| It is an alternative to **Wayland**, **XCB**, **SDL** or **Qt**.
10
11The main purpose for this driver is for testing/debugging the LVGL application in a **Linux** simulation window.
12
13
14Prerequisites
15-------------
16
17The X11 driver uses XLib to access the linux window manager.
18
191. Install XLib: ``sudo apt-get install libx11-6`` (should be installed already)
202. Install XLib development package: ``sudo apt-get install libx11-dev``
21
22
23Configure X11 driver
24--------------------
25
261. Enable the X11 driver support in lv_conf.h, by cmake compiler define or by KConfig
27    .. code-block:: c
28
29        #define LV_USE_X11  1
30
312. Optional configuration options:
32    -  Direct Exit
33        .. code-block:: c
34
35            #define LV_X11_DIRECT_EXIT  1 /* preferred default - ends the application automatically if last window has been closed */
36            // or
37            #define LV_X11_DIRECT_EXIT  0 /* application is responsible for ending the application (e.g. by own LV_EVENT_DELETE handler */
38
39
40    -  Double buffering
41        .. code-block:: c
42
43            #define LV_X11_DOUBLE_BUFFER  1 /* preferred default */
44            // or
45            #define LV_X11_DOUBLE_BUFFER  0 /* not recommended */
46
47    - Render mode
48        .. code-block:: c
49
50            #define LV_X11_RENDER_MODE_PARTIAL 1  /* LV_DISPLAY_RENDER_MODE_PARTIAL, preferred default */
51            // or
52            #define LV_X11_RENDER_MODE_DIRECT  1  /* LV_DISPLAY_RENDER_MODE_DIRECT, not recommended for X11 driver */
53            // or
54            #define LV_X11_RENDER_MODE_DULL    1  /* LV_DISPLAY_RENDER_MODE_FULL, not recommended for X11 driver */
55
56Usage
57-----
58
59| The minimal initialisation opening a window and enabling keyboard/mouse support
60| (e.g. in main.c, LV_X11_DIRECT_EXIT must be 1):
61
62.. code-block:: c
63
64    int main(int argc, char ** argv)
65    {
66        ...
67
68        /* initialize X11 display driver */
69        lv_display_t * disp = lv_x11_window_create("LVGL X11 Simulation", monitor_hor_res, monitor_ver_res);
70
71        /* initialize X11 input drivers (for keyboard, mouse & mousewheel) */
72        lv_x11_inputs_create(disp, NULL);
73
74        ...
75
76        while(true)
77        {
78            ...
79
80            /* Periodically call the lv_timer handler */
81            lv_timer_handler();
82        }
83    }
84
85| Full initialisation with mouse pointer symbol and own application exit handling
86| (dependent on LV_X11_DIRECT_EXIT (can be 1 or 0))
87
88.. code-block:: c
89
90    bool terminated = false;
91
92    #if !LV_X11_DIRECT_EXIT
93    static void on_close_cb(lv_event_t * e)
94    {
95        ...
96
97        terminate = true;
98    }
99    #endif
100
101    int main(int argc, char ** argv)
102    {
103        ...
104
105        /* initialize X11 display driver */
106        lv_display_t * disp = lv_x11_window_create("LVGL X11 Simulation", monitor_hor_res, monitor_ver_res);
107        lv_display_add_event_cb(disp, on_close_cb, LV_EVENT_DELETE, disp);
108
109        /* initialize X11 input drivers (for keyboard, mouse & mousewheel) */
110        LV_IMAGE_DECLARE(my_mouse_cursor_icon);
111        lv_x11_inputs_create(disp, &my_mouse_cursor_icon);
112
113        #if !LV_X11_DIRECT_EXIT
114        /* set optional window close callback to enable application cleanup and exit */
115        lv_x11_window_set_close_cb(disp, on_close_cb, disp);
116        #endif
117
118        ...
119
120        while(!terminated)
121        {
122            ...
123
124            /* Periodically call the lv_timer handler */
125            lv_timer_handler();
126        }
127    }
128