lib/m5ui: Add LVGL List widget and docs.

Signed-off-by: tinyu <tinyu@m5stack.com>

Author: Tinyu-Zhao

docs/en/m5ui/index.rst

@@ -34,6 +34,7 @@ Classes
 
  page.rst
  arc.rst
+ list.rst
  bar.rst
  button.rst
  calendar.rst

docs/en/m5ui/list.rst

@@ -0,0 +1,315 @@
+.. currentmodule:: m5ui
+
+M5List
+=======
+
+.. include:: ../refs/m5ui.list.ref
+
+M5List is a widget that can be used to create lists in user interfaces. It is basically a rectangle with vertical layout to which Buttons and Text can be added.
+
+
+UiFlow2 Example
+---------------
+
+list example
+^^^^^^^^^^^^
+
+Open the |cores3_list_example.m5f2| project in UiFlow2.
+
+This example demonstrates how to create a list that displays a series of items.
+
+UiFlow2 Code Block:
+
+ |cores3_list_example.png|
+
+Example output:
+
+ None
+
+
+MicroPython Example
+-------------------
+
+list example
+^^^^^^^^^^^^
+
+This example demonstrates how to create a list that displays a series of items.
+
+MicroPython Code Block:
+
+ .. literalinclude:: ../../../examples/m5ui/list/cores3_list_example.py
+ :language: python
+ :linenos:
+
+Example output:
+
+ None
+
+
+**API**
+-------
+
+M5List
+^^^^^^^
+
+.. autoclass:: m5ui.list.M5List
+ :members:
+
+ .. py:method:: add_text(text:str)
+
+ Add text to the list end.
+
+ :param str text: The text to add.
+
+ UiFlow2 Code Block:
+
+ |add_text.png|
+
+ MicroPython Code Block:
+
+ .. code-block:: python
+
+ text_0 = list_0.add_text("Item 1")
+
+ .. py:method:: add_button(icon, text)
+
+ Add a button to the list end.
+
+ :param int icon: The icon to display on the button, `refer icon list <https://docs.lvgl.io/9.3/details/main-modules/font.html#special-fonts>`_ .
+ :param str text: The text to display on the button.
+
+ UiFlow2 Code Block:
+
+ |add_button.png|
+
+ MicroPython Code Block:
+
+ .. code-block:: python
+
+ button_0 = list_0.add_button(lv.SYMBOL.BULLET, "Button0")
+
+ .. py:method:: move_background()
+
+ Move the background of the list to the end.
+
+ UiFlow2 Code Block:
+
+ |move_background.png|
+
+ MicroPython Code Block:
+
+ .. code-block:: python
+
+ button_0.move_background()
+ text_0.move_background()
+
+ 
+ .. py:method:: move_foreground()
+
+ Move the foreground of the list to the end.
+
+ UiFlow2 Code Block:
+
+ |move_foreground.png|
+
+ MicroPython Code Block:
+
+ .. code-block:: python
+
+ button_0.move_foreground()
+ text_0.move_foreground()
+
+ .. py:method:: move_to_index(index)
+
+ Move the item at the specified index to the end of the list.
+
+ UiFlow2 Code Block:
+
+ |move_to_index.png|
+
+ MicroPython Code Block:
+
+ .. code-block:: python
+
+ button_0.move_to_index(0)
+ text_0.move_to_index(1)
+
+ .. py:method:: delete()
+
+ Delete the item from the list.
+
+ UiFlow2 Code Block:
+
+ |delete.png|
+
+ MicroPython Code Block:
+
+ .. code-block:: python
+
+ button_0.delete()
+ text_0.delete()
+ list_0.delete()
+
+ .. py:method:: add_event_cb(handler, event, user_data)
+
+ Add an event callback to the button. The callback will be called when the specified event occurs.
+
+ :param function handler: The callback function to call.
+ :param int event: The event to listen for.
+ :param Any user_data: Optional user data to pass to the callback.
+ :return: None
+
+ UiFlow2 Code Block:
+
+ |event.png|
+
+ MicroPython Code Block:
+
+ .. code-block:: python
+
+ def button0_event_handler(event_struct):
+ code = event_struct.code
+ obj = event_struct.get_target_obj()
+ if code == lv.EVENT.CLICKED:
+ print("Clicked: list1" + list_0.get_button_text(obj))
+
+
+ def button1_event_handler(event_struct):
+ code = event_struct.code
+ obj = event_struct.get_target_obj()
+ if code == lv.EVENT.CLICKED:
+ print("Clicked: list1" + list_0.get_button_text(obj))
+
+
+ button_0.add_event_cb(button0_event_handler, lv.EVENT.CLICKED, None)
+ button_1.add_event_cb(button1_event_handler, lv.EVENT.CLICKED, None)
+
+ .. py:method:: set_flag(flag, value)
+
+ Set a flag on the object. If ``value`` is True, the flag is added; if False, the flag is removed.
+
+ :param int flag: The flag to set.
+ :param bool value: If True, the flag is added; if False, the flag is removed.
+ :return: None
+
+ UiFlow2 Code Block:
+
+ |set_flag.png|
+
+ MicroPython Code Block:
+
+ .. code-block:: python
+
+ label_0.set_flag(lv.obj.FLAG.HIDDEN, True)
+
+ .. py:method:: set_pos(x, y)
+
+ Set the position of the label.
+
+ :param int x: The x-coordinate of the label.
+ :param int y: The y-coordinate of the label.
+ :return: None
+
+ UiFlow2 Code Block:
+
+ |set_pos.png|
+
+ MicroPython Code Block:
+
+ .. code-block:: python
+
+ label_0.set_pos(100, 100)
+
+
+ .. py:method:: set_x(x)
+
+ Set the x-coordinate of the label.
+
+ :param int x: The x-coordinate of the label.
+ :return: None
+
+ UiFlow2 Code Block:
+
+ |set_x.png|
+
+ MicroPython Code Block:
+
+ .. code-block:: python
+
+ label_0.set_x(100)
+
+
+ .. py:method:: set_y(y)
+
+ Set the y-coordinate of the label.
+
+ :param int y: The y-coordinate of the label.
+ :return: None
+
+ UiFlow2 Code Block:
+
+ |set_y.png|
+
+ MicroPython Code Block:
+
+ .. code-block:: python
+
+ label_0.set_y(100)
+
+
+ .. py:method:: set_size(width, height)
+
+ Set the size of the label.
+
+ :param int width: The width of the label.
+ :param int height: The height of the label.
+ :return: None
+
+ UiFlow2 Code Block:
+
+ |set_size.png|
+
+ MicroPython Code Block:
+
+ .. code-block:: python
+
+ label_0.set_size(100, 50)
+
+
+ .. py:method:: set_width(width)
+
+ Set the width of the label.
+
+ :param int width: The width of the label.
+ :return: None
+
+ UiFlow2 Code Block:
+
+ |set_width.png|
+
+ MicroPython Code Block:
+
+ .. code-block:: python
+
+ label_0.set_width(100)
+
+
+ .. py:method:: align_to(obj, align, x, y)
+
+ Align the label to another object.
+
+ :param lv.obj obj: The object to align to.
+ :param int align: The alignment type.
+ :param int x: The x-offset from the aligned object.
+ :param int y: The y-offset from the aligned object.
+ :return: None
+
+ UiFlow2 Code Block:
+
+ |align_to.png|
+
+ MicroPython Code Block:
+
+ .. code-block:: python
+
+ label_0.align_to(page_0, lv.ALIGN.CENTER, 0, 0)

