LVGL（lv_btnmatrix矩阵按钮）

文章目录

- [🔧 1. 基本概念](#🔧 1. 基本概念)
- - [📌 lv\_btnmatrix 是什么？](#📌 lv_btnmatrix 是什么？)
- [🧱 2. 基本结构和用法](#🧱 2. 基本结构和用法)
- - [✅ 创建按钮矩阵](#✅ 创建按钮矩阵)
  - [✅ 设置按钮文字](#✅ 设置按钮文字)
- [🧰 3. 设置按钮行为](#🧰 3. 设置按钮行为)
- [🔄 4. 响应按钮点击](#🔄 4. 响应按钮点击)
- [🎨 5. 自定义样式](#🎨 5. 自定义样式)
- [📌 6. 使用技巧](#📌 6. 使用技巧)
- [🎯 7. 典型应用示例：数字键盘](#🎯 7. 典型应用示例：数字键盘)
- [✅ 总结](#✅ 总结)

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

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

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

🔧 1. 基本概念

📌 lv_btnmatrix 是什么？

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

🧱 2. 基本结构和用法

✅ 创建按钮矩阵

c 复制代码

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

✅ 设置按钮文字

c 复制代码

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 配置每个按钮的行为，比如是否可点击、是否为单选、是否隐藏等。

c 复制代码

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. 响应按钮点击

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

c 复制代码

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_* 或使用主题设置按钮矩阵、单元格的样式：

c 复制代码

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. 典型应用示例：数字键盘

c 复制代码

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()`