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.

Add events to the object

The user can assign callback functions to an object to see its events. In practice, it looks like this:

lv_obj_t * btn = lv_btn_create(lv_scr_act());
lv_obj_add_event(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(obj, my_event_cb_1, LV_EVENT_CLICKED, NULL);
lv_obj_add_event(obj, my_event_cb_2, LV_EVENT_PRESSED, NULL);
lv_obj_add_event(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(obj, increment_on_click, LV_EVENT_CLICKED, &num1);
lv_obj_add_event(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.

Remove event(s) from an object

Events can be removed from an object with the lv_obj_remove_event(obj, event_cb) function

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:

Input device events

• LV_EVENT_PRESSED: An object has been pressed

• LV_EVENT_PRESSING: An object is being pressed (called continuously while pressing)

• LV_EVENT_PRESS_LOST: An object is still being pressed but slid cursor/finger off of the object

• LV_EVENT_SHORT_CLICKED: An object was pressed for a short period of time, then released. Not called if scrolled.

• LV_EVENT_LONG_PRESSED: An object has been pressed for at least the long_press_time specified in the input device driver. Not called if scrolled.

• LV_EVENT_LONG_PRESSED_REPEAT: Called after long_press_time in every long_press_repeat_time ms. Not called if scrolled.

• LV_EVENT_CLICKED: Called on release if an object did not scroll (regardless of long press)

• LV_EVENT_RELEASED: Called in every case when an object has been released

• LV_EVENT_SCROLL_BEGIN: Scrolling begins. The event parameter is NULL or an lv_anim_t * with a scroll animation descriptor that can be modified if required.

• LV_EVENT_SCROLL_THROW_BEGIN: Sent once when the object is released while scrolling but the "momentum" still keeps the content scrolling.

• LV_EVENT_SCROLL_END: Scrolling ends.

• LV_EVENT_SCROLL: An object was scrolled

• LV_EVENT_GESTURE: A gesture is detected. Get the gesture with lv_indev_get_gesture_dir(lv_indev_get_act())

• LV_EVENT_KEY: A key is sent to an object. Get the key with lv_indev_get_key(lv_indev_get_act())

• LV_EVENT_FOCUSED: An object is focused

• LV_EVENT_DEFOCUSED: An object is unfocused

• LV_EVENT_LEAVE: An object is unfocused but still selected

• LV_EVENT_HIT_TEST: Perform advanced hit-testing. Use lv_hit_test_info_t * a = lv_event_get_hit_test_info(e) and check if a->point can click the object or not. If not set a->res = false

Drawing events

• LV_EVENT_COVER_CHECK: Check if an object fully covers an area. The event parameter is lv_cover_check_info_t *.

• LV_EVENT_REFR_EXT_DRAW_SIZE: Get the required extra draw area around an object (e.g. for a shadow). The event parameter is lv_coord_t * to store the size. Only overwrite it with a larger value.

• LV_EVENT_DRAW_MAIN_BEGIN: Starting the main drawing phase.

• LV_EVENT_DRAW_MAIN: Perform the main drawing

• LV_EVENT_DRAW_MAIN_END: Finishing the main drawing phase

• LV_EVENT_DRAW_POST_BEGIN: Starting the post draw phase (when all children are drawn)

• LV_EVENT_DRAW_POST: Perform the post draw phase (when all children are drawn)

• LV_EVENT_DRAW_POST_END: Finishing the post draw phase (when all children are drawn)

• LV_EVENT_DRAW_PART_BEGIN: Starting to draw a part. The event parameter is lv_obj_draw_dsc_t *. Learn more Drawing.

• LV_EVENT_DRAW_PART_END: Finishing to draw a part. The event parameter is lv_obj_draw_dsc_t *. Learn more Drawing.

In LV_EVENT_DRAW_... events it's not allowed to adjust the widgets' properties. E.g. you can not call lv_obj_set_width(). In other words only get functions can be called.

Other events

• LV_EVENT_DELETE: Object is being deleted

• LV_EVENT_CHILD_CHANGED: Child was removed/added

• LV_EVENT_CHILD_CREATED: Child was created, always bubbles up to all parents

• LV_EVENT_CHILD_DELETED: Child was deleted, always bubbles up to all parents

• LV_EVENT_SIZE_CHANGED: Object coordinates/size have changed

• LV_EVENT_STYLE_CHANGED: Object's style has changed

• LV_EVENT_BASE_DIR_CHANGED: The base dir has changed

• LV_EVENT_GET_SELF_SIZE: Get the internal size of a widget

• LV_EVENT_SCREEN_UNLOAD_START: A screen unload started, fired immediately when lv_scr_load/lv_scr_load_anim is called

• LV_EVENT_SCREEN_LOAD_START: A screen load started, fired when the screen change delay is expired

• LV_EVENT_SCREEN_LOADED: A screen was loaded, called when all animations are finished

• LV_EVENT_SCREEN_UNLOADED: A screen was unloaded, called when all animations are finished

Special events

• LV_EVENT_VALUE_CHANGED: The object's value has changed (i.e. slider moved)

• LV_EVENT_INSERT: Text is being inserted into the object. The event data is char * being inserted.

• LV_EVENT_REFRESH: Notify the object to refresh something on it (for the user)

• LV_EVENT_READY: A process has finished

• LV_EVENT_CANCEL: A process has been canceled

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)

Sending events

To manually send events to an object, use lv_event_send (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);

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

Fields of 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_get_code(e): get the event code

• lv_event_get_current_target(e): get the object to which an event was sent. I.e. the object whose event handler is being called.

• lv_event_get_target(e): get the object that originally triggered the event (different from lv_event_get_target() if event bubbling is enabled)

• lv_event_get_user_data(e): get the pointer passed as the last parameter of lv_obj_add_event().

• lv_event_get_param(e): get the parameter passed as the last parameter of lv_event_send()

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.

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_1(void)
{
    lv_obj_t * btn = lv_btn_create(lv_scr_act());
    lv_obj_set_size(btn, 100, 50);
    lv_obj_center(btn);
    lv_obj_add_event(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

MicroPython code  

 View on GitHub MicroPython Simulator

class Event_1():
    def __init__(self):
        self.cnt = 1
        #
        # Add click event to a button
        #

        btn = lv.btn(lv.scr_act())
        btn.set_size(100, 50)
        btn.center()
        btn.add_event(self.event_cb, lv.EVENT.CLICKED, None)

        label = lv.label(btn)
        label.set_text("Click me!")
        label.center()

    def event_cb(self,e):
        print("Clicked")

        btn = e.get_target_obj()
        label = btn.get_child(0)
        label.set_text(str(self.cnt))
        self.cnt += 1

evt1 = Event_1()

---

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_btn_create(lv_scr_act());
    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_scr_act());
    lv_label_set_text(info_label, "The last button event:\nNone");

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

#endif

MicroPython code  

 View on GitHub MicroPython Simulator

def event_cb(e,label):
    code = e.get_code()
    if code == lv.EVENT.PRESSED:
        label.set_text("The last button event:\nLV_EVENT_PRESSED")
    elif code == lv.EVENT.CLICKED:
        label.set_text("The last button event:\nLV_EVENT_CLICKED")
    elif code == lv.EVENT.LONG_PRESSED:
        label.set_text("The last button event:\nLV_EVENT_LONG_PRESSED")
    elif code == lv.EVENT.LONG_PRESSED_REPEAT:
        label.set_text("The last button event:\nLV_EVENT_LONG_PRESSED_REPEAT")
btn = lv.btn(lv.scr_act())
btn.set_size(100, 50)
btn.center()

btn_label = lv.label(btn)
btn_label.set_text("Click me!")
btn_label.center()

info_label = lv.label(lv.scr_act())
info_label.set_text("The last button event:\nNone")

btn.add_event(lambda e: event_cb(e,info_label), lv.EVENT.ALL, None)

---

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_scr_act());
    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_btn_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(cont, event_cb, LV_EVENT_CLICKED, NULL);
}

#endif

MicroPython code  

 View on GitHub MicroPython Simulator

def event_cb(e):

    # The original target of the event. Can be the buttons or the container
    target = e.get_target_obj()

    # The current target is always the container as the event is added to it
    cont = e.get_current_target_obj()

    # If container was clicked do nothing
    if target == cont:
        return

    # Make the clicked buttons red
    target.set_style_bg_color(lv.palette_main(lv.PALETTE.RED), 0)

#
# Demonstrate event bubbling
#

cont = lv.obj(lv.scr_act())
cont.set_size(290, 200)
cont.center()
cont.set_flex_flow(lv.FLEX_FLOW.ROW_WRAP)

for i in range(30):
    btn = lv.btn(cont)
    btn.set_size(70, 50)
    btn.add_flag(lv.obj.FLAG.EVENT_BUBBLE)

    label = lv.label(btn)
    label.set_text("{:d}".format(i))
    label.center()

cont.add_event(event_cb, lv.EVENT.CLICKED, None)

---

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_obj_draw_part_dsc_t * dsc = lv_event_get_draw_part_dsc(e);
    if(dsc->class_p == &lv_obj_class && 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(dsc->draw_ctx, &draw_dsc, &a);
    }
}

