Button Matrix

A grid of buttons defined from a single string map, emitting LV_EVENT_VALUE_CHANGED with the pressed button's index.

Button matrix per-button control flags

Apply checkable, checked, disabled, and hidden flags via ctrl_map.

Each token in ctrl_map is a |-separated list of flag names that applies to the matching button in map. The four buttons here show a plain button, a checkable button that starts checked (checkable|checked), a disabled button, and a hidden button which still reserves its slot in the layout.

lv_example_buttonmatrix_button_ctrl.c

Button matrix button widths

Set per-button relative widths through ctrl_map.

Each token in ctrl_map corresponds to one button in map (row-break tokens are skipped). Tokens like width_1..width_15 give the button a relative width that acts like CSS flex-grow within its row. Here the second row uses width_1, width_2, width_3, splitting the row into a 1/6, 2/6, 3/6 ratio.

The row break itself is written as '
' — the XML numeric character entity for a newline (U+000A) — because a raw \n inside an attribute would stay as the literal backslash-n.

lv_example_buttonmatrix_button_width.c

Button matrix value-changed event

Show which virtual button was pressed in a sibling label.

LV_EVENT_VALUE_CHANGED fires on every press. lv_buttonmatrix_get_selected_button returns the zero-based id; _get_button_text resolves it to the label string. The handler writes that string into a sibling label via lv_label_set_text_fmt.

lv_example_buttonmatrix_event.c

Button matrix map

Lay out buttons in rows using the map attribute.

The map attribute is a space-separated list of single-quoted button labels. A quoted newline token starts a new row, so the 3x3 keypad shown here is written as nine labels split by two row breaks. The newline is written as the XML entity 
 (numeric character reference for line feed, U+000A) because a raw \n inside an attribute would be kept as the literal two characters \ and n. Within a row the matrix shares the available width equally between buttons by default.

lv_example_buttonmatrix_map.c

Button matrix one-checked mode

Make the matrix behave like a radio group with a single checked button.

With one_checked="true", the buttons that carry checkable in ctrl_map form a mutually exclusive group: pressing one un-checks the previously checked button. Every weekday here is checkable, and Tue starts as checkable|checked so the example doubles as a small weekday selector.

lv_example_buttonmatrix_one_checked.c

Show a magnified label above a button while it is pressed.

The popover flag mirrors the on-screen keyboard convention: while a button is held down, its text floats up in a small popover above the finger so the user can still read what they are pressing. The entire top row carries popover in ctrl_map, which is how a keyboard layer typically enables the feature.

lv_example_buttonmatrix_popover.c

Button matrix per-button text recolor

Color parts of a button label inline with #RRGGBB ... # tags.

With the recolor flag set in ctrl_map, the same #RRGGBB ... # syntax used by lv_label recoloring becomes active in that button's map text. The three buttons share a layout but each colors a different word, so a single buttonmatrix can mix severity colors, badges, or status markers without per-button styles.

lv_example_buttonmatrix_recolor.c

Button matrix styling

Style the MAIN container, the ITEMS, and the checked-state items separately.

Button matrix has two parts: MAIN (the container) and ITEMS (each virtual button). The named styles target ITEMS in the default state and in the checked state via selector="items|checked", so the highlighted day picks up an accent fill. The container gets a flat, padded look via local style_* props on the matrix tag.

lv_example_buttonmatrix_styling.c