Button matrix（按钮矩阵） (lv_btnmatrix)

Overview（概述）

查看原文

The Button Matrix object is a lightweight way to display multiple buttons in rows and columns. Lightweight because the buttons are not actually created but just virtually drawn on the fly. This way, one button use only eight extra bytes of memory instead of the ~100-150 bytes a normal Button object plus the 100 or so bytes for the the Label object.

The Button matrix is added to the default group (if one is set). Besides the Button matrix is an editable object to allow selecting and clicking the buttons with encoder navigation too.

按钮矩阵(lv_btnmatrix)组件是一种在行和列中显示多个按钮的轻量级实现方式。按钮不是实际创建出来的，而是实时绘制出来的，所以轻量级，因为这样一个按钮仅使用 8 个字节的内存，而不是普通 Button 组件那样：~100-150 字节再加上 Label 组件的内存占用。

按钮矩阵添加到默认组（如果之前已设置了组）。此外，按钮矩阵是一个可编辑的对象，可以通过编码器导航选择和单击按钮。

Parts and Styles（零件和样式）

查看原文

• LV_PART_MAIN The background of the button matrix, uses the typical background style properties. pad_row and pad_column sets the space between the buttons.

• LV_PART_ITEMS The buttons all use the text and typical background style properties except translations and transformations.

• LV_PART_MAIN 按钮矩阵的背景，使用所有组件默认都有的典型的背景样式属性。可通过 pad_row 和 pad_column 设置按钮之间的空间。

• LV_PART_ITEMS 除了转变之外，按钮都使用文本和典型的背景样式属性。

Usage（用法）

Button's text（按钮的文字）

查看原文

There is a text on each button. To specify them a descriptor string array, called map, needs to be used. The map can be set with lv_btnmatrix_set_map(btnm, my_map). The declaration of a map should look like const char * map[] = {"btn1", "btn2", "btn3", NULL}. Note that the last element has to be either NULL or an empty string ("")!

Use "\n" in the map to insert a line break. E.g. {"btn1", "btn2", "\n", "btn3", ""}. Each line's buttons have their width calculated automatically. So in the example the first row will have 2 buttons each with 50% width and a second row with 1 button having 100% width.

每个按钮上都可以有文字。要指定按钮的文字，需要使用称为 map 的描述符按钮布局的字符串数组。 map 可以使用 lv_btnmatrix_set_map(btnm, my_map) 接口设置。 map 的格式： const char * map[] = {"btn1", "btn2", "btn3", NULL}。 请注意，map 数组的最后一个元素必须是 NULL 或空字符串 ("")！

在 map 中使用 "\n" 插入换行符。 例如。 {"btn1", "btn2", "\n", "btn3", ""}。 每行按钮的宽度都会自动计算平均分配(默认)。 因此，在上面的示例中，第一行将有 2 个按钮，每个按钮的宽度为 50%，第二行将有 1 个按钮的宽度为 100%。

Control buttons（控制按钮）

查看原文

The buttons' width can be set relative to the other button in the same row with lv_btnmatrix_set_btn_width(btnm, btn_id, width) E.g. in a line with two buttons: btnA, width = 1 and btnB, width = 2, btnA will have 33 % width and btnB will have 66 % width. It's similar to how the flex-grow property works in CSS. The width must be in the [1..7] range and the default width is 1.

In addition to the width, each button can be customized with the following parameters:

• LV_BTNMATRIX_CTRL_HIDDEN Makes a button hidden (hidden buttons still take up space in the layout, they are just not visible or clickable)

• LV_BTNMATRIX_CTRL_NO_REPEAT Disable repeating when the button is long pressed

• LV_BTNMATRIX_CTRL_DISABLED Makes a button disabled Like LV_STATE_DISABLED on normal objects

• LV_BTNMATRIX_CTRL_CHECKABLE Enable toggling of a button. I.e. LV_STATE_CHECHED will be added/removed as the button is clicked

• LV_BTNMATRIX_CTRL_CHECKED MAke the button checked. It will use the LV_STATE_CHECHKED styles.

• LV_BTNMATRIX_CTRL_CLICK_TRIG Enabled: send LV_EVENT_VALUE_CHANGE on CLICK, Disabled: send LV_EVENT_VALUE_CHANGE on PRESS*/

