The Button Matrix objects can display multiple buttons according to a descriptor string array, called map. You can specify the map with lv_btnm_set_map(btnm, my_map).

The declaration of a map looks like const char * map[] = {"btn1", "btn2", "btn3", ""}. Note that the last element has to be an empty string!

The first character of a string can be a control character to specify some attributes:

  • bit 7..6 Button relative width in the row (1..7)
  • bit 5 Inactive button
  • bit 4 Hidden button
  • bit 3 No long press for the button
  • bit 2..0 relative width compared to the buttons in the same row.

It is recommended to specify the control byte as an octal number. For example "\213button". The octal number always starts with 2 (bit 7..6) the middle part is the attributes (bit 5..3) and the last part is the width (bit 2..0). So the example describes a 3 unit wide, hidden button.

Use "\n" in the map to make line break: {"btn1", "btn2", "\n", "btn3", ""}. The button's width is recalculated in every line.

The lv_btnm_set_action(btnm, btnm_action) specifies an action to call when a button is released.

You can enable the buttons to toggle when they are clicked. There can be oly one toggled button an the same time. The lv_btnm_set_toggle(btnm, true, id) enables the toggling and makes the idth button to toggled.

Style usage

The Button matrix works with 6 styles: a background and 5 button styles for each states. You can set the styles with lv_btnm_set_style(btn, LV_BTNM_STYLE_..., &style). The background and the buttons use the style.body properties. The labels use the style.text properties of the button styles.

  • LV_BTNM_STYLE_BG Background style. Uses all style.body properties including padding Default: lv_style_pretty
  • LV_BTNM_STYLE_BTN_REL style of the released buttons. Default: lv_style_btn_rel
  • LV_BTNM_STYLE_BTN_PR style of the pressed buttons. Default: lv_style_btn_pr
  • LV_BTNM_STYLE_BTN_TGL_REL style of the toggled released buttons. Default: lv_style_btn_tgl_rel
  • LV_BTNM_STYLE_BTN_TGL_PR style of the toggled pressed buttons. Default: lv_style_btn_tgl_pr
  • LV_BTNM_STYLE_BTN_INA style of the inactive buttons. Default: lv_style_btn_ina


  • The Button matrix object is very light weighted. It creates only the Background Base object and draws the buttons on it instead of creating a lot of real button.
Example of Button matrix in Littlev Graphics Library

						/*Called when a button is released ot long pressed*/
static lv_res_t btnm_action(lv_obj_t * btnm, const char *txt)
    printf("Button: %s released\n", txt);

    return LV_RES_OK; /*Return OK because the button matrix is not deleted*/


/*Create a button descriptor string array*/
static const char * btnm_map[] = {"1", "2", "3", "4", "5", "\n",
                           "6", "7", "8", "9", "0", "\n",
                           "\202Action1", "Action2", ""};

/*Create a default button matrix*/
lv_obj_t * btnm1 = lv_btnm_create(lv_scr_act(), NULL);
lv_btnm_set_map(btnm1, btnm_map);
lv_btnm_set_action(btnm1, btnm_action);
lv_obj_set_size(btnm1, LV_HOR_RES, LV_VER_RES / 2);

/*Create a new style for the button matrix back ground*/
static lv_style_t style_bg;
lv_style_copy(&style_bg, &lv_style_plain);
style_bg.body.main_color = LV_COLOR_SILVER;
style_bg.body.grad_color = LV_COLOR_SILVER;
style_bg.body.padding.hor = 0;
style_bg.body.padding.ver = 0;
style_bg.body.padding.inner = 0;

/*Create 2 button styles*/
static lv_style_t style_btn_rel;
static lv_style_t style_btn_pr;
lv_style_copy(&style_btn_rel, &lv_style_btn_rel);
style_btn_rel.body.main_color = LV_COLOR_MAKE(0x30, 0x30, 0x30);
style_btn_rel.body.grad_color = LV_COLOR_BLACK;
style_btn_rel.body.border.color = LV_COLOR_SILVER;
style_btn_rel.body.border.width = 1;
style_btn_rel.body.border.opa = LV_OPA_50;
style_btn_rel.body.radius = 0;

lv_style_copy(&style_btn_pr, &style_btn_rel);
style_btn_pr.body.main_color = LV_COLOR_MAKE(0x55, 0x96, 0xd8);
style_btn_pr.body.grad_color = LV_COLOR_MAKE(0x37, 0x62, 0x90);
style_btn_pr.text.color = LV_COLOR_MAKE(0xbb, 0xd5, 0xf1);

/*Create a second button matrix with the new styles*/
lv_obj_t * btnm2 = lv_btnm_create(lv_scr_act(), btnm1);
lv_btnm_set_style(btnm2, LV_BTNM_STYLE_BG, &style_bg);
lv_btnm_set_style(btnm2, LV_BTNM_STYLE_BTN_REL, &style_btn_rel);
lv_btnm_set_style(btnm2, LV_BTNM_STYLE_BTN_PR, &style_btn_pr);
lv_obj_align(btnm2, btnm1, LV_ALIGN_OUT_BOTTOM_MID, 0, 0);

lv_obj_t *


(lv_obj_t * par, lv_obj_t * copy);

Create a button matrix objects

par pointer to an object, it will be the parent of the new button matrix

copy pointer to a button matrix object, if not NULL then the new object will be copied from it

return pointer to the created button matrix



(lv_obj_t * btnm, const char ** map);

Set a new map. Buttons will be created/deleted according to the map.

btnm pointer to a button matrix object

map pointer a string array. The last string has to be: "".
Use "\n" to begin a new line.
The first byte can be a control data:
- bit 7: always 1
- bit 6: always 0
- bit 5: inactive (disabled)
- bit 4: no repeat (on long press)
- bit 3: hidden
- bit 2..0: button relative width
Example (practically use octal numbers): "\224abc": "abc" text with 4 width and no long press



(lv_obj_t * btnm, lv_btnm_action_t action);

Set a new callback function for the buttons (It will be called when a button is released)

btnm: pointer to button matrix object

action pointer to a callback function



(lv_obj_t * btnm, bool en, uint16_t id);

Enable or disable button toggling

btnm pointer to button matrix object

en true: enable toggling; false: disable toggling

id index of the currently toggled button (ignored if 'en' == false)



(lv_obj_t *btnm, lv_btnm_style_t type, lv_style_t *style);

Set a style of a button matrix

btnm pointer to a button matrix object

type which style should be set

style pointer to a style



** lv_btnm_get_map(lv_obj_t * btnm);

Get the current map of a button matrix

btnm pointer to a button matrix object

return the current map



(lv_obj_t * btnm);

Get a the callback function of the buttons on a button matrix

btnm: pointer to button matrix object

return pointer to the callback function



(lv_obj_t * btnm);

Get the toggled button

btnm pointer to button matrix object

return index of the currently toggled button (0: if unset)

lv_style_t *


(lv_obj_t *btnm, lv_btnm_style_t type);

Get a style of a button matrix

btnm pointer to a button matrix object

type which style should be get

return style pointer to a style

LittlevGL - Open-source Embedded GUI Library

LittlevGL is a free and open-source graphics library providing everything you need to create embedded GUI with easy-to-use graphical elements, beautiful visual effects and low memory footprint.

If you like LittlevGL, please
support its deveopment!

The founder of Littlev Graphics Library (LittlevGL) and related software modules is:
Gábor Kiss-Vámosi
All Rights Reserved ©  2018 Hungary