Flex

Overview

The Flexbox (or Flex for short) is a subset of CSS Flexbox behaviors.

It can arrange items (child Widgets) into rows or columns (tracks), handle wrapping, adjust the spacing between items and tracks, handle grow to make item(s) fill remaining space with respect to min/max width and height.

To make a Widget a Flex container call lv_obj_set_layout(widget, LV_LAYOUT_FLEX).

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

Terms

• tracks: rows or columns

• main direction: row or column, the direction in which multiple items are placed first

• cross direction: the direction perpendicular to the main direction

• wrap: if there is no more space in the track, a new track is started

• grow: if set on an item it will "grow" to fill the remaining space in the track. The available space will be distributed among items respective to their grow value (larger value means more space)

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

See CSS Flexbox for illustrations showing the meanings of these terms.

Simple Interface

Use the following functions to set and control the Flex layout on any parent Widget.

Note

The parent Widget must be a Flex container for these styles to take effect. The functions below cause the parent Widget to become a Flex container if it is not already.

Flex flow

lv_obj_set_flex_flow(widget, flex_flow)

The possible values for flex_flow are:

• LV_FLEX_FLOW_ROW: Place the children in a row without wrapping

• LV_FLEX_FLOW_COLUMN: Place the children in a column without wrapping

• LV_FLEX_FLOW_ROW_WRAP: Place the children in a row with wrapping

• LV_FLEX_FLOW_COLUMN_WRAP: Place the children in a column with wrapping

• LV_FLEX_FLOW_ROW_REVERSE: Place the children in a row without wrapping but in reversed order

• LV_FLEX_FLOW_COLUMN_REVERSE: Place the children in a column without wrapping but in reversed order

• LV_FLEX_FLOW_ROW_WRAP_REVERSE: Place the children in a row with wrapping but in reversed order

• LV_FLEX_FLOW_COLUMN_WRAP_REVERSE: Place the children in a column with wrapping but in reversed order

These values cause the Widget's layout behavior to model CSS Flexbox behavior by combining flex-direction and flex-wrap as defined under flex-flow.

Flex align

To manage placement of children use lv_obj_set_flex_align(widget, main_place, cross_place, track_cross_place) which makes the parent Widget model the Flex-container behavior defined here.

