lvglpp: a C++ wrapper for LVGL

This package contains a rather bushy wrapper for LVGL. I originally needed to program a simple user interface, but I didn't want to write a GUI framework from scratch, and found LVGL rather nice. Only that it's written in C. So I started writing C++ classes for the part of the code I wanted to use, and then it got out of control. Now most of the library has some kind of wrapper class provided. I've tested nearly all examples on an ESP32 with a touch screen interface. You can find a working application here.

This is a work in progress. I will likely improve things as I use it, which will take between one day and forever. I of course welcome contributions.

At the time of writing, I use LVGL version 8.3 (available here). Your C++ compiler must support C++17 or newer.

Note that I'm not part of the LVGL team. If you have requests related to LVGL itself, please ask them.

TL;DR

See examples here and docs in the doc folder (you need to clone the repository for that).

Structure

I tried to mirror the directory structure of LVGL to some degree (with exceptions with extra and hal directories). A number of types that are defined in multiple files are compiled together as one (e.g. style, image, draw). I've put all the widgets (including extra ones) in the widgets directory.

My point was to provide functions that take a certain LVGL object type as first argument as a class method. For instance, all functions taking a lv_obj_t* as first argument end up as methods of the Object class. I tried to replace raw pointer args either with a C++ class instance passed by reference or a smart pointer.

There is a template class in lv_wrapper.h, PointerWrapper<lv_class, lv_deleter>, to facilitate encapsulation. It stores a unique_ptr of type lv_class with custom deleter function lv_deleter. A number of LVGL types have an associated deleter function, which can be provided there. For widgets, there's a template class called Widget<lv_allocator> that provides a constructor to nest objects.

Here is a list of classes with the corresponding link to LVGL:

