feat(obj): add unified obj property set/get API (#4579)

Signed-off-by: Xu Xingliang <xuxingliang@xiaomi.com>

docs/others/index.rst

@@ -14,3 +14,4 @@ Others
     imgfont
     ime_pinyin
     obj_id
+    obj_property

docs/others/obj_property.rst

@@ -0,0 +1,74 @@
+===============
+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_PROPERTY_ARRAY_SET(obj, props);