Button matrix（矩阵按钮） (lv_buttonmatrix)

Overview（概述）

按钮矩阵部件是一种以行列形式展示多个按钮的轻量级方式 ------ 之所以说它轻量级，是因为这些按钮实际上并未被创建，而只是在运行时虚拟绘制出来的。使用按钮矩阵时，每个按钮仅额外占用 8 字节内存，相比之下，一个普通的:ref:Button <lv_button>部件大约要占用100 - 150字节，再加上:ref:Label <lv_label>部件所需的约 100 字节左右。

新的按钮矩阵部件会被添加到默认组中（如果设置了默认组的话）。此外，按钮矩阵是一个可编辑部件：它也允许通过编码器和键盘导航来选择和点击按钮。

Parts and Styles（部分和样式）

LV_PART_MAIN 矩阵按钮的背景，使用所有控件默认都有的典型的背景样式属性。可通过 pad_row 和pad_column 设置按钮之间的空间。

• LV_PART_ITEMS 除了转变之外，按钮都使用文本和典型的背景样式属性。

Usage（用法）

Button map（按钮映射）

按钮的数量、它们的位置以及文本是由一个描述符字符串数组来控制的，这个数组被称作 "映射"（map），并传递给:cpp:expr:lv_buttonmatrix_set_map(btn_matrix, my_map)函数。一个映射的声明应该形如 ``const char * map[] = {"button1", "button2", "button3", NULL}。需要注意的是，最后一个元素必须是 NULL或者空字符串("")！

在映射中使用 "\n"来插入一个 **line break**。例如， {"button1", "button2", "\n", "button3", ""}。每一行的按钮宽度会自动计算。所以在这个例子中，第一行将会有 2 个按钮，每个按钮宽度占 50%，第二行有 1 个按钮，其宽度占 100%。
注意：按钮的数量既不包括换行元素，也不包括数组的终止元素。

Button widths（按钮宽度）

可以使用:cpp:expr:lv_buttonmatrix_set_button_width(btn_matrix, button_id, width)函数按照与同一行中其他按钮宽度的比例来设置按钮的宽度。例如，在一行中有两个按钮：buttonA，width = 1 和 buttonB，width = 2，那么buttonA 的宽度将占33%，buttonB 的宽度将占66%。这与CSS中的 "flex-grow" <https://developer.mozilla.org/en-US/docs/Web/CSS/flex-grow>__属性的工作原理类似。宽度必须在[1...15]这个范围内，默认值为1。

Button behavior（按钮行为）

每个按钮的行为都可以通过以下控制标志进行定制：

LV_BUTTONMATRIX_CTRL_HIDDEN: 隐藏按钮；它在布局中仍会保留其所占空间。

LV_BUTTONMATRIX_CTRL_NO_REPEAT: 在长按按钮时，不发出:cpp:enumerator:LV_EVENT_LONG_PRESSED_REPEAT事件。

LV_BUTTONMATRIX_CTRL_DISABLED: 禁用按钮，就如同普通部件上的:cpp:enumerator:LV_STATE_DISABLED状态一样。

LV_BUTTONMATRIX_CTRL_CHECKABLE: 点击时启用:cpp:enumerator:LV_STATE_CHECKED状态的切换。

LV_BUTTONMATRIX_CTRL_CHECKED: 使按钮处于选中状态。它将应用:cpp:enumerator:LV_STATE_CHECHKED样式。

LV_BUTTONMATRIX_CTRL_CLICK_TRIG: 值为1时：在 CLICK``操作时发送:cpp:enumerator:LV_EVENT_VALUE_CHANGE事件；值为 0 时：在 PRESS 操作时发送:cpp:enumerator:LV_EVENT_VALUE_CHANGE 事件。

LV_BUTTONMATRIX_CTRL_POPOVER: 在按下按钮时，在弹出框中显示按钮文本。

LV_BUTTONMATRIX_CTRL_RECOLOR: 启用通过 #color 对文本重新上色的功能。

LV_BUTTONMATRIX_CTRL_CUSTOM_1: 可自定义使用的标志

LV_BUTTONMATRIX_CTRL_CUSTOM_2: 可自定义使用的标志

默认情况下，所有标志都被禁用。

