1.. _flex: 2 3==== 4Flex 5==== 6 7 8 9Overview 10******** 11 12The Flexbox (or Flex for short) is a subset of `CSS Flexbox`_ behaviors. 13 14It can arrange items (child Widgets) into rows or columns (tracks), handle wrapping, 15adjust the spacing between items and tracks, handle *grow* to make 16item(s) fill remaining space with respect to min/max width and 17height. 18 19To make a Widget a Flex container call 20:cpp:expr:`lv_obj_set_layout(widget, LV_LAYOUT_FLEX)`. 21 22Note that the Flex layout feature of LVGL needs to be globally enabled 23with :c:macro:`LV_USE_FLEX` in ``lv_conf.h``. 24 25 26 27Terms 28***** 29 30- **tracks**: rows or columns 31- **main direction**: row or column, the direction in which multiple items are 32 placed first 33- **cross direction**: the direction perpendicular to the **main direction** 34- **wrap**: if there is no more space in the track, a new track is started 35- **grow**: if set on an item it will "grow" to fill the remaining space in 36 the track. The available space will be distributed among items 37 respective to their grow value (larger value means more space) 38- **gap**: the space between rows and columns or the items on a track 39 40See `CSS Flexbox`_ for illustrations showing the meanings of these terms. 41 42 43 44Simple Interface 45**************** 46 47Use the following functions to set and control the Flex layout on any parent Widget. 48 49.. note:: 50 51 The parent Widget must be a Flex container for these styles to take effect. 52 The functions below cause the parent Widget to become a Flex container if it is 53 not already. 54 55 56.. _flex_flow: 57 58Flex flow 59--------- 60 61:cpp:expr:`lv_obj_set_flex_flow(widget, flex_flow)` 62 63The possible values for ``flex_flow`` are: 64 65- :cpp:enumerator:`LV_FLEX_FLOW_ROW`: Place the children in a row without wrapping 66- :cpp:enumerator:`LV_FLEX_FLOW_COLUMN`: Place the children in a column without wrapping 67- :cpp:enumerator:`LV_FLEX_FLOW_ROW_WRAP`: Place the children in a row with wrapping 68- :cpp:enumerator:`LV_FLEX_FLOW_COLUMN_WRAP`: Place the children in a column with wrapping 69- :cpp:enumerator:`LV_FLEX_FLOW_ROW_REVERSE`: Place the children in a row without wrapping but in reversed order 70- :cpp:enumerator:`LV_FLEX_FLOW_COLUMN_REVERSE`: Place the children in a column without wrapping but in reversed order 71- :cpp:enumerator:`LV_FLEX_FLOW_ROW_WRAP_REVERSE`: Place the children in a row with wrapping but in reversed order 72- :cpp:enumerator:`LV_FLEX_FLOW_COLUMN_WRAP_REVERSE`: Place the children in a column with wrapping but in reversed order 73 74These values cause the Widget's layout behavior to model `CSS Flexbox`_ behavior 75by combining flex-direction_ and flex-wrap_ as defined under flex-flow_. 76 77 78 79.. _flex_align: 80 81Flex align 82---------- 83 84To manage placement of children use 85:cpp:expr:`lv_obj_set_flex_align(widget, main_place, cross_place, track_cross_place)` 86which makes the parent Widget model the Flex-container behavior defined `here 87<justify-content_>`_. 88 89- ``main_place`` determines how to distribute the items in their track 90 on the main axis. E.g. flush the items to the right on 91 :cpp:enumerator:`LV_FLEX_FLOW_ROW_WRAP`. (It's called 92 justify-content_ in CSS.) 93- ``cross_place`` determines how to distribute the items in their track 94 on the cross axis. E.g. if the items have different height, align them 95 against the bottom of the track. (It's called align-items_ in CSS.) 96- ``track_cross_place`` determines how to distribute the tracks (It's 97 called align-content_ in CSS.) 98 99The possible values are: 100 101- :cpp:enumerator:`LV_FLEX_ALIGN_START`: means left when direction is horizontal, top when vertical (default) 102- :cpp:enumerator:`LV_FLEX_ALIGN_END`: means right when direction is horizontal, bottom when vertical 103- :cpp:enumerator:`LV_FLEX_ALIGN_CENTER`: simply center with respect to direction 104- :cpp:enumerator:`LV_FLEX_ALIGN_SPACE_EVENLY`: items are distributed so 105 that the spacing between any two items (and the space to the edges) is 106 equal. Does not apply to ``track_cross_place``. 107- :cpp:enumerator:`LV_FLEX_ALIGN_SPACE_AROUND`: items are evenly 108 distributed in the track with equal space around them. Note that 109 visually the spaces are not equal since all the items have equal space 110 on both sides. This makes the space between items double the space 111 between edge items and the container's edge. Does not apply to 112 ``track_cross_place``. 113- :cpp:enumerator:`LV_FLEX_ALIGN_SPACE_BETWEEN`: items are evenly distributed in 114 the track with no space before and after first and last items. Does not apply 115 to ``track_cross_place``. 116 117See justify-content_, align-items_ and align-content_ for illustrations of these values. 118 119 120.. _flex_grow: 121 122Flex grow 123--------- 124 125Flex grow can be used to make one or more children fill available space in the track. 126When more than one child Widget have non-zero grow values, all available space will 127be distributed in proportion to their respective grow values. For example, if there 128is 400 px space remaining and 3 child Widgets with non-zero grow values: 129 130- ``A`` with grow = 1 131- ``B`` with grow = 1 132- ``C`` with grow = 2 133 134``A`` and ``B`` will occupy 100 px, and ``C`` will occupy 200 px. 135 136Flex grow can be set on a child Widget with 137:cpp:expr:`lv_obj_set_flex_grow(child, value)`. ``value`` needs to be >= 1381 or 0 to disable grow on the child. 139 140See flex-grow_ for an illustration of this behavior. 141 142 143 144.. _flex_style: 145 146Style Interface 147*************** 148 149All Flex-related values are style properties under the hood so you 150can use them as you would any other style property. 151 152The following flex related style properties exist: 153 154- :cpp:enumerator:`FLEX_FLOW` 155- :cpp:enumerator:`FLEX_MAIN_PLACE` 156- :cpp:enumerator:`FLEX_CROSS_PLACE` 157- :cpp:enumerator:`FLEX_TRACK_PLACE` 158- :cpp:enumerator:`FLEX_GROW` 159 160.. _flex_padding: 161 162Internal padding 163---------------- 164 165To modify the minimum space flexbox inserts between Widgets, the 166following functions can be used to set the flex container padding style: 167 168- :cpp:func:`lv_style_set_pad_row` sets padding between rows. 169 170- :cpp:func:`lv_style_set_pad_column` sets padding between columns. 171 172These can, for example, be used if you do not want any padding between 173Widgets: :cpp:expr:`lv_style_set_pad_column(&row_container_style, 0)` 174 175 176 177.. _flex_other: 178 179Other Features 180************** 181 182RTL 183--- 184 185If the base direction of the container is set the 186:cpp:enumerator:`LV_BASE_DIR_RTL` the meaning of 187:cpp:enumerator:`LV_FLEX_ALIGN_START` and 188:cpp:enumerator:`LV_FLEX_ALIGN_END` is swapped on ``ROW`` layouts. I.e. 189``START`` will mean right. 190 191The items on ``ROW`` layouts, and tracks of ``COLUMN`` layouts will be 192placed from right to left. 193 194New track 195--------- 196 197You can force Flex to put an item into a new line with 198:cpp:expr:`lv_obj_add_flag(child, LV_OBJ_FLAG_FLEX_IN_NEW_TRACK)`. 199 200 201 202.. admonition:: Further Reading 203 204 Learn more about `CSS Flexbox`_. 205 206 207 208.. _flex_examples: 209 210Examples 211******** 212 213.. include:: ../../../examples/layouts/flex/index.rst 214 215 216.. Hyperlinks 217 218.. _css flexbox: https://css-tricks.com/snippets/css/a-guide-to-flexbox/ 219.. _flex-direction: https://css-tricks.com/snippets/css/a-guide-to-flexbox/#aa-flex-direction 220.. _flex-wrap: https://css-tricks.com/snippets/css/a-guide-to-flexbox/#aa-flex-wrap 221.. _flex-flow: https://css-tricks.com/snippets/css/a-guide-to-flexbox/#aa-flex-flow 222.. _justify-content: https://css-tricks.com/snippets/css/a-guide-to-flexbox/#aa-justify-content 223.. _align-items: https://css-tricks.com/snippets/css/a-guide-to-flexbox/#aa-align-items 224.. _align-content: https://css-tricks.com/snippets/css/a-guide-to-flexbox/#aa-align-content 225.. _flex-grow: https://css-tricks.com/snippets/css/a-guide-to-flexbox/#aa-flex-grow 226 227 228.. _flex_api: 229 230API 231*** 232
