Labs / LVGL / 02 LVGL Basic Knowledge and Concepts

III. Interaction and Event Handling: The Interaction Nerve of GUI

Author: Li Zisheng · Source: FreakStudio open documentation, v1.0 · License: CC BY 4.0

Contents

Realizing a complete interaction chain of "user operation → interface response" through input device adaptation and event mechanism is the core of the operability of GUI.

3.1 Input Device Adaptation (Input devices)

The input devices defined by LVGL are mainly divided into four categories, covering the mainstream interaction methods in embedded scenarios:

  • Supported Types: Compatible with mainstream embedded input hardware such as pointer-class devices (touch, mouse), keyboards, encoders (, etc.
  • Working Logic: Convert hardware input signals into input events recognizable by LVGL, and deliver them to the corresponding objects to implement operations such as tapping, swiping, and key pressing.

3.1.1 Core Interaction Mechanism

Category

Core Interaction Capability

Key Mechanisms / Events

Important Supplement

Pointer Devices (Pointers)

Cursor, Gesture

Cursor: An image object can be bound as the cursor for an input device;

Gesture: LV_EVENT_GESTURE is used to capture four types of gestures: up, down, left, and right

The cursor object needs to remove the "clickable" flag (disabled by default for image objects);

By default, gestures are propagated to the parent object; to prevent this propagation, you need to remove LV_OBJ_FLAG_GESTURE_BUBBLE;

Objects that are scrolling will not trigger gestures;

After handling the gesture, you can call lv_indev_wait_release to block subsequent input events.

Keyboard / Encoder (Keypad and encoder)

No cursor, relies on Group interaction

First create a group and add UI components to it;

There is always only one focused object within the group;

The input device shall be associated with a group;

Default groups can be configured

One device can only be bound to one group, while one group can receive inputs from multiple devices;

Buttons, sliders, text boxes and other controls can all be added to groups to simplify interaction development

Encoder Navigation / Edit Mode

Turn left, turn right, press

Navigation mode: Rotating left/right switches the focused object (LV_KEY_PREV / LV_KEY_NEXT), and pressing the button enters edit mode (LV_KEY_ENTER);

Edit Mode: Rotating left/right corresponds to modifying values or states (LV_KEY_LEFT / LV_KEY_RIGHT), press to return to navigation mode

The "dual mode" is used to compensate for the limitation that the encoder only has three actions: left rotation, right rotation and pressing.

Style Feedback

Interactive state-driven style changes

LV_STATE_FOCUSED : Takes effect when the object is focused via touch, keyboard or encoder;

LV_STATE_EDITED `: Takes effect when the object enters edit mode

3.1.2 Core Constants (Predefined Keys)

The core of the interaction between the keyboard / encoder lies in the key constants predefined by LVGL, which map the general interaction logic. To realize standardized interaction, it is necessary to map the hardware keys to these constants. The following is the function description of the core constants:

Constant nameFunction meaning
LV_KEY_NEXTFocus the next object in the group
LV_KEY_PREVFocus the previous object in the group
LV_KEY_ENTERTriggers press, click, long-press and other events (e.g., button click, confirm action)
LV_KEY_UPIncrease value / move up (e.g., slider up, text box cursor up)
LV_KEY_DOWNDecrease value / move down
LV_KEY_RIGHTIncrease value / move right (e.g., slider right, text box cursor right)
LV_KEY_LEFTDecrease value / move left
LV_KEY_ESCClose / exit (e.g., close dropdown list, exit current page)
LV_KEY_DELDelete the character to the right of the cursor (e.g., text box editing)
LV_KEY_BACKSPACEDelete the character to the left of the cursor (e.g., text box editing)
LV_KEY_HOMEJump to the beginning / top (e.g., text box cursor to the beginning, list to the top)
LV_KEY_ENDJump to the end (e.g., text box cursor to the end, list to the bottom)

Instructions: In the read_cb () callback function of the input device, you only need to map the core constants (NEXT/PREV/ENTER/LEFT/RIGHT) to cover most interaction scenarios; for the encoder, only the three constants LEFT/RIGHT/ENTER need to be mapped.

3.2 Event Mechanism (Events)

3.2.1 Core Definition of an Event

The event system of LVGL serves as the "nerve center" for GUI interaction, which captures various behaviors including user operations, system state changes, and widget lifecycle events, and triggers custom logic accordingly.

An event is LVGL's notification mechanism for "noteworthy behaviors or state changes", and the triggering scenarios include:

Scope of Application: Not only common controls (buttons, sliders, labels) can listen for events, but also displays and input devices can register event listeners.

The core features are as follows:

3.2.2 Event Binding and Removal

3.2.2.1 Event Binding
3.2.2.2 Event Removal

3.2.3 Event Code Classification

Event categoryEvent codeFunction description
Input device events (can be received by all widgets)LV_EVENT_PRESSEDObject is pressed (triggered once)
LV_EVENT_PRESSINGObject is being continuously pressed (triggered repeatedly while pressed)
LV_EVENT_PRESS_LOSTObject is still pressed, but the cursor / finger slides out of the object area
LV_EVENT_SHORT_CLICKEDObject is released after a short press (not triggered if scrolling occurred)
LV_EVENT_LONG_PRESSEDObject press duration reaches the long-press threshold (not triggered if scrolling occurred)
LV_EVENT_LONG_PRESSED_REPEATAfter the long-press threshold, triggered once every specified interval (not triggered if scrolling occurred)
LV_EVENT_CLICKEDTriggered on release (regardless of short or long press; not triggered if scrolling occurred)
LV_EVENT_RELEASEDTriggered in all release scenarios (including release after sliding out of the object)
LV_EVENT_SCROLL_BEGINScrolling begins; the event parameter is a pointer to the scroll animation (modifiable)
LV_EVENT_SCROLL_THROW_BEGINScroll throw begins (no additional notes)
LV_EVENT_SCROLL_ENDScrolling ends
LV_EVENT_SCROLLTriggered during scrolling
LV_EVENT_GESTUREGesture detected; the gesture direction can be obtained with lv_indev_get_gesture_dir()
LV_EVENT_KEYA key is sent to the object; the key can be obtained with lv_indev_get_key()
LV_EVENT_FOCUSEDObject gains focus
LV_EVENT_DEFOCUSEDObject loses focus
LV_EVENT_LEAVEObject loses focus but remains selected
LV_EVENT_HIT_TESTPerform advanced hit testing
LV_EVENT_INDEV_RESETInput device is reset
Draw events (can be received by all widgets)LV_EVENT_COVER_CHECKCheck whether the object fully covers an area; the event parameter is lv_cover_check_info_t *
LV_EVENT_REFR_EXT_DRAW_SIZEGet the extra drawing area needed around the object (e.g., shadow); the event parameter is int32_t * (stores the size)
LV_EVENT_DRAW_MAIN_BEGINMain drawing phase begins
LV_EVENT_DRAW_MAINPerform main drawing logic
LV_EVENT_DRAW_MAIN_ENDMain drawing phase ends
LV_EVENT_DRAW_POST_BEGINPost-drawing phase begins (after all child objects are drawn)
LV_EVENT_DRAW_POSTPerform post-drawing logic (after all child objects are drawn)
LV_EVENT_DRAW_POST_ENDPost-drawing phase ends (after all child objects are drawn)
LV_EVENT_DRAW_TASK_ADDEDTriggered when a draw task is added
Special events (widget-specific, triggered only by certain widgets)LV_EVENT_VALUE_CHANGEDObject value changes (e.g., slider drag, progress bar update)
LV_EVENT_INSERTText is inserted into the object; the event data is the inserted string (char *)
LV_EVENT_REFRESHNotifies the object to refresh its own content (for user-initiated triggering)
LV_EVENT_READYA process has completed
LV_EVENT_CANCELA process was cancelled
Other events (can be received by all widgets)LV_EVENT_CREATEObject is being created
LV_EVENT_DELETEObject is being destroyed
LV_EVENT_CHILD_CHANGEDChild object is removed / added, or its size / position changes
LV_EVENT_CHILD_CREATEDChild object is created (bubbles up to all parent objects)
LV_EVENT_CHILD_DELETEDChild object is destroyed (bubbles up to all parent objects)
LV_EVENT_SCREEN_UNLOAD_STARTScreen unload starts (triggered immediately when scr_load is called)
LV_EVENT_SCREEN_LOAD_STARTScreen load starts (triggered after the screen switch delay expires)
LV_EVENT_SCREEN_LOADEDScreen load finished
LV_EVENT_SCREEN_UNLOADEDScreen unload finished
LV_EVENT_SIZE_CHANGEDObject coordinates / size changed
LV_EVENT_STYLE_CHANGEDObject style changed
LV_EVENT_LAYOUT_CHANGEDChild object position changed due to layout recalculation
LV_EVENT_GET_SELF_SIZEGet the widget's internal self size
Display event (received only by display objects)LV_EVENT_INVALIDATE_AREADisplay area invalidated (needs redraw)
LV_EVENT_RESOLUTION_CHANGEDDisplay resolution changed
LV_EVENT_COLOR_FORMAT_CHANGEDDisplay color format changed
LV_EVENT_REFR_REQUESTDisplay requests refresh
LV_EVENT_REFR_STARTDisplay refresh starts
LV_EVENT_REFR_READYDisplay refresh ready
LV_EVENT_RENDER_STARTDisplay rendering starts
LV_EVENT_RENDER_READYDisplay rendering ready
LV_EVENT_FLUSH_STARTDisplay flush starts
LV_EVENT_FLUSH_FINISHDisplay flush finished
Custom event (registered by the user, not triggered by LVGL itself)Custom event code1. Register a custom event code via lv_event_register_id() (e.g. uint32_t MY_EVENT_1 = lv_event_register_id()); 2. Send it manually to any object via lv_event_send(obj, custom event code, &data)

Of course, there are also manually dispatched events and the special Refresh event:

Event categoryCore API / trigger methodFunction descriptionExample scenario
Send event manually (general)1. Widget: lv_obj_send_event(obj, <EVENT_CODE>, &some_data)
2. Display: lv_display_send_event(obj, <EVENT_CODE>, &some_data)
3. Input device: lv_indev_send_event(obj, <EVENT_CODE>, &some_data)
Actively triggers the target event on the specified object and can pass custom data; used to simulate user actions / system state changes instead of triggering the event through real interactionSimulate a button press: send LV_EVENT_VALUE_CHANGED with the button ID to close the message box manually
Refresh special event (LV_EVENT_REFRESH)Must be sent manually via lv_obj_send_event() (LVGL does not trigger this event automatically)A refresh notification mechanism designed for the user, used to tell an object to update its own state, appearance or business logic1. A label refreshes its text from a variable (e.g. showing the real-time clock)
2. Refresh a label's displayed text when the language changes
3. Enable a button after the correct PIN is entered
4. Add / remove a warning style on an object when a value exceeds its limit

3.2.4 lv_event_t: Core Parameter for Event Callbacks

3.2.4.1 Core Concepts

In LVGL development with MicroPython (MPY), event_t (corresponding to lv_event_t in C language) is the only parameter received by the event callback function, which encapsulates all context information of the event, including event type, triggering object, custom data, etc.

MPY wraps the C-language lv_event_get_xxx (e) function form into a event_t class member method (such as e.get_code ()) that better conforms to Python syntax; it has no pointer concept, and all return values are class instances encapsulated by LVGL-MPY (such as the widget object obj and the area object area_t), serving as the "core hub" for event processing.

3.2.4.2 Summary Table of Core Methods
CategoryMethod name (MPY)Core meaningTypical use case / notes
Basic core methods (must know)get_code()Get the event code that triggered the current callback (e.g. LV_EVENT_CLICKED/LV_EVENT_VALUE_CHANGED)Branching in a callback: "run logic A on a click event, run logic B on a value-changed event"
get_target() / get_target_obj()Get the widget object that originally triggered the event (with event bubbling, still returns the original child widget)When a parent container listens to child widget events, pinpoints "who triggered the event"
get_current_target() / get_current_target_obj()Get the widget object currently handling the event (with event bubbling, returns the parent container when the parent handles it)Same return value as get_target_obj() when there is no bubbling; with bubbling, distinguishes the "trigger" from the "handler"
get_user_data()Get the custom user data passed when the event was bound (e.g. button ID, config dict)Multiple widgets share one callback and use user_data to distinguish the handling logic
get_param()Get the event parameter passed when the event was sent manually (e.g. the button ID of a simulated button click)Pass data when triggering an event manually to implement custom interaction
Event flow controlstop_bubbling()Stop the event from bubbling up (the parent container no longer receives it)After a child widget handles the event, prevents the parent container from responding again
stop_processing()Terminate all subsequent event callbacks of the current objectAfter the event is handled, stop redundant callback execution
Input device relatedget_indev()Get the input device object that triggered the event (touchscreen / key / encoder)Distinguish the event source: determine whether it was triggered by touch or by a key
get_key()Get the key value of an LV_EVENT_KEY event (integer type)Key interaction: determine whether the confirm key / back key / arrow key was pressed
get_rotary_diff()Get the increment of a rotary encoder (positive or negative indicates rotation direction)Encoder interaction: adjust volume / slider value based on the increment
Scroll / animation relatedget_scroll_anim()Get the animation object of the scroll animation (anim_t)Custom scroll animation: modify scroll duration / easing curve
Drawing / layout specific (custom widgets)set_ext_draw_size(size)Set the extra draw area size of the widget (e.g. the area that a shadow / border extends beyond)When a custom widget adds a shadow, specify the extra drawing space
get_self_size_info()Get the widget's self size information (point_t, x = width / y = height)Custom scroll container: calculate the actual content size and trigger scroll logic
get_hit_test_info()Get hit test information (hit_test_info_t)Custom clickable area: e.g. a circular widget responds only to clicks within the circle
get_cover_area()Get the widget's cover area (area_t)Drawing optimization: determine whether the widget covers other widgets and skip unnecessary drawing
set_cover_res(res)Set the cover check result (fully covered / partially covered / not covered)Tell LVGL the widget's cover status to reduce drawing overhead
get_draw_task()Get the current draw task object (draw_task_t)Custom drawing flow: modify draw priority / content
Extended information retrievalget_invalidated_area()Get the screen invalidated area when the event is triggered (area_t)Drawing optimization: redraw only the areas that need updating
get_layer()Get the layer object the widget belongs to (layer_t)Multi-layer management: determine whether the widget is on a normal layer / top layer
get_old_size()Get the widget's old size before the size change (area_t)Size change event: compare the size before and after modification

3.2.5 Event Bubbling

Event bubbling is a mechanism designed by LVGL for hierarchical controls to propagate events upwards:

The key method to enable event bubbling is add_flag:

III. Interaction and Event Handling: The Interaction Nerve of GUI

Core event methods for bubbling scenarios (distinguishing between "current target" and "original target"):

Method (MPY)FunctionKey role in bubbling scenarios
event.get_current_target_obj()Get the object currently handling the eventWhen bubbling to a parent container, returns the parent container; when bubbling to the screen, returns the screen
event.get_target_obj()Get the child object that originally triggered the eventRegardless of the level it bubbles to, always returns the widget that originally triggered the event (e.g. the clicked button)

Version Record

Version Number

Modifier

Time

Content

v1.0

Li Zisheng

2026/03/23

Initialize the document.