.. _layout_overview:

======== Overview

Layouts assigned to a Widget manage the positions and in some cases the sizes of that Widget's children. They can be used to automatically arrange the children into a line, a column, or into more complicated patterns.

The position and size set by the layout overwrites the "normal" x, y, and in some cases the width, and height settings.

There is only one function that is the same for every layout: :cpp:func:lv_obj_set_layout (widget, <LAYOUT_NAME>) sets the layout on a Widget. For further settings of the parent and children see the documentation of the given layout.

Built-In Layouts

LVGL comes with two very powerful layouts:

Flexbox: arranges child Widgets into rows or columns, with support for wrapping and expanding items.
Grid: arranges child Widgets into fixed positions in a 2D table.

Both are heavily inspired by the CSS layouts with the same name. Layouts are described in detail in their own section of documentation.

Flags

There are some flags that can be used on Widgets to affect how they behave with layouts:

:cpp:enumerator:LV_OBJ_FLAG_HIDDEN Hidden Widgets are ignored in layout calculations.
:cpp:enumerator:LV_OBJ_FLAG_IGNORE_LAYOUT The Widget is simply ignored by the layouts. Its coordinates can be set as usual.
:cpp:enumerator:LV_OBJ_FLAG_FLOATING Same as :cpp:enumerator:LV_OBJ_FLAG_IGNORE_LAYOUT but the Widget with :cpp:enumerator:LV_OBJ_FLAG_FLOATING will be ignored in :c:macro:LV_SIZE_CONTENT calculations.

These flags can be added/removed with :cpp:expr:lv_obj_add_flag(widget, FLAG) and :cpp:expr:lv_obj_remove_flag(widget, FLAG)

Adding New Layouts

LVGL can be freely extended by a custom layout like this:

.. code-block:: c

uint32_t MY_LAYOUT;

...

MY_LAYOUT = lv_layout_register(my_layout_update, &user_data); lv_layout_set_min_size_cb(MY_LAYOUT, my_layout_get_min_size); /* Optional */

...

void my_layout_update(lv_obj_t * widget, void * user_data) { /* Will be called automatically if it's required to reposition/resize the children of "widget" */ }

The min size callback is optional and can be used to precompute the minimum size of all the children in the layout before sizing and positioning them. This is useful for layouts like flex that need to know the minimum size of children to properly calculate the grow size of the children.

Custom style properties can be added which can be retrieved and used in the update callback. For example:

.. code-block:: c

uint32_t LV_STYLE_MY_PROP; ...

LV_STYLE_MY_PROP = lv_style_register_prop(LV_STYLE_PROP_FLAG_NONE);

... static inline void lv_style_set_my_prop(lv_style_t * style, uint32_t value) { lv_style_value_t v = { .num = (int32_t)value }; lv_style_set_prop(style, LV_STYLE_MY_PROP, v); }