LVGL（lv_btnmatrix矩阵按钮）

---

lv_btnmatrix 是 LVGL（Light and Versatile Graphics Library） 中的一个非常实用的控件，用于在一个区域内布局一组“按钮”，常见于：

• 键盘（数字键盘、软键盘）
• 控制面板
• 多选/单选按钮组等

下面我将分为几个方面为你详细讲解 lv_btnmatrix 的原理、常用用法及关键函数。

---

🔧 1. 基本概念

📌 lv_btnmatrix 是什么？

lv_btnmatrix（按钮矩阵）是一个将多个文本按钮排布成网格状的控件，每个按钮可以独立响应点击事件。

---

🧱 2. 基本结构和用法

✅ 创建按钮矩阵

lv_obj_t *btnm = lv_btnmatrix_create(lv_scr_act());  // 在当前屏幕创建按钮矩阵

✅ 设置按钮文字

static const char *btnm_map[] = {"1", "2", "3", "\n","4", "5", "6", "\n","7", "8", "9", "\n","Del", "0", "OK", ""
};lv_btnmatrix_set_map(btnm, btnm_map);

• 每个字符串是一个按钮的文字
• "\n" 表示换行
• ""（空字符串）表示结束符

---

🧰 3. 设置按钮行为

可以通过 ctrl_map 配置每个按钮的行为，比如是否可点击、是否为单选、是否隐藏等。

lv_btnmatrix_set_ctrl_map(btnm, ctrl_map);

控制位（LV_BTNMATRIX_CTRL_*）有：

控制位宏	含义
LV_BTNMATRIX_CTRL_HIDDEN	隐藏该按钮
LV_BTNMATRIX_CTRL_NO_REPEAT	禁止长按连续触发
LV_BTNMATRIX_CTRL_DISABLED	禁用按钮
LV_BTNMATRIX_CTRL_CHECKABLE	可切换状态
LV_BTNMATRIX_CTRL_CHECKED	初始时为选中状态
LV_BTNMATRIX_CTRL_CLICK_TRIG	是否触发事件

---

🔄 4. 响应按钮点击

你需要注册一个事件处理器：

void btnm_event_handler(lv_event_t *e)
{lv_event_code_t code = lv_event_get_code(e);lv_obj_t *btnm = lv_event_get_target(e);if (code == LV_EVENT_VALUE_CHANGED){const char *txt = lv_btnmatrix_get_btn_text(btnm, lv_btnmatrix_get_selected_btn(btnm));printf("Pressed: %s\n", txt);}
}lv_obj_add_event_cb(btnm, btnm_event_handler, LV_EVENT_ALL, NULL);

---

🎨 5. 自定义样式

你可以使用 lv_obj_set_style_* 或使用主题设置按钮矩阵、单元格的样式：

lv_obj_set_style_bg_color(btnm, lv_palette_main(LV_PALETTE_BLUE), 0);
lv_obj_set_style_text_font(btnm, &lv_font_montserrat_20, 0);

---

📌 6. 使用技巧

技巧	方法
设置按钮不可点	lv_btnmatrix_clear_btn_ctrl(btnm, idx, LV_BTNMATRIX_CTRL_CLICK_TRIG);
设置默认选中	lv_btnmatrix_set_selected_btn(btnm, idx);
获取按钮索引	lv_btnmatrix_get_selected_btn(btnm);
修改单个按钮文字	lv_btnmatrix_set_btn_text(btnm, idx, "NewText");

---

🎯 7. 典型应用示例：数字键盘

static const char * num_map[] = {"1", "2", "3", "\n","4", "5", "6", "\n","7", "8", "9", "\n",".", "0", "Del", ""
};lv_obj_t *kb = lv_btnmatrix_create(lv_scr_act());
lv_btnmatrix_set_map(kb, num_map);
lv_obj_add_event_cb(kb, kb_event_cb, LV_EVENT_ALL, NULL);

---

✅ 总结

功能点	描述
创建函数	lv_btnmatrix_create()
设置按钮文字	lv_btnmatrix_set_map()
设置按钮行为	lv_btnmatrix_set_ctrl_map()
获取点击内容	lv_btnmatrix_get_btn_text()
控制单个按钮属性	lv_btnmatrix_set_btn_ctrl()

---