lvgl/docs/widgets/core/btnmatrix.md

.. include:: /header.rst 
:github_url: |github_link_base|/widgets/btnmatrix.md

Button matrix (lv_btnmatrix)

Overview

The Button Matrix objects can display multiple buttons in rows and columns.

The Button matrix object is very light weighted because the buttons are not created just virtually drawn on the fly. This way, 1 button use only 8 extra bytes instead of the ~100-150 byte size of a normal Button object and other ~100 byte for the size of the Label object.

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

Parts and Styles

• LV_PART_MAIN The bacground of the button matrix. It uses the typical background style properties. pad_row and pad_column sets the space between the buttons.
• LV_PART_ITEMS The buttons and they all use the text and typical background style properties expect translations and transformations.

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 NULL or an empty string ("")!

Use "\n" in the map to make 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.

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's value mus be in the [1..7] range and the deafult 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 deafult all flags are disabled.

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

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

Events

• LV_EVENT_VALUE_CHANGED Sent when a button is pressed/released or repeated after long press. The event paramter is set to the ID of the pressed/released button.
• LV_EVENT_DRAW_PART_BEGIN and LV_EVENT_DRAW_PART_END are sent for both the main and the items (buttons) parts to allow hooking the drawing. The for more detail on the main part see the Base object's documentation. For the buttons the following fields are used: clip_area, draw_area, rect_dsc, rect_dsc, part, id (index of the button being drawn).

lv_btnmatrix_get_selected_btn(btnm) returns the index of the lastly pressed, 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.

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.

Example

.. include:: ../../../examples/widgets/btnmatrix/index.rst

API

.. doxygenfile:: lv_btnmatrix.h
  :project: lvgl