github-code/lvgl
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: fix links, add references, rename files (#5138)

Browse Source
This commit is contained in:
PGNetHun
2024-01-04 07:25:13 +01:00
committed by GitHub
parent 6136bd6cd0
commit 2a129562d8
94 changed files with 1441 additions and 837 deletions
Download Patch File Download Diff File Expand all files Collapse all files

83
docs/layouts/flex.rst
View File

@@ -1,3 +1,5 @@
.. _flex:
====
Flex
====
@@ -13,7 +15,7 @@ the item(s) fill the remaining space with respect to min/max width and
height.
To make an object flex container call
:c:expr:`lv_obj_set_layout(obj, LV_LAYOUT_FLEX)`.
:cpp:expr:`lv_obj_set_layout(obj, LV_LAYOUT_FLEX)`.
Note that the flex layout feature of LVGL needs to be globally enabled
with :c:macro:`LV_USE_FLEX` in ``lv_conf.h``.
@@ -36,30 +38,34 @@ Simple interface
With the following functions you can set a Flex layout on any parent.
.. _flex_flow:
Flex flow
---------
:c:expr:`lv_obj_set_flex_flow(obj, flex_flow)`
:cpp:expr:`lv_obj_set_flex_flow(obj, flex_flow)`
The possible values for ``flex_flow`` are:
- :c:enumerator:`LV_FLEX_FLOW_ROW`: Place the children in a row without wrapping
- :c:enumerator:`LV_FLEX_FLOW_COLUMN`: Place the children in a column without wrapping
- :c:enumerator:`LV_FLEX_FLOW_ROW_WRAP`: Place the children in a row with wrapping
- :c:enumerator:`LV_FLEX_FLOW_COLUMN_WRAP`: Place the children in a column with wrapping
- :c:enumerator:`LV_FLEX_FLOW_ROW_REVERSE`: Place the children in a row without wrapping but in reversed order
- :c:enumerator:`LV_FLEX_FLOW_COLUMN_REVERSE`: Place the children in a column without wrapping but in reversed order
- :c:enumerator:`LV_FLEX_FLOW_ROW_WRAP_REVERSE`: Place the children in a row with wrapping but in reversed order
- :c:enumerator:`LV_FLEX_FLOW_COLUMN_WRAP_REVERSE`: Place the children in a column with wrapping but in reversed order
- :cpp:enumerator:`LV_FLEX_FLOW_ROW`: Place the children in a row without wrapping
- :cpp:enumerator:`LV_FLEX_FLOW_COLUMN`: Place the children in a column without wrapping
- :cpp:enumerator:`LV_FLEX_FLOW_ROW_WRAP`: Place the children in a row with wrapping
- :cpp:enumerator:`LV_FLEX_FLOW_COLUMN_WRAP`: Place the children in a column with wrapping
- :cpp:enumerator:`LV_FLEX_FLOW_ROW_REVERSE`: Place the children in a row without wrapping but in reversed order
- :cpp:enumerator:`LV_FLEX_FLOW_COLUMN_REVERSE`: Place the children in a column without wrapping but in reversed order
- :cpp:enumerator:`LV_FLEX_FLOW_ROW_WRAP_REVERSE`: Place the children in a row with wrapping but in reversed order
- :cpp:enumerator:`LV_FLEX_FLOW_COLUMN_WRAP_REVERSE`: Place the children in a column with wrapping but in reversed order
.. _flex_align:
Flex align
----------
To manage the placement of the children use
:c:expr:`lv_obj_set_flex_align(obj, main_place, cross_place, track_cross_place)`
:cpp:expr:`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 on :c:enumerator:`LV_FLEX_FLOW_ROW_WRAP`. (It's called
on the main axis. E.g. flush the items to the right on :cpp:enumerator:`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 place them
@@ -69,37 +75,44 @@ To manage the placement of the children use
The possible values are:
- :c:enumerator:`LV_FLEX_ALIGN_START`: means left on a horizontally and top vertically. (default)
- :c:enumerator:`LV_FLEX_ALIGN_END`: means right on a horizontally and bottom vertically
- :c:enumerator:`LV_FLEX_ALIGN_CENTER`: simply center
- :c:enumerator:`LV_FLEX_ALIGN_SPACE_EVENLY`: items are distributed so
- :cpp:enumerator:`LV_FLEX_ALIGN_START`: means left on a horizontally and top vertically. (default)
- :cpp:enumerator:`LV_FLEX_ALIGN_END`: means right on a horizontally and bottom vertically
- :cpp:enumerator:`LV_FLEX_ALIGN_CENTER`: simply center
- :cpp:enumerator:`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``.
- :c:enumerator:`LV_FLEX_ALIGN_SPACE_AROUND`: items are evenly
- :cpp:enumerator:`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 to
``track_cross_place``.
- :c:enumerator:`LV_FLEX_ALIGN_SPACE_BETWEEN`: items are evenly distributed in
- :cpp:enumerator:`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``.
.. _flex_grow:
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 = 1 - ``B`` with grow = 1 - ``C`` with grow = 2
For example, there is 400 px remaining space and 4 objects with grow:
- ``A`` with grow = 1
- ``B`` with grow = 1
- ``C`` 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
:c:expr:`lv_obj_set_flex_grow(child, value)`. ``value`` needs to be >
:cpp:expr:`lv_obj_set_flex_grow(child, value)`. ``value`` needs to be >
1 or 0 to disable grow on the child.
.. _flex_style:
Style interface
***************
@@ -107,11 +120,13 @@ 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:
- :c:enumerator:`FLEX_FLOW`
- :c:enumerator:`FLEX_MAIN_PLACE`
- :c:enumerator:`FLEX_CROSS_PLACE`
- :c:enumerator:`FLEX_TRACK_PLACE`
- :c:enumerator:`FLEX_GROW`
- :cpp:enumerator:`FLEX_FLOW`
- :cpp:enumerator:`FLEX_MAIN_PLACE`
- :cpp:enumerator:`FLEX_CROSS_PLACE`
- :cpp:enumerator:`FLEX_TRACK_PLACE`
- :cpp:enumerator:`FLEX_GROW`
.. _flex_padding:
Internal padding
----------------
@@ -124,7 +139,9 @@ following properties can be set on the flex container style:
- ``pad_column`` Sets the padding between the columns.
These can for example be used if you don't want any padding between your
objects: :c:expr:`lv_style_set_pad_column(&row_container_style,0)`
objects: :cpp:expr:`lv_style_set_pad_column(&row_container_style,0)`
.. _flex_other:
Other features
**************
@@ -133,9 +150,9 @@ RTL
---
If the base direction of the container is set the
:c:enumerator:`LV_BASE_DIR_RTL` the meaning of
:c:enumerator:`LV_FLEX_ALIGN_START` and
:c:enumerator:`LV_FLEX_ALIGN_END` is swapped on ``ROW`` layouts. I.e.
:cpp:enumerator:`LV_BASE_DIR_RTL` the meaning of
:cpp:enumerator:`LV_FLEX_ALIGN_START` and
:cpp:enumerator:`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
@@ -145,12 +162,16 @@ New track
---------
You can force Flex to put an item into a new line with
:c:expr:`lv_obj_add_flag(child, LV_OBJ_FLAG_FLEX_IN_NEW_TRACK)`.
:cpp:expr:`lv_obj_add_flag(child, LV_OBJ_FLAG_FLEX_IN_NEW_TRACK)`.
.. _flex_example:
Example
*******
.. include:: ../examples/layouts/flex/index.rst
.. _flex_api:
API
***

70
docs/layouts/grid.rst
View File

@@ -1,3 +1,5 @@
.. _grid:
====
Grid
====
@@ -13,7 +15,7 @@ track's size can be set in pixel, to the largest item
(:c:macro:`LV_GRID_CONTENT`) or in "Free unit" (FR) to distribute the free
space proportionally.
To make an object a grid container call :c:expr:`lv_obj_set_layout(obj, LV_LAYOUT_GRID)`.
To make an object a grid container call :cpp:expr:`lv_obj_set_layout(obj, LV_LAYOUT_GRID)`.
Note that the grid layout feature of LVGL needs to be globally enabled
with :c:macro:`LV_USE_GRID` in ``lv_conf.h``.
@@ -32,6 +34,8 @@ Simple interface
With the following functions you can easily set a Grid layout on any
parent.
.. _grid_descriptors:
Grid descriptors
----------------
@@ -47,15 +51,17 @@ For example:
static int32_t row_dsc[] = {100, 100, 100, LV_GRID_TEMPLATE_LAST}; /*3 100 px tall rows*/
To set the descriptors on a parent use
:c:expr:`lv_obj_set_grid_dsc_array(obj, col_dsc, row_dsc)`.
:cpp:expr:`lv_obj_set_grid_dsc_array(obj, col_dsc, row_dsc)`.
Besides simple settings the size in pixel you can use two special
values:
- :c:macro:`LV_GRID_CONTENT` set the size to fit the largest child on this track
- :c:expr:`LV_GRID_FR(X)` tell what portion of the remaining space
- :cpp:expr:`LV_GRID_FR(X)` tell what portion of the remaining space
should be used by this track. Larger value means larger space.
.. _grid_items:
Grid items
----------
@@ -63,42 +69,45 @@ By default, the children are not added to the grid. They need to be
added manually to a cell.
To do this call
:c:expr:`lv_obj_set_grid_cell(child, column_align, column_pos, column_span, row_align, row_pos, row_span)`.
:cpp:expr:`lv_obj_set_grid_cell(child, column_align, column_pos, column_span, row_align, row_pos, row_span)`.
``column_align`` and ``row_align`` determine how to align the children
in its cell. The possible values are:
- :c:enumerator:`LV_GRID_ALIGN_START`: means left on a horizontally and top vertically. (default)
- :c:enumerator:`LV_GRID_ALIGN_END`: means right on a horizontally and bottom vertically
- :c:enumerator:`LV_GRID_ALIGN_CENTER`: simply center ``column_pos`` and ``row_pos``
- :cpp:enumerator:`LV_GRID_ALIGN_START`: means left on a horizontally and top vertically. (default)
- :cpp:enumerator:`LV_GRID_ALIGN_END`: means right on a horizontally and bottom vertically
- :cpp:enumerator:`LV_GRID_ALIGN_CENTER`: simply center ``column_pos`` and ``row_pos``
means the zero based index of the cell into the item should be placed.
``column_span`` and ``row_span`` means how many tracks should the item
involve from the start cell. Must be >= 1.
.. _grid_align:
Grid align
----------
If there are some empty space the track can be aligned several ways:
- :c:enumerator:`LV_GRID_ALIGN_START`: means left on a horizontally and top vertically. (default)
- :c:enumerator:`LV_GRID_ALIGN_END`: means right on a horizontally and bottom vertically
- :c:enumerator:`LV_GRID_ALIGN_CENTER`: simply center
- :c:enumerator:`LV_GRID_ALIGN_SPACE_EVENLY`: items are distributed so that the spacing
- :cpp:enumerator:`LV_GRID_ALIGN_START`: means left on a horizontally and top vertically. (default)
- :cpp:enumerator:`LV_GRID_ALIGN_END`: means right on a horizontally and bottom vertically
- :cpp:enumerator:`LV_GRID_ALIGN_CENTER`: simply center
- :cpp:enumerator:`LV_GRID_ALIGN_SPACE_EVENLY`: items are distributed so that the spacing
between any two items (and the space to the edges) is equal. Not applies to ``track_cross_place``.
- :c:enumerator:`LV_GRID_ALIGN_SPACE_AROUND`: items are
- :cpp:enumerator:`LV_GRID_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 to ``track_cross_place``.
- :c:enumerator:`LV_GRID_ALIGN_SPACE_BETWEEN`: items are
- :cpp:enumerator:`LV_GRID_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``.
To set the track's alignment use
:c:expr:`lv_obj_set_grid_align(obj, column_align, row_align)`.
:cpp:expr:`lv_obj_set_grid_align(obj, column_align, row_align)`.
.. _grid_subgrid:
Sub grid
--------
@@ -116,6 +125,7 @@ Limitations:
The sub grid feature works the same as in CSS. For further reference see `this description <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout/Subgrid>`__.
.. _grid_style:
Style interface
***************
@@ -124,16 +134,18 @@ All the Grid related values are style properties under the hood and you
can use them similarly to any other style properties. The following Grid
related style properties exist:
- :c:enumerator:`GRID_COLUMN_DSC_ARRAY`
- :c:enumerator:`GRID_ROW_DSC_ARRAY`
- :c:enumerator:`GRID_COLUMN_ALIGN`
- :c:enumerator:`GRID_ROW_ALIGN`
- :c:enumerator:`GRID_CELL_X_ALIGN`
- :c:enumerator:`GRID_CELL_COLUMN_POS`
- :c:enumerator:`GRID_CELL_COLUMN_SPAN`
- :c:enumerator:`GRID_CELL_Y_ALIGN`
- :c:enumerator:`GRID_CELL_ROW_POS`
- :c:enumerator:`GRID_CELL_ROW_SPAN`
- :cpp:enumerator:`GRID_COLUMN_DSC_ARRAY`
- :cpp:enumerator:`GRID_ROW_DSC_ARRAY`
- :cpp:enumerator:`GRID_COLUMN_ALIGN`
- :cpp:enumerator:`GRID_ROW_ALIGN`
- :cpp:enumerator:`GRID_CELL_X_ALIGN`
- :cpp:enumerator:`GRID_CELL_COLUMN_POS`
- :cpp:enumerator:`GRID_CELL_COLUMN_SPAN`
- :cpp:enumerator:`GRID_CELL_Y_ALIGN`
- :cpp:enumerator:`GRID_CELL_ROW_POS`
- :cpp:enumerator:`GRID_CELL_ROW_SPAN`
.. _grid_padding:
Internal padding
----------------
@@ -144,22 +156,28 @@ properties can be set on the Grid container style:
- ``pad_row`` Sets the padding between the rows.
- ``pad_column`` Sets the padding between the columns.
.. _grid_other:
Other features
**************
RTL
---
If the base direction of the container is set to :c:enumerator:`LV_BASE_DIR_RTL`,
the meaning of :c:enumerator:`LV_GRID_ALIGN_START` and :c:enumerator:`LV_GRID_ALIGN_END` is
If the base direction of the container is set to :cpp:enumerator:`LV_BASE_DIR_RTL`,
the meaning of :cpp:enumerator:`LV_GRID_ALIGN_START` and :cpp:enumerator:`LV_GRID_ALIGN_END` is
swapped. I.e. ``START`` will mean right-most.
The columns will be placed from right to left.
.. _grid_examples:
Example
*******
.. include:: ../examples/layouts/grid/index.rst
.. _grid_api:
API
***

2
docs/layouts/index.rst
View File

@@ -1,3 +1,5 @@
.. _layouts:
=======
Layouts
=======