• main_place determines how to distribute the items in their track on the main axis. E.g. flush the items to the right on LV_FLEX_FLOW_ROW_WRAP. (It's called justify-content in CSS.)

• cross_place determines how to distribute the items in their track on the cross axis. E.g. if the items have different height, align them against the bottom of the track. (It's called align-items in CSS.)

• track_cross_place determines how to distribute the tracks (It's called align-content in CSS.)

The possible values are:

• LV_FLEX_ALIGN_START: means left when direction is horizontal, top when vertical (default)

• LV_FLEX_ALIGN_END: means right when direction is horizontal, bottom when vertical

• LV_FLEX_ALIGN_CENTER: simply center with respect to direction

• LV_FLEX_ALIGN_SPACE_EVENLY: items are distributed so that the spacing between any two items (and the space to the edges) is equal. Does not apply to track_cross_place.

• LV_FLEX_ALIGN_SPACE_AROUND: items are evenly distributed in the track with equal space around them. Note that visually the spaces are not 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_FLEX_ALIGN_SPACE_BETWEEN: items are evenly distributed in the track with no space before and after first and last items. Does not apply to track_cross_place.

See justify-content, align-items and align-content for illustrations of these values.

Flex grow

Flex grow can be used to make one or more children fill available space in the track. When more than one child Widget have non-zero grow values, all available space will be distributed in proportion to their respective grow values. For example, if there is 400 px space remaining and 3 child Widgets with non-zero grow values:

• A with grow = 1

• B with grow = 1

• C with grow = 2

A and B will occupy 100 px, and C will occupy 200 px.

Flex grow can be set on a child Widget with lv_obj_set_flex_grow(child, value). value needs to be >= 1 or 0 to disable grow on the child.

See flex-grow for an illustration of this behavior.

Style Interface

All Flex-related values are style properties under the hood so you can use them as you would any other style property.

The following flex related style properties exist:

• FLEX_FLOW

• FLEX_MAIN_PLACE

• FLEX_CROSS_PLACE

• FLEX_TRACK_PLACE

• FLEX_GROW

Internal padding

To modify the minimum space flexbox inserts between Widgets, the following functions can be used to set the flex container padding style:

• lv_style_set_pad_row() sets padding between rows.

• lv_style_set_pad_column() sets padding between columns.

These can, for example, be used if you do not want any padding between Widgets: lv_style_set_pad_column(&row_container_style, 0)

Other Features

RTL

If the base direction of the container is set the LV_BASE_DIR_RTL the meaning of LV_FLEX_ALIGN_START and LV_FLEX_ALIGN_END is swapped on ROW layouts. I.e. START will mean right.

The items on ROW layouts, and tracks of COLUMN layouts will be placed from right to left.

New track

You can force Flex to put an item into a new line with lv_obj_add_flag(child, LV_OBJ_FLAG_FLEX_IN_NEW_TRACK).

Further Reading

Learn more about CSS Flexbox.

Examples

A simple row and a column layout with flexbox

C code  

 View on GitHub

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

/**
 * A simple row and a column layout with flexbox
 */
void lv_example_flex_1(void)
{
    /*Create a container with ROW flex direction*/
    lv_obj_t * cont_row = lv_obj_create(lv_screen_active());
    lv_obj_set_size(cont_row, 300, 75);
    lv_obj_align(cont_row, LV_ALIGN_TOP_MID, 0, 5);
    lv_obj_set_flex_flow(cont_row, LV_FLEX_FLOW_ROW);

    /*Create a container with COLUMN flex direction*/
    lv_obj_t * cont_col = lv_obj_create(lv_screen_active());
    lv_obj_set_size(cont_col, 200, 150);
    lv_obj_align_to(cont_col, cont_row, LV_ALIGN_OUT_BOTTOM_MID, 0, 5);
    lv_obj_set_flex_flow(cont_col, LV_FLEX_FLOW_COLUMN);

    uint32_t i;
    for(i = 0; i < 10; i++) {
        lv_obj_t * obj;
        lv_obj_t * label;

        /*Add items to the row*/
        obj = lv_button_create(cont_row);
        lv_obj_set_size(obj, 100, LV_PCT(100));

        label = lv_label_create(obj);
        lv_label_set_text_fmt(label, "Item: %"LV_PRIu32"", i);
        lv_obj_center(label);

        /*Add items to the column*/
        obj = lv_button_create(cont_col);
        lv_obj_set_size(obj, LV_PCT(100), LV_SIZE_CONTENT);

        label = lv_label_create(obj);
        lv_label_set_text_fmt(label, "Item: %"LV_PRIu32, i);
        lv_obj_center(label);
    }
}

#endif

---

Arrange items in rows with wrap and even spacing

C code  

 View on GitHub

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

/**
 * Arrange items in rows with wrap and place the items to get even space around them.
 */
void lv_example_flex_2(void)
{
    static lv_style_t style;
    lv_style_init(&style);
    lv_style_set_flex_flow(&style, LV_FLEX_FLOW_ROW_WRAP);
    lv_style_set_flex_main_place(&style, LV_FLEX_ALIGN_SPACE_EVENLY);
    lv_style_set_layout(&style, LV_LAYOUT_FLEX);

    lv_obj_t * cont = lv_obj_create(lv_screen_active());
    lv_obj_set_size(cont, 300, 220);
    lv_obj_center(cont);
    lv_obj_add_style(cont, &style, 0);

    uint32_t i;
    for(i = 0; i < 8; i++) {
        lv_obj_t * obj = lv_obj_create(cont);
        lv_obj_set_size(obj, 70, LV_SIZE_CONTENT);
        lv_obj_add_flag(obj, LV_OBJ_FLAG_CHECKABLE);

        lv_obj_t * label = lv_label_create(obj);
        lv_label_set_text_fmt(label, "%"LV_PRIu32, i);
        lv_obj_center(label);
    }
}

#endif

---

Demonstrate flex grow

C code  

 View on GitHub

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

/**
 * Demonstrate flex grow.
 */
void lv_example_flex_3(void)
{
    lv_obj_t * cont = lv_obj_create(lv_screen_active());
    lv_obj_set_size(cont, 300, 220);
    lv_obj_center(cont);
    lv_obj_set_flex_flow(cont, LV_FLEX_FLOW_ROW);

    lv_obj_t * obj;
    obj = lv_obj_create(cont);
    lv_obj_set_size(obj, 40, 40);           /*Fix size*/

    obj = lv_obj_create(cont);
    lv_obj_set_height(obj, 40);
    lv_obj_set_flex_grow(obj, 1);           /*1 portion from the free space*/

    obj = lv_obj_create(cont);
    lv_obj_set_height(obj, 40);
    lv_obj_set_flex_grow(obj, 2);           /*2 portion from the free space*/

    obj = lv_obj_create(cont);
    lv_obj_set_size(obj, 40, 40);           /*Fix size. It is flushed to the right by the "grow" items*/
}

#endif

---

Demonstrate flex grow.

C code  

 View on GitHub

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

/**
 * Reverse the order of flex items
 */
void lv_example_flex_4(void)
{

    lv_obj_t * cont = lv_obj_create(lv_screen_active());
    lv_obj_set_size(cont, 300, 220);
    lv_obj_center(cont);
    lv_obj_set_flex_flow(cont, LV_FLEX_FLOW_COLUMN_REVERSE);

    uint32_t i;
    for(i = 0; i < 6; i++) {
        lv_obj_t * obj = lv_obj_create(cont);
        lv_obj_set_size(obj, 100, 50);

        lv_obj_t * label = lv_label_create(obj);
        lv_label_set_text_fmt(label, "Item: %"LV_PRIu32, i);
        lv_obj_center(label);
    }
}

#endif

---

Demonstrate column and row gap style properties

C code  

 View on GitHub

#include "../../lv_examples.h"
#if LV_USE_FLEX && 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 the effect of column and row gap style properties
 */
void lv_example_flex_5(void)
{
    lv_obj_t * cont = lv_obj_create(lv_screen_active());
    lv_obj_set_size(cont, 300, 220);
    lv_obj_center(cont);
    lv_obj_set_flex_flow(cont, LV_FLEX_FLOW_ROW_WRAP);

    uint32_t i;
    for(i = 0; i < 9; i++) {
        lv_obj_t * obj = lv_obj_create(cont);
        lv_obj_set_size(obj, 70, LV_SIZE_CONTENT);

        lv_obj_t * label = lv_label_create(obj);
        lv_label_set_text_fmt(label, "%"LV_PRIu32, i);
        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_duration(&a, 500);
    lv_anim_set_reverse_duration(&a, 500);
    lv_anim_start(&a);

    lv_anim_set_exec_cb(&a, column_gap_anim);
    lv_anim_set_duration(&a, 3000);
    lv_anim_set_reverse_duration(&a, 3000);
    lv_anim_start(&a);
}

#endif

---

RTL base direction changes order of the items

C code  

 View on GitHub

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

/**
 * RTL base direction changes order of the items.
 * Also demonstrate how horizontal scrolling works with RTL.
 */
void lv_example_flex_6(void)
{
    lv_obj_t * cont = lv_obj_create(lv_screen_active());
    lv_obj_set_style_base_dir(cont, LV_BASE_DIR_RTL, 0);
    lv_obj_set_size(cont, 300, 220);
    lv_obj_center(cont);
    lv_obj_set_flex_flow(cont, LV_FLEX_FLOW_ROW_WRAP);

    uint32_t i;
    for(i = 0; i < 20; i++) {
        lv_obj_t * obj = lv_obj_create(cont);
        lv_obj_set_size(obj, 70, LV_SIZE_CONTENT);

        lv_obj_t * label = lv_label_create(obj);
        lv_label_set_text_fmt(label, "%"LV_PRIu32, i);
        lv_obj_center(label);
    }
}
#endif

---

API

lv_flex.h