Events

Learn how to handle and trigger events in LVGL Pro Editor using XML.

Respond to user interactions by defining events on widgets that trigger callbacks, navigate between screens, or update application state when specific actions occur.

Overview

There are several ways to define events for user interactions. These events can be added as children of any widget.

Triggers

In all event types, the trigger attribute defines what kind of user action should trigger the event. All LVGL event types are supported with straightforward mapping:

"all" - LV_EVENT_ALL
"clicked" - LV_EVENT_CLICKED
"pressed" - LV_EVENT_PRESSED
etc

Call Function

User-defined functions can be called in response to events like this:

xml

<view>
 <lv_button width="200" height="100">
  <event_cb callback="my_callback_1" trigger="clicked" user_data="some_text"/>
  <lv_label text="Hello"/>
 </lv_button>
</view>

The callback must follow the standard LVGL event callback signature:

void an_event_handler(lv_event_t * e);

In exported C code, a function with the exact name is assumed to defined by the user. For example, callback="my_callback_1" will be exported as:

void my_callback_1(lv_event_t * e); /* At the beginning of the exported file */

lv_obj_add_event_cb(obj, my_callback_1, LV_EVENT_CLICKED, "some_text");

And it's the developer's responsibility to implement the my_callback_1.

It's a good idea to add event function in the <project_name>.c file, created by the editor to keep all the related functions in one place. If there are a lot of event functions it's recommended to create multiple files for them.

To distinguish simulator builds from builds for an embedded device add defines like #define BUILD_SIMULATOR and wrap the event callbacks to #if BUILD_SIMULATOR.

The user_data attribute is optional. If omitted, NULL will be passed.

Screen Load and Create Events

Use the screen_load_event and screen_create_event tags as children of a widget or component to load or create screens in response to user interactions (such as a click).

The key difference between load and create is:

load - Loads an already existing screen. After leaving the screen, it remains in memory, so all states are preserved. The screen to load must have <screen permanent="true"/>
create - Creates the screen dynamically, and when leaving the screen, it is deleted, so all changes are lost (unless saved in subjects). The screen to load must have <screen permanent="false"/> (false is the default).

Both tags support these optional attributes:

trigger - Event code that triggers the action (e.g., "clicked", "long_pressed"). Default: "clicked".
anim_type - How the screen is loaded (e.g., "move_right", "fade_in"). Default: "none".
duration - Length of the animation in milliseconds. Default: 0. Only used if anim_type is not "none".
delay - Wait time before loading the screen in milliseconds. Default: 0.

Here is an example of both load and create events:

xml

<!-- screen1.xml -->
<screen permanent="true">
 <view style_bg_color="0xff7788">
  <lv_button>
   <lv_label text="Create"/>
   <!-- Create an instance of "screen2" and load it. -->
   <screen_create_event screen="screen2" anim_type="over_right" duration="500" delay="1000"/>
  </lv_button>
 </view>
</screen>

<!-- screen2.xml -->
<screen>
 <view style_bg_color="0x77ff88">
  <lv_button>
   <lv_label text="Load"/>
   <!-- Load an already created instance of screen1. -->
   <screen_load_event screen="screen1"/>
  </lv_button>
 </view>
</screen>

Set Subject Value

You can set subject values in response to user interactions by adding special event tags as children of any widget:

xml

<view>
 <lv_button width="200" height="100">
  <subject_set_int_event trigger="clicked" subject="subject_int" value="10"/>
  <subject_set_float_event trigger="clicked" subject="subject_float" value="12.34"/>
  <subject_set_string_event trigger="clicked" subject="subject_string" value="Hello"/>
  <lv_label text="Set the values"/>
 </lv_button>
</view>

The specified subject will be set to the given value when the trigger event occurs.

Increment Subject Value

Increment or decrement subject values in response to events using the subject_increment_event element:

xml

<view>
 <lv_button width="200" height="100">
  <subject_increment_event trigger="clicked" subject="subject_int1" step="10"/>
  <subject_increment_event trigger="clicked" subject="subject_int2" step="-10" min_value="0" max_value="50"/>
  <subject_increment_event trigger="clicked" subject="subject_float1" step="2"/>
 </lv_button>
</view>

The subject_increment_event element adds a step value to the subject's current value when the trigger event occurs.

The subject must be an int or float type.

If step is negative, the subject's value will be decremented. Currently, only integer step values are supported.

Optionally, use min_value and/or max_value to limit the subject's value. The default min/max values are INT32_MIN (-2,147,483,648) and INT32_MAX (+2,147,483,647) respectively.

The rollover property is optional. If false (default), the value stops at the min/max boundary; if true, it wraps to the other end.

Play Animation

Playing Timelines can be triggered by events (such as clicks) using the <play_timeline_event> element as a child of any widget.

Specify a target UI element and select one of its timelines to play. If target="self", the timeline is looked up in the current Component, or Screen (in the current XML file).

This example defines a timeline, and plays it on itself.

xml

<component>
	<animations>
		<timeline name="timeline_1">
			<animation target="self" duration="1000" prop="translate_x" start="100" end="0" />
			<animation target="main_button" duration="1000" prop="opa" start="0" end="255" />
		</timeline>
	</animations>

	<view>
		<lv_button name="main_button">
			<play_timeline_event trigger="clicked" timeline="timeline_1" target="self" />
			<lv_label text="Play" />
		</lv_button>
	</view>
</component>

Optionally a delay property can be set as well (in milliseconds), and the timeline can be played in reversed too:

xml

<play_timeline_event trigger="clicked" timeline="timeline_1" target="self" reverse="true" delay="500"/>