docs/src/common-widget-features/events.rst
.. _events: .. _lv_obj_events:
Events are triggered in LVGL when something happens which might be interesting to the user, e.g. when a Widget:
Besides Widgets, events can be registered for 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_.
.. _adding_events_to_a_widget:
Adding Events to a Widget
The user can assign callback functions to a widget to process events. In practice, it looks like this:
.. code-block:: c
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 :cpp:enumerator:LV_EVENT_CLICKED means that only the click event will
call my_event_cb. See the :ref:list of event codes <events_codes> for
all the options. :cpp:enumerator:LV_EVENT_ALL can be used to receive all events.
The last parameter of :cpp:func:lv_obj_add_event_cb 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:
.. code-block:: c
my_user_data_t * user_data;
...
user_data = lv_event_get_user_data(e);
More events can be added to a Widget, like this:
.. code-block:: c
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:
.. code-block:: c
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:
.. code-block:: c
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
.. code-block:: c
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; } }
.. _events_codes:
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 :ref:widgets' documentation <widgets> to learn when they
are sent,
Custom events are added by the user and are never sent by LVGL.
The following event codes exist:
.. _indev_events:
LV_EVENT_PRESSED: Widget has been pressedLV_EVENT_PRESSING: Widget is being pressed (called continuously while pressing)LV_EVENT_PRESS_LOST: Widget is still being pressed but slid cursor/finger off WidgetLV_EVENT_SHORT_CLICKED: Widget was pressed for a short period of time, and then released without scrolling.LV_EVENT_SINGLE_CLICKED: Widget 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: Widget 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: Widget 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: Widget 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 Widget 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_THROW_BEGIN:LV_EVENT_SCROLL_END: Scrolling endsLV_EVENT_SCROLL: ScrollingLV_EVENT_GESTURE: A gesture is detected. Get the gesture with :cpp:expr:lv_indev_get_gesture_dir(lv_indev_active())LV_EVENT_KEY: A key is sent to Widget. Get the key with :cpp:expr:lv_indev_get_key(lv_indev_active())LV_EVENT_FOCUSED: Widget received focusLV_EVENT_DEFOCUSED: Widget is defocusedLV_EVENT_LEAVE: Widget 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 WidgetLV_EVENT_HOVER_LEAVE: Indev hover leave WidgetLV_EVENT_COVER_CHECK: Check if Widget fully covers an area. The event parameter is :cpp:type:lv_cover_check_info_t *.LV_EVENT_REFR_EXT_DRAW_SIZE: Get the required extra draw area around Widget (e.g. for shadow). The event parameter is :cpp:type:int32_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.. attention::
In drawing-event callback functions the rendering
sequence has already begun, and during this period, making changes to any
Widget's attributes, styles, or creating/deleting widgets is forbidden. If you attempt to do so,
LVGL will generate an assertion failure with a message
indicating that invalidating an area is not allowed during rendering.
LV_EVENT_VALUE_CHANGED: Widget's value has changed (i.e. slider moved)LV_EVENT_INSERT: A text is inserted to Widget. The event data is char * being inserted.LV_EVENT_REFRESH: Notify Widget to refresh something on it (for the user)LV_EVENT_READY: A process has finishedLV_EVENT_CANCEL: A process has been cancelledLV_EVENT_STATE_CHANGED: The state of a widget has been changed.
E.g. :cpp:enumerator:LV_STATE_PRESSED was added. In the event :cpp:expr:lv_event_get_prev_state(e)
returns the previous state and :cpp:expr:lv_obj_get_state(obj) returns the current state.LV_EVENT_CREATE: Widget is being createdLV_EVENT_DELETE: Widget 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: Widget coordinates/size have changedLV_EVENT_STYLE_CHANGED: Widget'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.. include:: ../main-modules/display/display_events_list.txt
Any number of custom event codes can be registered by
uint32_t MY_EVENT_1 = :cpp:func:lv_event_register_id
They can be sent to any Widget with
:cpp:expr:lv_obj_send_event(widget, MY_EVENT_1, &some_data)
:cpp:enumerator:LV_EVENT_REFRESH is a special event because it's designed to let the
user notify a Widget to refresh itself. Some examples:
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):
.. code-block:: c
/* 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
:cpp:type: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 retrieved from it:
lv_event_get_code(e): get the event codelv_event_get_current_target(e): get Widget to which an event was sent. I.e. the Widget whose event handler is being called.lv_event_get_target(e): get the Widget, Display or Indev that originally triggered the event (different from :cpp:func:lv_event_get_current_target if :ref:event bubbling <event_bubbling> is enabled).lv_event_get_target_obj(e): get the Widget that originally triggered the event.lv_event_get_user_data(e): get the pointer passed as the last parameter of :cpp:func:lv_obj_add_event_cb.lv_event_get_param(e): get the parameter passed as the last parameter of :cpp:func:lv_obj_send_event_cb.. tip::
When using C++, prefer :cpp:expr:lv_event_get_target_obj(e) over :cpp:expr:lv_event_get_target(e)
when you know the target is a Widget, as it returns the correct type without requiring a cast.
.. warning::
Only call :cpp:expr:lv_event_get_target_obj(e) when the event target is known to be a Widget.
Calling it for Display or Indev targets is considered Undefined Behavior.
.. _event_bubbling:
Event Bubbling
If :cpp:expr: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
:cpp:enumerator: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
:cpp:expr:lv_event_get_target_obj(e) in the event handler.
.. _event_trickle:
Event Trickle
Also known as Event Capturing, if :cpp:expr:lv_obj_add_flag(widget, LV_OBJ_FLAG_EVENT_TRICKLE)
is enabled all events will be sent to the Widget's children as well. This is the opposite of
event bubbling --- instead of propagating up the parent, events propagate down to the children.
The trickle mechanism only affects immediate children, not grandchildren or
deeper descendants. If you need events to propagate to deeper levels, each child
would need to have the :cpp:enumerator:LV_OBJ_FLAG_EVENT_TRICKLE flag enabled.
Like with bubbling, the target parameter of the event is always the current target Widget,
not the original Widget. To get the original target call
:cpp:expr:lv_event_get_target_obj(e) in the event handler.
.. _events_examples:
Examples
.. include:: /examples/event/index.rst
.. _events_api:
API
.. API equals: lv_cover_check_info_t lv_display_add_event_cb lv_event_get_code lv_event_get_target_obj lv_event_get_user_data lv_event_register_id LV_EVENT_RENDER_START lv_event_t lv_indev_active lv_indev_add_event_cb lv_indev_get_gesture_dir lv_indev_get_key lv_obj_add_event_cb lv_obj_add_flag lv_obj_get_event_count lv_obj_remove_event lv_obj_send_event