Grid

Overview

The Grid layout is a subset of CSS Flexbox.

It can arrange items into 2D "table" that has rows or columns (tracks). The item can span through multiple columns or rows. 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.

To make an object a grid container call lv_obj_set_layout(obj, 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: the rows or columns

  • free unit (FR): if set on track's size is set in FR it will grow to fill the remaining space on the parent.

  • gap: the space between the rows and columns or the items on a track

Simple interface

With the following functions you can easily set a Grid layout on any parent.

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 lv_coord_t column_dsc[] = {100, 400, LV_GRID_TEMPLATE_LAST};   /*2 columns with 100 and 400 ps width*/
static lv_coord_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(obj, col_dsc, row_dsc).

Besides simple settings the size in pixel you can use two special values:

  • LV_GRID_CONTENT set the width to the largest children on this track

  • LV_GRID_FR(X) tell what portion of the remaining space should be used by this track. Larger value means larger space.

Grid items

By default the 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 children in its cell. The possible values are:

  • LV_GRID_ALIGN_START means left on a horizontally and top vertically. (default)

  • LV_GRID_ALIGN_END means right on a horizontally and bottom vertically

  • LV_GRID_ALIGN_CENTER simply center

colum_pos and row_pos means the zero based index of the cell into the item should be placed.

colum_span and row_span means how many tracks should the item involve from the start cell. Must be > 1.

Grid align

If there are some empty space the track can be aligned several ways:

  • LV_GRID_ALIGN_START means left on a horizontally and top vertically. (default)

  • LV_GRID_ALIGN_END means right on a horizontally and bottom vertically

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

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

To set the track's alignment use lv_obj_set_grid_align(obj, column_align, row_align).

Style interface

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:

  • 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

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.

Example

C

A simple grid

code     view on GitHub

#include "../../lv_examples.h"
#if LV_USE_GRID && LV_BUILD_EXAMPLES

/**
 * A simple grid
 */
void lv_example_grid_1(void)
{
    static lv_coord_t col_dsc[] = {70, 70, 70, LV_COORD_MAX};
    static lv_coord_t row_dsc[] = {50, 50, 50, LV_COORD_MAX};

    /*Create a container with grid*/
    lv_obj_t * cont = lv_obj_create(lv_scr_act());
    lv_obj_set_style_grid_column_dsc_array(cont, col_dsc, 0);
    lv_obj_set_style_grid_row_dsc_array(cont, row_dsc, 0);
    lv_obj_set_size(cont, 300, 220);
    lv_obj_center(cont);
    lv_obj_set_layout(cont, LV_LAYOUT_GRID);

    lv_obj_t * label;
    lv_obj_t * obj;

    uint32_t i;
    for(i = 0; i < 9; i++) {
        uint8_t col = i % 3;
        uint8_t row = i / 3;

        obj = lv_btn_create(cont);
        /*Stretch the cell horizontally and vertically too
         *Set span to 1 to make the cell 1 column/row sized*/
        lv_obj_set_grid_cell(obj, LV_GRID_ALIGN_STRETCH, col, 1,
                                  LV_GRID_ALIGN_STRETCH, row, 1);

        label = lv_label_create(obj);
        lv_label_set_text_fmt(label, "c%d, r%d", col, row);
        lv_obj_center(label);
    }
}

#endif

Demonstrate cell placement and span

code     view on GitHub

#include "../../lv_examples.h"
#if LV_USE_GRID && LV_BUILD_EXAMPLES


/**
 * Demonstrate cell placement and span
 */
void lv_example_grid_2(void)
{
    static lv_coord_t col_dsc[] = {70, 70, 70, LV_GRID_TEMPLATE_LAST};
    static lv_coord_t row_dsc[] = {50, 50, 50, LV_GRID_TEMPLATE_LAST};

    /*Create a container with grid*/
    lv_obj_t * cont = lv_obj_create(lv_scr_act());
    lv_obj_set_grid_dsc_array(cont, col_dsc, row_dsc);
    lv_obj_set_size(cont, 300, 220);
    lv_obj_center(cont);

    lv_obj_t * label;
    lv_obj_t * obj;

    /*Cell to 0;0 and align to to the start (left/top) horizontally and vertically too*/
    obj = lv_obj_create(cont);
    lv_obj_set_size(obj, LV_SIZE_CONTENT, LV_SIZE_CONTENT);
    lv_obj_set_grid_cell(obj, LV_GRID_ALIGN_START, 0, 1,
                              LV_GRID_ALIGN_START, 0, 1);
    label = lv_label_create(obj);
    lv_label_set_text(label, "c0, r0");

    /*Cell to 1;0 and align to to the start (left) horizontally and center vertically too*/
    obj = lv_obj_create(cont);
    lv_obj_set_size(obj, LV_SIZE_CONTENT, LV_SIZE_CONTENT);
    lv_obj_set_grid_cell(obj, LV_GRID_ALIGN_START, 1, 1,
                              LV_GRID_ALIGN_CENTER, 0, 1);
    label = lv_label_create(obj);
    lv_label_set_text(label, "c1, r0");

    /*Cell to 2;0 and align to to the start (left) horizontally and end (bottom) vertically too*/
    obj = lv_obj_create(cont);
    lv_obj_set_size(obj, LV_SIZE_CONTENT, LV_SIZE_CONTENT);
    lv_obj_set_grid_cell(obj, LV_GRID_ALIGN_START, 2, 1,
                              LV_GRID_ALIGN_END, 0, 1);
    label = lv_label_create(obj);
    lv_label_set_text(label, "c2, r0");

    /*Cell to 1;1 but 2 column wide (span = 2).Set width and height to stretched.*/
    obj = lv_obj_create(cont);
    lv_obj_set_size(obj, LV_SIZE_CONTENT, LV_SIZE_CONTENT);
    lv_obj_set_grid_cell(obj, LV_GRID_ALIGN_STRETCH, 1, 2,
                              LV_GRID_ALIGN_STRETCH, 1, 1);
    label = lv_label_create(obj);
    lv_label_set_text(label, "c1-2, r1");

    /*Cell to 0;1 but 2 rows tall (span = 2).Set width and height to stretched.*/
    obj = lv_obj_create(cont);
    lv_obj_set_size(obj, LV_SIZE_CONTENT, LV_SIZE_CONTENT);
    lv_obj_set_grid_cell(obj, LV_GRID_ALIGN_STRETCH, 0, 1,
                              LV_GRID_ALIGN_STRETCH, 1, 2);
    label = lv_label_create(obj);
    lv_label_set_text(label, "c0\nr1-2");
}

#endif

Demonstrate grid's "free unit"

code     view on GitHub

#include "../../lv_examples.h"
#if LV_USE_GRID && LV_BUILD_EXAMPLES

/**
 * Demonstrate grid's "free unit"
 */
void lv_example_grid_3(void)
{
    /*Column 1: fix width 60 px
     *Column 2: 1 unit from the remaining free space
     *Column 3: 2 unit from the remaining free space*/
    static lv_coord_t col_dsc[] = {60, LV_GRID_FR(1), LV_GRID_FR(2), LV_GRID_TEMPLATE_LAST};

    /*Row 1: fix width 50 px
     *Row 2: 1 unit from the remaining free space
     *Row 3: fix width 50 px*/
    static lv_coord_t row_dsc[] = {50, LV_GRID_FR(1), 50, LV_GRID_TEMPLATE_LAST};

    /*Create a container with grid*/
    lv_obj_t * cont = lv_obj_create(lv_scr_act());
    lv_obj_set_size(cont, 300, 220);
    lv_obj_center(cont);
    lv_obj_set_grid_dsc_array(cont, col_dsc, row_dsc);

    lv_obj_t * label;
    lv_obj_t * obj;
    uint32_t i;
    for(i = 0; i < 9; i++) {
        uint8_t col = i % 3;
        uint8_t row = i / 3;

        obj = lv_obj_create(cont);
        /*Stretch the cell horizontally and vertically too
         *Set span to 1 to make the cell 1 column/row sized*/
        lv_obj_set_grid_cell(obj, LV_GRID_ALIGN_STRETCH, col, 1,
                                 LV_GRID_ALIGN_STRETCH, row, 1);

        label = lv_label_create(obj);
        lv_label_set_text_fmt(label, "%d,%d", col, row);
        lv_obj_center(label);
    }
}

#endif

Demonstrate track placement

code     view on GitHub

#include "../../lv_examples.h"
#if LV_USE_GRID && LV_BUILD_EXAMPLES

/**
 * Demonstrate track placement
 */
void lv_example_grid_4(void)
{
    static lv_coord_t col_dsc[] = {60, 60, 60, LV_GRID_TEMPLATE_LAST};
    static lv_coord_t row_dsc[] = {45, 45, 45, LV_GRID_TEMPLATE_LAST};


    /*Add space between the columns and move the rows to the bottom (end)*/

    /*Create a container with grid*/
    lv_obj_t * cont = lv_obj_create(lv_scr_act());
    lv_obj_set_grid_align(cont, LV_GRID_ALIGN_SPACE_BETWEEN, LV_GRID_ALIGN_END);
    lv_obj_set_grid_dsc_array(cont, col_dsc, row_dsc);
    lv_obj_set_size(cont, 300, 220);
    lv_obj_center(cont);

    lv_obj_t * label;
    lv_obj_t * obj;
    uint32_t i;
    for(i = 0; i < 9; i++) {
        uint8_t col = i % 3;
        uint8_t row = i / 3;

        obj = lv_obj_create(cont);
        /*Stretch the cell horizontally and vertically too
         *Set span to 1 to make the cell 1 column/row sized*/
        lv_obj_set_grid_cell(obj, LV_GRID_ALIGN_STRETCH, col, 1,
                                  LV_GRID_ALIGN_STRETCH, row, 1);

        label = lv_label_create(obj);
        lv_label_set_text_fmt(label, "%d,%d", col, row);
        lv_obj_center(label);
    }
}

#endif

Demonstrate column and row gap

code     view on GitHub

#include "../../lv_examples.h"
#if LV_USE_GRID && LV_BUILD_EXAMPLES

static void row_gap_anim(void * obj, int32_t v)
{
    lv_obj_set_style_pad_row(obj, v, 0);
}

static void column_gap_anim(void * obj, int32_t v)
{
    lv_obj_set_style_pad_column(obj, v, 0);
}

/**
 * Demonstrate column and row gap
 */
void lv_example_grid_5(void)
{

    /*60x60 cells*/
    static lv_coord_t col_dsc[] = {60, 60, 60, LV_GRID_TEMPLATE_LAST};
    static lv_coord_t row_dsc[] = {45, 45, 45, LV_GRID_TEMPLATE_LAST};

    /*Create a container with grid*/
    lv_obj_t * cont = lv_obj_create(lv_scr_act());
    lv_obj_set_size(cont, 300, 220);
    lv_obj_center(cont);
    lv_obj_set_grid_dsc_array(cont, col_dsc, row_dsc);

    lv_obj_t * label;
    lv_obj_t * obj;
    uint32_t i;
    for(i = 0; i < 9; i++) {
        uint8_t col = i % 3;
        uint8_t row = i / 3;

        obj = lv_obj_create(cont);
        lv_obj_set_grid_cell(obj, LV_GRID_ALIGN_STRETCH, col, 1,
                                 LV_GRID_ALIGN_STRETCH, row, 1);
        label = lv_label_create(obj);
        lv_label_set_text_fmt(label, "%d,%d", col, row);
        lv_obj_center(label);
    }

    lv_anim_t a;
    lv_anim_init(&a);
    lv_anim_set_var(&a, cont);
    lv_anim_set_values(&a, 0, 10);
    lv_anim_set_repeat_count(&a, LV_ANIM_REPEAT_INFINITE);

    lv_anim_set_exec_cb(&a, row_gap_anim);
    lv_anim_set_time(&a, 500);
    lv_anim_set_playback_time(&a, 500);
    lv_anim_start(&a);

    lv_anim_set_exec_cb(&a, column_gap_anim);
    lv_anim_set_time(&a, 3000);
    lv_anim_set_playback_time(&a, 3000);
    lv_anim_start(&a);
}

#endif

Demonstrate RTL direction on grid

code     view on GitHub

#include "../../lv_examples.h"
#if LV_USE_GRID && LV_BUILD_EXAMPLES

/**
 * Demonstrate RTL direction on grid
 */
void lv_example_grid_6(void)
{

    static lv_coord_t col_dsc[] = {60, 60, 60, LV_GRID_TEMPLATE_LAST};
    static lv_coord_t row_dsc[] = {45, 45, 45, LV_GRID_TEMPLATE_LAST};

    /*Create a container with grid*/
    lv_obj_t * cont = lv_obj_create(lv_scr_act());
    lv_obj_set_size(cont, 300, 220);
    lv_obj_center(cont);
    lv_obj_set_style_base_dir(cont, LV_BASE_DIR_RTL, 0);
    lv_obj_set_grid_dsc_array(cont, col_dsc, row_dsc);

    lv_obj_t * label;
    lv_obj_t * obj;
    uint32_t i;
    for(i = 0; i < 9; i++) {
        uint8_t col = i % 3;
        uint8_t row = i / 3;

        obj = lv_obj_create(cont);
        /*Stretch the cell horizontally and vertically too
         *Set span to 1 to make the cell 1 column/row sized*/
        lv_obj_set_grid_cell(obj, LV_GRID_ALIGN_STRETCH, col, 1,
                                 LV_GRID_ALIGN_STRETCH, row, 1);

        label = lv_label_create(obj);
        lv_label_set_text_fmt(label, "%d,%d", col, row);
        lv_obj_center(label);
    }
}

#endif

MicroPython

No examples yet.

API

Enums

enum lv_grid_align_t

Values:

enumerator LV_GRID_ALIGN_START
enumerator LV_GRID_ALIGN_CENTER
enumerator LV_GRID_ALIGN_END
enumerator LV_GRID_ALIGN_STRETCH
enumerator LV_GRID_ALIGN_SPACE_EVENLY
enumerator LV_GRID_ALIGN_SPACE_AROUND
enumerator LV_GRID_ALIGN_SPACE_BETWEEN

Functions

LV_EXPORT_CONST_INT(LV_GRID_CONTENT)
LV_EXPORT_CONST_INT(LV_GRID_TEMPLATE_LAST)
void lv_grid_init(void)
void lv_obj_set_grid_dsc_array(lv_obj_t *obj, const lv_coord_t col_dsc[], const lv_coord_t row_dsc[])
void lv_obj_set_grid_align(lv_obj_t *obj, lv_grid_align_t column_align, lv_grid_align_t row_align)
void lv_obj_set_grid_cell(lv_obj_t *obj, lv_grid_align_t column_align, uint8_t col_pos, uint8_t col_span, lv_grid_align_t row_align, uint8_t row_pos, uint8_t row_span)

Set the cell of an object. The object's parent needs to have grid layout, else nothing will happen

Parameters

  • obj -- pointer to an object

  • hor_place -- the vertical alignment in the cell. LV_GRID_START/END/CENTER/STRETCH

  • col_pos -- column ID

  • col_span -- number of columns to take (>= 1)

  • ver_place -- the horizontal alignment in the cell. LV_GRID_START/END/CENTER/STRETCH

  • row_pos -- row ID

  • row_span -- number of rows to take (>= 1)

static inline lv_coord_t lv_grid_fr(uint8_t x)

Just a wrapper to LV_GRID_FR for bindings.

void lv_style_set_grid_row_dsc_array(lv_style_t *style, const lv_coord_t value[])
void lv_style_set_grid_column_dsc_array(lv_style_t *style, const lv_coord_t value[])
void lv_style_set_grid_row_align(lv_style_t *style, lv_grid_align_t value)
void lv_style_set_grid_column_align(lv_style_t *style, lv_grid_align_t value)
void lv_style_set_grid_cell_column_pos(lv_style_t *style, lv_coord_t value)
void lv_style_set_grid_cell_column_span(lv_style_t *style, lv_coord_t value)
void lv_style_set_grid_cell_row_pos(lv_style_t *style, lv_coord_t value)
void lv_style_set_grid_cell_row_span(lv_style_t *style, lv_coord_t value)
void lv_style_set_grid_cell_x_align(lv_style_t *style, lv_coord_t value)
void lv_style_set_grid_cell_y_align(lv_style_t *style, lv_coord_t value)
void lv_obj_set_style_grid_row_dsc_array(lv_obj_t *obj, const lv_coord_t value[], lv_style_selector_t selector)
void lv_obj_set_style_grid_column_dsc_array(lv_obj_t *obj, const lv_coord_t value[], lv_style_selector_t selector)
void lv_obj_set_style_grid_row_align(lv_obj_t *obj, lv_grid_align_t value, lv_style_selector_t selector)
void lv_obj_set_style_grid_column_align(lv_obj_t *obj, lv_grid_align_t value, lv_style_selector_t selector)
void lv_obj_set_style_grid_cell_column_pos(lv_obj_t *obj, lv_coord_t value, lv_style_selector_t selector)
void lv_obj_set_style_grid_cell_column_span(lv_obj_t *obj, lv_coord_t value, lv_style_selector_t selector)
void lv_obj_set_style_grid_cell_row_pos(lv_obj_t *obj, lv_coord_t value, lv_style_selector_t selector)
void lv_obj_set_style_grid_cell_row_span(lv_obj_t *obj, lv_coord_t value, lv_style_selector_t selector)
void lv_obj_set_style_grid_cell_x_align(lv_obj_t *obj, lv_coord_t value, lv_style_selector_t selector)
void lv_obj_set_style_grid_cell_y_align(lv_obj_t *obj, lv_coord_t value, lv_style_selector_t selector)
static inline const lv_coord_t *lv_obj_get_style_grid_row_dsc_array(const lv_obj_t *obj, uint32_t part)
static inline const lv_coord_t *lv_obj_get_style_grid_column_dsc_array(const lv_obj_t *obj, uint32_t part)
static inline lv_grid_align_t lv_obj_get_style_grid_row_align(const lv_obj_t *obj, uint32_t part)
static inline lv_grid_align_t lv_obj_get_style_grid_column_align(const lv_obj_t *obj, uint32_t part)
static inline lv_coord_t lv_obj_get_style_grid_cell_column_pos(const lv_obj_t *obj, uint32_t part)
static inline lv_coord_t lv_obj_get_style_grid_cell_column_span(const lv_obj_t *obj, uint32_t part)
static inline lv_coord_t lv_obj_get_style_grid_cell_row_pos(const lv_obj_t *obj, uint32_t part)
static inline lv_coord_t lv_obj_get_style_grid_cell_row_span(const lv_obj_t *obj, uint32_t part)
static inline lv_coord_t lv_obj_get_style_grid_cell_x_align(const lv_obj_t *obj, uint32_t part)
static inline lv_coord_t lv_obj_get_style_grid_cell_y_align(const lv_obj_t *obj, uint32_t part)

Variables

uint32_t LV_LAYOUT_GRID
lv_style_prop_t LV_STYLE_GRID_COLUMN_DSC_ARRAY
lv_style_prop_t LV_STYLE_GRID_COLUMN_ALIGN
lv_style_prop_t LV_STYLE_GRID_ROW_DSC_ARRAY
lv_style_prop_t LV_STYLE_GRID_ROW_ALIGN
lv_style_prop_t LV_STYLE_GRID_CELL_COLUMN_POS
lv_style_prop_t LV_STYLE_GRID_CELL_COLUMN_SPAN
lv_style_prop_t LV_STYLE_GRID_CELL_X_ALIGN
lv_style_prop_t LV_STYLE_GRID_CELL_ROW_POS
lv_style_prop_t LV_STYLE_GRID_CELL_ROW_SPAN
lv_style_prop_t LV_STYLE_GRID_CELL_Y_ALIGN