1.. _lv_buttonmatrix:
2
3===============================
4Button Matrix (lv_buttonmatrix)
5===============================
6
7
8Overview
9********
10
11The Button Matrix Widget is a lightweight way to display multiple
12Buttons in rows and columns --- lightweight because the buttons are not
13actually created but just virtually drawn on the fly.  With Button Matrix,
14each button uses only eight extra bytes of memory instead of the ~100-150
15bytes a normal :ref:`Button <lv_button>` Widget plus the 100 or so bytes
16for the :ref:`Label <lv_label>` Widget.
17
18New Button Matrix Widgets are added to the default group (if one is set).
19Additionally, Button Matrix is an editable Widget:  it allows selecting and clicking
20the buttons with encoder and keyboard navigation as well.
21
22
23.. _lv_buttonmatrix_parts_and_styles:
24
25Parts and Styles
26****************
27
28-  :cpp:enumerator:`LV_PART_MAIN` The background of the Button Matrix, uses the
29   typical background style properties. ``pad_row`` and ``pad_column``
30   sets the space between the buttons.
31-  :cpp:enumerator:`LV_PART_ITEMS` The buttons all use the text and typical background
32   style properties except translations and transformations.
33
34
35.. _lv_buttonmatrix_usage:
36
37Usage
38*****
39
40.. _button map:
41
42Button map
43-----------
44
45The number of buttons, their positions and text are controlled by a descriptor string
46array, called a *map*, passed to
47:cpp:expr:`lv_buttonmatrix_set_map(btn_matrix, my_map)`. The declaration of a map should
48look like ``const char * map[] = {"button1", "button2", "button3", NULL}``. Note
49that the last element must be either ``NULL`` or an empty string
50(``""``)!
51
52Use ``"\n"`` in the map to insert a **line break**. E.g.
53``{"button1", "button2", "\n", "button3", ""}``. Each line's buttons have their
54width calculated automatically. So in the example the first row will
55have 2 buttons each with 50% width and a second row with 1 button having
56100% width.
57
58.. note::
59    The number of buttons neither includes the newline elements nor the terminating
60    element of the array.
61
62Button widths
63-------------
64
65The buttons' width can be set in proportion to the width of other buttons in the same
66row with :cpp:expr:`lv_buttonmatrix_set_button_width(btn_matrix, button_id, width)` E.g. in a
67line with two buttons: *buttonA, width = 1* and *buttonB, width = 2*, *buttonA*
68will have 33 % width and *buttonB* will have 66 % width.  This is similar to how the
69`"flex-grow" <https://developer.mozilla.org/en-US/docs/Web/CSS/flex-grow>`__
70property works in CSS. The width must be in the range [1..15] with the default being 1.
71
72Button behavior
73---------------
74
75Each button's behavior can be customized with the following control flags:
76
77- :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_HIDDEN`: Hides button; it continues to hold its space in layout.
78- :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_NO_REPEAT`: Do not emit :cpp:enumerator:`LV_EVENT_LONG_PRESSED_REPEAT` events while button is long-pressed.
79- :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_DISABLED`: Disables button like :cpp:enumerator:`LV_STATE_DISABLED` on normal Widgets.
80- :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_CHECKABLE`: Enable toggling of :cpp:enumerator:`LV_STATE_CHECKED` when clicked.
81- :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_CHECKED`: Make the button checked. It will use the :cpp:enumerator:`LV_STATE_CHECHKED` styles.
82- :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_CLICK_TRIG`: 1: Enables sending :cpp:enumerator:`LV_EVENT_VALUE_CHANGE` on ``CLICK``, 0: sends :cpp:enumerator:`LV_EVENT_VALUE_CHANGE` on ``PRESS``.
83- :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_POPOVER`: Show button text in a pop-over while being pressed.
84- :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_RECOLOR`: Enable text recoloring with ``#color``
85- :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_CUSTOM_1`: Custom free-to-use flag
86- :cpp:enumerator:`LV_BUTTONMATRIX_CTRL_CUSTOM_2`: Custom free-to-use flag
87
88By default, these flags are disabled.
89
90To set and clear a button's control flags, use
91
92- :cpp:expr:`lv_buttonmatrix_set_button_ctrl(btn_matrix, button_id, LV_BUTTONMATRIX_CTRL_...)` and
93- :cpp:expr:`lv_buttonmatrix_clear_button_ctrl(btn_matrix, button_id, LV_BUTTONMATRIX_CTRL_...)`
94
95respectively.  ``button_id`` is a zero-based button index (0 = first button).
96``LV_BUTTONMATRIX_CTRL_...`` values can be bit-wise OR-ed together when passed to
97these functions.
98
99To set and clear the same control attribute for all buttons in a Button Matrix, use
100
101- :cpp:expr:`lv_buttonmatrix_set_button_ctrl_all(btn_matrix, LV_BUTTONMATRIX_CTRL_...)` and
102- :cpp:expr:`lv_buttonmatrix_clear_button_ctrl_all(btn_matrix, LV_BUTTONMATRIX_CTRL_...)`
103
104respectively.
105
106To set a control map for a Button Matrix (similar to `Button map`_), use
107
108- :cpp:expr:`lv_buttonmatrix_set_ctrl_map(btn_matrix, ctrl_map)`.
109
110An element of ``ctrl_map`` should look like
111:cpp:expr:`ctrl_map[0] = width | LV_BUTTONMATRIX_CTRL_NO_REPEAT |  LV_BUTTONMATRIX_CTRL_CHECHKABLE`.
112The number of elements must be equal to the number of buttons.
113
114One checked
115-----------
116
117The "One-checked" feature can be enabled with
118:cpp:expr:`lv_buttonmatrix_set_one_checked(btn_matrix, true)` to allow only one button to
119be checked at a time.
120
121
122
123.. _lv_buttonmatrix_events:
124
125Events
126******
127
128-  :cpp:enumerator:`LV_EVENT_VALUE_CHANGED`: Sent when a button is pressed/released or
129   repeated after long press. The event parameter is set to the ID of
130   the pressed/released button.
131
132:cpp:expr:`lv_buttonmatrix_get_selected_button(btn_matrix)` returns the index of the button
133most recently released (the button with focus) or :cpp:enumerator:`LV_BUTTONMATRIX_BUTTON_NONE`
134if no such button was found.
135
136:cpp:expr:`lv_buttonmatrix_get_button_text(btn_matrix, button_id)` returns a pointer
137to the text of the button specified by zero-based index ``button_id``.
138
139.. admonition::  Further Reading
140
141    Learn more about :ref:`lv_obj_events` emitted by all Widgets.
142
143    Learn more about :ref:`events`.
144
145
146
147.. _lv_buttonmatrix_keys:
148
149Keys
150****
151
152-  ``LV_KEY_RIGHT/UP/LEFT/RIGHT`` To navigate among the buttons to
153   select one
154-  :cpp:enumerator:`LV_KEY_ENTER` To press/release the selected button
155
156Note that long pressing the Button Matrix with an encoder can mean to
157enter/leave edit mode and simply long pressing a button to make it
158repeat as well. To avoid this contradiction, add
159:cpp:expr:`lv_buttonmatrix_set_button_ctrl_all(btn_matrix, LV_BUTTONMATRIX_CTRL_CLICK_TRIG | LV_BUTTONMATRIX_CTRL_NO_REPEAT)`
160to the Button Matrix if used with an encoder.  This disables the repeat feature so
161the button will not be activated upon leaving edit mode.
162
163.. admonition::  Further Reading
164
165    Learn more about :ref:`indev_keys`.
166
167
168
169.. _lv_buttonmatrix_example:
170
171Example
172*******
173
174.. include:: ../../examples/widgets/buttonmatrix/index.rst
175
176
177
178.. _lv_buttonmatrix_api:
179
180API
181***
182