LVGL Pro使用指南[08] LVGL XML 事件

本文说明如何在 LVGL XML 定义和使用事件(Events)。

概述 链接到标题

LVGL XML 提供多种方式定义用户交互事件。这些事件可以作为子元素添加任意控件内。

事件触发器（Triggers） 链接到标题

在事件类型中，trigger 属性用于定义哪种用户操作会触发该事件。所有 LVGL 事件类型都可以通过简单的映射方式支持，例如：

  • LV_EVENT_ALL ："all"
  • LV_EVENT_CLICKED ："clicked"
  • LV_EVENT_PRESSED ："pressed"

这里并没有找到一个统一的映射表，但不用担心，在LVGL Pro的编辑器中编写时会自动感知并供你选择。

事件调用函数（Call function） 链接到标题

以下示例展示为事件(clicked)添加调用函数名为(my_callback_1)的调用函数

<view>
<lv_button width="200" height="100">
    <event_cb callback="my_callback_1" trigger="clicked" user_data="some_text"/>
    <lv_label text="Hello"/>
</lv_button>
</view>

如果是运行时加载该 XML，需要通过以下方式在C代码中将回调名称(my_callback_1)映射到函数(an_event_handler)：

lv_xml_register_event_cb("my_callback_1", an_event_handler);

回调函数格式应遵循 LVGL 标准的事件回调函数格式：

void an_event_handler(lv_event_t * e);

如果是将XML导出为 C 代码，生成的代码中会声明函数，并注册。例如callback="my_callback_1" 会被导出为：

void my_callback_1(lv_event_t * e); /* 在导出文件的开头声明 */
lv_obj_add_event_cb(obj, my_callback_1, LV_EVENT_CLICKED, "some_text");

user_data 参数是可选的。如果省略，将传递 NULL。

此时你需要实现my_callback_1。

Screens 加载与创建事件 链接到标题

通过在组件或控件的子元素中使用 <screen_load_event> 和 <screen_create_event> 标签，可以在特定触发条件下（例如点击）加载或创建Screen。两者的区别在于：

  • load：仅加载一个已存在的Screen。离开该Screen后，Screen仍保留在内存中，因此其状态会被保存。
  • create：动态创建一个新的Screen。当离开该Screen后，Screen会被删除，因此所有对Screen更改都会丢失（更改已保存到 subjects 中的除外）。

两个标签都支持以下可选属性：

属性 说明 默认值
trigger 触发动作的事件码（如 "clicked", "long_pressed" 等） "clicked"
anim_type Screen加载的动画类型（如 "move_right", "fade_in"） "none"
duration 动画持续时间（毫秒），仅在 anim_type 不为 "none" 时使用 0
delay Screen加载前的等待时间（毫秒） 0

以下加载与创建Screen的简单示例(没有设置trigger属性，因此都是clicked触发)：

<!-- screen1.xml -->
<screen>
    <view style_bg_color="0xff7788">
        <lv_button>
            <lv_label text="Create"/>
            <!-- Create an instance of "screen2" and load it. -->
            <screen_create_event screen="screen2" anim_type="over_right" duration="500" delay="1000"/>
        </lv_button>
    </view>
</screen>

<!-- screen2.xml -->
<screen>
    <view style_bg_color="0x77ff88">
        <lv_button>
            <lv_label text="Load"/>
            <!-- Load an already created instance of screen1.-->
            <screen_load_event screen="screen1"/>
        </lv_button>
    </view>
</screen>

在运行时加载上述 XML 时，需要先注册这两个 Screen，然后创建一个 Screen 实例以便加载：

lv_xml_register_component_from_data("screen1", screen1_xml);
lv_xml_register_component_from_data("screen2", screen2_xml);

/* Create an instance of screen1 so that it can be loaded from screen2. */
lv_obj_t * screen1 = lv_xml_create(NULL, "screen1", NULL);
lv_screen_load(screen1);

设置 Subject 值 链接到标题

可以在控件下添加子元素，当用户交互时会设置 Subject 的值：

<view>
    <lv_button width="200" height="100">
        <subject_set_int_event    trigger="clicked" subject="subject_int"    value="10"/>
        <subject_set_float_event  trigger="clicked" subject="subject_float"  value="12.34"/>
        <subject_set_string_event trigger="clicked" subject="subject_string" value="Hello"/>
        <lv_label text="Set the values"/>
</lv_button>
</view>

写法很直观：当触发事件发生时，指定的 Subject 会被设置为给定的值。

改变 Subject 值 链接到标题

可以通过如下方式增加或减少 Subject 值：

<view>
    <lv_button width="200" height="100">
        <subject_increment_event trigger="clicked" subject="subject_int1" step="10"/>
        <subject_increment_event trigger="clicked" subject="subject_int2" step="-10" min="0" max="50" rollover=true/>
        <subject_increment_event trigger="clicked" subject="subject_float1" step="2"/>
    </lv_button>
</view>

<subject_increment_event> 元素定义了在触发事件发生时要加到 Subject 当前值上的步长（step）。

  • 可选设置 min 和/或 max 来限制 Subject 的取值范围。默认的最小值和最大值分别为 INT32_MIN (-2,147,483,648) 和 INT32_MAX (+2,147,483,647)
  • subject 必须是整数或浮点数类型。
  • 如果 step 为负值，则会对 Subject 的值进行减少。当前仅支持整数步长（step）值。
  • rollover 可选属性。当其值为 false（默认值）时，变量值到达极限后会停止在最小值或最大值；若为 true，则变量值在到达极限后会回绕到另一端（例如，超过最大值时跳转到最小值）

参考 链接到标题

https://docs.lvgl.io/master/details/xml/ui_elements/events.html#