LVGL v9 Complete Beginner → Advanced Guide (ESP32 + ST7789 320x240)

🧠 What is LVGL?

LVGL (Light and Versatile Graphics Library) is a powerful embedded GUI library.

Smart displays
IoT dashboards
Industrial panels
Wearables

🏗️ LVGL Architecture (IMPORTANT)


Hardware (ESP32 + Display + Touch)
        ↓
Display Driver (flush_cb)
        ↓
LVGL Core Engine
        ↓
Objects (Buttons, Labels, etc.)

🌐 LVGL UI DESIGNER

🔗 Open LVGL Editor

🚀 1. Initialization

lv_init();

👉 Initializes LVGL core system

🔁 Main Loop


while(1) {
    lv_timer_handler();
}

👉 Handles:

Rendering
Animations
Events

🧱 2. Core Object System

Create object

lv_obj_t * obj = lv_obj_create(lv_scr_act());

Size & Position


lv_obj_set_size(obj, 100, 50);
lv_obj_set_pos(obj, 10, 20);

Alignment


lv_obj_center(obj);
lv_obj_align(obj, LV_ALIGN_BOTTOM_RIGHT, -10, -10);

🧩 3. Object Manipulation Functions

Visibility


lv_obj_add_flag(obj, LV_OBJ_FLAG_HIDDEN);
lv_obj_clear_flag(obj, LV_OBJ_FLAG_HIDDEN);

Enable/Disable

lv_obj_add_state(obj, LV_STATE_DISABLED);

Delete

lv_obj_del(obj);

🏷️ 4. Label (Text Widget)


lv_obj_t * label = lv_label_create(lv_scr_act());
lv_label_set_text(label, "Hello World");

Dynamic text

lv_label_set_text_fmt(label, "Value: %d", 10);

🔘 5. Button Widget

lv_obj_t * btn = lv_btn_create(lv_scr_act());

Add label inside


lv_obj_t * lbl = lv_label_create(btn);
lv_label_set_text(lbl, "Press");
lv_obj_center(lbl);

🎚️ 6. Slider Widget


lv_obj_t * slider = lv_slider_create(lv_scr_act());
lv_slider_set_range(slider, 0, 100);
lv_slider_set_value(slider, 50, LV_ANIM_OFF);

📊 7. Bar Widget


lv_obj_t * bar = lv_bar_create(lv_scr_act());
lv_bar_set_value(bar, 70, LV_ANIM_ON);

🖼️ 8. Image Widget


lv_obj_t * img = lv_img_create(lv_scr_act());
lv_img_set_src(img, &my_image);

⚡ 9. Event System (VERY IMPORTANT)

Add event


void cb(lv_event_t * e) {
    printf("Event triggered\n");
}
lv_obj_add_event_cb(btn, cb, LV_EVENT_CLICKED, NULL);

Manually trigger event

lv_obj_send_event(btn, LV_EVENT_CLICKED, NULL);

Common Events

LV_EVENT_CLICKED
LV_EVENT_PRESSED
LV_EVENT_RELEASED
LV_EVENT_VALUE_CHANGED

🎨 10. Styling System

Background

lv_obj_set_style_bg_color(obj, lv_color_hex(0x0000FF), 0);
lv_obj_set_style_bg_color(obj, lv_color_make(66, 138, 245), 0);

Border

lv_obj_set_style_border_width(obj, 2, 0);

Border Color

lv_obj_set_style_border_color(obj, lv_color_hex(0xFF0000), 0);
lv_obj_set_style_border_color(obj, lv_color_make(66, 138, 245), 0);

Radius

lv_obj_set_style_radius(obj, 10, 0);

📐 11. Layout System

Flex Layout


lv_obj_set_layout(parent, LV_LAYOUT_FLEX);
lv_obj_set_flex_flow(parent, LV_FLEX_FLOW_ROW_WRAP);

🔁 12. Timer System


void timer_cb(lv_timer_t * t) {
    printf("Tick\n");
}
lv_timer_create(timer_cb, 1000, NULL);

🎬 13. Animation System


lv_anim_t a;
lv_anim_init(&a);

lv_anim_set_var(&a, obj);
lv_anim_set_values(&a, 0, 100);
lv_anim_set_time(&a, 500);