Class	File	Wrapped type	LVGL file(s)
Display	core/display.h	lv_disp_t lv_disp_drv_t	hal/lv_hal_disp.h core/lv_disp.h
Event	core/event.h	lv_event_t	core/lv_event.h
Group	core/group.h	lv_group_t	core/lv_group.h
InputDevice PointerInputDevice ButtonInputDevice KeypadInputDevice EncoderInputDevice	core/indev.h	lv_indev_t lv_indev_drv_t	hal/lv_hal_indev.h core/lv_indev.h
Object	core/object.h	lv_obj_t	core/lv_obj.h core/lv_obj_draw.h core/lv_obj_pos.h core/lv_scroll.h core/lv_obj_style.h core/lv_obj_style_gen.h core/lv_obj_tree.h extra/layouts/flex/lv_flex.h extra/layouts/grid/lv_grid.h
Theme	core/theme.h	lv_theme_t	core/lv_theme.h
RectangleDrawDescriptor	draw/desc.h	lv_draw_rect_dsc_t	draw/lv_draw_rect.h
LabelDrawDescriptor	draw/desc.h	lv_draw_label_dsc_t	draw/lv_draw_label.h
ImageDrawDescriptor	draw/desc.h	lv_draw_img_dsc_t	draw/lv_draw_img.h
LineDrawDescriptor	draw/desc.h	lv_draw_line_dsc_t	draw/lv_draw_line.h
ArcDrawDescriptor	draw/desc.h	lv_draw_arc_dsc_t	draw/lv_draw_arc.h
ImageDecoder	draw/image.h	lv_img_decoder_dsc_t	draw/lv_img_decoder.h
ImageHeader	draw/image.h	lv_img_header_t	draw/lv_img_buf.h
ImageDescriptor	draw/image.h	lv_img_dsc_t	draw/lv_img_buf.h
LineMask	draw/mask.h	lv_draw_mask_line_param_t	draw/lv_draw_mask.h
AngleMask	draw/mask.h	lv_draw_mask_angle_param_t	draw/lv_draw_mask.h
RadiusMask	draw/mask.h	lv_draw_mask_radius_param_t	draw/lv_draw_mask.h
FadeMask	draw/mask.h	lv_draw_mask_fade_param_t	draw/lv_draw_mask.h
MapMask	draw/mask.h	lv_draw_mask_map_param_t	draw/lv_draw_mask.h
PolygonMask	draw/mask.h	lv_draw_mask_polygon_param_t	draw/lv_draw_mask.h
Font	font/font.h	lv_font_t	font/lv_font.h
Animation	misc/anim.h	lv_anim_t	misc/lv_anim.h
AnimationTimeline	misc/anim.h	lv_anim_timeline_t	misc/lv_anim_timeline.h
Area	misc/area.h	lv_area_t	misc/lv_area.h
FileSystem	misc/fs.h	lv_fs_t	misc/lv_fs.h
File	misc/fs.h	lv_fs_file_t	misc/lv_fs.h
Directory	misc/fs.h	lv_fs_dir_t	misc/lv_fs.h
Style	misc/style.h	lv_style_t	misc/lv_style.h misc/lv_style_gen.h
Timer	misc/timer.h	lv_timer_t	misc/lv_timer.h
AnimatedImage	widgets/animimg/animimg.h	lv_animimg_t	extra/widgets/animimg/lv_animimg.h
Arc	widgets/arc/arc.h	lv_arc_t	widgets/lv_arc.h
Bar	widgets/bar/bar.h	lv_bar_t	widgets/lv_bar.h
ButtonMatrix	widgets/btnmatrix/btnmatrix.h	lv_btnmatrix_t	widgets/lv_btnmatrix.h
Button	widgets/button/button.h	lv_btn_t	widgets/lv_btn.h
Calendar	widgets/calendar/calendar.h	lv_calendar_t	extra/widgets/calendar/lv_calendar.h
Canvas	widgets/canvas/canvas.h	lv_canvas_t	widgets/lv_canvas.h
Chart	widgets/chart/chart.h	lv_chart_t	extra/widgets/chart/lv_chart.h
Checkbox	widgets/checkbox/checkbox.h	lv_checkbox_t	widgets/lv_checkbox.h
ColorWheel	widgets/colorwheel/colorwheel.h	lv_colorwheel_t	extra/widgets/colorwheel/lv_colorwheel.h
Dropdown	widgets/dropdown/dropdown.h	lv_dropdown_t	widgets/lv_dropdown.h
Image	widgets/image/image.h	lv_image_t	widgets/lv_img.h
ImageButton	widgets/imgbtn/imgbtn.h	lv_imgbtn_t	extra/widgets/imgbtn/lv_imgbtn.h
Keyboard	widgets/keyboard/keyboard.h	lv_keyboard_t	extra/widgets/keyboard/lv_keyboard.h
Label	widgets/label/label.h	lv_label_t	widgets/lv_label.h
Led	widgets/led/led.h	lv_led_t	extra/widgets/led/lv_led.h
Line	widgets/line/line.h	lv_line_t	widgets/lv_line.h
List	widgets/list/list.h	lv_list_t	extra/widgets/list/lv_list.h
Menu	widgets/menu/menu.h	lv_menu_t	extra/widgets/menu/lv_menu.h
Meter	widgets/meter/meter.h	lv_meter_t	extra/widgets/meter/lv_meter.h
MessageBox	widgets/msgbox/msgbox.h	lv_msgbox_t	extra/widgets/msgbox/lv_msgbox.h
Roller	widgets/roller/roller.h	lv_roller_t	widgets/lv_roller.h
Slider	widgets/slider/slider.h	lv_slider_t	widgets/lv_slider.h
Span	widgets/span/span.h	lv_span_t	extra/widgets/span/lv_span.h
Spinbox	widgets/spinbox/spinbox.h	lv_spinbox_t	extra/widgets/spinbox/lv_spinbox.h
Spinner	widgets/spinner/spinner.h	lv_spinner_t	extra/widgets/spinner/lv_spinner.h
Switch	widgets/switch/switch.h	lv_switch_t	widgets/lv_switch.h
Table	widgets/table/table.h	lv_table_t	widgets/lv_table.h
Tabview	widgets/tabview/tabview.h	lv_tabview_t	extra/widgets/tabview/lv_tabview.h
TextArea	widgets/textarea/textarea.h	lv_textarea_t	widgets/lv_textarea.h
TileView	widgets/tileview/tileview.h	lv_tileview_t	extra/widgets/tileview/lv_tileview.h
Window	widgets/win/win.h	lv_win_t	extra/widgets/win/lv_win.h

I've included some useful functions that don't take a specific LVGL type as argument in namespaces. These are:

Namespace	Content
lvgl::core::obj	For now, contains the function draw_part_check_type, that allows checking the type of a drawable part. I may move other functions related to objects there in the future.
lvgl::draw::mask	This contains functions about masks.
lvgl::misc::color	Since lv_color_t is a uint32_t with some coating, I found inefficient to build a class around it. Therefore, you'll find color functions in there.
lvgl::misc::palette	Access to the three standard palettes is found here in a C++ way.
lvgl::misc::txt	This contains some of the text functions found in lv_txt.h.

How to use

First of all, you need LVGL in the include paths. As for lvglpp, unlike with LVGL, you need to include each header that corresponds to what you want to use. To illustrate what I mean, a typical program would be:

#include "lvglpp/lvglpp.h" // for init
#include "lvglpp/core/display.h" // for Display
#include "lvglpp/core/indev.h" // for InputDevice
#include "lvglpp/widgets/button.h" // for Button
// ... add includes for widgets your want to use here
#include "lvglpp/misc/style.h" // for Style
// .. add includes for other classes you want to use (Animation, Timer, ...)

using namespace lvgl::core;
using namespace lvgl::misc;
using namespace lvgl::widgets;

void main() {
    // initialize LVGL
    lvgl::init();
    // place here display and input device initialization;
    // read examples in examples/lvglpp directory to see how.

    // create button on active display
    auto btn = Button(scr_act());
    btn.center();
    // ... initialize more things ...

    // main loop
    for (;;) {
        // I didn't implement ticks yet -> use base LVGL ones;
        // you need to call both of these to get LVGL to work, but
        // you should put them in two different threads, with lv_tick_inc
        // in a higher priority thread.
        lv_tick_inc(10);
        lv_task_handler();
        // add here a function to wait for 10ms
    }
}

Displays, input devices, filesystems

I've included some basic examples in examples/lvglpp. Since I only tested my code with a rather basic display, I didn't write classes that make uses of callbacks for monochrome or special displays. However, it's possible to do it yourself in a simple way:

class CustomDisplay : public Display {
private:
    // arguments should be the arguments of the callback without the 1st one (lv_disp_drv_t* drv)
    void callback_to_implement(arguments) {
        // Put here what your callback does.
    }

public:
    CustomDisplay(lv_coord_t hor_res, lv_coord_t ver_res, uint32_t fb_size)
        : Display(hor_res, ver_res, fb_size) {
        // you need to link the callback with the display driver here
        auto cb = [](lv_disp_drv_t* drv, other arguments) {
            auto obj = reinterpret_cast<CustomDisplay*>(drv->user_data);
            obj->callback_to_implement(other arguments);
        };
        this->lv_disp_drv.callback_to_implement = cb;
        this->update_driver();
    }
};

For input devices, I included specialized classes for each type of input device available. I didn't implement the feedback_cb callback though. If you need it, you can write a derived class following the same scheme as for displays.

There's also a commented example for a custom filesystem driver. It'd be possible to port the available drivers to C++ using this template. Note that this only makes sense if you need to access files directly (for images, you can just as well register a C driver that will be used under the hood).

Accessing managed object

Through the PointerWrapper class, I provide several ways to access the managed LVGL object:

• raw() returns a reference to the object;
• raw_ptr() returns a pointer to the object;
• the dereference operator * (e.g. *obj) returns a reference to the object (equivalent to raw());
• the pointer-to-member operator -> gives access to the object's structure (e.g. obj->coords for a wrapped lv_obj_t* will yield coords field of type lv_area_t).

A note on callbacks and child objects

A number of classes (e.g. objects, timers, animations) use callbacks for different purposes. To make them look C++-like, I used the user_data field, which (almost) every LVGL structure provides, to give access to the C++ callback (by storing a pointer to the class object containing the callback function, or a pointer to a structure containing the callback functions, or a pointer to the callback function itself). This avoids storing C++ objects in some kind of global storage, but comes with two limitations: 1) we cannot use the user_data field for anything else; 2) we need to re-instantiate a C++ object to feed the callback with, everytime the callback is called. In most cases, the additional complexity won't matter. Nonetheless, where speed matters, it's always possible to use raw C callbacks instead.

