Button Matrix (lv_buttonmatrix)

Overview

The Button Matrix Widget 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. With Button Matrix, each button uses only eight extra bytes of memory instead of the ~100-150 bytes a normal Button Widget plus the 100 or so bytes for the Label Widget.

New Button Matrix Widgets are added to the default group (if one is set). Additionally, Button Matrix is an editable Widget: it allows selecting and clicking the buttons with encoder and keyboard navigation as well.

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.

Usage

Button map

The number of buttons, their positions and text are controlled by a descriptor string array, called a map, passed to lv_buttonmatrix_set_map(btn_matrix, my_map). The declaration of a map should look like const char * map[] = {"button1", "button2", "button3", NULL}. Note that the last element must be either NULL or an empty string ("")!

Use "\n" in the map to insert a line break. E.g. {"button1", "button2", "\n", "button3", ""}. 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.

The number of buttons neither includes the newline elements nor the terminating element of the array.

Button widths

The buttons' width can be set in proportion to the width of other buttons in the same row with lv_buttonmatrix_set_button_width(btn_matrix, button_id, width) E.g. in a line with two buttons: buttonA, width = 1 and buttonB, width = 2, buttonA will have 33 % width and buttonB will have 66 % width. This is similar to how the "flex-grow" property works in CSS. The width must be in the range [1..15] with the default being 1.

Button behavior

Each button's behavior can be customized with the following control flags:

LV_BUTTONMATRIX_CTRL_HIDDEN: Hides button; it continues to hold its space in layout.
LV_BUTTONMATRIX_CTRL_NO_REPEAT: Do not emit LV_EVENT_LONG_PRESSED_REPEAT events while button is long-pressed.
LV_BUTTONMATRIX_CTRL_DISABLED: Disables button like LV_STATE_DISABLED on normal Widgets.
LV_BUTTONMATRIX_CTRL_CHECKABLE: Enable toggling of LV_STATE_CHECKED when clicked.
LV_BUTTONMATRIX_CTRL_CHECKED: Make the button checked. It will use the LV_STATE_CHECKED styles.
LV_BUTTONMATRIX_CTRL_CLICK_TRIG: 1: Enables sending LV_EVENT_VALUE_CHANGED on CLICK, 0: sends LV_EVENT_VALUE_CHANGED on PRESS.
LV_BUTTONMATRIX_CTRL_POPOVER: Show button text in a pop-over while being pressed.
LV_BUTTONMATRIX_CTRL_RECOLOR: Enable text recoloring with #color
LV_BUTTONMATRIX_CTRL_CUSTOM_1: Custom free-to-use flag
LV_BUTTONMATRIX_CTRL_CUSTOM_2: Custom free-to-use flag

By default, these flags are disabled.

To set and clear a button's control flags, use

respectively. button_id is a zero-based button index (0 = first button). LV_BUTTONMATRIX_CTRL_... values can be bit-wise OR-ed together when passed to these functions.

To set and clear the same control attribute for all buttons in a Button Matrix, use

respectively.

To set a control map for a Button Matrix (similar to Button map), use

lv_buttonmatrix_set_ctrl_map(btn_matrix, ctrl_map).

An element of ctrl_map should look like ctrl_map[0] = width | LV_BUTTONMATRIX_CTRL_NO_REPEAT | LV_BUTTONMATRIX_CTRL_CHECKABLE. The number of elements must be equal to the number of buttons.

One checked

The "One-checked" feature can be enabled with lv_buttonmatrix_set_one_checked(btn_matrix, true) to allow only one button to be checked at a time.

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_buttonmatrix_get_selected_button(btn_matrix) returns the index of the button most recently released (the button with focus) or LV_BUTTONMATRIX_BUTTON_NONE if no such button was found.

lv_buttonmatrix_get_button_text(btn_matrix, button_id) returns a pointer to the text of the button specified by zero-based index button_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

Note that long pressing the Button Matrix with an encoder can mean to enter/leave edit mode and simply long pressing a button to make it repeat as well. To avoid this contradiction, add

lv_buttonmatrix_set_button_ctrl_all(btn_matrix, LV_BUTTONMATRIX_CTRL_CLICK_TRIG | LV_BUTTONMATRIX_CTRL_NO_REPEAT)

to the Button Matrix if used with an encoder. This disables the repeat feature so the button will not be activated upon leaving edit mode.