acid-drop

- Hacking the planet from a LilyGo T-Deck using custom firmware
git clone git://git.acid.vegas/acid-drop.git
Log | Files | Refs | Archive | README | LICENSE

flex.md (5441B)

      1 ```eval_rst
      2 .. include:: /header.rst
      3 :github_url: |github_link_base|/layouts/flex.md
      4 ```
      5 
      6 # Flex
      7 
      8 ## Overview
      9 
     10 The Flexbox (or Flex for short) is a subset of [CSS Flexbox](https://css-tricks.com/snippets/css/a-guide-to-flexbox/).
     11 
     12 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.
     13 
     14 To make an object flex container call `lv_obj_set_layout(obj, LV_LAYOUT_FLEX)`.
     15 
     16 Note that the flex layout feature of LVGL needs to be globally enabled with `LV_USE_FLEX` in `lv_conf.h`.
     17 
     18 ## Terms
     19 - tracks: the rows or columns
     20 - main direction: row or column, the direction in which the items are placed
     21 - cross direction: perpendicular to the main direction
     22 - wrap: if there is no more space in the track a new track is started
     23 - grow: if set on an item it will grow to fill the remaining space on the track.
     24 The available space will be distributed among items respective to their grow value (larger value means more space)
     25 - gap: the space between the rows and columns or the items on a track
     26 
     27 ## Simple interface
     28 
     29 With the following functions you can set a Flex layout on any parent.
     30 
     31 ### Flex flow
     32 
     33 `lv_obj_set_flex_flow(obj, flex_flow)`
     34 
     35 The possible values for `flex_flow` are:
     36 - `LV_FLEX_FLOW_ROW` Place the children in a row without wrapping
     37 - `LV_FLEX_FLOW_COLUMN` Place the children in a column without wrapping
     38 - `LV_FLEX_FLOW_ROW_WRAP` Place the children in a row with wrapping
     39 - `LV_FLEX_FLOW_COLUMN_WRAP` Place the children in a column with wrapping
     40 - `LV_FLEX_FLOW_ROW_REVERSE` Place the children in a row without wrapping but in reversed order
     41 - `LV_FLEX_FLOW_COLUMN_REVERSE` Place the children in a column without wrapping but in reversed order
     42 - `LV_FLEX_FLOW_ROW_WRAP_REVERSE` Place the children in a row with wrapping but in reversed order
     43 - `LV_FLEX_FLOW_COLUMN_WRAP_REVERSE` Place the children in a column with wrapping but in reversed order
     44 
     45 ### Flex align
     46 To manage the placement of the children use `lv_obj_set_flex_align(obj,  main_place, cross_place, track_cross_place)`
     47 
     48 - `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)
     49 - `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 called `align-items` in CSS)
     50 - `track_cross_place` determines how to distribute the tracks (It's called `align-content` in CSS)
     51 
     52 The possible values are:
     53 - `LV_FLEX_ALIGN_START` means left on a horizontally and top vertically. (default)
     54 - `LV_FLEX_ALIGN_END` means right on a horizontally and bottom vertically
     55 - `LV_FLEX_ALIGN_CENTER` simply center
     56 - `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`.
     57 - `LV_FLEX_ALIGN_SPACE_AROUND` items are evenly distributed in the track with equal space around them.
     58 Note that visually the spaces aren’t equal, since all the items have equal space on both sides.
     59 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`.
     60 - `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 to `track_cross_place`.
     61 
     62 
     63 ### Flex grow
     64 
     65 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.
     66 For example, there is 400 px remaining space and 4 objects with grow:
     67 - `A` with grow = 1
     68 - `B` with grow = 1
     69 - `C` with grow = 2
     70 
     71 `A` and `B` will have 100 px size, and `C` will have 200 px size.
     72 
     73 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.
     74 
     75 
     76 ## Style interface
     77 
     78 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:
     79 
     80 - `FLEX_FLOW`
     81 - `FLEX_MAIN_PLACE`
     82 - `FLEX_CROSS_PLACE`
     83 - `FLEX_TRACK_PLACE`
     84 - `FLEX_GROW`
     85 
     86 ### Internal padding
     87 
     88 To modify the minimum space flexbox inserts between objects, the following properties can be set on the flex container style:
     89 
     90 - `pad_row` Sets the padding between the rows.
     91 
     92 - `pad_column` Sets the padding between the columns.
     93 
     94 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)`
     95 
     96 ## Other features
     97 
     98 ### RTL
     99 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.
    100 
    101 The items on `ROW` layouts, and tracks of `COLUMN` layouts will be placed from right to left.
    102 
    103 ### New track
    104 
    105 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)`.
    106 
    107 
    108 ## Example
    109 
    110 ```eval_rst
    111 
    112 .. include:: ../../examples/layouts/flex/index.rst
    113 
    114 ```
    115 
    116 ## API
    117 
    118 ```eval_rst
    119 
    120 .. doxygenfile:: lv_flex.h
    121   :project: lvgl
    122 
    123 ```