• LV_BTNMATRIX_CTRL_RECOLOR Enable recoloring of button texts with #. E.g. "It's #ff0000 red#"

• LV_BTNMATRIX_CTRL_CUSTOM_1 Custom free to use flag

• LV_BTNMATRIX_CTRL_CUSTOM_2 Custom free to use flag

By default all flags are disabled.

可以使用 lv_btnmatrix_set_btn_width(btnm, btn_id, width) 接口设置相对于同一行中的另一个按钮的宽度。 例如。在一行中有两个按钮这样设置：btnA, width = 1 和 btnB, width = 2，这样btnA 将有 33% 的宽度，btnB 将有 66% 的宽度。 它类似于 flex-grow 属性在 CSS 中的工作方式。 宽度必须在 [1..7] 范围内，默认宽度为 1。

除了宽度之外，每个按钮还可以使用以下参数进行自定义：

• LV_BTNMATRIX_CTRL_HIDDEN 隐藏按钮（隐藏的按钮仍然占用布局中的空间，它们只是不可见或不可点击）

• LV_BTNMATRIX_CTRL_NO_REPEAT 长按按钮时禁用重复

• LV_BTNMATRIX_CTRL_DISABLED 使按钮被禁用，就像普通对象上的 LV_STATE_DISABLED

• LV_BTNMATRIX_CTRL_CHECKABLE 启用按钮切换。也就是 LV_STATE_CHECHED 将在按钮被点击时添加/删除

• LV_BTNMATRIX_CTRL_CHECKED 检查按钮。它将使用 LV_STATE_CHECHKED 的样式。

• LV_BTNMATRIX_CTRL_CLICK_TRIG 启用：在点击时发送 LV_EVENT_VALUE_CHANGE ；禁用：在按下时发送 LV_EVENT_VALUE_CHANGE

• LV_BTNMATRIX_CTRL_RECOLOR 使用 # 启用按钮文本的重新着色。例如 "It's #ff0000 red btn#"

• LV_BTNMATRIX_CTRL_CUSTOM_1 可自定义使用的标志

• LV_BTNMATRIX_CTRL_CUSTOM_2 可自定义使用的标志

默认情况下，所有标志都被禁用。

查看原文

To set or clear a button's control attribute, use lv_btnmatrix_set_btn_ctrl(btnm, btn_id, LV_BTNM_CTRL_...) and lv_btnmatrix_clear_btn_ctrl(btnm, btn_id, LV_BTNMATRIX_CTRL_...) respectively. More LV_BTNM_CTRL_... values can be OR-ed

To set/clear the same control attribute for all buttons of a button matrix, use lv_btnmatrix_set_btn_ctrl_all(btnm, btn_id, LV_BTNM_CTRL_...) and lv_btnmatrix_clear_btn_ctrl_all(btnm, btn_id, LV_BTNMATRIX_CTRL_...).

The set a control map for a button matrix (similarly to the map for the text), use lv_btnmatrix_set_ctrl_map(btnm, ctrl_map). An element of ctrl_map should look like ctrl_map[0] = width | LV_BTNM_CTRL_NO_REPEAT |  LV_BTNM_CTRL_CHECHKABLE. The number of elements should be equal to the number of buttons (excluding newlines characters).

要设置或清除按钮的控制属性，请使用 lv_btnmatrix_set_btn_ctrl(btnm, btn_id, LV_BTNM_CTRL_...) 和 lv_btnmatrix_clear_btn_ctrl(btnm, btn_id, LV_BTNMATRIX_CTRL_...) 分别。 更多 LV_BTNM_CTRL_... 值可以被 OR-ed

要为按钮矩阵的所有按钮设置/清除相同的控制属性，请使用 lv_btnmatrix_set_btn_ctrl_all(btnm, btn_id, LV_BTNM_CTRL_...) 和 lv_btnmatrix_clear_btn_ctrl_all(btnm, btn_id, LV_BTNMATRIX_CTRL_...)。

我们可以写一个数组来一次单独设置多个或者所有的按钮，这有点像一个控制表，这里称其为 ctrl_map ，我们可以使用 lv_btnmatrix_set_ctrl_map(btnm, ctrl_map) 将控制表添加到按钮矩阵中。 ctrl_map 中的元素的格式：ctrl_map[0] = width | LV_BTNM_CTRL_NO_REPEAT | LV_BTNM_CTRL_CHECHKABLE ，也就是我们可以添加多个属性。 元素的数量应该等于(可以小于，但是不应该超出)按钮的数量(不包括换行符)。

