Grid

The Grid layout is a subset of CSS Grid layout.

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 (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 lv_obj_set_layout(widget, LV_LAYOUT_GRID).

Note that the Grid layout feature of LVGL needs to be globally enabled with LV_USE_GRID in lv_conf.h.

Terms

• tracks: rows or columns
• free (FR) units: if a track's size is set in 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.
• gap: the space between rows and columns or the items on a track

Simple Interface

With the following functions you can cause any parent Widget to have Grid-layout behaviors.

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 LV_GRID_TEMPLATE_LAST.

For example:

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 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 track
• LV_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 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 vertical
• LV_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 vertical
• LV_GRID_ALIGN_CENTER: simply center
• 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.
• 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 lv_obj_set_grid_align(widget, column_align, row_align).

Sub grid

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.
• 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.

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_ARRAY
• GRID_ROW_DSC_ARRAY
• GRID_COLUMN_ALIGN
• GRID_ROW_ALIGN
• GRID_CELL_X_ALIGN
• GRID_CELL_COLUMN_POS
• GRID_CELL_COLUMN_SPAN
• GRID_CELL_Y_ALIGN
• GRID_CELL_ROW_POS
• GRID_CELL_ROW_SPAN

Internal padding

To modify the minimum space Grid inserts between Widgets, the following properties can be set on the Grid container style:

• lv_style_set_pad_row sets padding between rows.
• lv_style_set_pad_column sets padding between columns.

Other features

RTL

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.

The columns will be placed from right to left.

Edge cases and notes

• Min/max as content or percent: Child Widgets can set min/max width/height to LV_SIZE_CONTENT or LV_PCT(x). These constraints are respected when computing LV_GRID_CONTENT tracks (tracks sized to their largest child) and when distributing space to FR-unit tracks.

Examples

A simple grid

Demonstrate cell placement and span

Demonstrate grid's -free unit-

Demonstrate track placement

Demonstrate column and row gap

Demonstrate RTL direction on grid

API