Events（事件）

显示原文

Events are triggered in LVGL when something happens which might be interesting to the user, e.g. when a Widget:

  • is clicked

  • is scrolled

  • has its value changed

  • is redrawn, etc.

Besides Widgets, events can registered from displays and input devices as well. It is not detailed below, but you can do this by changing the prefix of the functions from lv_obj_ to lv_display_ or lv_indev_.


在 LVGL 中，当发生某些可能引起用户兴趣的事情时会触发事件，例如当一个 Widget：

  • 被点击

  • 被滚动

  • 更改了它的值

  • 重新绘制等。

除了 Widgets，也可以从 displays 和 input devices 注册事件。 下面没有详细说明，但您可以通过将函数的前缀从 lv_obj_ 更改为 lv_display_ 或 lv_indev_ 来实现这一点。

Adding Events to a Widget（添加事件到对象）

显示原文

The user can assign callback functions to a widget to process events. In practice, it looks like this:

lv_obj_t * btn = lv_button_create(lv_screen_active());
lv_obj_add_event_cb(btn, my_event_cb, LV_EVENT_CLICKED, user_data);   /* Assign an event callback */

...

static void my_event_cb(lv_event_t * event)
{
    printf("Clicked\n");
}

In the example LV_EVENT_CLICKED means that only the click event will call my_event_cb. See the list of event codes for all the options. LV_EVENT_ALL can be used to receive all events.

The last parameter of lv_obj_add_event() is a pointer to any custom data that will be available in the event. NULL may be passed for this argument if there is no need to use that data when the event is processed. You can retrieve the pointer passed when setting the callback function like this:

my_user_data_t  * user_data;
...
user_data = lv_event_get_user_data(e);

More events can be added to a Widget, like this:

lv_obj_add_event_cb(widget, my_event_cb_1, LV_EVENT_CLICKED, NULL);
lv_obj_add_event_cb(widget, my_event_cb_2, LV_EVENT_PRESSED, NULL);
lv_obj_add_event_cb(widget, my_event_cb_3, LV_EVENT_ALL, NULL);       /* No filtering, receive all events */

Even the same event callback can be used on a Widget with different user_data. For example:

lv_obj_add_event_cb(widget, increment_on_click, LV_EVENT_CLICKED, &num1);
lv_obj_add_event_cb(widget, increment_on_click, LV_EVENT_CLICKED, &num2);

The events will be called in the order as they were added.

Other Widgets can use the same event callback.

In the very same way, events can be attached to input devices and displays like this:

lv_display_add_event_cb(disp, event_cb, LV_EVENT_RESOLUTION_CHANGED, NULL);
lv_indev_add_event_cb(indev, event_cb, LV_EVENT_CLICKED, NULL);

用户可以为控件分配回调函数来处理事件。 实际上，它的操作如下所示：

lv_obj_t * btn = lv_button_create(lv_screen_active());
lv_obj_add_event_cb(btn, my_event_cb, LV_EVENT_CLICKED, user_data);   /* 分配一个事件回调 */

...

static void my_event_cb(lv_event_t * event)
{
    printf("Clicked\n");
}

在示例中，LV_EVENT_CLICKED 表示只有点击事件会调用 my_event_cb。 请参阅 list of event codes 以获取所有选项。 LV_EVENT_ALL 可用于接收所有事件。

lv_obj_add_event() 的最后一个参数是指向任何自定义数据的指针，该数据将在事件中可用。 如果不需要在处理事件时使用该数据，可以为此参数传递 NULL。 您可以像这样检索设置回调函数时传递的指针：

my_user_data_t  * user_data;
...
user_data = lv_event_get_user_data(e);

可以向控件添加更多事件，如下所示：

lv_obj_add_event_cb(widget, my_event_cb_1, LV_EVENT_CLICKED, NULL);
lv_obj_add_event_cb(widget, my_event_cb_2, LV_EVENT_PRESSED, NULL);
lv_obj_add_event_cb(widget, my_event_cb_3, LV_EVENT_ALL, NULL);       /* 无过滤，接收所有事件 */

即使是相同的事件回调也可以在控件上使用不同的 user_data。例如：

lv_obj_add_event_cb(widget, increment_on_click, LV_EVENT_CLICKED, &num1);
lv_obj_add_event_cb(widget, increment_on_click, LV_EVENT_CLICKED, &num2);

事件将按照它们被添加的顺序调用。

其他控件也可以使用相同的 事件回调。