One check（一次检查）

查看原文

The "One check" feature can be enabled with lv_btnmatrix_set_one_check(btnm, true) to allow only one button to be checked at a time.

可以使用 lv_btnmatrix_set_one_check(btnm, true) 启用 “一次检查” 功能，这样一次只能检查一个按钮(我们就能知道最后点击的是哪个按钮)。

Events（事件）

查看原文

• LV_EVENT_VALUE_CHANGED Sent when a button is pressed/released or repeated after long press. The event parameter is set to the ID of the pressed/released button.

• LV_EVENT_DRAW_PART_BEGIN and LV_EVENT_DRAW_PART_END are sent for the following types:

  • LV_BTNMATRIX_DRAW_PART_BTN The individual buttons.

    • part: LV_PART_ITEMS

    • id:index of the button being drawn

    • draw_area: the area of teh button

    • rect_dsc

• LV_EVENT_VALUE_CHANGED 按下/释放按钮或长按时发送。事件参数设置为按下/释放按钮的ID。

• 为以下类型发送LV_EVENT_DRAW_PART_BEGIN和LV_EVENT_DRAW_PART_END：

  • LV_BTNMATRIX_DRAW_PART_BTN 单个按钮。

    • 部分：LV_PART_ITEMS

    • id：正在绘制的按钮的索引

    • draw_area：按钮的区域

    • rect_dsc

查看原文

See the events of the Base object too.

lv_btnmatrix_get_selected_btn(btnm) returns the index of the most recently released or focused button or LV_BTNMATRIX_BTN_NONE if no such button.

lv_btnmatrix_get_btn_text(btnm, btn_id) returns a pointer to the text of btn_idth button.

Learn more about Events.

参见 基础对象 的事件。

lv_btnmatrix_get_selected_btn(btnm) 返回最后被释放或聚焦的按钮的索引值，如果没有这样的按钮，则返回 LV_BTNMATRIX_BTN_NONE。

lv_btnmatrix_get_btn_text(btnm, btn_id) 返回索引为 btn_id 的按钮的文本的指针。

详细了解 事件。

Keys（按键）

查看原文

• LV_KEY_RIGHT/UP/LEFT/RIGHT To navigate among the buttons to select one

• LV_KEY_ENTER To press/release the selected button

Learn more about Keys.

• LV_KEY_RIGHT/UP/LEFT/RIGHT 在按钮矩阵的按钮之间导航来选中不同的按钮。

• LV_KEY_ENTER 按下/释放所选按钮。

了解有关 按键 的更多信息。

Example

Simple Button matrix

C code  

 GitHub

#include "../../lv_examples.h"
#if LV_USE_BTNMATRIX && LV_BUILD_EXAMPLES

static void event_handler(lv_event_t * e)
{
    lv_event_code_t code = lv_event_get_code(e);
    lv_obj_t * obj = lv_event_get_target(e);
    if(code == LV_EVENT_VALUE_CHANGED) {
        uint32_t id = lv_btnmatrix_get_selected_btn(obj);
        const char * txt = lv_btnmatrix_get_btn_text(obj, id);

        LV_LOG_USER("%s was pressed\n", txt);
    }
}


static const char * btnm_map[] = {"1", "2", "3", "4", "5", "\n",
                                  "6", "7", "8", "9", "0", "\n",
                                  "Action1", "Action2", ""};

void lv_example_btnmatrix_1(void)
{
    lv_obj_t * btnm1 = lv_btnmatrix_create(lv_scr_act());
    lv_btnmatrix_set_map(btnm1, btnm_map);
    lv_btnmatrix_set_btn_width(btnm1, 10, 2);        /*Make "Action1" twice as wide as "Action2"*/
    lv_btnmatrix_set_btn_ctrl(btnm1, 10, LV_BTNMATRIX_CTRL_CHECKABLE);
    lv_btnmatrix_set_btn_ctrl(btnm1, 11, LV_BTNMATRIX_CTRL_CHECKED);
    lv_obj_align(btnm1, LV_ALIGN_CENTER, 0, 0);
    lv_obj_add_event_cb(btnm1, event_handler, LV_EVENT_ALL, NULL);
}

