mirror of
https://github.com/lvgl/lvgl.git
synced 2025-01-14 06:42:58 +08:00
75 lines
2.8 KiB
ReStructuredText
75 lines
2.8 KiB
ReStructuredText
===============
|
|
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`.
|
|
|
|
.. code:: c
|
|
|
|
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(struct _lv_obj_t * obj, const lv_property_t * value);
|
|
lv_property_t lv_obj_get_property(struct _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.
|
|
|
|
.. code:: c
|
|
|
|
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);
|