5.2 KiB
Button matrix (lv_btnmatrix)
Overview
The Button Matrix object is a lightweight way to display multiple buttons in rows and columns. Lightweight because the buttons are not actually created but just virtually drawn on the fly. This way, one button use only eight extra bytes of memory instead of the ~100-150 bytes a normal Button object plus the 100 or so bytes for the Label object.
The Button matrix is added to the default group (if one is set). Besides the Button matrix is an editable object to allow selecting and clicking the buttons with encoder navigation too.
Parts and Styles
LV_PART_MAIN
The background of the button matrix, uses the typical background style properties.pad_row
andpad_column
sets the space between the buttons.LV_PART_ITEMS
The buttons all use the text and typical background style properties except 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 either NULL
or an empty string (""
)!
Use "\n"
in the map to insert a 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 must be in the [1..15] range and the default 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 pressedLV_BTNMATRIX_CTRL_DISABLED
Makes a button disabled LikeLV_STATE_DISABLED
on normal objectsLV_BTNMATRIX_CTRL_CHECKABLE
Enable toggling of a button. I.e.LV_STATE_CHECHED
will be added/removed as the button is clickedLV_BTNMATRIX_CTRL_CHECKED
Make the button checked. It will use theLV_STATE_CHECHKED
styles.LV_BTNMATRIX_CTRL_CLICK_TRIG
Enabled: send LV_EVENT_VALUE_CHANGE on CLICK, Disabled: send LV_EVENT_VALUE_CHANGE on PRESSLV_BTNMATRIX_CTRL_POPOVER
Show the button label in a popover when pressing this keyLV_BTNMATRIX_CTRL_RECOLOR
Enable recoloring of button texts with#
. E.g."It's #ff0000 red#"
LV_BTNMATRIX_CTRL_CUSTOM_1
Custom free to use flagLV_BTNMATRIX_CTRL_CUSTOM_2
Custom free to use flag
By default, 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, LV_BTNM_CTRL_...)
and
lv_btnmatrix_clear_btn_ctrl_all(btnm, 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_checked(btnm, true)
to allow only one button to be checked at a time.
Events
LV_EVENT_VALUE_CHANGED
Sent when a button is pressed/released or repeated after long press. The event parameter is set to the ID of the pressed/released button.LV_EVENT_DRAW_PART_BEGIN
andLV_EVENT_DRAW_PART_END
are sent for the following types:LV_BTNMATRIX_DRAW_PART_BTN
The individual buttons.part
:LV_PART_ITEMS
id
:index of the button being drawndraw_area
: the area of teh buttonrect_dsc
See the events of the Base object too.
lv_btnmatrix_get_selected_btn(btnm)
returns the index of the most recently 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_id
th button.
Learn more about Events.
Keys
LV_KEY_RIGHT/UP/LEFT/RIGHT
To navigate among the buttons to select oneLV_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