#endif

MicroPython code  

 GitHub Simulator

def event_handler(evt):
    code = evt.get_code()
    obj  = evt.get_target()

    if code == lv.EVENT.VALUE_CHANGED :
        id = obj.get_selected_btn()
        txt = obj.get_btn_text(id)

        print("%s was pressed"%txt)

btnm_map = ["1", "2", "3", "4", "5", "\n",
            "6", "7", "8", "9", "0", "\n",
            "Action1", "Action2", ""]

btnm1 = lv.btnmatrix(lv.scr_act())
btnm1.set_map(btnm_map)
btnm1.set_btn_width(10, 2)        # Make "Action1" twice as wide as "Action2"
btnm1.set_btn_ctrl(10, lv.btnmatrix.CTRL.CHECKABLE)
btnm1.set_btn_ctrl(11, lv.btnmatrix.CTRL.CHECKED)
btnm1.align(lv.ALIGN.CENTER, 0, 0)
btnm1.add_event_cb(event_handler, lv.EVENT.ALL, None)


#endif

---

Custom buttons

C code  

 GitHub

#include "../../lv_examples.h"
#if LV_USE_BTNMATRIX && LV_BUILD_EXAMPLES


static void event_cb(lv_event_t * e)
{
    lv_event_code_t code = lv_event_get_code(e);
    lv_obj_t * obj = lv_event_get_target(e);
    if(code == LV_EVENT_DRAW_PART_BEGIN) {
        lv_obj_draw_part_dsc_t * dsc = lv_event_get_param(e);

        /*Change the draw descriptor the 2nd button*/
        if(dsc->id == 1) {
            dsc->rect_dsc->radius = 0;
            if(lv_btnmatrix_get_selected_btn(obj) == dsc->id)  dsc->rect_dsc->bg_color = lv_palette_darken(LV_PALETTE_BLUE, 3);
            else dsc->rect_dsc->bg_color = lv_palette_main(LV_PALETTE_BLUE);

            dsc->rect_dsc->shadow_width = 6;
            dsc->rect_dsc->shadow_ofs_x = 3;
            dsc->rect_dsc->shadow_ofs_y = 3;
            dsc->label_dsc->color = lv_color_white();
        }
        /*Change the draw descriptor the 3rd button*/
        else if(dsc->id == 2) {
            dsc->rect_dsc->radius = LV_RADIUS_CIRCLE;
            if(lv_btnmatrix_get_selected_btn(obj) == dsc->id)  dsc->rect_dsc->bg_color = lv_palette_darken(LV_PALETTE_RED, 3);
            else dsc->rect_dsc->bg_color = lv_palette_main(LV_PALETTE_RED);

            dsc->label_dsc->color = lv_color_white();
        }
        else if(dsc->id == 3) {
            dsc->label_dsc->opa = LV_OPA_TRANSP; /*Hide the text if any*/

        }
    }
    if(code == LV_EVENT_DRAW_PART_END) {
        lv_obj_draw_part_dsc_t * dsc = lv_event_get_param(e);

        /*Add custom content to the 4th button when the button itself was drawn*/
        if(dsc->id == 3) {
            LV_IMG_DECLARE(img_star);
            lv_img_header_t header;
            lv_res_t res = lv_img_decoder_get_info(&img_star, &header);
            if(res != LV_RES_OK) return;

            lv_area_t a;
            a.x1 = dsc->draw_area->x1 + (lv_area_get_width(dsc->draw_area) - header.w) / 2;
            a.x2 = a.x1 + header.w - 1;
            a.y1 = dsc->draw_area->y1 + (lv_area_get_height(dsc->draw_area) - header.h) / 2;
            a.y2 = a.y1 + header.h - 1;

            lv_draw_img_dsc_t img_draw_dsc;
            lv_draw_img_dsc_init(&img_draw_dsc);
            img_draw_dsc.recolor = lv_color_black();
            if(lv_btnmatrix_get_selected_btn(obj) == dsc->id)  img_draw_dsc.recolor_opa = LV_OPA_30;

            lv_draw_img(dsc->draw_ctx, &img_draw_dsc, &a, &img_star);
        }
    }
}