docs/en/refs/m5ui.list.ref

@@ -0,0 +1,26 @@
+
+.. |align_to.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/label/align_to.png
+.. |event.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/label/event.png
+.. |set_flag.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/label/set_flag.png
+.. |set_pos.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/label/set_pos.png
+.. |set_size.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/label/set_size.png
+.. |set_width.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/label/set_width.png
+.. |set_x.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/label/set_x.png
+.. |set_y.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/label/set_y.png
+.. |add_text.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/label/add_text.png
+.. |add_button.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/label/add_button.png
+.. |move_foreground.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/label/move_foreground.png
+.. |move_to_index.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/label/move_to_index.png
+.. |move_background.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/label/move_background.png
+.. |delete.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/label/delete.png
+
+.. |cores3_list_example.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/label/cores3_list_example.png
+
+.. |cores3_list_example.m5f2| raw:: html
+
+ <a
+ href="https://uiflow2.m5stack.com/?example=https://raw.githubusercontent.com/m5stack/uiflow-micropython/develop/examples/m5ui/label/cores3_list_example.m5f2"
+ target="_blank"
+ >
+ cores3_list_example.m5f2
+ </a>

examples/m5ui/list/cores3_list_example.m5f2

@@ -0,0 +1 @@
+{"version":"V2.0","versionNumber":"V2.3.0","type":"cores3","components":[{"name":"page0","type":"lvgl_page","layer":0,"screenId":"builtin","screenName":"","id":"zGUSgLk%P9BF_bji","createTime":1750906906496,"backgroundColor":"#ffffff","isLVGL":true,"isSelected":true},{"name":"label0","type":"lvgl_label","layer":1,"screenId":"builtin","screenName":"","id":"ktg+xZQJ^lvI#N=M","createTime":1750907034945,"x":60,"y":110,"color":"#000000","backgroundColor":"#ffffff","bg_opacity":0,"text":"It is a circularly scrolling text. ","font":"lv.font_montserrat_14","pageId":"zGUSgLk%P9BF_bji","isLVGL":true,"isSelected":false,"width":207,"height":15}],"resources":[{"hardware":["hardware_button","hardware_pin_button","imu","speaker","touch","als","mic","sdcard"]}],"units":[],"hats":[],"bases":[],"i2cs":[],"blockly":"<block type=\"basic_on_setup\" id=\"setup_block\" deletable=\"false\" x=\"50\" y=\"51\"><mutation isBegin=\"true\"></mutation><field name=\"UPDATEOP\">true</field><statement name=\"FUNC\"><block type=\"system_m5_begin\" id=\"h^WDhC_Sfxe`T#-Bq?0C\"><next><block type=\"lvgl_page_screen_load\" id=\"XnobnY])ej65P;.Sw-Zo\"><field name=\"NAME\">page0</field><next><block type=\"lvgl_label_set_long_mode\" id=\"W4skIJcVcH:I{r%*wUd/\"><field name=\"NAME\">label0</field><field name=\"OPTION\">SCROLL_CIRCULAR</field><next><block type=\"lvgl_label_set_width\" id=\"LI2ACFi|nBvkqyww3Xb*\"><field name=\"NAME\">label0</field><value name=\"VALUE\"><shadow type=\"math_number\" id=\"3w=1@49joOEy4p#Igu=]\"><mutation max=\"Infinity\" min=\"-Infinity\" precision=\"0\"></mutation><field name=\"NUM\">150</field></shadow></value><next><block type=\"lvgl_label_set_align\" id=\"NKEo#E23Z2]C|k/^co9Q\"><mutation pageId=\"zGUSgLk%P9BF_bji\"></mutation><field name=\"NAME\">label0</field><field name=\"OPTION\">CENTER</field><field name=\"OBJ\">page0</field><value name=\"X\"><shadow type=\"math_number\" id=\"q89ty$rbQGY+}tXJx4*3\"><mutation max=\"Infinity\" min=\"-Infinity\" precision=\"0\"></mutation><field name=\"NUM\">0</field></shadow></value><value name=\"Y\"><shadow type=\"math_number\" id=\"^[cE7xCHwH$rkQi.}cO}\"><mutation max=\"Infinity\" min=\"-Infinity\" precision=\"0\"></mutation><field name=\"NUM\">0</field></shadow></value></block></next></block></next></block></next></block></next></block></statement></block><block type=\"basic_on_loop\" id=\"loop_block\" deletable=\"false\" x=\"450\" y=\"50\"><mutation isUpdate=\"true\"></mutation><field name=\"UPDATEOP\">true</field><statement name=\"FUNC\"><block type=\"system_m5_update\" id=\"8eQ!L~hf?1qJ4;Y2L-J$\"></block></statement></block>","screen":[{"simulationName":"Built-in","type":"builtin","width":320,"height":240,"scale":0.77,"screenName":"","blockId":"","screenColorType":0,"rotation":1,"id":"builtin","createTime":1750906899526}],"logicWhenNum":0,"customList":[]}