[中文]

Widget Property

Widgets have many properties that can decide what they look like and how they behave. For example, the size, position, color, font, etc. are properties of a widget. Specially, widget local style is also a property of a widget.

Usage

Two APIs are provided to get/set widget properties. It can be enabled by setting LV_USE_OBJ_PROPERTY to 1 in lv_conf.h.

typedef struct {
    lv_prop_id_t id;
    union {
        int32_t num;                /**< Number integer number (opacity, enums, booleans or "normal" numbers)*/
        const void * ptr;           /**< Constant pointers  (font, cone text, etc)*/
        lv_color_t color;           /**< Colors*/
        lv_style_value_t _style;    /**< A place holder for style value which is same as property value.*/
    };
} lv_property_t;

lv_result_t lv_obj_set_property(lv_obj_t * obj, const lv_property_t * value);
lv_property_t lv_obj_get_property(lv_obj_t * obj, lv_prop_id_t id);

Property ID

lv_prop_id_t identifies which property to get/set. lv_property_t is an enum value defined in lv_obj_property.h that are grouped by widget class. You can add your own widget property ID following same rule and using helper macro LV_PROPERTY_ID. Do make sure the ID is unique across all widgets.

Property ID is a 32-bit value. The higher 4bits indicates the property value type. The lower 28bits is the property ID.

Note that lv_style_prop_t is also valid property ID.

Property Value

Property value is a union of all possible property types including integer, pointer and color. _style is kept their just to indicate it's compatible with style value type.

A Step Further

The unified widget property set/get API is useful when developing wrapper layer for other modules like micropython, lua, or for an external animation engine.

For pointer type of property value, which typically points to a specific struct, it still needs additional code to convert values from dict, table etc to a C struct before setting to widget.

Another possible use case is to ease of creating UI from lots of code. For example, you can gather all properties to an array now and set properties with a for loop.

lv_property_t props[] = {
    { .id = LV_PROPERTY_IMAGE_SRC, .ptr = &img_demo_widgets_avatar, },
    { .id = LV_PROPERTY_IMAGE_PIVOT, .ptr = &pivot_50, },
    { .id = LV_PROPERTY_IMAGE_SCALE, .num = 128, },
    { .id = LV_PROPERTY_OBJ_FLAG_CLICKABLE, .num = 1, },
    { .id = LV_STYLE_IMAGE_OPA, .num = 128, },
    { .id = LV_STYLE_BG_COLOR, .color = (lv_color_t){.red = 0x11, .green = 0x22, .blue = 0x33}, },
}

LV_OBJ_SET_PROPERTY_ARRAY(obj, props);