矩阵按钮控件可以在行和列中显示多个按钮，并且每个按钮都可以设置标签、相对大小和按钮的各种属性。矩阵按钮的主要部分称为 LV_BTNMATRIX_PART_BG ，它使用典型的背景样式属性绘制背景。LV_BTNMATRIX_PART_BTN 是虚拟部分，它指的是按钮矩阵上的按钮。背景中的 top/bottom/left/right 填充值用于在侧面保留一些空间，而设置按钮之间的距离应使用内部填充。

需要注意的是，矩阵按钮对象可以看作是一系列伪按钮的集合，它不是真正的 lv_btn 按钮对象，而是 lv_btnmatrix 内部纯绘制出来的具有按钮外观的图形，而且这个图形具有和 lv_btn 按钮一样的点击效果，这种伪按钮的好处是它基本不占内存消耗（一个伪按钮大概需要 8 个字节，而容器加普通按钮对象组合大概需要100-150 字节），这属于LVGL 的一种优化操作。所以如果你有多个按钮集合的应用场景的话，最好使用矩阵按钮控件，而不要去使用容器外加普通按钮的方案。

不过这种优化的缺点是，将各个按钮的样式设置为与其他按钮不同的功能受到限制（除了切换功能之外）。如果需要设置不同按钮使用不同的样式，则使用单个按钮很可能是一种更好的方法。

在矩阵按钮中的每个按钮上都有一个文本标签。要指定它们，需要使用一个称为 map 的描述符字符串数组，使用 lv_btnmatrix_set_map(btnm, my_map) 将传入描述符字符串数组。map的声明形式应为const char * map[] = {“btn1”, “btn2”, “btn3”, “”} ，请注意，最后一个元素必须为空字符串！在描述符字符串数组中使用 “\n” 起换行作用，例如 {“btn1”, “btn2”, “\n”, “btn3”, “”}将创建下图所示的矩阵按钮。

矩阵按钮中按钮的宽度可以用 lv_btnmatrix_set_btn_width(btnm, btn_id, width) 来设置为相对于同一行其他按钮的宽度比例，例如一行中有两个按钮：btnA宽度= 1 和btnB 宽度= 2，btnA 将有 33％的行宽度而 btnB 将有 66％的行宽度。这类似于CSS中的flex-grow属性的工作方式。若按钮的宽度不进行单独设置，则每行按钮的宽度自动平分矩阵按钮的宽度。除了宽度，每个按钮都可以使用以下参数进行自定义：

• LV_BTNMATRIX_CTRL_HIDDEN 将按钮隐藏（隐藏的按钮仍占据布局中的空间，它们不可见或不可单击）。
• LV_BTNMATRIX_CTRL_NO_REPEAT 长按按钮时禁用重复触发。
• LV_BTNMATRIX_CTRL_DISABLED 禁用按钮。
• LV_BTNMATRIX_CTRL_CHECKABLE 启用按钮的切换功能。
• LV_BTNMATRIX_CTRL_CHECK_STATE 设置当前为已切换的状态。
• LV_BTNMATRIX_CTRL_CLICK_TRIG 如果为 0，按钮将在按下时触发回调函数，如果为1，则在释放时触发。

设置或清除按钮的控件属性，分别使用 lv_btnmatrix_set_btn_ctrl(btnm, btn_id, LV_BTNM_CTRL_…) 和 lv_btnmatrix_clear_btn_ctrl(btnm, btn_id, LV_BTNM_CTRL_…)。为按钮矩阵的所有按钮设置/清除相同的控件属性，请使用 lv_btnmatrix_set_btn_ctrl_all(btnm, btn_id, LV_BTNM_CTRL_…) 和lv_btnmatrix_clear_btn_ctrl_all(btnm, btn_id, LV_BTNM_CTRL_…)。

使用lv_btnmatrix_set_ctrl_map(btnm, ctrl_map) 为按钮矩阵设置控制map（类似于文本的描述符字符串数组）。ctrl_map的元素应类似于 ctrl_mapctrl_map[0] = width | LV_BTNM_CTRL_NO_REPEAT | LV_BTNM_CTRL_TGL_ENABLE，其中元素的数量应等于按钮的数量（不包括换行符）。

用户可以使用 lv_btnmatrix_set_one_check(btnm, true) 来启用“one check”功能，一次只允许检测（切换）一个按钮。

按钮上的文本可以开启类似于标签对象的重新着色功能。要启用它，请使用lv_btnmatrix_set_recolor(btnm, true)。之后，带有#FF0000 btn1# 文字的按钮将变为红色。

使用lv_btnmatrix_set_align(roller, LV_LABEL_ALIGN_LEFT/CENTER/RIGHT)可以让按钮上的文本对齐，按钮矩阵中的所有文本项都将符合设置的对齐方式。

除了通用事件外，矩阵按钮还发送以下特殊事件：

• LV_EVENT_VALUE_CHANGED 在按下/释放按钮时或在长按之后重复时发送。事件数据为按钮的 ID。

以下键值由按钮处理：

• LV_KEY_DOWN / UP / LEFT / RIGHT 在按钮之间导航以选择一个
• LV_KEY_ENTER 按下/释放所选按钮

lv_obj_t * label;
int red_color_flag = 0;
 
void event_handler(lv_obj_t * obj, lv_event_t event)                     /* 回调函数 */
{
	if(event == LV_EVENT_VALUE_CHANGED) {
		const char * txt = lv_btnmatrix_get_active_btn_text(obj);/* 获取按下的按键文本 */
		rt_kprintf("%s was pressed\n", txt);                     /* 串口打印 */
		if(!strcmp(txt, "red"))red_color_flag = !red_color_flag; /* red按钮状态切换 */
		if(red_color_flag == 1)lv_label_set_text_fmt(label, "#ff0000 %s was pressed#\n", txt); /* 更新标签内容 */
		else lv_label_set_text_fmt(label, "#000000 %s was pressed#\n", txt);
} }
 
static const char * btnm_map[] = {"1", "2", "3", "4", "5", "\n", "6", "7", "8", "9", "0", "\n", "red", "Action2", ""};  /* 按键分布图 */
 
void lv_gui_run(void) {
 
	lvgl2rtt_init("lcd");                                            /* 初始化lvgl2rtt */
	label = lv_label_create(lv_scr_act(), NULL);                     /* 创建标签 */
	lv_obj_set_pos(label, 20, 20);                                   /* 设置显示坐标 */
	lv_label_set_recolor(label, true);                               /* 使能重新着色 */
	lv_label_set_text(label, " NULL was pressed\n");                 /* 设置初始内容 */
 
	lv_obj_t * btnm1 = lv_btnmatrix_create(lv_scr_act(), NULL);      /* 创建矩阵按钮 */
	lv_obj_set_size(btnm1, 200, 100);                                /* 设置尺寸 */
	lv_btnmatrix_set_map(btnm1, btnm_map);                           /* 传入按键分布图 */
	lv_btnmatrix_set_btn_width(btnm1, 10, 2);                        /* 设置"red"的宽度为"Action2"的两倍 */
	lv_btnmatrix_set_btn_ctrl(btnm1, 10, LV_BTNMATRIX_CTRL_CHECKABLE);/* 使能按钮切换 */
	lv_btnmatrix_set_btn_ctrl(btnm1, 11, LV_BTNMATRIX_CTRL_CHECK_STATE); /* 设置按钮为已切换状态 */
	lv_obj_align(btnm1, NULL, LV_ALIGN_CENTER, 0, 0);                /* 设置位置 */
	lv_obj_set_event_cb(btnm1, event_handler);                       /* 设置回调函数 */
}