libs/m5ui: Add M5ButtonMatrix support.

Signed-off-by: lbuque <[email protected]>

Author: lbuque

docs/en/m5ui/buttonmatrix.rst

@@ -36,6 +36,7 @@ Classes
     arc.rst
     bar.rst
     button.rst
+    buttonmatrix.rst
     calendar.rst
     canvas.rst
     checkbox.rst

docs/en/m5ui/index.rst

@@ -0,0 +1,36 @@
+.. |cores3_buttonmatrix_basic_example.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/button_matrix/cores3_buttonmatrix_basic_example.png
+
+.. |align_to.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/button_matrix/align_to.png
+.. |clear_button_ctrl.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/button_matrix/clear_button_ctrl.png
+.. |clear_button_ctrl_all.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/button_matrix/clear_button_ctrl_all.png
+.. |event.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/button_matrix/event.png
+.. |get_button_text.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/button_matrix/get_button_text.png
+.. |get_height.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/button_matrix/get_height.png
+.. |get_selected_button.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/button_matrix/get_selected_button.png
+.. |get_textarea.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/button_matrix/get_textarea.png
+.. |get_width.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/button_matrix/get_width.png
+.. |set_button_ctrl.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/button_matrix/set_button_ctrl.png
+.. |set_button_ctrl_all.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/button_matrix/set_button_ctrl_all.png
+.. |set_button_width.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/button_matrix/set_button_width.png
+.. |set_flag.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/button_matrix/set_flag.png
+.. |set_height.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/button_matrix/set_height.png
+.. |set_one_checked.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/button_matrix/set_one_checked.png
+.. |set_pos.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/button_matrix/set_pos.png
+.. |set_size.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/button_matrix/set_size.png
+.. |set_state.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/button_matrix/set_state.png
+.. |set_textarea.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/button_matrix/set_textarea.png
+.. |set_width.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/button_matrix/set_width.png
+.. |set_x.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/button_matrix/set_x.png
+.. |set_y.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/button_matrix/set_y.png
+.. |toggle_button_ctrl.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/button_matrix/toggle_button_ctrl.png
+.. |toggle_flag.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/button_matrix/toggle_flag.png
+.. |toggle_state.png| image:: https://static-cdn.m5stack.com/mpy_docs/m5ui/button_matrix/toggle_state.png
+
+.. |cores3_buttonmatrix_basic_example.m5f2| raw:: html
+
+    <a
+        href="https://uiflow2.m5stack.com/?example=https://raw.githubusercontent.com/m5stack/uiflow-micropython/develop/examples/m5ui/buttonmatrix/cores3_buttonmatrix_basic_example.m5f2"
+        target="_blank"
+    >
+        cores3_buttonmatrix_basic_example.m5f2
+    </a>

docs/en/refs/m5ui.buttonmatrix.ref