/**
 * Demonstrate the usage of draw event
 */
void lv_example_event_4(void)
{
    lv_obj_t * cont = lv_obj_create(lv_scr_act());
    lv_obj_set_size(cont, 200, 200);
    lv_obj_center(cont);
    lv_obj_add_event(cont, event_cb, LV_EVENT_DRAW_PART_END, NULL);
    lv_timer_create(timer_cb, 30, cont);
}

#endif

MicroPython code  

 View on GitHub MicroPython Simulator

class LV_Example_Event_4:

    def __init__(self):
        #
        # Demonstrate the usage of draw event
        #
        self.size = 0
        self.size_dec = False
        self.cont = lv.obj(lv.scr_act())
        self.cont.set_size(200, 200)
        self.cont.center()
        self.cont.add_event(self.event_cb, lv.EVENT.DRAW_PART_END, None)
        lv.timer_create(self.timer_cb, 30, None)

    def timer_cb(self,timer) :
        self.cont.invalidate()
        if self.size_dec :
            self.size -= 1
        else :
            self.size += 1

        if self.size == 50 :
            self.size_dec = True
        elif self.size == 0:
            self.size_dec = False

    def event_cb(self,e) :
        obj = e.get_target_obj()
        dsc = e.get_draw_part_dsc()
        if dsc.class_p == lv.obj_class and dsc.part == lv.PART.MAIN :
            draw_dsc = lv.draw_rect_dsc_t()
            draw_dsc.init()
            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

            a = lv.area_t()
            a.x1 = 0
            a.y1 = 0
            a.x2 = self.size
            a.y2 = self.size
            coords = lv.area_t()
            obj.get_coords(coords)
            coords.align(a, lv.ALIGN.CENTER, 0, 0)

            dsc.draw_ctx.rect(draw_dsc, a)

lv_example_event_4 = LV_Example_Event_4()

---

API

lv_event.h

lv_obj_event.h