docs/src/common-widget-features/layouts/grid.rst
.. include:: /include/external_links.txt .. _grid:
Overview
The Grid layout is a subset of CSS Grid_ layout.
It can arrange items (child Widgets) into a 2D "table" that has rows and columns
(tracks). An item can span multiple columns or rows. The
track's size can be set in pixels, to the largest item
(:c:macro:LV_GRID_CONTENT), or to a fraction of the available free space
(i.e. Free [FR] Units <fr units_>_) to distribute free space proportionally.
To make a Widget a Grid container call :cpp:expr:lv_obj_set_layout(widget, LV_LAYOUT_GRID).
Note that the Grid layout feature of LVGL needs to be globally enabled
with :c:macro:LV_USE_GRID in lv_conf.h.
Terms
FR units it will grow
to fill the remaining space in the parent Widget (container), in proportion with
other tracks that have non-zero FR-unit values.Simple Interface
With the following functions you can cause any parent Widget to have Grid-layout behaviors.
.. note::
As with Flex containers, the parent Widget must be a Grid container for these
styles to take effect. The functions below cause the parent Widget to become a
Grid container if it is not already.
.. _grid_descriptors:
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 :c:macro:LV_GRID_TEMPLATE_LAST.
For example:
.. code-block:: c
static int32_t column_dsc[] = {100, 400, LV_GRID_TEMPLATE_LAST}; /* 2 columns with 100- and 400-px width / static int32_t row_dsc[] = {100, 100, 100, LV_GRID_TEMPLATE_LAST}; / 3 100-px tall rows */
To set the descriptors on a parent use
:cpp:expr:lv_obj_set_grid_dsc_array(widget, col_dsc, row_dsc).
Besides settings the sizes in pixels, you can use two special values:
LV_GRID_CONTENT sets size to fit the largest child on this trackLV_GRID_FR(X) determines what portion of the remaining space
should be used by this track. Larger values means larger space... _grid_items:
By default, a Widget's children are not added to the grid. They need to be added manually to a cell.
To do this call
:cpp:expr:lv_obj_set_grid_cell(child, column_align, column_pos, column_span, row_align, row_pos, row_span).
column_align and row_align determine how to align the child Widget
in its cell. Possible values are:
LV_GRID_ALIGN_START: means left when direction is horizontal and top when vertical (default)LV_GRID_ALIGN_END: means right when direction is horizontal and bottom when verticalLV_GRID_ALIGN_CENTER: simply center column_pos and row_pos
means the zero-based index of the cell in which the item should be placed.column_span and row_span means how many tracks should be occupied
from the start cell. Must be >= 1.
.. _grid_align:
If there is some empty space, items (Widgets) in Grid tracks can be aligned in several ways:
LV_GRID_ALIGN_START: means left when direction is horizontal and top when vertical. (default)LV_GRID_ALIGN_END: means right when direction is horizontal and bottom when verticalLV_GRID_ALIGN_CENTER: simply centerLV_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.LV_GRID_ALIGN_SPACE_AROUND: items are
evenly distributed in the track with equal space around them. Note that
visually the spaces aren't equal, since all the items have equal space
on both sides. This makes the space between items double the space
between edge items and the container's edge. Does not apply to track_cross_place.LV_GRID_ALIGN_SPACE_BETWEEN: items are
evenly distributed in the track with first and last items next to container's edges.
Does not apply to track_cross_place.To set the track's alignment use
:cpp:expr:lv_obj_set_grid_align(widget, column_align, row_align).
.. _grid_subgrid:
If you set the column and/or row grid descriptors of a widget to NULL it will use
the grid descriptor(s) from it's parent.
For example if you create a grid item that spans columns 2..6 columns and rows 1..3 of the grid, the grid item will occupy 5 columns and 4 rows with the corresponding track size from the parent Grid container.
This way even if a wrapper item is used in the grid, it can be made "transparent" from the grid's point of view.
Limitations:
The sub-grid is resolved only to a depth of 1 level. That is, a grid can have a sub-grid child, but that sub-grid cannot have another sub-grid.
:c:macro:LV_GRID_CONTENT tracks on the grid are not handled in the sub-grid, only in its
own grid.
The sub-grid feature works the same as in CSS. For further information, see
CSS Subgrid_.
.. _grid_style:
Style Interface
All the Grid-related values are style properties under the hood so you can use them as you would any other style property.
The following Grid-related style properties exist:
GRID_COLUMN_DSC_ARRAYGRID_ROW_DSC_ARRAYGRID_COLUMN_ALIGNGRID_ROW_ALIGNGRID_CELL_X_ALIGNGRID_CELL_COLUMN_POSGRID_CELL_COLUMN_SPANGRID_CELL_Y_ALIGNGRID_CELL_ROW_POSGRID_CELL_ROW_SPAN.. _grid_padding:
To modify the minimum space Grid inserts between Widgets, the following properties can be set on the Grid container style:
:cpp:func:lv_style_set_pad_row sets padding between rows.
:cpp:func:lv_style_set_pad_column sets padding between columns.
.. _grid_other:
Other features
If the base direction of the container is set to :cpp:enumerator:LV_BASE_DIR_RTL,
the meaning of :cpp:enumerator:LV_GRID_ALIGN_START and :cpp:enumerator:LV_GRID_ALIGN_END is
swapped. I.e. START will mean right-most.
The columns will be placed from right to left.
LV_SIZE_CONTENT or :cpp:expr:LV_PCT(x). These constraints are respected
when computing :c:macro:LV_GRID_CONTENT tracks (tracks sized to their largest
child) and when distributing space to FR-unit tracks... admonition:: Further Reading
- Learn more about `CSS Grid`_ layout.
- Learn more about `CSS Subgrid`_ layout.
.. _grid_examples:
Examples
.. include:: /examples/layouts/grid/index.rst
.. _grid_api:
API