lvgl.hpp

Go to the documentation of this file.

/*
 * Copyright (C) 2026 Kamil Lulko <kamil.lulko@gmail.com>
 *
 * SPDX-License-Identifier: GPL-3.0-or-later
 *
 * This file is part of oveRTOS.
 */
 
#pragma once
 
#include <ove/lvgl.h>
#include <cstdarg>
#include <cstdint>
#include <cstdio>
#include <type_traits>
#include <concepts>
 
namespace ove::lvgl {
 
/* ================================================================== */
/*  LvglGuard — RAII lock for thread-safe LVGL access                 */
/* ================================================================== */
 
class LvglGuard {
public:
    LvglGuard() { ove_lvgl_lock(); }
 
    ~LvglGuard() { ove_lvgl_unlock(); }
 
    LvglGuard(const LvglGuard &) = delete;
    LvglGuard &operator=(const LvglGuard &) = delete;
    LvglGuard(LvglGuard &&) = delete;
    LvglGuard &operator=(LvglGuard &&) = delete;
};
 
/* ================================================================== */
/*  ObjectView — non-owning lv_obj_t* wrapper                         */
/* ================================================================== */
 
class ObjectView {
public:
    ObjectView() : obj_(nullptr) {}
 
    explicit ObjectView(lv_obj_t *obj) : obj_(obj) {}
 
    lv_obj_t *get() const { return obj_; }
 
    operator lv_obj_t *() const { return obj_; }
 
    explicit operator bool() const { return obj_ != nullptr; }
 
    ObjectView parent() const {
        return ObjectView(lv_obj_get_parent(obj_));
    }
 
    uint32_t child_count() const {
        return lv_obj_get_child_count(obj_);
    }
 
    int32_t get_width() const { return lv_obj_get_width(obj_); }
 
    int32_t get_height() const { return lv_obj_get_height(obj_); }
 
    void del() { lv_obj_delete(obj_); obj_ = nullptr; }
 
    void clean() { lv_obj_clean(obj_); }
 
    static ObjectView screen_active() {
        return ObjectView(lv_screen_active());
    }
 
protected:
    lv_obj_t *obj_;
};
 
static_assert(sizeof(ObjectView) == sizeof(void *),
          "ObjectView must be pointer-sized");
 
/* ================================================================== */
/*  ObjectMixin<Derived> — fluent setters via CRTP                    */
/* ================================================================== */
 
template <typename Derived>
class ObjectMixin {
public:
    Derived &size(int32_t w, int32_t h) {
        lv_obj_set_size(self().get(), w, h);
        return self();
    }
 
    Derived &width(int32_t w) {
        lv_obj_set_width(self().get(), w);
        return self();
    }
 
    Derived &height(int32_t h) {
        lv_obj_set_height(self().get(), h);
        return self();
    }
 
    Derived &pos(int32_t x, int32_t y) {
        lv_obj_set_pos(self().get(), x, y);
        return self();
    }
 
    Derived &center() {
        lv_obj_center(self().get());
        return self();
    }
 
    Derived &align(lv_align_t a, int32_t x_ofs = 0, int32_t y_ofs = 0) {
        lv_obj_align(self().get(), a, x_ofs, y_ofs);
        return self();
    }
 
    Derived &hide() {
        lv_obj_add_flag(self().get(), LV_OBJ_FLAG_HIDDEN);
        return self();
    }
 
    Derived &show() {
        lv_obj_remove_flag(self().get(), LV_OBJ_FLAG_HIDDEN);
        return self();
    }
 
    Derived &visible(bool v) { return v ? show() : hide(); }
 
    Derived &add_flag(lv_obj_flag_t f) {
        lv_obj_add_flag(self().get(), f);
        return self();
    }
 
    Derived &remove_flag(lv_obj_flag_t f) {
        lv_obj_remove_flag(self().get(), f);
        return self();
    }
 
    Derived &add_state(lv_state_t s) {
        lv_obj_add_state(self().get(), s);
        return self();
    }
 
    Derived &remove_state(lv_state_t s) {
        lv_obj_remove_state(self().get(), s);
        return self();
    }
 
    Derived &user_data(void *data) {
        lv_obj_set_user_data(self().get(), data);
        return self();
    }
 
