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:
- Pointer-type devices: devices such as touchpads and mice that can control the movement of the cursor;
- Keyboard devices: key assembly devices such as standard keyboards and numeric keypads;
- Encoder: A -type device that supports left/right rotation and press operations;
- External hardware keys: physical keys bound to specific positions on the screen.
- 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: | 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 Objects that are scrolling will not trigger gestures; After handling the gesture, you can call |
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 ( Edit Mode: Rotating left/right corresponds to modifying values or states ( | 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 |
|
|
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 name | Function meaning |
|---|---|
| LV_KEY_NEXT | Focus the next object in the group |
| LV_KEY_PREV | Focus the previous object in the group |
| LV_KEY_ENTER | Triggers press, click, long-press and other events (e.g., button click, confirm action) |
| LV_KEY_UP | Increase value / move up (e.g., slider up, text box cursor up) |
| LV_KEY_DOWN | Decrease value / move down |
| LV_KEY_RIGHT | Increase value / move right (e.g., slider right, text box cursor right) |
| LV_KEY_LEFT | Decrease value / move left |
| LV_KEY_ESC | Close / exit (e.g., close dropdown list, exit current page) |
| LV_KEY_DEL | Delete the character to the right of the cursor (e.g., text box editing) |
| LV_KEY_BACKSPACE | Delete the character to the left of the cursor (e.g., text box editing) |
| LV_KEY_HOME | Jump to the beginning / top (e.g., text box cursor to the beginning, list to the top) |
| LV_KEY_END | Jump 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:
- User interaction: triggered by control clicks, scrolling, keystrokes, and gesture operations;
- System status: control redraw, size/style/layout change, object creation/deletion, screen switch;
- Custom Behavior: Custom logic triggered manually by the user.
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:
- Event Binding: Allows adding/removing event callbacks for objects to respond to events such as click, long press, status change, value change, etc.
- Event propagation: supports event bubbling (events of child objects are propagated upward to parent objects), allows manual event dispatching, and enables flexible implementation of complex interaction logic.
- Event context: It passes information such as event sources and parameters via the
lv_event_tstruct, enabling the callback function to accurately handle interaction scenarios.
3.2.2 Event Binding and Removal
3.2.2.1 Event Binding
- Core logic: Associate a "callback function" with an object and specify the event type to be monitored (e. g., only monitor clicks, or monitor all events);
- Key Features:
- Multiple event callbacks can be bound to a single object (e. g., listening for both "press" and "click" events simultaneously), and their execution order follows the sequence in which they are bound;
- The same callback function can be bound to multiple objects, or bound to the same object multiple times (with different custom data passed);
- It supports passing custom data (specified when binding events), which can be obtained in the callback to implement differentiated logic;
- The event binding logic of the display screen and input devices is completely consistent with that of the controls.
3.2.2.2 Event Removal
- Core logic: You need to first traverse the event list of the object, find the event descriptor corresponding to the target callback, and then remove it via the index;
- Applicable scenario: When you no longer need to listen for a certain type of event (e. g., cleaning up callbacks before a control is destroyed).
3.2.3 Event Code Classification
| Event category | Event code | Function description |
|---|---|---|
| Input device events (can be received by all widgets) | LV_EVENT_PRESSED | Object is pressed (triggered once) |
| LV_EVENT_PRESSING | Object is being continuously pressed (triggered repeatedly while pressed) | |
| LV_EVENT_PRESS_LOST | Object is still pressed, but the cursor / finger slides out of the object area | |
| LV_EVENT_SHORT_CLICKED | Object is released after a short press (not triggered if scrolling occurred) | |
| LV_EVENT_LONG_PRESSED | Object press duration reaches the long-press threshold (not triggered if scrolling occurred) | |
| LV_EVENT_LONG_PRESSED_REPEAT | After the long-press threshold, triggered once every specified interval (not triggered if scrolling occurred) | |
| LV_EVENT_CLICKED | Triggered on release (regardless of short or long press; not triggered if scrolling occurred) | |
| LV_EVENT_RELEASED | Triggered in all release scenarios (including release after sliding out of the object) | |
| LV_EVENT_SCROLL_BEGIN | Scrolling begins; the event parameter is a pointer to the scroll animation (modifiable) | |
| LV_EVENT_SCROLL_THROW_BEGIN | Scroll throw begins (no additional notes) | |
| LV_EVENT_SCROLL_END | Scrolling ends | |
| LV_EVENT_SCROLL | Triggered during scrolling | |
| LV_EVENT_GESTURE | Gesture detected; the gesture direction can be obtained with lv_indev_get_gesture_dir() | |
| LV_EVENT_KEY | A key is sent to the object; the key can be obtained with lv_indev_get_key() | |
| LV_EVENT_FOCUSED | Object gains focus | |
| LV_EVENT_DEFOCUSED | Object loses focus | |
| LV_EVENT_LEAVE | Object loses focus but remains selected | |
| LV_EVENT_HIT_TEST | Perform advanced hit testing | |
| LV_EVENT_INDEV_RESET | Input device is reset | |
| Draw events (can be received by all widgets) | LV_EVENT_COVER_CHECK | Check whether the object fully covers an area; the event parameter is lv_cover_check_info_t * |
| LV_EVENT_REFR_EXT_DRAW_SIZE | Get the extra drawing area needed around the object (e.g., shadow); the event parameter is int32_t * (stores the size) | |
| LV_EVENT_DRAW_MAIN_BEGIN | Main drawing phase begins | |
| LV_EVENT_DRAW_MAIN | Perform main drawing logic | |
| LV_EVENT_DRAW_MAIN_END | Main drawing phase ends | |
| LV_EVENT_DRAW_POST_BEGIN | Post-drawing phase begins (after all child objects are drawn) | |
| LV_EVENT_DRAW_POST | Perform post-drawing logic (after all child objects are drawn) | |
| LV_EVENT_DRAW_POST_END | Post-drawing phase ends (after all child objects are drawn) | |
| LV_EVENT_DRAW_TASK_ADDED | Triggered when a draw task is added | |
| Special events (widget-specific, triggered only by certain widgets) | LV_EVENT_VALUE_CHANGED | Object value changes (e.g., slider drag, progress bar update) |
| LV_EVENT_INSERT | Text is inserted into the object; the event data is the inserted string (char *) | |
| LV_EVENT_REFRESH | Notifies the object to refresh its own content (for user-initiated triggering) | |
| LV_EVENT_READY | A process has completed | |
| LV_EVENT_CANCEL | A process was cancelled | |
| Other events (can be received by all widgets) | LV_EVENT_CREATE | Object is being created |
| LV_EVENT_DELETE | Object is being destroyed | |
| LV_EVENT_CHILD_CHANGED | Child object is removed / added, or its size / position changes | |
| LV_EVENT_CHILD_CREATED | Child object is created (bubbles up to all parent objects) | |
| LV_EVENT_CHILD_DELETED | Child object is destroyed (bubbles up to all parent objects) | |
| LV_EVENT_SCREEN_UNLOAD_START | Screen unload starts (triggered immediately when scr_load is called) | |
| LV_EVENT_SCREEN_LOAD_START | Screen load starts (triggered after the screen switch delay expires) | |
| LV_EVENT_SCREEN_LOADED | Screen load finished | |
| LV_EVENT_SCREEN_UNLOADED | Screen unload finished | |
| LV_EVENT_SIZE_CHANGED | Object coordinates / size changed | |
| LV_EVENT_STYLE_CHANGED | Object style changed | |
| LV_EVENT_LAYOUT_CHANGED | Child object position changed due to layout recalculation | |
| LV_EVENT_GET_SELF_SIZE | Get the widget's internal self size | |
| Display event (received only by display objects) | LV_EVENT_INVALIDATE_AREA | Display area invalidated (needs redraw) |
| LV_EVENT_RESOLUTION_CHANGED | Display resolution changed | |
| LV_EVENT_COLOR_FORMAT_CHANGED | Display color format changed | |
| LV_EVENT_REFR_REQUEST | Display requests refresh | |
| LV_EVENT_REFR_START | Display refresh starts | |
| LV_EVENT_REFR_READY | Display refresh ready | |
| LV_EVENT_RENDER_START | Display rendering starts | |
| LV_EVENT_RENDER_READY | Display rendering ready | |
| LV_EVENT_FLUSH_START | Display flush starts | |
| LV_EVENT_FLUSH_FINISH | Display flush finished | |
| Custom event (registered by the user, not triggered by LVGL itself) | Custom event code | 1. 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 category | Core API / trigger method | Function description | Example 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 interaction | Simulate 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 logic | 1. 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
| Category | Method name (MPY) | Core meaning | Typical 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 control | stop_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 object | After the event is handled, stop redundant callback execution | |
| Input device related | get_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 related | get_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 retrieval | get_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:
- When a child control triggers an event (such as a click or value change), if the
LV_OBJ_FLAG_EVENT_BUBBLEflag is enabled for that child control, the event will automatically be propagated to its parent container; - If the parent container also has this bubbling flag enabled, the event will continue to propagate upward to the grandparent container until it encounters "a parent object with the bubbling flag disabled" or "no parent object (such as the screen)".
- Core value: There is no need to bind events to each sub-control individually, as the parent container can uniformly handle events for all sub-controls (for example, if there are 10 buttons in a container, you only need to bind one callback to the container to handle all button clicks).
The key method to enable event bubbling is add_flag:

Core event methods for bubbling scenarios (distinguishing between "current target" and "original target"):
| Method (MPY) | Function | Key role in bubbling scenarios |
|---|---|---|
| event.get_current_target_obj() | Get the object currently handling the event | When 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 event | Regardless 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. |