同样地，事件可以附加到输入设备和显示器上，如下所示：

lv_display_add_event_cb(disp, event_cb, LV_EVENT_RESOLUTION_CHANGED, NULL);
lv_indev_add_event_cb(indev, event_cb, LV_EVENT_CLICKED, NULL);

Removing Event(s) from Widgets(从对象中删除事件)

uint32_t i;
uint32_t event_cnt = lv_obj_get_event_count(widget);
for(i = 0; i < event_cnt; i++) {
    lv_event_dsc_t * event_dsc = lv_obj_get_event_dsc(widget, i);
    if(lv_event_dsc_get_cb(event_dsc) == some_event_cb) {
        lv_obj_remove_event(widget, i);
        break;
    }
}

Event Codes（事件代码）

显示原文

The event codes can be grouped into these categories: - Input device events - Drawing events - Other events - Special events - Custom events

All Widgets (such as Buttons/Labels/Sliders etc.) regardless their type receive the Input device, Drawing and Other events.

However, the Special events are specific to a particular widget type. See the widgets' documentation to learn when they are sent,

Custom events are added by the user and are never sent by LVGL.

The following event codes exist:


事件代码可以分为以下几类：- 输入设备事件 - 绘制事件 - 其他事件 - 特殊事件 - 自定义事件

所有Widgets（如Buttons/Labels/Sliders等），无论其类型，都会接收*输入设备*、*绘制*和*其他*事件。

然而，*特殊事件*是特定于某个Widget类型的。参见 widgets' documentation 以了解它们在何时被发送，

*自定义事件*由用户添加，并且永远不会由LVGL发送。

以下事件代码存在：

Input device events（输入设备事件）

显示原文

Drawing Events（绘图事件）

显示原文

Special Events（特殊事件）

显示原文

Other Events（其他事件）

显示原文

Display Events（展示时间）

Custom Events（自定义事件）

显示原文

Any number of custom event codes can be registered by uint32_t MY_EVENT_1 = lv_event_register_id()

They can be sent to any Widget with lv_obj_send_event(widget, MY_EVENT_1, &some_data)


任何自定义事件代码都可以通过 uint32_t MY_EVENT_1 = lv_event_register_id() 来注册。

它们可以发送到任何对象中，使用 lv_event_send(obj, MY_EVENT_1, &some_data)

Sending events（发送事件）

显示原文

To manually send events to an object, use lv_obj_send_event(obj, <EVENT_CODE>, &some_data).

For example, this can be used to manually close a message box by simulating a button press (although there are simpler ways to do this):

/*Simulate the press of the first button (indexes start from zero)*/
uint32_t btn_id = 0;
lv_event_send(mbox, LV_EVENT_VALUE_CHANGED, &btn_id);

The same works for display and input devices with lv_display_send_event(obj, <EVENT_CODE>, &some_data) and lv_indev_send_event(obj, <EVENT_CODE>, &some_data).


手动发送事件到对象，使用以下代码 lv_obj_send_event(obj, <EVENT_CODE>, &some_data)。

例如，这可以用于通过模拟按钮按下来手动关闭消息框（尽管有更简单的方法来做到这一点）：

/*模拟第一个按钮的按下（索引从零开始）*/
uint32_t btn_id = 0;
lv_event_send(mbox, LV_EVENT_VALUE_CHANGED, &btn_id);

对于显示器和输入设备也同样适用： lv_display_send_event(obj, <EVENT_CODE>, &some_data) 和 lv_indev_send_event(obj, <EVENT_CODE>, &some_data)。

Refresh event（刷新事件）

显示原文

LV_EVENT_REFRESH is a special event because it's designed to let the user notify a Widget to refresh itself. Some examples:

  • notify a label to refresh its text according to one or more variables (e.g. current time)

  • refresh a label when the language changes

  • enable a button if some conditions are met (e.g. the correct PIN is entered)

  • add/remove styles to/from a Widget if a limit is exceeded, etc


cpp:enumerator:LV_EVENT_REFRESH 是一个特殊事件，因为它设计用于让用户通知一个Widget刷新自身。一些例子包括：

  • 通知标签根据一个或多个变量（例如当前时间）刷新其文本

  • 当语言更改时刷新标签

  • 如果满足某些条件（例如输入了正确的PIN码）启用按钮

  • 如果超过了限制，则向Widget添加/移除样式等

Sending Events Manually

To manually send events to a Widget, use lv_obj_send_event(widget, <EVENT_CODE>, &some_data).