lv_anim_set_exec_cb(&a, (lv_anim_exec_xcb_t) lv_obj_set_x);

lv_anim_start(&a);

🧠 14. Advanced Useful APIs

Get position

int x = lv_obj_get_x(obj);

Get size

int w = lv_obj_get_width(obj);

Set opacity

lv_obj_set_style_opa(obj, LV_OPA_50, 0);

📦 15. Screens


lv_obj_t * screen = lv_obj_create(NULL);
lv_scr_load(screen);

📺 16. ESP32 + ST7789 Full Example


#include <lvgl.h>
#include <TFT_eSPI.h>

TFT_eSPI tft = TFT_eSPI();

static lv_disp_draw_buf_t draw_buf;
static lv_color_t buf[320 * 10];

void flush_cb(lv_disp_t * disp, const lv_area_t * area, uint8_t * px_map) {
    tft.startWrite();
    tft.setAddrWindow(area->x1, area->y1,
        area->x2 - area->x1 + 1,
        area->y2 - area->y1 + 1);
    tft.pushColors((uint16_t*)px_map,
        (area->x2 - area->x1 + 1)*(area->y2 - area->y1 + 1), true);
    tft.endWrite();
    lv_disp_flush_ready(disp);
}

void setup() {
    tft.begin();
    lv_init();

    lv_disp_draw_buf_init(&draw_buf, buf, NULL, 320 * 10);

    lv_disp_drv_t disp_drv;
    lv_disp_drv_init(&disp_drv);

    disp_drv.hor_res = 320;
    disp_drv.ver_res = 240;
    disp_drv.flush_cb = flush_cb;
    disp_drv.draw_buf = &draw_buf;

    lv_disp_drv_register(&disp_drv);

    // UI
    lv_obj_t * btn = lv_btn_create(lv_scr_act());
    lv_obj_center(btn);

    lv_obj_t * label = lv_label_create(btn);
    lv_label_set_text(label, "LVGL ESP32");
    lv_obj_center(label);
}

void loop() {
    lv_timer_handler();
    delay(5);
}

🧩 17. More Widgets & Functions (Expanded API with Examples)

Checkbox


lv_obj_t * cb = lv_checkbox_create(lv_scr_act());
lv_checkbox_set_text(cb, "Accept");
lv_obj_align(cb, LV_ALIGN_TOP_LEFT, 10, 10);

Switch


lv_obj_t * sw = lv_switch_create(lv_scr_act());
lv_obj_align(sw, LV_ALIGN_TOP_RIGHT, -10, 10);

Textarea (Input Box)


lv_obj_t * ta = lv_textarea_create(lv_scr_act());
lv_textarea_set_placeholder_text(ta, "Enter text...");
lv_obj_set_size(ta, 200, 50);

Keyboard


lv_obj_t * kb = lv_keyboard_create(lv_scr_act());
lv_keyboard_set_textarea(kb, ta);

Chart


lv_obj_t * chart = lv_chart_create(lv_scr_act());
lv_obj_set_size(chart, 200, 120);

lv_chart_series_t * ser = lv_chart_add_series(chart, lv_palette_main(LV_PALETTE_RED), LV_CHART_AXIS_PRIMARY_Y);
lv_chart_set_next_value(chart, ser, 10);
lv_chart_set_next_value(chart, ser, 50);
lv_chart_set_next_value(chart, ser, 30);

🧠 18. Event Handling Deep Dive

Get Event Target

lv_obj_t * target = lv_event_get_target(e);

Get User Data

void * data = lv_event_get_user_data(e);

Example: Slider Value Change


void slider_cb(lv_event_t * e) {
    lv_obj_t * slider = lv_event_get_target(e);
    int val = lv_slider_get_value(slider);
    printf("Value: %d\n", val);
}

🎨 19. Style System (Advanced)


static lv_style_t style;
lv_style_init(&style);

lv_style_set_bg_color(&style, lv_color_hex(0x00FF00));
lv_style_set_radius(&style, 8);

lv_obj_add_style(obj, &style, 0);

📦 20. Input Devices (Touch/Encoder)


lv_indev_drv_t indev_drv;
lv_indev_drv_init(&indev_drv);
indev_drv.type = LV_INDEV_TYPE_POINTER;
indev_drv.read_cb = my_touch_read;
v_indev_drv_register(&indev_drv);