使用 lvgl9 的 Button Matrix (lv_buttonmatrix) 入门指南-EW帮帮网

文章目录

前言

在用户界面设计中，按钮矩阵是一种常见的控件，用于以紧凑和高效的方式排列多个按钮。LittlevGL 的 lv_buttonmatrix 提供了一种轻量化的实现方式，避免为每个按钮单独创建对象，从而节省内存和计算资源。本文将详细介绍 lv_buttonmatrix 的功能、用法和事件处理。

主体介绍

1. 按钮矩阵概述

lv_buttonmatrix 使用虚拟绘制的方式显示按钮，每个按钮仅占用约 8 字节内存，而普通按钮对象需 100-150 字节。按钮矩阵支持使用行列布局，适合键盘导航和编码器操作。

创建按钮矩阵

以下是一个简单的按钮矩阵示例：

const char *map[] = {"Button1", "Button2", "\n", "Button3", "Button4", ""}; // 定义按钮布局
lv_obj_t *btnm = lv_buttonmatrix_create(lv_scr_act()); // 创建按钮矩阵
lv_buttonmatrix_set_map(btnm, map);                   // 设置布局
lv_obj_align(btnm, LV_ALIGN_CENTER, 0, 0);            // 居中对齐

2. 按钮样式和布局

样式部分

LV_PART_MAIN：矩阵背景的样式，例如背景颜色、行间距 (pad_row) 和列间距 (pad_column)。
LV_PART_ITEMS：每个按钮的样式，支持设置文本样式、背景样式等。

示例：

lv_obj_set_style_bg_color(btnm, lv_color_hex(0xf0f0f0), LV_PART_MAIN); // 背景为浅灰色
lv_obj_set_style_pad_row(btnm, 10, LV_PART_MAIN);                     // 行间距为10像素
lv_obj_set_style_text_color(btnm, lv_color_black(), LV_PART_ITEMS);   // 按钮文本颜色为黑色

控制按钮宽度

可以通过 lv_buttonmatrix_set_button_width() 设置按钮在同一行中的相对宽度。例如：

lv_buttonmatrix_set_button_width(btnm, 0, 2); // 将第一个按钮宽度设置为默认宽度的2倍

3. 按钮控制功能

控制属性

每个按钮可以设置以下属性：

LV_BUTTONMATRIX_CTRL_HIDDEN：隐藏按钮。
LV_BUTTONMATRIX_CTRL_NO_REPEAT：禁用长按重复。
LV_BUTTONMATRIX_CTRL_DISABLED：禁用按钮。
LV_BUTTONMATRIX_CTRL_CHECKABLE：启用按钮的可切换状态。
LV_BUTTONMATRIX_CTRL_CHECKED：将按钮设置为选中状态。
LV_BUTTONMATRIX_CTRL_CLICK_TRIG：单击触发 LV_EVENT_VALUE_CHANGED 事件。
LV_BUTTONMATRIX_CTRL_POPOVER：长按按钮时显示弹出提示。

示例：将某按钮设置为禁用状态

lv_buttonmatrix_set_button_ctrl(btnm, 1, LV_BUTTONMATRIX_CTRL_DISABLED); // 禁用第2个按钮

可以批量为所有按钮设置属性：

lv_buttonmatrix_set_button_ctrl_all(btnm, LV_BUTTONMATRIX_CTRL_NO_REPEAT); // 禁用所有按钮的长按重复

独占选中模式

通过 lv_buttonmatrix_set_one_checked() 启用“独占选中”模式，一次只能选中一个按钮：

lv_buttonmatrix_set_one_checked(btnm, true); // 启用独占选中模式

4. 事件处理

按钮矩阵提供以下常用事件：

LV_EVENT_VALUE_CHANGED：当按钮被按下或释放时触发，事件参数返回被点击按钮的 ID。

示例：处理按钮点击事件

void btnm_event_cb(lv_event_t *e) {
    lv_obj_t *btnm = lv_event_get_target(e);
    uint16_t id = lv_buttonmatrix_get_selected_button(btnm); // 获取选中按钮的ID
    const char *text = lv_buttonmatrix_get_button_text(btnm, id); // 获取按钮文本
    printf("Button %d (%s) clicked.\n", id, text);
}

lv_obj_add_event_cb(btnm, btnm_event_cb, LV_EVENT_VALUE_CHANGED, NULL); // 注册事件回调

5. 键盘支持

按钮矩阵支持键盘或编码器操作，允许通过方向键导航和选择按钮：

LV_KEY_UP/RIGHT/LEFT/DOWN：在按钮之间导航。
LV_KEY_ENTER：按下或释放选中的按钮。

示例：为按钮矩阵设置键盘导航支持

lv_group_t *group = lv_group_create();              // 创建一个组
lv_group_add_obj(group, btnm);                      // 将按钮矩阵添加到组
lv_indev_set_group(lv_indev_get_default(), group);  // 将输入设备绑定到组

总结

lv_buttonmatrix 是一个强大而灵活的控件，适合需要排列多个按钮的场景。通过简单的配置即可实现多行、多列布局，以及丰富的交互功能。以下是完整的代码示例：

完整示例代码

#include "lvgl.h"

void btnm_event_cb(lv_event_t *e) {
    lv_obj_t *btnm = lv_event_get_target(e);
    uint16_t id = lv_buttonmatrix_get_selected_button(btnm);
    const char *text = lv_buttonmatrix_get_button_text(btnm, id);
    if (id != LV_BUTTONMATRIX_BUTTON_NONE) {
        printf("Button %d (%s) clicked.\n", id, text);
    }
}

void create_btnm_demo() {
    const char *map[] = {
        "1", "2", "3", "\n",
        "4", "5", "6", "\n",
        "7", "8", "9", "\n",
        "0", "Clear", "OK", ""
    };

    lv_obj_t *btnm = lv_buttonmatrix_create(lv_scr_act());
    lv_buttonmatrix_set_map(btnm, map);
    lv_obj_set_size(btnm, 200, 150);
    lv_obj_align(btnm, LV_ALIGN_CENTER, 0, 0);

    // 设置样式
    lv_obj_set_style_pad_row(btnm, 10, LV_PART_MAIN);
    lv_obj_set_style_pad_column(btnm, 5, LV_PART_MAIN);

    // 禁用 "Clear" 按钮
    lv_buttonmatrix_set_button_ctrl(btnm, 10, LV_BUTTONMATRIX_CTRL_DISABLED);

    // 启用独占选中模式
    lv_buttonmatrix_set_one_checked(btnm, true);

    // 添加事件回调
    lv_obj_add_event_cb(btnm, btnm_event_cb, LV_EVENT_VALUE_CHANGED, NULL);
}

int main() {
    lv_init();
    create_btnm_demo();
    while (1) {
        lv_task_handler();
    }
}

运行该代码，您将获得一个多行、多列的按钮矩阵，并支持键盘导航、独占选中和事件响应等功能。希望本文能帮助您快速掌握 lv_buttonmatrix 的使用方法！

使用 lvgl9 的 Button Matrix (lv_buttonmatrix) 入门指南