feat(docs): migrate from .md to .rst (#4129)
This commit is contained in:
Kevin Schlosser
147
docs/widgets/btnmatrix.rst
Normal file
147
docs/widgets/btnmatrix.rst
Normal file
@@ -0,0 +1,147 @@
|
||||
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 </widgets/btn>`__ object plus the 100 or so bytes
|
||||
for the `Label </widgets/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
|
||||
****************
|
||||
|
||||
- :cpp:enumerator:`LV_PART_MAIN` The background of the button matrix, uses the
|
||||
typical background style properties. ``pad_row`` and ``pad_column``
|
||||
sets the space between the buttons.
|
||||
- :cpp:enumerator:`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
|
||||
:cpp:expr:`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 :cpp:expr:`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`` <https://developer.mozilla.org/en-US/docs/Web/CSS/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:
|
||||
|
||||
- :cpp:enumerator:`LV_BTNMATRIX_CTRL_HIDDEN`: Makes a button hidden (hidden buttons still take up space in the layout, they are just not visible or clickable)
|
||||
- :cpp:enumerator:`LV_BTNMATRIX_CTRL_NO_REPEAT`: Disable repeating when the button is long pressed
|
||||
- :cpp:enumerator:`LV_BTNMATRIX_CTRL_DISABLED`: Makes a button disabled Like :cpp:enumerator:`LV_STATE_DISABLED` on normal objects
|
||||
- :cpp:enumerator:`LV_BTNMATRIX_CTRL_CHECKABLE`: Enable toggling of a button. I.e. :cpp:enumerator:`LV_STATE_CHECHED` will be added/removed as the button is clicked
|
||||
- :cpp:enumerator:`LV_BTNMATRIX_CTRL_CHECKED`: Make the button checked. It will use the :cpp:enumerator:`LV_STATE_CHECHKED` styles.
|
||||
- :cpp:enumerator:`LV_BTNMATRIX_CTRL_CLICK_TRIG`: Enabled: send LV_EVENT_VALUE_CHANGE on CLICK, Disabled: send :cpp:enumerator:`LV_EVENT_VALUE_CHANGE` on PRESS
|
||||
- :cpp:enumerator:`LV_BTNMATRIX_CTRL_POPOVER`: Show the button label in a popover when pressing this key
|
||||
- :cpp:enumerator:`LV_BTNMATRIX_CTRL_RECOLOR`: Enable recoloring of button texts with ``#``. E.g. ``"It's #ff0000 red#"``
|
||||
- :cpp:enumerator:`LV_BTNMATRIX_CTRL_CUSTOM_1`: Custom free to use flag
|
||||
- :cpp:enumerator:`LV_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
|
||||
:cpp:expr:`lv_btnmatrix_set_one_checked(btnm, true)` to allow only one button to
|
||||
be checked at a time.
|
||||
|
||||
Events
|
||||
******
|
||||
|
||||
- :cpp:enumerator:`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.
|
||||
- :cpp:enumerator:`LV_EVENT_DRAW_PART_BEGIN` and :cpp:enumerator:`LV_EVENT_DRAW_PART_END` are sent
|
||||
for the following types:
|
||||
|
||||
- :cpp:enumerator:`LV_BTNMATRIX_DRAW_PART_BTN` The individual buttons.
|
||||
|
||||
- ``part``: :cpp:enumerator:`LV_PART_ITEMS`
|
||||
- ``id``:index of the button being drawn
|
||||
- ``draw_area``: the area of teh button
|
||||
- ``rect_dsc``
|
||||
|
||||
See the events of the `Base object </widgets/obj>`__ too.
|
||||
|
||||
:cpp:expr:`lv_btnmatrix_get_selected_btn(btnm)` returns the index of the most
|
||||
recently released or focused button or :cpp:enumerator:`LV_BTNMATRIX_BTN_NONE` if no
|
||||
such button.
|
||||
|
||||
:cpp:expr:`lv_btnmatrix_get_btn_text(btnm, btn_id)` returns a pointer to the
|
||||
text of ``btn_id``\ th button.
|
||||
|
||||
Learn more about :ref:`events`.
|
||||
|
||||
Keys
|
||||
****
|
||||
|
||||
- ``LV_KEY_RIGHT/UP/LEFT/RIGHT`` To navigate among the buttons to
|
||||
select one
|
||||
- :cpp:enumerator:`LV_KEY_ENTER` To press/release the selected button
|
||||
|
||||
Note that long pressing the button matrix with an encoder can mean to
|
||||
enter/leave edit mode and simply long pressing a button to make it
|
||||
repeat as well. To avoid this contradiction it’s suggested to add
|
||||
:cpp:expr:`lv_btnmatrix_set_btn_ctrl_all(btnm, LV_BTNMATRIX_CTRL_CLICK_TRIG | LV_BTNMATRIX_CTRL_NO_REPEAT)`
|
||||
to the button matrix if used with encoder. This way, the pressed button
|
||||
repeat feature is disabled and on leaving edit mode the selected button
|
||||
won’t be activated.
|
||||
|
||||
Learn more about :ref:`indev_keys`.
|
||||
|
||||
Example
|
||||
*******
|
||||
|
||||
.. include:: ../examples/widgets/btnmatrix/index.rst
|
||||
|
||||
API
|
||||
***
|
||||
Reference in New Issue
Block a user