@@ -0,0 +1 @@
+{"version":"V2.0","versionNumber":"V2.3.3","type":"core2","components":[{"name":"page0","type":"lvgl_page","layer":0,"screenId":"builtin","screenName":"","id":"w#OUTx5g2=WUes=i","createTime":1755596357827,"backgroundColor":"#ffffff","isLVGL":true,"isSelected":true},{"name":"textarea0","type":"lvgl_textarea","layer":1,"screenId":"builtin","screenName":"","id":"h*==WkzQoUKv*z$1","createTime":1755596420739,"x":24,"y":15,"width":150,"height":70,"color":"#212121","borderColor":"#e0e0e0","backgroundColor":"#ffffff","text":"","placeholder":"Placeholder...","font":"lv.font_montserrat_14","pageId":"w#OUTx5g2=WUes=i","isLVGL":true,"isSelected":false},{"name":"buttonmatrix0","type":"lvgl_buttonmatrix","layer":2,"screenId":"builtin","screenName":"","id":"n+@+k6w_5RL-ZEJs","createTime":1755596423752,"x":25,"y":100,"width":260,"height":130,"keyList":[["0","1","2","4"],["5","6","7","8","9"]],"targetTextarea":"h*==WkzQoUKv*z$1","pageId":"w#OUTx5g2=WUes=i","isLVGL":true,"isSelected":false},{"name":"label0","type":"lvgl_label","layer":3,"screenId":"builtin","screenName":"","id":"vWXox&Pi7i#P@4az","createTime":1755656081220,"x":189,"y":15,"color":"#c9c9c9","backgroundColor":"#ffffff","bg_opacity":0,"text":"last key:","font":"lv.font_montserrat_14","pageId":"w#OUTx5g2=WUes=i","isLVGL":true,"isSelected":false,"width":56,"height":15},{"name":"label1","type":"lvgl_label","layer":4,"screenId":"builtin","screenName":"","id":"w`*DcO^huctVu6Lc","createTime":1755656142705,"x":203,"y":42,"color":"#000000","backgroundColor":"#ffffff","bg_opacity":0,"text":"label1","font":"lv.font_montserrat_24","pageId":"w#OUTx5g2=WUes=i","isLVGL":true,"isSelected":false,"width":67,"height":27}],"resources":[{"hardware":["hardware_button","hardware_pin_button","imu","speaker","touch","mic","sdcard"]}],"units":[],"hats":[],"bases":[],"i2cs":[],"blockly":"<block type=\"basic_on_setup\" id=\"setup_block\" deletable=\"false\" x=\"50\" y=\"50\"><mutation isBegin=\"true\"></mutation><field name=\"UPDATEOP\">true</field><statement name=\"FUNC\"><block type=\"system_m5_begin\" id=\"n/EL5mgZYup*D.$s))da\"><next><block type=\"lvgl_page_screen_load\" id=\"yY9-+uFZoop$:Epo?PsR\"><field name=\"NAME\">page0</field></block></next></block></statement></block><block type=\"basic_on_loop\" id=\"loop_block\" deletable=\"false\" x=\"50\" y=\"210\"><mutation isUpdate=\"true\"></mutation><field name=\"UPDATEOP\">true</field><statement name=\"FUNC\"><block type=\"system_m5_update\" id=\"Ya^:riycUT^%I6hX;w.3\"></block></statement></block><block type=\"lvgl_buttonmatrix_event\" id=\"Px*p+V$6OyV)?+8cy+f`\" x=\"70\" y=\"330\"><field name=\"NAME\">buttonmatrix0</field><statement name=\"FUNC\"><block type=\"lvgl_label_set_text\" id=\"r5KxK(]/auvL1B#mp9V$\"><field name=\"NAME\">label1</field><value name=\"VALUE\"><shadow type=\"text\" id=\"D,*|?v[]w`.?VIAt;9Qf\"><field name=\"TEXT\">hello M5</field></shadow><block type=\"lvgl_buttonmatrix_get_button_text\" id=\"KxJpC?UCsx9bUq*M^G|j\"><field name=\"NAME\">buttonmatrix0</field><value name=\"VALUE\"><shadow type=\"math_number\" id=\"OP6E6@2~fn5us6g4TPj?\"><mutation max=\"Infinity\" min=\"0\" precision=\"0\"></mutation><field name=\"NUM\">0</field></shadow><block type=\"lvgl_buttonmatrix_get_selected_button\" id=\"ZWX(unyQ-A%2jR]q]p)D\"><field name=\"NAME\">buttonmatrix0</field></block></value></block></value></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":1755596357824}],"logicWhenNum":0,"customList":[]}

docs/locales/zh_CN/LC_MESSAGES/m5ui/buttonmatrix.po

