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