# Button Matrix (/examples/widgets/buttonmatrix)



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 [#button-matrix-per-button-control-flags]

<LvglExampleBrief>
  Apply checkable, checked, disabled, and hidden flags via 

  `ctrl_map`

  .
</LvglExampleBrief>

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.

<LvglExample name="lv_example_buttonmatrix_button_ctrl" path="widgets/buttonmatrix/lv_example_buttonmatrix_button_ctrl" />

Button matrix button widths [#button-matrix-button-widths]

<LvglExampleBrief>
  Set per-button relative widths through 

  `ctrl_map`

  .
</LvglExampleBrief>

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 `'&#10;'` — the XML numeric character entity
for a newline (U+000A) — because a raw `\n` inside an attribute would stay as
the literal backslash-n.

<LvglExample name="lv_example_buttonmatrix_button_width" path="widgets/buttonmatrix/lv_example_buttonmatrix_button_width" />

Button matrix value-changed event [#button-matrix-value-changed-event]

<LvglExampleBrief>
  Show which virtual button was pressed in a sibling label.
</LvglExampleBrief>

`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`.

<LvglExample name="lv_example_buttonmatrix_event" path="widgets/buttonmatrix/lv_example_buttonmatrix_event" />

Button matrix map [#button-matrix-map]

<LvglExampleBrief>
  Lay out buttons in rows using the 

  `map`

   attribute.
</LvglExampleBrief>

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
`&#10;` (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.

<LvglExample name="lv_example_buttonmatrix_map" path="widgets/buttonmatrix/lv_example_buttonmatrix_map" />

Button matrix one-checked mode [#button-matrix-one-checked-mode]

<LvglExampleBrief>
  Make the matrix behave like a radio group with a single checked button.
</LvglExampleBrief>

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.

<LvglExample name="lv_example_buttonmatrix_one_checked" path="widgets/buttonmatrix/lv_example_buttonmatrix_one_checked" />

Button matrix popover preview [#button-matrix-popover-preview]

<LvglExampleBrief>
  Show a magnified label above a button while it is pressed.
</LvglExampleBrief>

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.

<LvglExample name="lv_example_buttonmatrix_popover" path="widgets/buttonmatrix/lv_example_buttonmatrix_popover" />

Button matrix per-button text recolor [#button-matrix-per-button-text-recolor]

<LvglExampleBrief>
  Color parts of a button label inline with 

  `#RRGGBB ... #`

   tags.
</LvglExampleBrief>

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.

<LvglExample name="lv_example_buttonmatrix_recolor" path="widgets/buttonmatrix/lv_example_buttonmatrix_recolor" />

Button matrix styling [#button-matrix-styling]

<LvglExampleBrief>
  Style the MAIN container, the ITEMS, and the checked-state items separately.
</LvglExampleBrief>

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.

<LvglExample name="lv_example_buttonmatrix_styling" path="widgets/buttonmatrix/lv_example_buttonmatrix_styling" />