4、第一个LVGL程序：从零开始创建一个简单的LVGL应用

在完成了LVGL图形库的环境搭建与基础概念学习之后，我们正式进入第一个实战环节。本章的目标不是堆砌复杂的UI效果，而是通过一个最小可运行的工程，彻底打通“初始化→创建控件→事件响应→刷新显示”的完整链路。你将亲手创建一个包含窗口（Screen）、按钮（Button）和标签（Label）的应用程序，并实现点击按钮改变文本的交互逻辑。通过这个过程，我们将深入剖析LVGL的项目结构、对象树模型以及事件驱动机制，为后续学习复杂布局和自定义控件打下坚实的工程基础。

4.1 工程结构解析：理解LVGL项目的骨架

一个规范的LVGL工程，其目录结构直接决定了后续开发的效率和可维护性。我们以PC模拟器（SDL驱动）为例，剖析一个最小但完整的工程骨架。核心原则是：LVGL核心库与应用程序代码分离，硬件驱动与平台逻辑解耦。

目录/文件	作用	是否必须
lvgl/	LVGL核心源码（src、demo、examples）	是
lv_drivers/	显示、输入设备驱动（如SDL、framebuffer）	是
lv_conf.h	LVGL配置头文件，控制功能开关与内存大小	是
main.c	程序入口，包含初始化与主循环	是
Makefile / CMakeLists.txt	构建脚本，链接所有源文件	是

在main.c中，代码的执行逻辑遵循一个固定的生命周期：初始化硬件 → 初始化LVGL → 创建UI → 进入无限循环。这个循环是LVGL的心脏，它负责处理输入事件、执行动画、刷新脏矩形区域。理解这个循环是理解LVGL运行机制的关键。

4.2 手写第一个应用：创建窗口与控件

我们直接通过代码来构建一个简单的交互界面。这个界面包含一个背景窗口（Screen）、一个居中的按钮（Button）和一个用于显示文本的标签（Label）。当按钮被点击时，标签的文本内容会发生变化。

#include "lvgl/lvgl.h"
#include "lv_drivers/display/sdl_display.h"
#include "lv_drivers/indev/sdl_mouse.h"

// 声明驱动刷新回调
static void disp_flush(lv_disp_drv_t * disp_drv, const lv_area_t * area, lv_color_t * color_p) {
    sdl_display_flush(disp_drv, area, color_p);
}

// 声明输入设备读取回调
static void mouse_read(lv_indev_drv_t * indev_drv, lv_indev_data_t * data) {
    sdl_mouse_read(indev_drv, data);
}

// 按钮事件回调函数
static void btn_event_cb(lv_event_t * e) {
    lv_obj_t * label = (lv_obj_t *)lv_event_get_user_data(e);
    lv_label_set_text(label, "按钮被点击了！");
}

int main(void) {
    // 1. 初始化SDL显示与输入驱动
    sdl_display_init();
    sdl_mouse_init();

    // 2. 初始化LVGL核心库
    lv_init();

    // 3. 注册显示驱动
    static lv_disp_draw_buf_t draw_buf;
    static lv_color_t buf[SDL_HOR_RES * 10];
    lv_disp_draw_buf_init(&draw_buf, buf, NULL, SDL_HOR_RES * 10);

    static lv_disp_drv_t disp_drv;
    lv_disp_drv_init(&disp_drv);
    disp_drv.hor_res = SDL_HOR_RES;
    disp_drv.ver_res = SDL_VER_RES;
    disp_drv.flush_cb = disp_flush;
    disp_drv.draw_buf = &draw_buf;
    lv_disp_drv_register(&disp_drv);

    // 4. 注册输入设备驱动
    static lv_indev_drv_t indev_drv;
    lv_indev_drv_init(&indev_drv);
    indev_drv.type = LV_INDEV_TYPE_POINTER;
    indev_drv.read_cb = mouse_read;
    lv_indev_drv_register(&indev_drv);

    // 5. 创建UI对象树
    lv_obj_t * scr = lv_scr_act(); // 获取当前活动屏幕

    // 创建一个标签，显示初始文本
    lv_obj_t * label = lv_label_create(scr);
    lv_label_set_text(label, "Hello LVGL!");
    lv_obj_align(label, LV_ALIGN_CENTER, 0, -40);

    // 创建一个按钮
    lv_obj_t * btn = lv_btn_create(scr);
    lv_obj_set_size(btn, 120, 50);
    lv_obj_align(btn, LV_ALIGN_CENTER, 0, 40);

    // 在按钮上创建一个子标签
    lv_obj_t * btn_label = lv_label_create(btn);
    lv_label_set_text(btn_label, "点击我");
    lv_obj_center(btn_label);

    // 为按钮添加事件回调，并传递label对象作为用户数据
    lv_obj_add_event_cb(btn, btn_event_cb, LV_EVENT_CLICKED, label);

    // 6. 进入LVGL主循环
    while (1) {
        lv_timer_handler(); // 核心处理函数：处理任务、刷新屏幕
        lv_delay_ms(5);     // 延时5ms，避免CPU占用过高
    }

    return 0;
}

这段代码虽然简短，却包含了LVGL应用的全部要素。我们逐段分析：驱动初始化是基础，lv_init()是核心库的启动开关，UI创建是业务逻辑的载体，而while循环则是让整个系统“活”起来的引擎。

4.3 事件驱动机制：让控件“动”起来

LVGL采用事件驱动模型来处理用户交互。当用户点击、拖动、滚动时，LVGL会生成相应的事件，并调用注册了该事件的回调函数。在上面的代码中，我们通过lv_obj_add_event_cb(btn, btn_event_cb, LV_EVENT_CLICKED, label)为按钮注册了点击事件。

事件回调函数的签名是固定的：void (*lv_event_cb_t)(lv_event_t * e)。在回调函数内部，我们可以通过lv_event_get_target(e)获取触发事件的对象，通过lv_event_get_user_data(e)获取我们注册时传入的用户数据（这里我们传入了label指针）。

这种机制的好处是：UI逻辑与硬件完全隔离，你只需要关注“什么操作触发什么变化”，而不必关心底层像素如何刷新。

4.4 常见误区与工程复盘

初学者在编写第一个LVGL程序时，往往会遇到一些典型的“坑”。我们总结如下，帮助你少走弯路。

误区	现象	正确做法
忘记调用lv_timer_handler()	屏幕无显示或点击无反应	确保主循环中周期性调用
在回调中执行耗时操作	UI卡顿、动画不流畅	回调中只做逻辑修改，耗时任务放到后台线程或任务中
对象创建后未设置对齐	控件出现在屏幕左上角(0,0)	使用lv_obj_align()或lv_obj_center()设置位置
混淆lv_scr_act()与lv_obj_create(NULL)	控件不在当前屏幕显示	默认控件应创建在lv_scr_act()上，或创建后lv_scr_load()
事件回调中未获取用户数据	无法操作目标控件	通过lv_event_get_user_data(e)获取