/**
 * Add custom drawer to the button matrix to customize buttons one by one
 */
void lv_example_btnmatrix_2(void)
{
    lv_obj_t * btnm = lv_btnmatrix_create(lv_scr_act());
    lv_obj_add_event_cb(btnm, event_cb, LV_EVENT_ALL, NULL);
    lv_obj_center(btnm);
}

#endif

MicroPython code  

 GitHub Simulator

from imagetools import get_png_info, open_png

# Register PNG image decoder
decoder = lv.img.decoder_create()
decoder.info_cb = get_png_info
decoder.open_cb = open_png

# Create an image from the png file
try:
    with open('../../assets/img_star.png','rb') as f:
        png_data = f.read()
except:
    print("Could not find star.png")
    sys.exit()
    
img_star_argb = lv.img_dsc_t({
  'data_size': len(png_data),
  'data': png_data 
})

def event_cb(e):
    code = e.get_code()
    obj = e.get_target()
    dsc = lv.obj_draw_part_dsc_t.__cast__(e.get_param())
    if code == lv.EVENT.DRAW_PART_BEGIN:
        # Change the draw descriptor the 2nd button
        if dsc.id == 1:
            dsc.rect_dsc.radius = 0
            if obj.get_selected_btn() == dsc.id:
                dsc.rect_dsc.bg_color = lv.palette_darken(lv.PALETTE.GREY, 3)
            else:
                dsc.rect_dsc.bg_color = lv.palette_main(lv.PALETTE.BLUE)

            dsc.rect_dsc.shadow_width = 6
            dsc.rect_dsc.shadow_ofs_x = 3
            dsc.rect_dsc.shadow_ofs_y = 3
            dsc.label_dsc.color = lv.color_white()

        # Change the draw descriptor the 3rd button

        elif dsc.id == 2:
            dsc.rect_dsc.radius = lv.RADIUS.CIRCLE
            if obj.get_selected_btn() == dsc.id:
                dsc.rect_dsc.bg_color = lv.palette_darken(lv.PALETTE.RED, 3)
            else:
                dsc.rect_dsc.bg_color = lv.palette_main(lv.PALETTE.RED)
                
                dsc.label_dsc.color = lv.color_white()
        elif dsc.id == 3:
            dsc.label_dsc.opa = lv.OPA.TRANSP  # Hide the text if any

    if code == lv.EVENT.DRAW_PART_END:
        # Add custom content to the 4th button when the button itself was drawn
        if dsc.id == 3:
            # LV_IMG_DECLARE(img_star)
            header = lv.img_header_t()
            res = lv.img.decoder_get_info(img_star_argb, header)
            if res != lv.RES.OK:
                print("error when getting image header")
                return
            else:
                a = lv.area_t()
                a.x1 = dsc.draw_area.x1 + (dsc.draw_area.get_width() - header.w) // 2
                a.x2 = a.x1 + header.w - 1
                a.y1 = dsc.draw_area.y1 + (dsc.draw_area.get_height() - header.h) // 2
                a.y2 = a.y1 + header.h - 1
                img_draw_dsc = lv.draw_img_dsc_t()
                img_draw_dsc.init()
                img_draw_dsc.recolor = lv.color_black()
                if obj.get_selected_btn() == dsc.id:
                    img_draw_dsc.recolor_opa = lv.OPA._30

                dsc.draw_ctx.img(img_draw_dsc, a, img_star_argb)

#
# Add custom drawer to the button matrix to c
#
btnm = lv.btnmatrix(lv.scr_act())
btnm.add_event_cb(event_cb, lv.EVENT.ALL, None)
btnm.center()

---

Pagination

C code  

 GitHub

#include "../../lv_examples.h"
#if LV_USE_BTNMATRIX  && LV_BUILD_EXAMPLES

static void event_cb(lv_event_t * e)
{
    lv_obj_t * obj = lv_event_get_target(e);
    uint32_t id = lv_btnmatrix_get_selected_btn(obj);
    bool prev = id == 0 ? true : false;
    bool next = id == 6 ? true : false;
    if(prev || next) {
        /*Find the checked button*/
        uint32_t i;
        for(i = 1; i < 7; i++) {
            if(lv_btnmatrix_has_btn_ctrl(obj, i, LV_BTNMATRIX_CTRL_CHECKED)) break;
        }

        if(prev && i > 1) i--;
        else if(next && i < 5) i++;

        lv_btnmatrix_set_btn_ctrl(obj, i, LV_BTNMATRIX_CTRL_CHECKED);
    }
}

