[English]

Events（事件）

显示原文

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

  • is clicked

  • is scrolled

  • has its value changed

  • is redrawn, etc.

Besides widgets, events can registered from displays and input devices too.


当发生某些对用户可能感兴趣的事情时，LVGL中的事件将被触发，例如：

  • 被点击

  • 被滚动

  • 值发生改变

  • 重新绘制等。

除了部件，事件还可以从显示和输入设备进行注册。

Add events to a widget（添加事件到对象）

显示原文

The user can assign callback functions to an object to see its 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, NULL);   /*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. It will be described later in more detail.

More events can be added to an object, like this:

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

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

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

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

Other objects can use the same event callback.

In the very same way events can attached to the 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, NULL);   /*分配一个事件回调*/

...

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

在示例中 LV_EVENT_CLICKED 意味着只有点击事件会调用 my_event_cb。查看 事件代码列表 以获取所有选项。 LV_EVENT_ALL 可用于接收所有事件。

lv_obj_add_event() 的最后一个参数是指向事件中可用的任何自定义数据的指针。稍后将更详细地描述它。

可以向对象添加更多事件，像这样：

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

甚至相同的事件回调也可以在具有不同“user_data”的对象上使用。例如：

lv_obj_add_event_cb(obj, increment_on_click, LV_EVENT_CLICKED, &num1);
lv_obj_add_event_cb(obj, 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);

Remove event(s) from widgets(从对象中删除事件)

uint32_t i;
uint32_t event_cnt = lv_obj_get_event_count(obj);
for(i = 0; i < event_cnt; i++) {
    lv_event_dsc_t * event_dsc = lv_obj_get_event_dsc(obj, i);
    if(lv_event_dsc_get_cb(event_dsc) == some_event_cb) {
        lv_obj_remove_event(obj, 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 objects (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' documentation 以了解它们何时被发送。

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

存在以下事件代码：

Input device events（输入设备事件）

显示原文

Drawing events（绘图事件）

显示原文

Special events（特殊事件）

显示原文

Other events（其他事件）

显示原文

Display events（展示时间）

Custom events（自定义事件）

显示原文

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

They can be sent to any object with lv_event_send(obj, 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 an object 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 an object if a limit is exceeded, etc


LV_EVENT_REFRESH 是一个特殊事件，因为它被设计用来让用户通知对象刷新自身。一些例子包括：

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

  • 当语言发生变化时刷新标签

  • 如果满足一些条件（比如输入了正确的PIN码），则启用一个按钮

  • 当超出限制时，为对象添加/移除样式，等等

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(obj, LV_OBJ_FLAG_EVENT_BUBBLE) is enabled all events will be sent to an object's parent too. 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 object, not the original object. To get the original target call lv_event_get_target_obj(e) in the event handler.


如果启用了 lv_obj_add_flag(obj, LV_OBJ_FLAG_EVENT_BUBBLE)，那么所有事件也会发送给对象的父级。如果父级也启用了 LV_OBJ_FLAG_EVENT_BUBBLE，那么该事件将继续被发送给其父级，依此类推。

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

Examples

[English]

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_1(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

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_2(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_3(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(timer->user_data);
    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 = draw_task->draw_dsc;
    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.outline_color = lv_color_hex(0xff0000);
        draw_dsc.outline_pad = 3;
        draw_dsc.outline_width = 2;

        lv_area_t a;
        a.x1 = 0;
        a.y1 = 0;
        a.x2 = size;
        a.y2 = size;
        lv_area_align(&obj->coords, &a, LV_ALIGN_CENTER, 0, 0);

        lv_draw_rect(base_dsc->layer, &draw_dsc, &a);
    }
}

/**
 * Demonstrate the usage of draw event
 */
void lv_example_event_4(void)
{
    lv_obj_t * cont = lv_obj_create(lv_screen_active());
    lv_obj_set_size(cont, 200, 200);
    lv_obj_center(cont);
    lv_obj_add_event_cb(cont, event_cb, LV_EVENT_DRAW_TASK_ADDED, NULL);
    lv_obj_add_flag(cont, LV_OBJ_FLAG_SEND_DRAW_TASK_EVENTS);
    lv_timer_create(timer_cb, 30, cont);
}

#endif

API

lv_event.h

lv_obj_event.h

lv_types.h