要设置和清除一个按钮的控制标志，可分别使用以下函数：

lv_buttonmatrix_set_button_ctrl(btn_matrix, LV_BUTTONMATRIX_CTRL_...) 和

lv_buttonmatrix_clear_button_ctrl(btn_matrix, LV_BUTTONMATRIX_CTRL_...)

其中， button_id 是以 0 为起始的按钮索引（0 表示第一个按钮）。将 LV_BUTTONMATRIX_CTRL_... 的值传递给这些函数时，可以进行按位或运算。

要为按钮矩阵中的所有按钮设置和清除相同的控制属性，可分别使用以下函数：

lv_buttonmatrix_set_button_ctrl_all(btn_matrix, LV_BUTTONMATRIX_CTRL_...) 和

lv_buttonmatrix_clear_button_ctrl_all(btn_matrix, LV_BUTTONMATRIX_CTRL_...)

要为按钮矩阵设置一个控制映射（类似于 Button map_），可使用以下函数：

lv_buttonmatrix_set_ctrl_map(btn_matrix, ctrl_map)

ctrl_map 的一个元素应形如:cpp:expr:ctrl_map[0] = width | LV_BUTTONMATRIX_CTRL_NO_REPEAT | LV_BUTTONMATRIX_CTRL_CHECHKABLE。

元素的数量必须与按钮的数量相等。

One check（一次检查）

可以使用:cpp:expr:lv_buttonmatrix_set_one_checked(btn_matrix, true)启用"单选"功能，以便一次只允许一个按钮处于选中状态。

Events（事件）
LV_EVENT_VALUE_CHANGED: 当按钮被按下/松开，或者在长按后重复触发动作时发送该事件。事件参数被设置为被按下/松开按钮的ID。
lv_buttonmatrix_get_selected_button(btn_matrix)会返回最近松开的按钮（即获得焦点的按钮）的索引，如果未找到这样的按钮，则返回:cpp:enumerator:LV_BUTTONMATRIX_BUTTON_NONE
lv_buttonmatrix_get_button_text(btn_matrix, button_id) 会返回一个指针，指向由以零为起始的索引 button_id所指定的按钮的文本。

Keys（按键）
LV_KEY_RIGHT/UP/LEFT/RIGHT 在矩阵按钮的按钮之间导航来选中不同的按钮。
LV_KEY_ENTER 按下/释放所选按钮。

例子1：

c 复制代码

/*button matrix 矩阵按钮*/

static const char * btnm_map[] = {"1", "2", "3", "4", "5", "\n",
                                  "6", "7", "8", "9", "0", "\n",
                                  "Action1", "Action2", ""
                                 };
static void event_handler_btnmatrix(lv_event_t * e)
{
    lv_event_code_t code = lv_event_get_code(e);
    lv_obj_t * obj = lv_event_get_target(e);
    if(code == LV_EVENT_VALUE_CHANGED) {
        uint32_t id = lv_btnmatrix_get_selected_btn(obj);
        const char * txt = lv_btnmatrix_get_btn_text(obj, id);
        LV_UNUSED(txt); // 我不用 txt，别警告
        LV_LOG_USER("%s was pressed\n", txt);
    }
}

void example_buttonmatrix_1(){
    screen=lv_obj_create(NULL);
    lv_scr_load(screen); 
    lv_obj_t * btnm1 = lv_btnmatrix_create(screen);
    lv_obj_set_width(btnm1,600);
    lv_obj_set_height(btnm1,400);
    lv_btnmatrix_set_map(btnm1, btnm_map);
    lv_btnmatrix_set_btn_width(btnm1, 10, 2); //把按钮矩阵里的【第 10 号按钮】的宽度设置为【占 2 列】
    lv_btnmatrix_set_btn_ctrl(btnm1, 10, LV_BTNMATRIX_CTRL_CHECKABLE);
    lv_btnmatrix_set_btn_ctrl(btnm1, 11, LV_BTNMATRIX_CTRL_CHECKED);
    lv_obj_align(btnm1, LV_ALIGN_CENTER, 0, 0);
    lv_obj_add_event_cb(btnm1, event_handler_btnmatrix, LV_EVENT_ALL, NULL);
}

运行结果：