For example, this can be used to manually close a message box by simulating a button press (although there are simpler ways to do this):

/* Simulate the press of the first button (indexes start from zero) */
uint32_t btn_id = 0;
lv_obj_send_event(mbox, LV_EVENT_VALUE_CHANGED, &btn_id);

The same works for display and input devices with lv_display_send_event(widget, <EVENT_CODE>, &some_data) and lv_indev_send_event(widget, <EVENT_CODE>, &some_data).

Fields of lv_event_t（lv_event_t 的字段）

显示原文

lv_event_t is the only parameter passed to the event callback and it contains all data about the event. The following values can be gotten from it:


lv_event_t 是传递给事件回调函数的唯一参数，它包含了该事件的所有数据。可以从中获取以下值：

Event Bubbling（事件冒泡）

显示原文

If lv_obj_add_flag(widget, LV_OBJ_FLAG_EVENT_BUBBLE) is enabled all events will be sent to a Widget's parent as well. If the parent also has LV_OBJ_FLAG_EVENT_BUBBLE enabled the event will be sent to its parent, and so on.

The target parameter of the event is always the current target Widget, not the original Widget. To get the original target call lv_event_get_target_obj(e) in the event handler.


如果启用了 lv_obj_add_flag(widget, LV_OBJ_FLAG_EVENT_BUBBLE)，则所有事件也将发送给Widget的父级。如果父级也启用了 LV_OBJ_FLAG_EVENT_BUBBLE，那么事件将被发送给它的父级，依此类推。

事件的 target 参数始终是当前的目标Widget，而不是原始的Widget。要获取原始目标，可以在事件处理程序中调用 lv_event_get_target_obj(e)。

Examples

Button click event

C code  

 View on GitHub
#include "../lv_examples.h"
#if LV_BUILD_EXAMPLES && LV_USE_SWITCH

static void event_cb(lv_event_t * e)
{
    LV_LOG_USER("Clicked");

    static uint32_t cnt = 1;
    lv_obj_t * btn = lv_event_get_target(e);
    lv_obj_t * label = lv_obj_get_child(btn, 0);
    lv_label_set_text_fmt(label, "%"LV_PRIu32, cnt);
    cnt++;
}

/**
 * Add click event to a button
 */
void lv_example_event_click(void)
{
    lv_obj_t * btn = lv_button_create(lv_screen_active());
    lv_obj_set_size(btn, 100, 50);
    lv_obj_center(btn);
    lv_obj_add_event_cb(btn, event_cb, LV_EVENT_CLICKED, NULL);

    lv_obj_t * label = lv_label_create(btn);
    lv_label_set_text(label, "Click me!");
    lv_obj_center(label);
}

#endif

Click streaks

C code  

 View on GitHub
#include "../lv_examples.h"
#if LV_BUILD_EXAMPLES && LV_USE_LABEL

static void short_click_event_cb(lv_event_t * e)
{
    LV_LOG_USER("Short clicked");

    lv_obj_t * info_label = lv_event_get_user_data(e);
    lv_indev_t * indev = lv_event_get_param(e);
    uint8_t cnt = lv_indev_get_short_click_streak(indev);
    lv_label_set_text_fmt(info_label, "Short click streak: %u", cnt);
}

static void streak_event_cb(lv_event_t * e)
{
    lv_obj_t * btn = lv_event_get_target(e);
    lv_obj_t * label = lv_obj_get_child(btn, 0);
    const char * text = lv_event_get_user_data(e);
    lv_label_set_text(label, text);
}

void lv_example_event_streak(void)
{
    lv_obj_t * info_label = lv_label_create(lv_screen_active());
    lv_label_set_text(info_label, "No events yet");

    lv_obj_t * btn = lv_button_create(lv_screen_active());
    lv_obj_set_size(btn, 100, 50);
    lv_obj_center(btn);
    lv_obj_add_event_cb(btn, short_click_event_cb, LV_EVENT_SHORT_CLICKED, info_label);
    lv_obj_add_event_cb(btn, streak_event_cb, LV_EVENT_SINGLE_CLICKED, "Single clicked");
    lv_obj_add_event_cb(btn, streak_event_cb, LV_EVENT_DOUBLE_CLICKED, "Double clicked");
    lv_obj_add_event_cb(btn, streak_event_cb, LV_EVENT_TRIPLE_CLICKED, "Triple clicked");

    lv_obj_t * label = lv_label_create(btn);
    lv_label_set_text(label, "Click me!");
    lv_obj_center(label);
}