/**
 * Make a button group (pagination)
 */
void lv_example_btnmatrix_3(void)
{
    static lv_style_t style_bg;
    lv_style_init(&style_bg);
    lv_style_set_pad_all(&style_bg, 0);
    lv_style_set_pad_gap(&style_bg, 0);
    lv_style_set_clip_corner(&style_bg, true);
    lv_style_set_radius(&style_bg, LV_RADIUS_CIRCLE);
    lv_style_set_border_width(&style_bg, 0);


    static lv_style_t style_btn;
    lv_style_init(&style_btn);
    lv_style_set_radius(&style_btn, 0);
    lv_style_set_border_width(&style_btn, 1);
    lv_style_set_border_opa(&style_btn, LV_OPA_50);
    lv_style_set_border_color(&style_btn, lv_palette_main(LV_PALETTE_GREY));
    lv_style_set_border_side(&style_btn, LV_BORDER_SIDE_INTERNAL);
    lv_style_set_radius(&style_btn, 0);

    static const char * map[] = {LV_SYMBOL_LEFT, "1", "2", "3", "4", "5", LV_SYMBOL_RIGHT, ""};

    lv_obj_t * btnm = lv_btnmatrix_create(lv_scr_act());
    lv_btnmatrix_set_map(btnm, map);
    lv_obj_add_style(btnm, &style_bg, 0);
    lv_obj_add_style(btnm, &style_btn, LV_PART_ITEMS);
    lv_obj_add_event_cb(btnm, event_cb, LV_EVENT_VALUE_CHANGED, NULL);
    lv_obj_set_size(btnm, 225, 35);

    /*Allow selecting on one number at time*/
    lv_btnmatrix_set_btn_ctrl_all(btnm, LV_BTNMATRIX_CTRL_CHECKABLE);
    lv_btnmatrix_clear_btn_ctrl(btnm, 0, LV_BTNMATRIX_CTRL_CHECKABLE);
    lv_btnmatrix_clear_btn_ctrl(btnm, 6, LV_BTNMATRIX_CTRL_CHECKABLE);

    lv_btnmatrix_set_one_checked(btnm, true);
    lv_btnmatrix_set_btn_ctrl(btnm, 1, LV_BTNMATRIX_CTRL_CHECKED);

    lv_obj_center(btnm);

}

#endif

MicroPython code  

 GitHub Simulator

def event_cb(e):
    obj = e.get_target()
    id = obj.get_selected_btn()
    if id == 0:
        prev = True
    else:
        prev = False
    if id == 6:
        next = True
    else:
        next = False
    if prev or next:
        # Find the checked butto
        for i in range(7):
            if obj.has_btn_ctrl(i, lv.btnmatrix.CTRL.CHECKED):
                break
        if prev and i > 1:
            i-=1
        elif next and i < 5:
            i+=1

        obj.set_btn_ctrl(i, lv.btnmatrix.CTRL.CHECKED)

#
# Make a button group
#

style_bg = lv.style_t()
style_bg.init()
style_bg.set_pad_all(0)
style_bg.set_pad_gap(0)
style_bg.set_clip_corner(True)
style_bg.set_radius(lv.RADIUS.CIRCLE)
style_bg.set_border_width(0)


style_btn = lv.style_t()
style_btn.init()
style_btn.set_radius(0)
style_btn.set_border_width(1)
style_btn.set_border_opa(lv.OPA._50)
style_btn.set_border_color(lv.palette_main(lv.PALETTE.GREY))
style_btn.set_border_side(lv.BORDER_SIDE.INTERNAL)
style_btn.set_radius(0)

map = [lv.SYMBOL.LEFT,"1","2", "3", "4", "5",lv.SYMBOL.RIGHT, ""]

btnm = lv.btnmatrix(lv.scr_act())
btnm.set_map(map)
btnm.add_style(style_bg, 0)
btnm.add_style(style_btn, lv.PART.ITEMS)
btnm.add_event_cb(event_cb, lv.EVENT.VALUE_CHANGED, None)
btnm.set_size(225, 35)