    Derived &clickable(bool on) {
        if (on)
            lv_obj_add_flag(self().get(), LV_OBJ_FLAG_CLICKABLE);
        else
            lv_obj_remove_flag(self().get(), LV_OBJ_FLAG_CLICKABLE);
        return self();
    }
 
private:
    Derived &self() { return static_cast<Derived &>(*this); }
};
 
/* ================================================================== */
/*  EventMixin<Derived> — type-safe event callbacks via CRTP          */
/* ================================================================== */
 
namespace detail {
 
template <typename F>
concept StatelessCallable = std::is_convertible_v<F, void (*)(lv_event_t *)>;
 
} /* namespace detail */
 
template <typename Derived>
class EventMixin {
public:
    template <detail::StatelessCallable F>
    Derived &on(lv_event_code_t code, F &&fn) {
        lv_obj_add_event_cb(self().get(),
                    static_cast<lv_event_cb_t>(fn),
                    code, nullptr);
        return self();
    }
 
    template <auto MemFn, typename T>
    Derived &on(lv_event_code_t code, T *instance) {
        lv_obj_add_event_cb(self().get(),
                    [](lv_event_t *e) {
                        auto *self = static_cast<T *>(
                            lv_event_get_user_data(e));
                        (self->*MemFn)(e);
                    },
                    code, instance);
        return self();
    }
 
    template <detail::StatelessCallable F>
    Derived &on_click(F &&fn) {
        return on(LV_EVENT_CLICKED, static_cast<F &&>(fn));
    }
 
    template <auto MemFn, typename T>
    Derived &on_click(T *instance) {
        return on<MemFn>(LV_EVENT_CLICKED, instance);
    }
 
    template <detail::StatelessCallable F>
    Derived &on_value_changed(F &&fn) {
        return on(LV_EVENT_VALUE_CHANGED, static_cast<F &&>(fn));
    }
 
    template <auto MemFn, typename T>
    Derived &on_value_changed(T *instance) {
        return on<MemFn>(LV_EVENT_VALUE_CHANGED, instance);
    }
 
private:
    Derived &self() { return static_cast<Derived &>(*this); }
};
 
/* ================================================================== */
/*  StyleMixin<Derived> — inline style setters via CRTP               */
/* ================================================================== */
 
template <typename Derived>
class StyleMixin {
public:
    Derived &bg_color(lv_color_t c) {
        lv_obj_set_style_bg_color(self().get(), c, LV_PART_MAIN);
        return self();
    }
 
    Derived &bg_opa(lv_opa_t opa) {
        lv_obj_set_style_bg_opa(self().get(), opa, LV_PART_MAIN);
        return self();
    }
 
    Derived &border_color(lv_color_t c) {
        lv_obj_set_style_border_color(self().get(), c, LV_PART_MAIN);
        return self();
    }
 
    Derived &border_width(int32_t w) {
        lv_obj_set_style_border_width(self().get(), w, LV_PART_MAIN);
        return self();
    }
 
    Derived &radius(int32_t r) {
        lv_obj_set_style_radius(self().get(), r, LV_PART_MAIN);
        return self();
    }
 
    Derived &pad_all(int32_t p) {
        lv_obj_set_style_pad_all(self().get(), p, LV_PART_MAIN);
        return self();
    }
 
    Derived &pad_hor(int32_t p) {
        lv_obj_set_style_pad_hor(self().get(), p, LV_PART_MAIN);
        return self();
    }
 
    Derived &pad_ver(int32_t p) {
        lv_obj_set_style_pad_ver(self().get(), p, LV_PART_MAIN);
        return self();
    }
 
    Derived &pad_gap(int32_t g) {
        lv_obj_set_style_pad_gap(self().get(), g, LV_PART_MAIN);
        return self();
    }
 
    Derived &text_color(lv_color_t c) {
        lv_obj_set_style_text_color(self().get(), c, LV_PART_MAIN);
        return self();
    }
 
    Derived &text_font(const lv_font_t *f) {
        lv_obj_set_style_text_font(self().get(), f, LV_PART_MAIN);
        return self();
    }
 
private:
    Derived &self() { return static_cast<Derived &>(*this); }
};
 
/* ================================================================== */
/*  Style — RAII style object                                         */
/* ================================================================== */
 
class Style {
public:
    Style() { lv_style_init(&style_); }
 
    ~Style() { lv_style_reset(&style_); }
 
    Style(const Style &) = delete;
    Style &operator=(const Style &) = delete;
 
    Style(Style &&other) noexcept : style_(other.style_) {
        lv_style_init(&other.style_);
    }
 