@@ -0,0 +1,104 @@
+# SPDX-FileCopyrightText: 2025 M5Stack Technology CO LTD
+#
+# SPDX-License-Identifier: MIT
+
+import os, sys, io
+import M5
+from M5 import *
+import m5ui
+import lvgl as lv
+
+
+page0 = None
+textarea0 = None
+buttonmatrix0 = None
+label0 = None
+label1 = None
+
+
+def buttonmatrix0_value_changed_event(event_struct):
+    global page0, textarea0, buttonmatrix0, label0, label1
+    label1.set_text(str(buttonmatrix0.get_button_text(buttonmatrix0.get_selected_button())))
+
+
+def buttonmatrix0_event_handler(event_struct):
+    global page0, textarea0, buttonmatrix0, label0, label1
+    event = event_struct.code
+    if event == lv.EVENT.VALUE_CHANGED and True:
+        buttonmatrix0_value_changed_event(event_struct)
+    return
+
+
+def setup():
+    global page0, textarea0, buttonmatrix0, label0, label1
+
+    M5.begin()
+    Widgets.setRotation(1)
+    m5ui.init()
+    page0 = m5ui.M5Page(bg_c=0xFFFFFF)
+    textarea0 = m5ui.M5TextArea(
+        text="",
+        placeholder="Placeholder...",
+        x=24,
+        y=15,
+        w=150,
+        h=70,
+        font=lv.font_montserrat_14,
+        bg_c=0xFFFFFF,
+        border_c=0xE0E0E0,
+        text_c=0x212121,
+        parent=page0,
+    )
+    buttonmatrix0 = m5ui.M5ButtonMatrix(
+        ["0", "1", "2", "4", "\n", "5", "6", "7", "8", "9"],
+        x=25,
+        y=100,
+        w=260,
+        h=130,
+        target_textarea=textarea0,
+        parent=page0,
+    )
+    label0 = m5ui.M5Label(
+        "last key:",
+        x=189,
+        y=15,
+        text_c=0xC9C9C9,
+        bg_c=0xFFFFFF,
+        bg_opa=0,
+        font=lv.font_montserrat_14,
+        parent=page0,
+    )
+    label1 = m5ui.M5Label(
+        "label1",
+        x=203,
+        y=42,
+        text_c=0x000000,
+        bg_c=0xFFFFFF,
+        bg_opa=0,
+        font=lv.font_montserrat_24,
+        parent=page0,
+    )
+
+    buttonmatrix0.add_event_cb(buttonmatrix0_event_handler, lv.EVENT.ALL, None)
+
+    page0.screen_load()
+
+
+def loop():
+    global page0, textarea0, buttonmatrix0, label0, label1
+    M5.update()
+
+
+if __name__ == "__main__":
+    try:
+        setup()
+        while True:
+            loop()
+    except (Exception, KeyboardInterrupt) as e:
+        try:
+            m5ui.deinit()
+            from utility import print_error_msg
+
+            print_error_msg(e)
+        except ImportError:
+            print("please update to latest firmware")

examples/m5ui/buttonmatrix/cores3_buttonmatrix_basic_example.m5f2

@@ -8,6 +8,7 @@
     "M5Arc": "arc",
     "M5Bar": "bar",
     "M5Button": "button",
+    "M5ButtonMatrix": "buttonmatrix",
     "M5Calendar": "calendar",
     "M5Canvas": "canvas",
     "M5Checkbox": "checkbox",

examples/m5ui/buttonmatrix/cores3_buttonmatrix_basic_example.py

@@ -0,0 +1,129 @@
+# SPDX-FileCopyrightText: 2025 M5Stack Technology CO LTD
+#
+# SPDX-License-Identifier: MIT
+
+from .base import M5Base
+import lvgl as lv
+
+
+class M5ButtonMatrix(lv.buttonmatrix):
+    """Create a button matrix object.
+
+    :param list map: A list of button labels. Use "\\\\n" to create a new row.
+    :param int x: The x position of the button matrix.
+    :param int y: The y position of the button matrix.
+    :param int w: The width of the button matrix.
+    :param int h: The height of the button matrix.
+    :param m5ui.M5TextArea target_textarea: A M5TextArea to display the button text when a button is pressed.
+    :param lv.obj parent: The parent object to attach the button matrix to.
+
+    UiFlow2 Code Block:
+
+        None
+
+    MicroPython Code Block:
+
+        .. code-block:: python
+
+            import m5ui
+            import lvgl as lv
+
+            m5ui.init()
+            page0 = m5ui.M5Page()
+            page0.screen_load()
+            textarea0 = m5ui.M5TextArea(x=10, y=10, w=200, h=60, parent=page0)
+            buttonmatrix_0 = m5ui.M5ButtonMatrix(
+                ["0", "1", "2", "3", "4","\\n", "5", "6", "7", "8", "9",],
+                x=10, y=80, w=260, h=130,
+                target_textarea=textarea0,
+                parent=page0
+            )
+
+    """
+
+    def __init__(
+        self,
+        map,
+        x=0,
+        y=0,
+        w=260,
+        h=130,
+        target_textarea=None,
+        parent=None,
+    ):
+        super().__init__(parent)
+        self.set_map(map)
+        self.set_pos(x, y)
+        self.set_size(w, h)
+
+        self.add_event_cb(self.value_changed_event, lv.EVENT.VALUE_CHANGED, None)
+        self.textarea = target_textarea  # To hold a reference to a M5TextArea if set
+
+    def value_changed_event(self, event_struct):
+        btn_id = self.get_selected_button()
+        if self.textarea:
+            self.textarea.add_text(self.get_button_text(btn_id))
+
+    def toggle_button_ctrl(self, btn_id, ctrl):
+        """Toggle control flags for a specific button.
+
+        :param int btn_id: The button ID to toggle control flags for.
+        :param int ctrl: The control flags to toggle.
+
+        UiFlow2 Code Block:
+
+            |toggle_button_ctrl.png|
+
+        MicroPython Code Block:
+
+            .. code-block:: python
+
+                buttonmatrix_0.toggle_button_ctrl(0, lv.buttonmatrix.CTRL.HIDDEN)
+        """
+        if self.has_button_ctrl(btn_id, ctrl):
+            self.clear_button_ctrl(btn_id, ctrl)
+        else:
+            self.set_button_ctrl(btn_id, ctrl)
+
+    def set_textarea(self, textarea):
+        """Set a M5TextArea to display button text.
+
+        :param m5ui.M5TextArea textarea: The M5TextArea to set.
+
+        UiFlow2 Code Block:
+
+            |set_textarea.png|
+
+        MicroPython Code Block:
+
+            .. code-block:: python
+
+                buttonmatrix_0.set_textarea(textarea0)
+        """
+        self.textarea = textarea
+
+    def get_textarea(self):
+        """Get the currently set M5TextArea.
+
+        :return: The M5TextArea currently set for the button matrix.
+        :rtype: m5ui.M5TextArea
+
+        UiFlow2 Code Block:
+
+            |get_textarea.png|
+
+        MicroPython Code Block:
+
+            .. code-block:: python
+
+                textarea = buttonmatrix_0.get_textarea()
+        """
+        return self.textarea
+
+    def __getattr__(self, name):
+        if hasattr(M5Base, name):
+            method = getattr(M5Base, name)
+            bound_method = lambda *args, **kwargs: method(self, *args, **kwargs)
+            setattr(self, name, bound_method)
+            return bound_method
+        raise AttributeError(f"'{self.__class__.__name__}' object has no attribute '{name}'")

