Components

Overview

<component> can have <consts>, <api>, <styles>, and <view> tags inside.

Unlike widgets (which are always compiled into the application), components can either:

Be loaded at runtime from XML.
Be exported to C code.

Usage from exported code

From each component XML file, a C and H file is exported with a single function inside:

lv_obj_t * component_name_create(lv_obj_t * parent, ...api properties...);

When a component is used in another component’s XML code and the code is exported, this create function will be called. This means that components do not have a detailed set/get API but can be created with a fixed set of parameters.

If the user needs to access or modify values dynamically, it is recommended to use a subject.

The user can also call these _create_ functions at any time from the application code.

Usage from XML

Registration

Once a component is created (e.g., my_button), it can be registered by calling either:

lv_xml_component_register_from_file("A:lvgl/examples/others/xml/my_button.xml");
lv_xml_component_register_from_data("my_button", xml_data_of_my_button);

These registration functions process the XML data and store relevant information internally. This is required to make LVGL recognize the component by name.

When loaded from a file, the file name is used as the component name.

Instantiation

After registration, a new instance of any registered component can be created with:

lv_obj_t * obj = lv_xml_create(lv_screen_active(), "my_button", NULL);

The created widget is a normal LVGL widget that can be used like any other manually created widget.

The last parameter can be NULL or an attribute list, like this:

/* Can be local */
char * my_button_attrs[] = {
    "x", "10",
    "y", "-10",
    "align", "bottom_left",
    "btn_text", "New button",
    NULL, NULL,
};

lv_obj_t * btn1 = lv_xml_create(lv_screen_active(), "my_button", my_button_attrs);

Parameters

The properties of child elements can be adjusted, such as:

<lv_label x="10" text="Hello"/>

These parameters can be set to a fixed value. However, with the help of <prop> elements inside the <api> tag, they can also be passed when an instance is created. Only the whole property can be passed, but not individual <param> elements.

Additionally, when a component is created, it can use the extended widget's attributes (see <view extends="...">).

This means that components inherit the API of the extended widget as well.

The following example demonstrates parameter passing and the use of the text label property on a component:

<!-- h3.xml -->
<component>
    <view extends="lv_label"/>
</component>

<!-- red_button.xml -->
<component>
    <api>
        <prop type="string" name="btn_text" default="None"/>
    </api>
    <view extends="lv_button" style_radius="0" style_bg_color="0xff0000">
        <h3 text="Some text"/>
        <h3 text="$btn_text" y="40"/>
    </view>
</component>

lv_xml_component_register_from_file("A:path/to/h3.xml");
lv_xml_component_register_from_file("A:path/to/red_button.xml");

/* Creates a button with "None" text */
lv_xml_create(lv_screen_active(), "red_button", NULL);

/* Use attributes to set the button text */
const char * attrs[] = {
    "btn_text", "Click here",
    NULL, NULL,
};
lv_xml_create(lv_screen_active(), "red_button", attrs);