M5ButtonMatrix

M5ButtonMatrix是一个可以在用户界面中创建按钮矩阵的控件。它提供了一个灵活的布局来以网格格式显示多个按钮，支持不同的按钮配置和文本标签。

UiFlow2 示例

基础按钮矩阵

在UiFlow2中打开 cores3_buttonmatrix_basic_example.m5f2 项目。

此示例演示如何创建带有自定义标签的按钮矩阵并处理按钮按下事件。

UiFlow2 代码块：

示例输出：

None

MicroPython 示例

基础按钮矩阵

此示例演示如何创建带有自定义标签的按钮矩阵并处理按钮按下事件。

MicroPython 代码块：

# 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")

示例输出：

None

API参考

M5ButtonMatrix

class m5ui.buttonmatrix.M5ButtonMatrix(*args, **kwargs)

基类：buttonmatrix

创建一个按钮矩阵对象。

参数:

• map (list) – 按钮标签的列表。使用 “\n” 来创建新行。

• x (int) – 按钮矩阵的X坐标位置。

• y (int) – 按钮矩阵的Y坐标位置。

• w (int) – 按钮矩阵的宽度。

• h (int) – 按钮矩阵的高度。

• target_textarea (m5ui.M5TextArea) – 按下按钮时显示按钮文本的M5TextArea。

• parent (lv.obj) – 要附加按钮矩阵的父对象。

UiFlow2 代码块：

None

MicroPython 代码块：

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
)

set_flag(flag, value)

为对象设置标志。如果 value 为True，则添加标志；如果为False，则移除标志。

参数:

• flag (int) – 要设置的标志。

• value (bool) – 如果为True，则添加标志；如果为False，则移除标志。

返回:

None

UiFlow2 代码块：

MicroPython 代码块：

buttonmatrix_0.set_flag(lv.obj.FLAG.HIDDEN, True)

toggle_flag(flag)

切换对象的标志。如果标志已设置，则将其移除；如果未设置，则将其添加。

参数:

flag (int) – 要切换的标志。

返回:

None

UiFlow2 代码块：

MicroPython 代码块：

buttonmatrix_0.toggle_flag(lv.obj.FLAG.HIDDEN)

set_state(state, value)

设置按钮矩阵的状态。如果 value 为True，则设置状态；如果为False，则取消设置状态。

参数:

• state (int) – 要设置的状态。

• value (bool) – 如果为True，则设置状态；如果为False，则取消设置状态。

返回:

None

UiFlow2 代码块：

MicroPython 代码块：

buttonmatrix_0.set_state(lv.STATE.PRESSED, True)

toggle_state(state)

切换按钮矩阵的状态。如果状态已设置，则取消设置；如果未设置，则将其设置。

参数:

state (int) – 要切换的状态。

返回:

None

UiFlow2 代码块：

MicroPython 代码块：

buttonmatrix_0.toggle_state(lv.STATE.PRESSED)

add_event_cb(handler, event, user_data)

为按钮矩阵添加事件回调。当指定事件发生时将调用回调函数。

参数:

• handler (function) – 要调用的回调函数。

• event (int) – 要监听的事件。

• user_data (Any) – 传递给回调函数的可选用户数据。

返回:

None

UiFlow2 代码块：

MicroPython 代码块：

def buttonmatrix_0_pressed_event(event_struct):
    global page0
    btn_id = buttonmatrix_0.get_selected_button()
    print(f"Button {btn_id} pressed")

def buttonmatrix_0_event_handler(event_struct):
    event = event_struct.code
    if event == lv.EVENT.VALUE_CHANGED:
        buttonmatrix_0_pressed_event(event_struct)
    return

buttonmatrix_0.add_event_cb(buttonmatrix_0_event_handler, lv.EVENT.ALL, None)

set_button_width(btn_id, width)

设置特定按钮的相对宽度。

参数:

• btn_id (int) – 按钮的索引。

• width (int) – 相对宽度（1-7，其中1为正常宽度）。

返回:

None

UiFlow2 代码块：

MicroPython 代码块：

buttonmatrix_0.set_button_width(0, 2)  # Make first button twice as wide

get_button_text(btn_id)

获取特定按钮的文本。

参数:

btn_id (int) – 按钮的索引。

返回:

按钮的文本。

返回类型:

str

UiFlow2 代码块：

MicroPython 代码块：

text = buttonmatrix_0.get_button_text(0)

clear_button_ctrl(btn_id, ctrl)

清除特定按钮的控制标志。

参数:

• btn_id (int) – 要清除控制标志的按钮ID。

• ctrl (int) – 要清除的控制标志。

UiFlow2 代码块：

MicroPython 代码块：

buttonmatrix_0.clear_button_ctrl(0, lv.buttonmatrix.CTRL.HIDDEN)

set_button_ctrl(btn_id, ctrl)