    Style &operator=(Style &&other) noexcept {
        if (this != &other) {
            lv_style_reset(&style_);
            style_ = other.style_;
            lv_style_init(&other.style_);
        }
        return *this;
    }
 
    lv_style_t *get() { return &style_; }
 
    const lv_style_t *get() const { return &style_; }
 
    Style &bg_color(lv_color_t c) {
        lv_style_set_bg_color(&style_, c);
        return *this;
    }
 
    Style &bg_opa(lv_opa_t opa) {
        lv_style_set_bg_opa(&style_, opa);
        return *this;
    }
 
    Style &radius(int32_t r) {
        lv_style_set_radius(&style_, r);
        return *this;
    }
 
    Style &border_color(lv_color_t c) {
        lv_style_set_border_color(&style_, c);
        return *this;
    }
 
    Style &border_width(int32_t w) {
        lv_style_set_border_width(&style_, w);
        return *this;
    }
 
    Style &pad_all(int32_t p) {
        lv_style_set_pad_all(&style_, p);
        return *this;
    }
 
    Style &text_color(lv_color_t c) {
        lv_style_set_text_color(&style_, c);
        return *this;
    }
 
    Style &text_font(const lv_font_t *f) {
        lv_style_set_text_font(&style_, f);
        return *this;
    }
 
private:
    lv_style_t style_;
};
 
/* ================================================================== */
/*  State<T> — reactive state (requires LV_USE_OBSERVER)              */
/* ================================================================== */
 
#if LV_USE_OBSERVER
 
template <std::integral T>
class State {
public:
    explicit State(T initial = 0) {
        lv_subject_init_int(&subject_, static_cast<int32_t>(initial));
    }
 
    ~State() { lv_subject_deinit(&subject_); }
 
    State(const State &) = delete;
    State &operator=(const State &) = delete;
 
    void set(T val) { lv_subject_set_int(&subject_, static_cast<int32_t>(val)); }
 
    T get() const {
        return static_cast<T>(lv_subject_get_int(
            const_cast<lv_subject_t *>(&subject_)));
    }
 
    operator T() const { return get(); }
 
    State &operator++() { set(get() + 1); return *this; }
 
    State &operator--() { set(get() - 1); return *this; }
 
