acid-drop

- Hacking the planet from a LilyGo T-Deck using custom firmware
git clone git://git.acid.vegas/acid-drop.git
btnmatrix.md (5372B)
      1 ```eval_rst
      2 .. include:: /header.rst
      3 :github_url: |github_link_base|/widgets/core/btnmatrix.md
      4 ```
      5 # Button matrix (lv_btnmatrix)
      6 
      7 ## Overview
      8 
      9 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/core/btn) object plus the 100 or so bytes for the [Label](/widgets/core/label) object.
     10 
     11 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.
     12 
     13 ## Parts and Styles
     14 - `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.
     15 - `LV_PART_ITEMS` The buttons all use the text and typical background style properties except translations and transformations.
     16 
     17 ## Usage
     18 
     19 ### Button's text
     20 There is a text on each button. To specify them a descriptor string array, called *map*, needs to be used.
     21 The map can be set with `lv_btnmatrix_set_map(btnm, my_map)`.
     22 The declaration of a map should look like `const char * map[] = {"btn1", "btn2", "btn3", NULL}`.
     23 Note that the last element has to be either `NULL` or an empty string (`""`)!
     24 
     25 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.
     26 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.
     27 
     28 ### Control buttons
     29 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)`
     30 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.
     31 It's similar to how the [`flex-grow`](https://developer.mozilla.org/en-US/docs/Web/CSS/flex-grow) property works in CSS.
     32 The width must be in the \[1..7\] range and the default width is 1.
     33 
     34 In addition to the width, each button can be customized with the following parameters:
     35 - `LV_BTNMATRIX_CTRL_HIDDEN` Makes a button hidden (hidden buttons still take up space in the layout, they are just not visible or clickable)
     36 - `LV_BTNMATRIX_CTRL_NO_REPEAT` Disable repeating when the button is long pressed
     37 - `LV_BTNMATRIX_CTRL_DISABLED` Makes a button disabled Like `LV_STATE_DISABLED` on normal objects
     38 - `LV_BTNMATRIX_CTRL_CHECKABLE` Enable toggling of a button. I.e. `LV_STATE_CHECHED` will be added/removed as the button is clicked
     39 - `LV_BTNMATRIX_CTRL_CHECKED` Make the button checked. It will use the `LV_STATE_CHECHKED` styles.
     40 - `LV_BTNMATRIX_CTRL_CLICK_TRIG` Enabled: send LV_EVENT_VALUE_CHANGE on CLICK, Disabled: send LV_EVENT_VALUE_CHANGE on PRESS
     41 - `LV_BTNMATRIX_CTRL_POPOVER` Show the button label in a popover when pressing this key
     42 - `LV_BTNMATRIX_CTRL_RECOLOR` Enable recoloring of button texts with `#`. E.g. `"It's #ff0000 red#"`
     43 - `LV_BTNMATRIX_CTRL_CUSTOM_1` Custom free to use flag
     44 - `LV_BTNMATRIX_CTRL_CUSTOM_2` Custom free to use flag
     45 
     46 By default, all flags are disabled.
     47 
     48 To set or clear a button's control attribute, use `lv_btnmatrix_set_btn_ctrl(btnm, btn_id, LV_BTNM_CTRL_...)` and
     49 `lv_btnmatrix_clear_btn_ctrl(btnm, btn_id, LV_BTNMATRIX_CTRL_...)` respectively. More `LV_BTNM_CTRL_...` values can be OR-ed
     50 
     51 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
     52 `lv_btnmatrix_clear_btn_ctrl_all(btnm, LV_BTNMATRIX_CTRL_...)`.
     53 
     54 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)`.
     55 An element of `ctrl_map` should look like `ctrl_map[0] = width | LV_BTNM_CTRL_NO_REPEAT |  LV_BTNM_CTRL_CHECHKABLE`.
     56 The number of elements should be equal to the number of buttons (excluding newlines characters).
     57 
     58 ### One check
     59 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.
     60 
     61 ## Events
     62 - `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.
     63 - `LV_EVENT_DRAW_PART_BEGIN` and `LV_EVENT_DRAW_PART_END` are sent for the following types:
     64     - `LV_BTNMATRIX_DRAW_PART_BTN` The individual buttons.
     65         - `part`: `LV_PART_ITEMS`
     66         - `id`:index of the button being drawn
     67         - `draw_area`: the area of teh button
     68         - `rect_dsc`
     69 
     70 See the events of the [Base object](/widgets/obj) too.
     71 
     72 `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.
     73 
     74 `lv_btnmatrix_get_btn_text(btnm, btn_id)` returns a pointer to the text of `btn_id`th button.
     75 
     76 Learn more about [Events](/overview/event).
     77 
     78 ## Keys
     79 - `LV_KEY_RIGHT/UP/LEFT/RIGHT` To navigate among the buttons to select one
     80 - `LV_KEY_ENTER` To press/release the selected button
     81 
     82 Learn more about [Keys](/overview/indev).
     83 
     84 ## Example
     85 
     86 ```eval_rst
     87 
     88 .. include:: ../../../examples/widgets/btnmatrix/index.rst
     89 
     90 ```
     91 
     92 ## API
     93 
     94 ```eval_rst
     95 
     96 .. doxygenfile:: lv_btnmatrix.h
     97   :project: lvgl
     98 
     99 ```