m5stack/libs/m5ui/__init__.py

@@ -10,6 +10,7 @@
         "bar.py",
         "base.py",
         "button.py",
+        "buttonmatrix.py",
         "calendar.py",
         "canvas.py",
         "checkbox.py",

m5stack/libs/m5ui/buttonmatrix.py

@@ -0,0 +1,56 @@
+# SPDX-FileCopyrightText: 2025 M5Stack Technology CO LTD
+#
+# SPDX-License-Identifier: MIT
+
+import lvgl as lv
+import sys
+
+sys.path.append("../../m5stack/libs")
+import m5ui
+import unittest
+
+
+class Test(unittest.TestCase):
+    def __init__(self) -> None:
+        super().__init__()
+        m5ui.init()
+        page0 = m5ui.M5Page()
+        self.textarea0 = m5ui.M5TextArea(x=10, y=10, w=200, h=60, parent=page0)
+        self.buttonmatrix0 = m5ui.M5ButtonMatrix(
+            ["0", "1", "2", "4", "\n", "5", "6", "7", "8", "9"],
+            x=25,
+            y=100,
+            w=260,
+            h=130,
+            target_textarea=self.textarea0,
+            parent=page0,
+        )
+        page0.screen_load()
+
+    def test_get_textarea(self):
+        self.buttonmatrix0.set_textarea(None)
+        self.assertIsNone(self.buttonmatrix0.textarea)
+        self.buttonmatrix0.set_textarea(self.textarea0)
+        self.assertIsInstance(self.buttonmatrix0.textarea, m5ui.M5TextArea)
+
+    def test_toggle_button_ctrl(self):
+        self.buttonmatrix0.toggle_button_ctrl(0, lv.buttonmatrix.CTRL.NO_REPEAT)
+        self.assertTrue(self.buttonmatrix0.has_button_ctrl(0, lv.buttonmatrix.CTRL.NO_REPEAT))
+
+    def test_text_area_update(self):
+        self.textarea0.set_text("")
+        self.buttonmatrix0.set_selected_button(0)
+        self.buttonmatrix0.send_event(lv.EVENT.VALUE_CHANGED, None)
+        self.assertEqual(self.textarea0.get_text(), "0")
+
+        self.buttonmatrix0.set_selected_button(1)
+        self.buttonmatrix0.send_event(lv.EVENT.VALUE_CHANGED, None)
+        self.assertEqual(self.textarea0.get_text(), "01")
+
+        self.buttonmatrix0.set_selected_button(2)
+        self.buttonmatrix0.send_event(lv.EVENT.VALUE_CHANGED, None)
+        self.assertEqual(self.textarea0.get_text(), "012")
+
+
+if __name__ == "__main__":
+    unittest.main()