Another caveat comes with child objects. Several widgets, especially, provide functions to create elements. For instance, the Tabview class has a function add_tab that returns an Object giving access to the created tab. The Tabview instance manages the new tab and deletes it when it gets deleted. Therefore, it's important not to delete it otherwise. Since Object instances wrap a raw C pointer in a unique_ptr, this would happen if the tab object gets out of scope. Therefore, I introduced a property, owns_ptr, that can be set on construction, and tells if the object owns the wrapped pointer. If it doesn't, the pointer gets released in the object's destructor. One can also force releasing the wrapped pointer with release_ptr. This can be useful when defining complex objects with lots of children that won't need to be accessed after creation. This way, the C++ object can be deleted without affecting the element it has created, freeing memory. You'll find several examples that make use of this.

Caveats

Because of the way wrappers are implemented, it is important to remember to store the elements that are displayed. If any instance of a C++ object gets out of scope, the wrapped element gets deleted too (unless you use release_ptr or it's a child element generated by a widget).

LVGL stores the relationship of objects and takes care of deleting children of objects getting deleted. This means that you can safely use release_ptr on sub-widgets. Conversely, nothing is stored about instances of other types, like styles, animations, timers, ... Therefore, you must not release_ptr one of those, of you won't have any possibility to free it up afterwards. For those, you should either provide some kind of storage (std::vector, class member variable, ...) or make them static.

The equivalent of lv_obj_create is the Container class, and not the Object class, which stores a lv_obj_t but doesn't initialize one. The distinction is made as I wanted to avoid this: Object(Object & parent). This would be seen as the copy constructor by the compiler, which is unwise for a class as general as Object.

For C++-style callbacks, it is important to remember that any object obtained from within the callback by calling an accessor function (such as Event::get_target) creates a temporary object wrapping a raw pointer. This means that you cannot create derived classes that would carry data along. Every call to the callback gets fed with a newly created temporary object with, other than the raw pointer, default values. Moreover, you cannot pass data using the user_data field, as it is used internally to pass the C++-style callback. For such cases, you need to define a global variable to transfer data to or from the callback.

Just like LVGL, lvglpp is NOT thread-safe. Therefore, as for LVGL, it is necessary to prevent concurrent execution of lv_task_handler() and other functions (with the exception of callbacks called from within task handler, like events or timers). This is typically done with a mutex, like:

#include <mutex>
#include <thread>
std::mutex mtx;

void task_handler_thread() {
    for (;;) {
        {
            const std::lock_guard<std::mutex> lock(mtx);
            lv_task_handler();
        }
        std::this_thread::sleep_for(std::chrono::milliseconds(10));
    }
}

void another_thread() {
    for (;;) {
        mtx.lock();
        // place code calling LVGL functions here
        mtx.unlock();
    }
}

Be aware that objects that get deleted because they go out of scope must also be treated. The easiest way, if possible, is to create a lock_guard in the beginning of the scope. If you cannot do that, I suggest using the following method:

void a_function(const Object & parent) {
    mtx.lock();
    auto cnt = std::make_unique<Container>(parent);
    cnt->remove_style_all();
    cnt->set_size(parent.get_width(), parent.get_height());
    // ... code that creates objects ...
    auto obj = AnyObjectType(*cnt);
    // ... 
    mtx.unlock();
    // a bit of safe code ...
    // ... time to terminate function
    // we remove cnt and its content in a safe way
    mtx.lock();
    cnt = nullptr;
    mtx.unlock();
}

Footprint

As lvglpp is essentially a layer over LVGL, it of course increases the memory footprint. However, most wrapper classes have only two member variables: a pointer to the wrapped object and a bool. This makes an overhead of 12 bytes per wrapped object. Several items need to store more content (e.g. Animation and ButtonMatrix) and will therefore need a little more space. Naturally, the binary size will also increase depending on the number of functions that are in use. I'll try to quantify these values at some point. If you're hunting for free bytes, I'd rather recommend to use the original library instead.

API documentation

There is a documentation generated from docstrings in the doc folder. See here. You can re-generate the doc using doxygen in the project folder.

Examples

I adapted most of the examples provided with LVGL. You'll find them in the examples folder here. For examples that involve images, you need to include the appropriate files from LVGL examples. Don't forget to initialize LVGL and define a screen and an input device.