acid-drop

- Hacking the planet from a LilyGo T-Deck using custom firmware
git clone git://git.acid.vegas/acid-drop.git
grid.md (4724B)
      1 ```eval_rst
      2 .. include:: /header.rst
      3 :github_url: |github_link_base|/layouts/grid.md
      4 ```
      5 
      6 # Grid
      7 
      8 ## Overview
      9 
     10 The Grid layout is a subset of [CSS Flexbox](https://css-tricks.com/snippets/css/complete-guide-grid/).
     11 
     12 It can arrange items into a 2D "table" that has rows or columns (tracks). The item can span through multiple columns or rows.
     13 The track's size can be set in pixel, to the largest item (`LV_GRID_CONTENT`) or in "Free unit" (FR) to distribute the free space proportionally.
     14 
     15 To make an object a grid container call `lv_obj_set_layout(obj, LV_LAYOUT_GRID)`.
     16 
     17 Note that the grid layout feature of LVGL needs to be globally enabled with `LV_USE_GRID` in `lv_conf.h`.
     18 
     19 ## Terms
     20 - tracks: the rows or columns
     21 - free unit (FR): if set on track's size is set in `FR` it will grow to fill the remaining space on the parent.
     22 - gap: the space between the rows and columns or the items on a track
     23 
     24 ## Simple interface
     25 
     26 With the following functions you can easily set a Grid layout on any parent.
     27 
     28 ### Grid descriptors
     29 
     30 First you need to describe the size of rows and columns. It can be done by declaring 2 arrays and the track sizes in them. The last element must be `LV_GRID_TEMPLATE_LAST`.
     31 
     32 For example:
     33 ```
     34 static lv_coord_t column_dsc[] = {100, 400, LV_GRID_TEMPLATE_LAST};   /*2 columns with 100 and 400 ps width*/
     35 static lv_coord_t row_dsc[] = {100, 100, 100, LV_GRID_TEMPLATE_LAST}; /*3 100 px tall rows*/
     36 ```
     37 
     38 To set the descriptors on a parent use `lv_obj_set_grid_dsc_array(obj, col_dsc, row_dsc)`.
     39 
     40 Besides simple settings the size in pixel you can use two special values:
     41 - `LV_GRID_CONTENT` set the width to the largest children on this track
     42 - `LV_GRID_FR(X)` tell what portion of the remaining space should be used by this track. Larger value means larger space.
     43 
     44 ### Grid items
     45 By default, the children are not added to the grid. They need to be added manually to a cell.
     46 
     47 To do this call `lv_obj_set_grid_cell(child, column_align, column_pos, column_span, row_align, row_pos, row_span)`.
     48 
     49 `column_align` and `row_align` determine how to align the children in its cell. The possible values are:
     50 - `LV_GRID_ALIGN_START` means left on a horizontally and top vertically. (default)
     51 - `LV_GRID_ALIGN_END` means right on a horizontally and bottom vertically
     52 - `LV_GRID_ALIGN_CENTER` simply center
     53 
     54 `colum_pos` and `row_pos` means the zero based index of the cell into the item should be placed.
     55 
     56 `colum_span` and `row_span` means how many tracks should the item involve from the start cell. Must be &gt; 1.
     57 
     58 ### Grid align
     59 
     60 If there are some empty space the track can be aligned several ways:
     61 - `LV_GRID_ALIGN_START` means left on a horizontally and top vertically. (default)
     62 - `LV_GRID_ALIGN_END` means right on a horizontally and bottom vertically
     63 - `LV_GRID_ALIGN_CENTER` simply center
     64 - `LV_GRID_ALIGN_SPACE_EVENLY` items are distributed so that the spacing between any two items (and the space to the edges) is equal. Not applies to `track_cross_place`.
     65 - `LV_GRID_ALIGN_SPACE_AROUND` items are evenly distributed in the track with equal space around them.
     66 Note that visually the spaces aren’t equal, since all the items have equal space on both sides.
     67 The first item will have one unit of space against the container edge, but two units of space between the next item because that next item has its own spacing that applies. Not applies to `track_cross_place`.
     68 - `LV_GRID_ALIGN_SPACE_BETWEEN` items are evenly distributed in the track: first item is on the start line, last item on the end line. Not applies to `track_cross_place`.
     69 
     70 To set the track's alignment use `lv_obj_set_grid_align(obj, column_align, row_align)`.
     71 
     72 ## Style interface
     73 
     74 All the Grid related values are style properties under the hood and you can use them similarly to any other style properties. The following Grid related style properties exist:
     75 
     76 - `GRID_COLUMN_DSC_ARRAY`
     77 - `GRID_ROW_DSC_ARRAY`
     78 - `GRID_COLUMN_ALIGN`
     79 - `GRID_ROW_ALIGN`
     80 - `GRID_CELL_X_ALIGN`
     81 - `GRID_CELL_COLUMN_POS`
     82 - `GRID_CELL_COLUMN_SPAN`
     83 - `GRID_CELL_Y_ALIGN`
     84 - `GRID_CELL_ROW_POS`
     85 - `GRID_CELL_ROW_SPAN`
     86 
     87 ### Internal padding
     88 
     89 To modify the minimum space Grid inserts between objects, the following properties can be set on the Grid container style:
     90 
     91 - `pad_row` Sets the padding between the rows.
     92 - `pad_column` Sets the padding between the columns.
     93 
     94 ## Other features
     95 
     96 ### RTL
     97 If the base direction of the container is set to `LV_BASE_DIR_RTL`, the meaning of `LV_GRID_ALIGN_START` and `LV_GRID_ALIGN_END` is swapped. I.e. `START` will mean right-most.
     98 
     99 The columns will be placed from right to left.
    100 
    101 
    102 ## Example
    103 
    104 ```eval_rst
    105 
    106 .. include:: ../../examples/layouts/grid/index.rst
    107 
    108 ```
    109 
    110 ## API
    111 
    112 ```eval_rst
    113 
    114 .. doxygenfile:: lv_grid.h
    115   :project: lvgl
    116 
    117 ```