# Allow selecting on one number at time
btnm.set_btn_ctrl_all(lv.btnmatrix.CTRL.CHECKABLE)
btnm.clear_btn_ctrl(0, lv.btnmatrix.CTRL.CHECKABLE)
btnm.clear_btn_ctrl(6, lv.btnmatrix.CTRL.CHECKABLE)

btnm.set_one_checked(True)
btnm.set_btn_ctrl(1, lv.btnmatrix.CTRL.CHECKED)

btnm.center()

---

API

Typedefs

typedef uint16_t lv_btnmatrix_ctrl_t

typedef bool (*lv_btnmatrix_btn_draw_cb_t)(lv_obj_t *btnm, uint32_t btn_id, const lv_area_t *draw_area, const lv_area_t *clip_area)

Enums

enum [anonymous]

Type to store button control bits (disabled, hidden etc.) The first 3 bits are used to store the width

Values:

enumerator _LV_BTNMATRIX_WIDTH

Reserved to stire the size units

enumerator LV_BTNMATRIX_CTRL_HIDDEN

Button hidden

enumerator LV_BTNMATRIX_CTRL_NO_REPEAT

Do not repeat press this button.

enumerator LV_BTNMATRIX_CTRL_DISABLED

Disable this button.

enumerator LV_BTNMATRIX_CTRL_CHECKABLE

The button can be toggled.

enumerator LV_BTNMATRIX_CTRL_CHECKED

Button is currently toggled (e.g. checked).

enumerator LV_BTNMATRIX_CTRL_CLICK_TRIG

1: Send LV_EVENT_VALUE_CHANGE on CLICK, 0: Send LV_EVENT_VALUE_CHANGE on PRESS

enumerator LV_BTNMATRIX_CTRL_POPOVER

Show a popover when pressing this key

enumerator LV_BTNMATRIX_CTRL_RECOLOR

Enable text recoloring with #color

enumerator _LV_BTNMATRIX_CTRL_RESERVED

Reserved for later use

enumerator LV_BTNMATRIX_CTRL_CUSTOM_1

Custom free to use flag

enumerator LV_BTNMATRIX_CTRL_CUSTOM_2

Custom free to use flag

enum lv_btnmatrix_draw_part_type_t

type field in lv_obj_draw_part_dsc_t if class_p = lv_btnmatrix_class Used in LV_EVENT_DRAW_PART_BEGIN and LV_EVENT_DRAW_PART_END

Values:

enumerator LV_BTNMATRIX_DRAW_PART_BTN

The rectangle and label of buttons

Functions

LV_EXPORT_CONST_INT(LV_BTNMATRIX_BTN_NONE)

lv_obj_t *lv_btnmatrix_create(lv_obj_t *parent)

Create a button matrix object

参数

parent -- pointer to an object, it will be the parent of the new button matrix

返回

pointer to the created button matrix

void lv_btnmatrix_set_map(lv_obj_t *obj, const char *map[])

Set a new map. Buttons will be created/deleted according to the map. The button matrix keeps a reference to the map and so the string array must not be deallocated during the life of the matrix.

参数

• obj -- pointer to a button matrix object

• map -- pointer a string array. The last string has to be: "". Use "\n" to make a line break.

void lv_btnmatrix_set_ctrl_map(lv_obj_t *obj, const lv_btnmatrix_ctrl_t ctrl_map[])

Set the button control map (hidden, disabled etc.) for a button matrix. The control map array will be copied and so may be deallocated after this function returns.

参数

• obj -- pointer to a button matrix object

• ctrl_map -- pointer to an array of lv_btn_ctrl_t control bytes. The length of the array and position of the elements must match the number and order of the individual buttons (i.e. excludes newline entries). An element of the map should look like e.g.: ctrl_map[0] = width | LV_BTNMATRIX_CTRL_NO_REPEAT | LV_BTNMATRIX_CTRL_TGL_ENABLE

void lv_btnmatrix_set_selected_btn(lv_obj_t *obj, uint16_t btn_id)

Set the selected buttons

参数

• obj -- pointer to button matrix object

• btn_id -- 0 based index of the button to modify. (Not counting new lines)

void lv_btnmatrix_set_btn_ctrl(lv_obj_t *obj, uint16_t btn_id, lv_btnmatrix_ctrl_t ctrl)

