# Events (/syntax/events)



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

Overview [#overview]

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

Triggers [#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 [#call-function]

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

```xml title="xml" lineNumbers=1
<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:

```c title=" " lineNumbers=1
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:

```c title=" " lineNumbers=1
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`.

Recommendations [#recommendations]

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 [#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"/>`](./screens)
* **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"/>`](./screens) (`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 title="xml" lineNumbers=1
<!-- 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 [#set-subject-value]

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

```xml title="xml" lineNumbers=1
<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-subject-value]

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

```xml title="xml" lineNumbers=1
<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 [#play-animation]

Playing [Timelines](./animations) 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 `timeline`s 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 title="xml" lineNumbers=1
<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 title="xml" lineNumbers=1
<play_timeline_event trigger="clicked" timeline="timeline_1" target="self" reverse="true" delay="500"/>
```