设置特定按钮的控制标志。

参数:

• btn_id (int) – 要设置控制标志的按钮ID。

• ctrl (int) – 要设置的控制标志。

UiFlow2 代码块：

MicroPython 代码块：

buttonmatrix_0.set_button_ctrl(0, lv.buttonmatrix.CTRL.HIDDEN)

set_button_ctrl_all(ctrl)

设置所有按钮的控制标志。

参数:

ctrl (int) – 要为所有按钮设置的控制标志。

UiFlow2 代码块：

MicroPython 代码块：

buttonmatrix_0.set_button_ctrl_all(lv.buttonmatrix.CTRL.HIDDEN)

clear_button_ctrl_all(ctrl)

清除所有按钮的控制标志。

参数:

ctrl (int) – 要为所有按钮清除的控制标志。

UiFlow2 代码块：

MicroPython 代码块：

buttonmatrix_0.clear_button_ctrl_all(lv.buttonmatrix.CTRL.HIDDEN)

set_one_checked(btn_id)

将特定按钮设置为选中状态。

参数:

btn_id (int) – 要设置为选中状态的按钮ID。

UiFlow2 代码块：

MicroPython 代码块：

buttonmatrix_0.set_one_checked(0)

set_pos(x, y)

设置按钮矩阵的位置。

参数:

• x (int) – 按钮矩阵的x坐标。

• y (int) – 按钮矩阵的y坐标。

返回:

None

UiFlow2 代码块：

MicroPython 代码块：

buttonmatrix_0.set_pos(100, 100)

set_x(x)

设置按钮矩阵的x坐标。

参数:

x (int) – 按钮矩阵的x坐标。

返回:

None

UiFlow2 代码块：

MicroPython 代码块：

buttonmatrix_0.set_x(100)

set_y(y)

设置按钮矩阵的y坐标。

参数:

y (int) – 按钮矩阵的y坐标。

返回:

None

UiFlow2 代码块：

MicroPython 代码块：

buttonmatrix_0.set_y(100)

set_size(width, height)

设置按钮矩阵的大小。

参数:

• width (int) – 按钮矩阵的宽度。

• height (int) – 按钮矩阵的高度。

返回:

None

UiFlow2 代码块：

MicroPython 代码块：

buttonmatrix_0.set_size(300, 200)

set_width(width)

设置按钮矩阵的宽度。

参数:

width (int) – 按钮矩阵的宽度。

返回:

None

UiFlow2 代码块：

MicroPython 代码块：

buttonmatrix_0.set_width(300)

get_width()

获取按钮矩阵的宽度。

返回:

按钮矩阵的宽度。

返回类型:

int

UiFlow2 代码块：

MicroPython 代码块：

width = buttonmatrix_0.get_width()

set_height(height)

设置按钮矩阵的高度。

参数:

height (int) – 按钮矩阵的高度。

返回:

None

UiFlow2 代码块：

MicroPython 代码块：

buttonmatrix_0.set_height(200)

get_height()

获取按钮矩阵的高度。

返回:

按钮矩阵的高度。

返回类型:

int

UiFlow2 代码块：

MicroPython 代码块：

height = buttonmatrix_0.get_height()

align_to(obj, align, x, y)

将按钮矩阵对齐到另一个对象。

参数:

• obj (lv.obj) – 要对齐到的对象。

• align (int) – 对齐类型。

• x (int) – 与对齐对象的x偏移量。

• y (int) – 与对齐对象的y偏移量。

返回:

None

UiFlow2 代码块：

MicroPython 代码块：

buttonmatrix_0.align_to(page_0, lv.ALIGN.CENTER, 0, 0)

toggle_button_ctrl(btn_id, ctrl)

切换特定按钮的控制标志。

参数:

• btn_id (int) – 要切换控制标志的按钮ID。

• ctrl (int) – 要切换的控制标志。

UiFlow2 代码块：

MicroPython 代码块：

buttonmatrix_0.toggle_button_ctrl(0, lv.buttonmatrix.CTRL.HIDDEN)

set_textarea(textarea)

设置M5TextArea以显示按钮文本。

参数:

textarea (m5ui.M5TextArea) – 要设置的M5TextArea。

UiFlow2 代码块：

MicroPython 代码块：

buttonmatrix_0.set_textarea(textarea0)

get_textarea()

获取当前设置的M5TextArea。

返回:

当前为按钮矩阵设置的M5TextArea。

返回类型:

m5ui.M5TextArea

UiFlow2 代码块：

MicroPython 代码块：

textarea = buttonmatrix_0.get_textarea()

get_selected_button()

获取最后按下按钮的索引。

返回:

当前选定按钮的 ID，如果未选定则为 -1。

返回类型:

int

UiFlow2 代码块：

MicroPython 代码块：

selected_button = buttonmatrix_0.get_selected_button()