X11

The X11 driver opens a window on an X11 desktop and reads mouse, mousewheel and keyboard input, mainly for simulating an LVGL application on a Linux development machine.

Edit on GitHub

Overview

The X11 display/input driver opens a window on an X11 desktop through Xlib and reads mouse, mousewheel and keyboard input.

X11 is a CPU-blit driver with no GPU path. For production embedded targets prefer DRM or Wayland.

Configuration

Enable LV_USE_X11.

LV_COLOR_FORMAT_DEFAULT must be LV_COLOR_FORMAT_RGB565, LV_COLOR_FORMAT_RGB888 or LV_COLOR_FORMAT_XRGB8888.

Options

Symbol	Default	Effect
`LV_X11_RENDER_MODE`	`LV_DISPLAY_RENDER_MODE_PARTIAL`	Render mode
`LV_X11_DOUBLE_BUFFER`	on	Use two buffers
`LV_X11_DIRECT_EXIT`	on	Exit the application once all windows are closed

Building

The driver always requires xlib.

LVGL's CMake integration resolves it for you. Make sure the required libraries are present on your system or in your sysroot.

See Dependency Management.

Usage

Create the window with lv_x11_window_create, then attach input with lv_x11_inputs_create. The second argument is an optional cursor image; pass NULL for none.

int main(int argc, char ** argv)
{
    lv_init();

    lv_display_t * disp = lv_x11_window_create("LVGL X11 Simulation", 800, 480);

    /* Keyboard, mouse and mousewheel */
    lv_x11_inputs_create(disp, NULL);

    lv_demo_widgets();

    while(1) {
        uint32_t time_until_next = lv_timer_handler();
        if(time_until_next == LV_NO_TIMER_READY) time_until_next = LV_DEF_REFR_PERIOD;
        lv_delay_ms(time_until_next);
    }
}

Call lv_x11_window_create again to open more windows; each returns its own display.

Handling window closure yourself

With LV_X11_DIRECT_EXIT off, the application decides what happens when a window closes. Register an LV_EVENT_DELETE handler on the display and run your own loop condition:

static bool terminated = false;

static void on_close_cb(lv_event_t * e)
{
    LV_UNUSED(e);
    terminated = true;
}

int main(int argc, char ** argv)
{
    lv_init();

    lv_display_t * disp = lv_x11_window_create("LVGL X11 Simulation", 800, 480);
    lv_display_add_event_cb(disp, on_close_cb, LV_EVENT_DELETE, disp);

    /* Attach inputs, optionally with a cursor image */
    LV_IMAGE_DECLARE(mouse_cursor_icon);
    lv_x11_inputs_create(disp, &mouse_cursor_icon);

    while(!terminated) {
        uint32_t time_until_next = lv_timer_handler();
        if(time_until_next == LV_NO_TIMER_READY) time_until_next = LV_DEF_REFR_PERIOD;
        lv_delay_ms(time_until_next);
    }

    /* Clean up here */
}

Support

Capability	Value
Rotation	None
Runtime resolution change	Yes
Runtime color format change	No
Color formats	RGB565, RGB888 or XRGB8888, from `LV_COLOR_FORMAT_DEFAULT`
Multiple displays / windows	Yes, one display per window
Hardware acceleration	None
Render mode	Configurable via `LV_X11_RENDER_MODE`
Input	Built in. Mouse, mousewheel and keyboard via `lv_x11_inputs_create`

X11