Flex¶
Overview¶
The Flexbox (or Flex for short) is a subset of CSS Flexbox.
It can arrange items into rows or columns (tracks), handle wrapping, adjust the spacing between the items and tracks, handle grow to make the item(s) fill the remaining space with respect to min/max width and height.
To make an object flex container call lv_obj_set_layout(obj, 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: the rows or columns
main direction: row or column, the direction in which the items are placed
cross 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 on the track. The available space will be distributed among items respective to their grow value (larger value means more space)
gap: the space between the rows and columns or the items on a track
Simple interface¶
With the following functions you can set a Flex layout on any parent.
Flex flow¶
lv_obj_set_flex_flow(obj, flex_flow)
The possible values for flex_flow
are:
LV_FLEX_FLOW_ROW
Place the children in a row without wrappingLV_FLEX_FLOW_COLUMN
Place the children in a column without wrappingLV_FLEX_FLOW_ROW_WRAP
Place the children in a row with wrappingLV_FLEX_FLOW_COLUMN_WRAP
Place the children in a column with wrappingLV_FLEX_FLOW_ROW_REVERSE
Place the children in a row without wrapping but in reversed orderLV_FLEX_FLOW_COLUMN_REVERSE
Place the children in a column without wrapping but in reversed orderLV_FLEX_FLOW_ROW_WRAP_REVERSE
Place the children in a row with wrapping but in reversed orderLV_FLEX_FLOW_COLUMN_WRAP_REVERSE
Place the children in a column with wrapping but in reversed order
Flex align¶
To manage the placement of the children use lv_obj_set_flex_align(obj, main_place, cross_place, track_cross_place)
main_place
determines how to distribute the items in their track on the main axis. E.g. flush the items to the right onLV_FLEX_FLOW_ROW_WRAP
. (It's calledjustify-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 place them to the bottom of the track. (It's calledalign-items
in CSS)track_cross_place
determines how to distribute the tracks (It's calledalign-content
in CSS)
The possible values are:
LV_FLEX_ALIGN_START
means left on a horizontally and top vertically. (default)LV_FLEX_ALIGN_END
means right on a horizontally and bottom verticallyLV_FLEX_ALIGN_CENTER
simply centerLV_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 totrack_cross_place
.LV_FLEX_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 totrack_cross_place
.LV_FLEX_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 totrack_cross_place
.
Flex grow¶
Flex grow can be used to make one or more children fill the available space on the track. When more children have grow parameters, the available space will be distributed proportionally to the grow values. For example, there is 400 px remaining space and 4 objects with grow:
A
with grow = 1B
with grow = 1C
with grow = 2
A
and B
will have 100 px size, and C
will have 200 px size.
Flex grow can be set on a child with lv_obj_set_flex_grow(child, value)
. value
needs to be > 1 or 0 to disable grow on the child.
Style interface¶
All the Flex-related values are style properties under the hood and you can use them similarly to 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 objects, the following properties can be set on the flex container style:
pad_row
Sets the padding between the rows.pad_column
Sets the padding between the columns.
These can for example be used if you don't want any padding between your objects: 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)
.
Example¶
A simple row and a column layout with flexbox¶
C code
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_scr_act());
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_scr_act());
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_btn_create(cont_row);
lv_obj_set_size(obj, 100, LV_PCT(100));
label = lv_label_create(obj);
lv_label_set_text_fmt(label, "Item: %u", i);
lv_obj_center(label);
/*Add items to the column*/
obj = lv_btn_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
#
# A simple row and a column layout with flexbox
#
# Create a container with ROW flex direction
cont_row = lv.obj(lv.scr_act())
cont_row.set_size(300, 75)
cont_row.align(lv.ALIGN.TOP_MID, 0, 5)
cont_row.set_flex_flow(lv.FLEX_FLOW.ROW)
# Create a container with COLUMN flex direction
cont_col = lv.obj(lv.scr_act())
cont_col.set_size(200, 150)
cont_col.align_to(cont_row, lv.ALIGN.OUT_BOTTOM_MID, 0, 5)
cont_col.set_flex_flow(lv.FLEX_FLOW.COLUMN)
for i in range(10):
# Add items to the row
obj = lv.btn(cont_row)
obj.set_size(100, lv.pct(100))
label = lv.label(obj)
label.set_text("Item: {:d}".format(i))
label.center()
# Add items to the column
obj = lv.btn(cont_col)
obj.set_size(lv.pct(100), lv.SIZE.CONTENT)
label = lv.label(obj)
label.set_text("Item: {:d}".format(i))
label.center()
Arrange items in rows with wrap and even spacing¶
C code
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_scr_act());
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
#
# Arrange items in rows with wrap and place the items to get even space around them.
#
style = lv.style_t()
style.init()
style.set_flex_flow(lv.FLEX_FLOW.ROW_WRAP)
style.set_flex_main_place(lv.FLEX_ALIGN.SPACE_EVENLY)
style.set_layout(lv.LAYOUT_FLEX.value)
cont = lv.obj(lv.scr_act())
cont.set_size(300, 220)
cont.center()
cont.add_style(style, 0)
for i in range(8):
obj = lv.obj(cont)
obj.set_size(70, lv.SIZE.CONTENT)
label = lv.label(obj)
label.set_text("{:d}".format(i))
label.center()
Demonstrate flex grow¶
C code
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_scr_act());
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.
#
cont = lv.obj(lv.scr_act())
cont.set_size(300, 220)
cont.center()
cont.set_flex_flow(lv.FLEX_FLOW.ROW)
obj = lv.obj(cont)
obj.set_size(40, 40) # Fix size
obj = lv.obj(cont)
obj.set_height(40)
obj.set_flex_grow(1) # 1 portion from the free space
obj = lv.obj(cont)
obj.set_height(40)
obj.set_flex_grow(2) # 2 portion from the free space
obj = lv.obj(cont)
obj.set_size(40, 40) # Fix size. It is flushed to the right by the "grow" items
Demonstrate flex grow.¶
C code
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_scr_act());
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
#
# Reverse the order of flex items
#
cont = lv.obj(lv.scr_act())
cont.set_size(300, 220)
cont.center()
cont.set_flex_flow(lv.FLEX_FLOW.COLUMN_REVERSE)
for i in range(6):
obj = lv.obj(cont)
obj.set_size(100, 50)
label = lv.label(obj)
label.set_text("Item: " + str(i))
label.center()
Demonstrate column and row gap style properties¶
C code
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_scr_act());
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_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
def row_gap_anim(obj, v):
obj.set_style_pad_row(v, 0)
def column_gap_anim(obj, v):
obj.set_style_pad_column(v, 0)
#
# Demonstrate the effect of column and row gap style properties
#
cont = lv.obj(lv.scr_act())
cont.set_size(300, 220)
cont.center()
cont.set_flex_flow(lv.FLEX_FLOW.ROW_WRAP)
for i in range(9):
obj = lv.obj(cont)
obj.set_size(70, lv.SIZE.CONTENT)
label = lv.label(obj)
label.set_text(str(i))
label.center()
a_row = lv.anim_t()
a_row.init()
a_row.set_var(cont)
a_row.set_values(0, 10)
a_row.set_repeat_count(lv.ANIM_REPEAT.INFINITE)
a_row.set_time(500)
a_row.set_playback_time(500)
a_row.set_custom_exec_cb(lambda a,val: row_gap_anim(cont,val))
lv.anim_t.start(a_row)
a_col = lv.anim_t()
a_col.init()
a_col.set_var(cont)
a_col.set_values(0, 10)
a_col.set_repeat_count(lv.ANIM_REPEAT.INFINITE)
a_col.set_time(3000)
a_col.set_playback_time(3000)
a_col.set_custom_exec_cb(lambda a,val: column_gap_anim(cont,val))
lv.anim_t.start(a_col)
RTL base direction changes order of the items¶
C code
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_scr_act());
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
#
# RTL base direction changes order of the items.
# Also demonstrate how horizontal scrolling works with RTL.
#
cont = lv.obj(lv.scr_act())
cont.set_style_base_dir(lv.BASE_DIR.RTL,0)
cont.set_size(300, 220)
cont.center()
cont.set_flex_flow(lv.FLEX_FLOW.ROW_WRAP)
for i in range(20):
obj = lv.obj(cont)
obj.set_size(70, lv.SIZE.CONTENT)
label = lv.label(obj)
label.set_text(str(i))
label.center()
API¶
Enums
-
enum lv_flex_align_t¶
Values:
-
enumerator LV_FLEX_ALIGN_START¶
-
enumerator LV_FLEX_ALIGN_END¶
-
enumerator LV_FLEX_ALIGN_CENTER¶
-
enumerator LV_FLEX_ALIGN_SPACE_EVENLY¶
-
enumerator LV_FLEX_ALIGN_SPACE_AROUND¶
-
enumerator LV_FLEX_ALIGN_SPACE_BETWEEN¶
-
enumerator LV_FLEX_ALIGN_START¶
-
enum lv_flex_flow_t¶
Values:
-
enumerator LV_FLEX_FLOW_ROW¶
-
enumerator LV_FLEX_FLOW_COLUMN¶
-
enumerator LV_FLEX_FLOW_ROW_WRAP¶
-
enumerator LV_FLEX_FLOW_ROW_REVERSE¶
-
enumerator LV_FLEX_FLOW_ROW_WRAP_REVERSE¶
-
enumerator LV_FLEX_FLOW_COLUMN_WRAP¶
-
enumerator LV_FLEX_FLOW_COLUMN_REVERSE¶
-
enumerator LV_FLEX_FLOW_COLUMN_WRAP_REVERSE¶
-
enumerator LV_FLEX_FLOW_ROW¶
Functions
-
LV_EXPORT_CONST_INT(LV_OBJ_FLAG_FLEX_IN_NEW_TRACK)¶
-
void lv_flex_init(void)¶
Initialize a flex layout the default values
- Parameters
flex -- pointer to a flex layout descriptor
-
void lv_obj_set_flex_flow(lv_obj_t *obj, lv_flex_flow_t flow)¶
Set hot the item should flow
- Parameters
flex -- pointer to a flex layout descriptor
flow -- an element of
lv_flex_flow_t
.
-
void lv_obj_set_flex_align(lv_obj_t *obj, lv_flex_align_t main_place, lv_flex_align_t cross_place, lv_flex_align_t track_cross_place)¶
Set how to place (where to align) the items and tracks
- Parameters
flex -- pointer: to a flex layout descriptor
main_place -- where to place the items on main axis (in their track). Any value of
lv_flex_align_t
.cross_place -- where to place the item in their track on the cross axis.
LV_FLEX_ALIGN_START/END/CENTER
track_place -- where to place the tracks in the cross direction. Any value of
lv_flex_align_t
.
-
void lv_obj_set_flex_grow(lv_obj_t *obj, uint8_t grow)¶
Sets the width or height (on main axis) to grow the object in order fill the free space
- Parameters
obj -- pointer to an object. The parent must have flex layout else nothing will happen.
grow -- a value to set how much free space to take proportionally to other growing items.
-
void lv_style_set_flex_flow(lv_style_t *style, lv_flex_flow_t value)¶
-
void lv_style_set_flex_main_place(lv_style_t *style, lv_flex_align_t value)¶
-
void lv_style_set_flex_cross_place(lv_style_t *style, lv_flex_align_t value)¶
-
void lv_style_set_flex_track_place(lv_style_t *style, lv_flex_align_t value)¶
-
void lv_style_set_flex_grow(lv_style_t *style, uint8_t value)¶
-
void lv_obj_set_style_flex_flow(lv_obj_t *obj, lv_flex_flow_t value, lv_style_selector_t selector)¶
-
void lv_obj_set_style_flex_main_place(lv_obj_t *obj, lv_flex_align_t value, lv_style_selector_t selector)¶
-
void lv_obj_set_style_flex_cross_place(lv_obj_t *obj, lv_flex_align_t value, lv_style_selector_t selector)¶
-
void lv_obj_set_style_flex_track_place(lv_obj_t *obj, lv_flex_align_t value, lv_style_selector_t selector)¶
-
static inline lv_flex_flow_t lv_obj_get_style_flex_flow(const lv_obj_t *obj, uint32_t part)¶
-
static inline lv_flex_align_t lv_obj_get_style_flex_main_place(const lv_obj_t *obj, uint32_t part)¶
-
static inline lv_flex_align_t lv_obj_get_style_flex_cross_place(const lv_obj_t *obj, uint32_t part)¶
-
static inline lv_flex_align_t lv_obj_get_style_flex_track_place(const lv_obj_t *obj, uint32_t part)¶
Variables
-
uint32_t LV_LAYOUT_FLEX¶
-
lv_style_prop_t LV_STYLE_FLEX_FLOW¶
-
lv_style_prop_t LV_STYLE_FLEX_MAIN_PLACE¶
-
lv_style_prop_t LV_STYLE_FLEX_CROSS_PLACE¶
-
lv_style_prop_t LV_STYLE_FLEX_TRACK_PLACE¶
-
lv_style_prop_t LV_STYLE_FLEX_GROW¶