#endif

Handle multiple events

C code  

 View on GitHub
#include "../lv_examples.h"
#if LV_BUILD_EXAMPLES && LV_USE_SWITCH

static void event_cb(lv_event_t * e)
{
    lv_event_code_t code = lv_event_get_code(e);
    lv_obj_t * label = lv_event_get_user_data(e);

    switch(code) {
        case LV_EVENT_PRESSED:
            lv_label_set_text(label, "The last button event:\nLV_EVENT_PRESSED");
            break;
        case LV_EVENT_CLICKED:
            lv_label_set_text(label, "The last button event:\nLV_EVENT_CLICKED");
            break;
        case LV_EVENT_LONG_PRESSED:
            lv_label_set_text(label, "The last button event:\nLV_EVENT_LONG_PRESSED");
            break;
        case LV_EVENT_LONG_PRESSED_REPEAT:
            lv_label_set_text(label, "The last button event:\nLV_EVENT_LONG_PRESSED_REPEAT");
            break;
        default:
            break;
    }
}

/**
 * Handle multiple events
 */
void lv_example_event_button(void)
{
    lv_obj_t * btn = lv_button_create(lv_screen_active());
    lv_obj_set_size(btn, 100, 50);
    lv_obj_center(btn);

    lv_obj_t * btn_label = lv_label_create(btn);
    lv_label_set_text(btn_label, "Click me!");
    lv_obj_center(btn_label);

    lv_obj_t * info_label = lv_label_create(lv_screen_active());
    lv_label_set_text(info_label, "The last button event:\nNone");

    lv_obj_add_event_cb(btn, event_cb, LV_EVENT_ALL, info_label);
}

#endif

Event bubbling

C code  

 View on GitHub
#include "../lv_examples.h"
#if LV_BUILD_EXAMPLES && LV_USE_FLEX

static void event_cb(lv_event_t * e)
{
    /*The original target of the event. Can be the buttons or the container*/
    lv_obj_t * target = lv_event_get_target(e);

    /*The current target is always the container as the event is added to it*/
    lv_obj_t * cont = lv_event_get_current_target(e);

    /*If container was clicked do nothing*/
    if(target == cont) return;

    /*Make the clicked buttons red*/
    lv_obj_set_style_bg_color(target, lv_palette_main(LV_PALETTE_RED), 0);
}

/**
 * Demonstrate event bubbling
 */
void lv_example_event_bubble(void)
{

    lv_obj_t * cont = lv_obj_create(lv_screen_active());
    lv_obj_set_size(cont, 290, 200);
    lv_obj_center(cont);
    lv_obj_set_flex_flow(cont, LV_FLEX_FLOW_ROW_WRAP);

    uint32_t i;
    for(i = 0; i < 30; i++) {
        lv_obj_t * btn = lv_button_create(cont);
        lv_obj_set_size(btn, 70, 50);
        lv_obj_add_flag(btn, LV_OBJ_FLAG_EVENT_BUBBLE);

        lv_obj_t * label = lv_label_create(btn);
        lv_label_set_text_fmt(label, "%"LV_PRIu32, i);
        lv_obj_center(label);
    }

    lv_obj_add_event_cb(cont, event_cb, LV_EVENT_CLICKED, NULL);
}

#endif

Draw event

C code  

 View on GitHub
#include "../lv_examples.h"

#if LV_BUILD_EXAMPLES

static uint32_t size = 0;
static bool size_dec = false;

static void timer_cb(lv_timer_t * timer)
{
    lv_obj_invalidate(lv_timer_get_user_data(timer));
    if(size_dec) size--;
    else size++;

    if(size == 50) size_dec = true;
    else if(size == 0) size_dec = false;
}

static void event_cb(lv_event_t * e)
{
    lv_obj_t * obj = lv_event_get_target(e);
    lv_draw_task_t * draw_task = lv_event_get_draw_task(e);
    lv_draw_dsc_base_t * base_dsc = lv_draw_task_get_draw_dsc(draw_task);
    if(base_dsc->part == LV_PART_MAIN) {
        lv_draw_rect_dsc_t draw_dsc;
        lv_draw_rect_dsc_init(&draw_dsc);
        draw_dsc.bg_color = lv_color_hex(0xffaaaa);
        draw_dsc.radius = LV_RADIUS_CIRCLE;
        draw_dsc.border_color = lv_color_hex(0xff5555);
        draw_dsc.border_width = 2;
        draw_dsc.out