LVGL- 按钮矩阵控件

news2025/7/20 0:46:01

1 按钮矩阵控件

lv_btnmatrix 是 LVGL（Light and Versatile Graphics Library） v8 中提供的一个非常实用的控件，用于创建带有多个按钮的矩阵布局。它常用于实现虚拟键盘、数字键盘、操作面板、选择菜单等场景，特别适用于嵌入式设备、触摸屏等界面。

1.1 功能与特点

lv_btnmatrix 控件的主要功能是展示多个按钮，并提供灵活的布局与交互方式。它的特点包括：

动态布局：按钮布局可以根据需求进行调整，可以显示任意大小和排列方式的按钮。

支持事件回调：按钮矩阵支持绑定事件回调，用户可以在按钮被点击时执行特定的操作。

支持按钮样式设置：每个按钮的样式可以通过 LVGL 的样式机制进行灵活定制，例如字体、颜色、边框、背景等。

1.2 基本结构与工作原理

lv_btnmatrix 是由一组按钮构成的矩阵，其中每个按钮都可以被单独配置和控制。按钮矩阵在实际应用中表现为一组具有相同样式和布局的按钮，可以通过行和列来定义按钮的位置。

1.3 应用场景

虚拟键盘：创建数字键盘、字符键盘等输入设备。

控制面板：用于展示一组操作按钮，如家电控制面板。

选择菜单：实现多选项的选择界面。

2 使用 lv_btnmatrix 的基本步骤：

创建按钮矩阵对象：使用 lv_btnmatrix_create 函数来创建按钮矩阵控件。
设置按钮文本：使用 lv_btnmatrix_set_map 函数来设置按钮的文本布局，可以通过这个函数定义每个按钮的标签。
设置按钮行为：你可以通过事件回调函数来处理按钮的点击事件。

2.1 创建按钮矩阵

创建一个按钮矩阵对象通常使用 lv_btnmatrix_create() 函数。该函数需要指定父对象，一般情况下，父对象是屏幕对象（lv_scr_act()），表示该控件将在当前显示的屏幕上显示。

    lv_obj_t* btnm = lv_btnmatrix_create(lv_scr_act());

在这里插入图片描述

2.2 设置按钮文本和布局

按钮矩阵最核心的功能之一是设置按钮的文本。按钮的文本布局是通过 lv_btnmatrix_set_map() 函数进行设置的。这个函数使用一个字符串映射（类似于字符数组）来定义按钮的文本，并且支持多行布局。

2.2.1 设置

void lv_btnmatrix_set_map(lv_obj_t * btnm, const char ** map);

btnm：按钮矩阵对象，通常是通过 lv_btnmatrix_create() 创建的按钮矩阵对象。

map：一个指向字符指针数组的指针，每个字符指针数组元素表示按钮矩阵中的一行按钮文本。每个数组元素中的文本可以通过空格分隔按钮。

2.2.2 案例

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

在这里插入图片描述

2.3 设置颜色和位置

static lv_style_t style;
lv_style_init(&style);
lv_style_set_bg_color(&style, lv_color_hex(0x003366));      // 背景色：深蓝色
lv_style_set_border_color(&style, lv_color_hex(0xffffff));   // 边框颜色：白色
lv_style_set_text_color(&style, lv_color_hex(0xffffff));     // 文字颜色：白色

lv_obj_add_style(btnm, &style, 0);  // 将样式应用到按钮矩阵

lv_obj_set_size(btnm, 300, 150);                  // 设置控件尺寸
lv_obj_align(btnm, LV_ALIGN_CENTER, 0, 0);  // 将按钮矩阵居中显示

在这里插入图片描述

2.4 事件处理

按钮矩阵支持事件处理，通常用于响应用户点击某个按钮时的操作。可以为按钮矩阵添加事件回调函数，例如，当按钮状态变化时触发的 LV_EVENT_VALUE_CHANGED 事件。

static void btnm_event_handler(lv_event_t* e)
{
    lv_obj_t* btn = lv_event_get_target(e);  // 获取被点击的按钮对象
    uint32_t id = lv_btnmatrix_get_selected_btn(btn);
    const char* text = lv_btnmatrix_get_btn_text(btn, id);  // 获取按钮的文本
    LV_LOG("按钮 %s 被点击\n", text);
}

   lv_obj_add_event_cb(btnm, btnm_event_handler, LV_EVENT_VALUE_CHANGED, NULL);

在这里插入图片描述

2.5 选中或者可选

void lv_btnmatrix_set_btn_ctrl(lv_obj_t *btnm, uint16_t btn_id, lv_btnmatrix_ctrl_t ctrl);

在这里插入图片描述

lv_btnmatrix_set_btn_ctrl(btnm, 10, LV_BTNMATRIX_CTRL_CHECKABLE);  //  ok 可以选中
lv_btnmatrix_set_btn_ctrl(btnm, 11, LV_BTNMATRIX_CTRL_CHECKED);   // cancel 选中

在这里插入图片描述

检查哪个按键是否被按下

if (lv_btnmatrix_has_btn_ctrl(btn, 10, LV_BTNMATRIX_CTRL_CHECKED)) {
    LV_LOG("按钮 %s 被点击\n", "OK");
}

2.6 修改内部按键的风格

static lv_style_t style_btn;
lv_style_init(&style_btn);
lv_style_set_radius(&style_btn,10);
lv_style_set_border_width(&style_btn, 1);
lv_style_set_border_opa(&style_btn, LV_OPA_COVER);
lv_style_set_border_color(&style_btn, lv_palette_main(LV_PALETTE_RED));
lv_style_set_border_side(&style_btn, LV_BORDER_SIDE_INTERNAL);
lv_style_set_bg_color(&style_btn, lv_palette_main(LV_PALETTE_RED));
lv_style_set_text_color(&style_btn, lv_palette_main(LV_PALETTE_YELLOW));
lv_obj_add_style(btnm, &style_btn, LV_PART_ITEMS);