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.
It's not detailed below, however the same applies to displays and indevs as well
by changing the prefix of the functions from lv_obj_
to lv_display_
or lv_indev_
.
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);
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:
Input device events
LV_EVENT_PRESSED
: The object has been pressedLV_EVENT_PRESSING
: The object is being pressed (called continuously while pressing)LV_EVENT_PRESS_LOST
: The object is still being pressed but slid cursor/finger off of the objectLV_EVENT_SHORT_CLICKED
: The object was pressed for a short period of time, and then released without scrolling.LV_EVENT_SINGLE_CLICKED
: The object was pressed for a short period of time, and then released without scrolling, for the first time in a click streak. A click streak refers to multiple short clicks within a short period of time and a small distance.LV_EVENT_DOUBLE_CLICKED
: The object was pressed for a short period of time, and then released without scrolling, for the second time in a click streak.LV_EVENT_TRIPLE_CLICKED
: The object was pressed for a short period of time, and then released without scrolling, for the third time in a click streak.LV_EVENT_LONG_PRESSED
: Object has been pressed for at least long_press_time. 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 not scrolled (regardless of long press)LV_EVENT_RELEASED
: Called in every cases when the object has been releasedLV_EVENT_SCROLL_BEGIN
: Scrolling begins. The event parameter is a pointer to the animation of the scroll. Can be modifiedLV_EVENT_SCROLL_END
: Scrolling endsLV_EVENT_SCROLL
: ScrollingLV_EVENT_GESTURE
: A gesture is detected. Get the gesture with lv_indev_get_gesture_dir(lv_indev_active())LV_EVENT_KEY
: A key is sent to the object. Get the key with lv_indev_get_key(lv_indev_active())LV_EVENT_FOCUSED
: The object is focusedLV_EVENT_DEFOCUSED
: The object is defocusedLV_EVENT_LEAVE
: The object is defocused but still selectedLV_EVENT_HIT_TEST
: Perform advanced hit-testingLV_EVENT_INDEV_RESET
: Indev has been resetLV_EVENT_HOVER_OVER
: Indev hover over objectLV_EVENT_HOVER_LEAVE
: Indev hover leave object
Drawing Events
LV_EVENT_COVER_CHECK
: Check if the object fully covers an area. The event parameter islv_cover_check_info_t
*
.LV_EVENT_REFR_EXT_DRAW_SIZE
: Get the required extra draw area around the object (e.g. for shadow). The event parameter isint32_t
*
to store the size.LV_EVENT_DRAW_MAIN_BEGIN
: Starting the main drawing phaseLV_EVENT_DRAW_MAIN
: Perform the main drawingLV_EVENT_DRAW_MAIN_END
: Finishing the main drawing phaseLV_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_TASK_ADDED
: Adding a draw task
Special events
LV_EVENT_VALUE_CHANGED
: The object's value has changed (i.e. slider moved)LV_EVENT_INSERT
: A text is inserted to the object. The event data ischar
*
being inserted.LV_EVENT_REFRESH
: Notify the object to refresh something on it (for the user)LV_EVENT_READY
: A process has finishedLV_EVENT_CANCEL
: A process has been cancelled
Other events
LV_EVENT_CREATE
: Object is being createdLV_EVENT_DELETE
: Object is being deletedLV_EVENT_CHILD_CHANGED
: Child was removed, added, or its size, position were changedLV_EVENT_CHILD_CREATED
: Child was created, always bubbles up to all parentsLV_EVENT_CHILD_DELETED
: Child was deleted, always bubbles up to all parentsLV_EVENT_SCREEN_UNLOAD_START
: A screen unload started, fired immediately when scr_load is calledLV_EVENT_SCREEN_LOAD_START
: A screen load started, fired when the screen change delay is expiredLV_EVENT_SCREEN_LOADED
: A screen was loadedLV_EVENT_SCREEN_UNLOADED
: A screen was unloadedLV_EVENT_SIZE_CHANGED
: Object coordinates/size have changedLV_EVENT_STYLE_CHANGED
: Object's style has changedLV_EVENT_LAYOUT_CHANGED
: The children position has changed due to a layout recalculationLV_EVENT_GET_SELF_SIZE
: Get the internal size of a widget
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 objects with lv_obj_send_event(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_obj_send_event(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)
.
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_obj_send_event()
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
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.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_t obj_coords;
lv_obj_get_coords(obj, &obj_coords);
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_draw(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