⌨️ Button Matrix

The Button Matrix widget (btnmatrix) is a highly memory-efficient way to create a grid of buttons. Instead of creating dozens of individual button widgets, the Matrix manages a single object that handles multiple interactive areas—perfect for numpads, calculators, or keyboard layouts.

---

⚙️ Properties (Props)

The Button Matrix configuration is defined by the ButtonMatrixWidget interface. It uses array-based logic to define the grid and visual weighting.

Property	Type	Description
Buttons	string[]	An array of labels for the buttons. Use "\n" as an element to force a new row.
Button Weights	number[]	(Optional) An array of relative widths for each button. A weight of 2 makes a button twice as wide as a weight of 1.
Selected	number	The index of the currently active or toggled button.

---

🛠 Grid Configuration

The layout of the matrix is determined strictly by your button array. For example, to create a 3x2 grid:

Button Map: ["A", "B", "C", "\n", "D", "E", "F"]

• Row Breaks: The \n string acts as a "new line" command for the engine.
• Relative Widths: If your buttonWeights array is [1, 1, 1, 2, 1, 1], the "D" button will take up twice as much horizontal space as the others in its row.

---

🎨 Visual States

You can style the entire matrix in the Inspector Panel.

• Main Background: Styles the container holding all buttons.
• Items: Styles the individual buttons. You can apply corner radii, gradients, and border styles that apply to all buttons in the matrix simultaneously for a consistent look.

---

⚡ Runtime API (Lua)

The Button Matrix simplifies event handling by using a single callback that identifies which button index was pressed.

-- Get the text of the button currently pressed
local index = matrix_numpad:get_selected_btn()
local label = matrix_numpad:get_btn_text(index)

-- Check if the "Enter" key (index 11) was pressed
if index == 11 then
    app:process_input()
end

-- Dynamically change the weights to highlight a row
matrix_numpad:set_btn_width(0, 2) -- Make the first button wider

---

PRO TIP

Use the Button Matrix for any UI element that requires more than 4 buttons in a row or column. It drastically reduces the memory footprint and simplifies the Widget Tree.

---

🚀 Next Steps

• Button — Use for single, standalone action triggers.
• Keyboard — A specialized version of the Matrix designed for text input.
• Logic and Events — Learn how to handle matrix click indices.