Set the attributes of a button of the button matrix

参数

• obj -- pointer to button matrix object

• btn_id -- 0 based index of the button to modify. (Not counting new lines)

• ctrl -- OR-ed attributs. E.g. LV_BTNMATRIX_CTRL_NO_REPEAT | LV_BTNMATRIX_CTRL_CHECKABLE

void lv_btnmatrix_clear_btn_ctrl(lv_obj_t *obj, uint16_t btn_id, lv_btnmatrix_ctrl_t ctrl)

Clear the attributes of a button of the button matrix

参数

• obj -- pointer to button matrix object

• btn_id -- 0 based index of the button to modify. (Not counting new lines)

• ctrl -- OR-ed attributs. E.g. LV_BTNMATRIX_CTRL_NO_REPEAT | LV_BTNMATRIX_CTRL_CHECKABLE

void lv_btnmatrix_set_btn_ctrl_all(lv_obj_t *obj, lv_btnmatrix_ctrl_t ctrl)

Set attributes of all buttons of a button matrix

参数

• obj -- pointer to a button matrix object

• ctrl -- attribute(s) to set from lv_btnmatrix_ctrl_t. Values can be ORed.

void lv_btnmatrix_clear_btn_ctrl_all(lv_obj_t *obj, lv_btnmatrix_ctrl_t ctrl)

Clear the attributes of all buttons of a button matrix

参数

• obj -- pointer to a button matrix object

• ctrl -- attribute(s) to set from lv_btnmatrix_ctrl_t. Values can be ORed.

• en -- true: set the attributes; false: clear the attributes

void lv_btnmatrix_set_btn_width(lv_obj_t *obj, uint16_t btn_id, uint8_t width)

Set a single button's relative width. This method will cause the matrix be regenerated and is a relatively expensive operation. It is recommended that initial width be specified using lv_btnmatrix_set_ctrl_map and this method only be used for dynamic changes.

参数

• obj -- pointer to button matrix object

• btn_id -- 0 based index of the button to modify.

• width -- relative width compared to the buttons in the same row. [1..7]

void lv_btnmatrix_set_one_checked(lv_obj_t *obj, bool en)

Make the button matrix like a selector widget (only one button may be checked at a time). LV_BTNMATRIX_CTRL_CHECKABLE must be enabled on the buttons to be selected using lv_btnmatrix_set_ctrl() or lv_btnmatrix_set_btn_ctrl_all().

参数

• obj -- pointer to a button matrix object

• en -- whether "one check" mode is enabled

const char **lv_btnmatrix_get_map(const lv_obj_t *obj)

Get the current map of a button matrix

参数

obj -- pointer to a button matrix object

返回

the current map

uint16_t lv_btnmatrix_get_selected_btn(const lv_obj_t *obj)

Get the index of the lastly "activated" button by the user (pressed, released, focused etc) Useful in the event_cb to get the text of the button, check if hidden etc.

参数

obj -- pointer to button matrix object

返回

index of the last released button (LV_BTNMATRIX_BTN_NONE: if unset)

const char *lv_btnmatrix_get_btn_text(const lv_obj_t *obj, uint16_t btn_id)

Get the button's text

参数

• obj -- pointer to button matrix object

• btn_id -- the index a button not counting new line characters.

返回

text of btn_index` button

bool lv_btnmatrix_has_btn_ctrl(lv_obj_t *obj, uint16_t btn_id, lv_btnmatrix_ctrl_t ctrl)

Get the whether a control value is enabled or disabled for button of a button matrix

参数

• obj -- pointer to a button matrix object

• btn_id -- the index of a button not counting new line characters.

• ctrl -- control values to check (ORed value can be used)

返回

true: the control attribute is enabled false: disabled

bool lv_btnmatrix_get_one_checked(const lv_obj_t *obj)

Tell whether "one check" mode is enabled or not.

参数

obj -- Button matrix object

返回

true: "one check" mode is enabled; false: disabled

Variables

const lv_obj_class_t lv_btnmatrix_class

struct lv_btnmatrix_t

Public Members

lv_obj_t obj

const char **map_p

lv_area_t *button_areas

lv_btnmatrix_ctrl_t *ctrl_bits

uint16_t btn_cnt

uint16_t row_cnt

uint16_t btn_id_sel

uint8_t one_check