Events

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:

Call function

User-defined functions can be called like this:

<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>

When the XML is loaded at runtime, the callback name needs to be mapped to a function using lv_xml_register_event_cb("my_callback_1", an_event_handler).

The callback should follow the standard LVGL event callback signature: void an_event_handler(lv_event_t * e);

In the exported C code, it is assumed that a function with the exact name exists. 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");

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

Screen Load and Create events

By using the <screen_load_event> and <screen_create_event> tags as a child of a widget or component, screens can be loaded or created on a trigger (e.g. click).

The difference between load and create is that:

  • load: Just loads an already existing screen. After leaving the screen, it remains in memory, so all states are preserved.

  • create: The screen is created dynamically, and when leaving the screen, it is deleted, so all changes are lost (unless they are saved in subjects).

Both tags support the following optional attributes:

  • trigger: Event code that triggers the action (e.g. "clicked", "long_pressed", etc). Default: "clicked".

  • anim_type: Describes 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.

This is a simple example of both load and create:

<!-- screen1.xml -->
<screen>
   <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>

lv_xml_component_register_from_data("screen1", screen1_xml);
lv_xml_component_register_from_data("screen2", screen2_xml);

/*Create an instance of screen_1 so that it can loaded from screen2.*/
lv_obj_t * screen1 = lv_xml_create(NULL, "screen1", NULL);
lv_screen_load(screen1);

Set subject value

It's possible to set a Subject value on user interaction by adding a special child to any widget:

<view>
    <lv_button width="200" height="100">
        <subject_set_int trigger="clicked" subject="subject1" value="10"/>
        <subject_set_string trigger="clicked" subject="subject2" value="Hello"/>
        <lv_label text="Set to 10"/>
    </lv_button>
</view>

The usage is straightforward: the specified subject will be set to the given value when the trigger occurs.

Increment subject value

Incrementing or decrementing a Subject value can be defined as follows:

<view>
    <lv_button width="200" height="100">
        <subject_increment trigger="clicked" subject="subject1" step="10"/>
        <subject_increment trigger="clicked" subject="subject2" step="-10" min="0" max="50"/>
    </lv_button>
</view>

The <subject_increment> element defines a step to be added to the subject's current value when the trigger occurs. Optionally, min and/or max can be set to limit the subject's value.

If step is negative, the subject's value will be decremented.

Note: Only integer subjects are supported by <subject_increment>.