    lv_subject_t *subject() { return &subject_; }
 
private:
    lv_subject_t subject_;
};
 
 
#endif /* LV_USE_OBSERVER */
 
/* ================================================================== */
/*  Widget wrappers — Label, Bar, Box                                 */
/* ================================================================== */
 
class Label : public ObjectView,
          public ObjectMixin<Label>,
          public EventMixin<Label>,
          public StyleMixin<Label> {
public:
    explicit Label(lv_obj_t *obj) : ObjectView(obj) {}
 
    static Label create(ObjectView parent) {
        return Label(lv_label_create(parent));
    }
 
    Label &text(const char *txt) {
        lv_label_set_text(obj_, txt);
        return *this;
    }
 
    Label &text_static(const char *txt) {
        lv_label_set_text_static(obj_, txt);
        return *this;
    }
 
    Label &text_fmt(const char *fmt, ...) {
        va_list args;
        va_start(args, fmt);
        /* LVGL doesn't have a va_list variant, use snprintf + set */
        char buf[128];
        vsnprintf(buf, sizeof(buf), fmt, args);
        va_end(args);
        lv_label_set_text(obj_, buf);
        return *this;
    }
 
    Label &font(const lv_font_t *f) {
        lv_obj_set_style_text_font(obj_, f, LV_PART_MAIN);
        return *this;
    }
 
    Label &color(lv_color_t c) {
        lv_obj_set_style_text_color(obj_, c, LV_PART_MAIN);
        return *this;
    }
 
    Label &long_mode(lv_label_long_mode_t mode) {
        lv_label_set_long_mode(obj_, mode);
        return *this;
    }
 
#if LV_USE_OBSERVER
    template <std::integral T>
    Label &bind_text(State<T> &state, const char *fmt) {
        lv_label_bind_text(obj_, state.subject(), fmt);
        return *this;
    }
#endif
};
 
static_assert(sizeof(Label) == sizeof(void *),
          "Label must be pointer-sized");
 
class Bar : public ObjectView,
        public ObjectMixin<Bar>,
        public EventMixin<Bar>,
        public StyleMixin<Bar> {
public:
    explicit Bar(lv_obj_t *obj) : ObjectView(obj) {}
 
    static Bar create(ObjectView parent) {
        return Bar(lv_bar_create(parent));
    }
 
    Bar &value(int32_t val) {
        lv_bar_set_value(obj_, val, LV_ANIM_ON);
        return *this;
    }
 
    Bar &value(int32_t val, lv_anim_enable_t anim) {
        lv_bar_set_value(obj_, val, anim);
        return *this;
    }
 
    Bar &range(int32_t min, int32_t max) {
        lv_bar_set_range(obj_, min, max);
        return *this;
    }
 
    Bar &indicator_color(lv_color_t c) {
        lv_obj_set_style_bg_color(obj_, c, LV_PART_INDICATOR);
        return *this;
    }
 
    Bar &bar_color(lv_color_t c) {
        lv_obj_set_style_bg_color(obj_, c, LV_PART_MAIN);
        return *this;
    }
 
    /* Note: lv_bar_bind_value() does NOT exist in LVGL 9.2-9.3 */
};
 
static_assert(sizeof(Bar) == sizeof(void *),
          "Bar must be pointer-sized");
 
class Box : public ObjectView,
        public ObjectMixin<Box>,
        public EventMixin<Box>,
        public StyleMixin<Box> {
public:
    explicit Box(lv_obj_t *obj) : ObjectView(obj) {}
 
    static Box create(ObjectView parent) {
        lv_obj_t *obj = lv_obj_create(parent);
        lv_obj_remove_flag(obj, LV_OBJ_FLAG_SCROLLABLE);
        return Box(obj);
    }
};
 
static_assert(sizeof(Box) == sizeof(void *),
          "Box must be pointer-sized");
 
/* ================================================================== */
/*  Layout helpers                                                    */
/* ================================================================== */
 
inline Box vbox(ObjectView parent) {
    auto b = Box::create(parent);
    lv_obj_set_flex_flow(b.get(), LV_FLEX_FLOW_COLUMN);
    lv_obj_set_size(b.get(), LV_SIZE_CONTENT, LV_SIZE_CONTENT);
    return b;
}
 
inline Box hbox(ObjectView parent) {
    auto b = Box::create(parent);
    lv_obj_set_flex_flow(b.get(), LV_FLEX_FLOW_ROW);
    lv_obj_set_size(b.get(), LV_SIZE_CONTENT, LV_SIZE_CONTENT);
    return b;
}
 
/* ================================================================== */
/*  Component<Derived> — CRTP UI composition base                     */
/* ================================================================== */
 
template <typename Derived>
class Component {
public:
    Component() = default;
    ~Component() = default;
 
    Component(const Component &) = delete;
    Component &operator=(const Component &) = delete;
 
    void mount(ObjectView parent) {
        if (root_)
            return;
        root_ = static_cast<Derived *>(this)->build(parent);
        /* Store 'this' in root's user data for from_event() */
        lv_obj_set_user_data(root_.get(), this);
        /* Track external deletion (e.g. screen auto_del) */
        lv_obj_add_event_cb(root_.get(),
                    delete_cb, LV_EVENT_DELETE, this);
    }
 
    void unmount() {
        if (!root_)
            return;
        /* Remove the delete callback before we delete, to avoid
         * the callback nulling root_ and then us using it. */
        lv_obj_t *obj = root_.get();
        root_ = ObjectView();
        lv_obj_delete(obj);
    }
 
    bool is_mounted() const { return static_cast<bool>(root_); }
 
    ObjectView root() const { return root_; }
 
    void hide() {
        if (root_)
            lv_obj_add_flag(root_.get(), LV_OBJ_FLAG_HIDDEN);
    }
 
    void show() {
        if (root_)
            lv_obj_remove_flag(root_.get(), LV_OBJ_FLAG_HIDDEN);
    }
 
    static Derived *from_event(lv_event_t *e) {
        lv_obj_t *target = static_cast<lv_obj_t *>(lv_event_get_target(e));
        while (target) {
            void *ud = lv_obj_get_user_data(target);
            if (ud)
                return static_cast<Derived *>(
                    static_cast<Component *>(ud));
            target = lv_obj_get_parent(target);
        }
        return nullptr;
    }
 
protected:
    ObjectView root_;
 
private:
    static void delete_cb(lv_event_t *e) {
        auto *self = static_cast<Component *>(
            lv_event_get_user_data(e));
        /* Object is being deleted externally — just clear our ref */
        self->root_ = ObjectView();
    }
};
 
} /* namespace ove::lvgl */