Grid（网格布局）
Overview（概述）
显示原文
The Grid layout is a subset of CSS Grid.
It can arrange items into a 2D "table" that has rows or columns
(tracks). The item can span through multiple columns or rows. The
track's size can be set in pixel, to the largest item
(LV_GRID_CONTENT) or in "Free unit" (FR) to distribute the free
space proportionally.
To make an object a grid container call lv_obj_set_layout(obj, LV_LAYOUT_GRID).
Note that the grid layout feature of LVGL needs to be globally enabled
with LV_USE_GRID in lv_conf.h.
Grid（网格布局）是 CSS Grid 的一个子集。
它可以将元素排列成具有行或列（轨道）的二维 “表格” 中。该元素可以跨越多个列或行。轨道的大小可以设置为像素、最大元素（LV_GRID_CONTENT）或 “空闲单元” （FR） 以按比例分配自由空间。
要使对象成为网格容器，请调用函数 lv_obj_set_layout(obj, LV_LAYOUT_GRID) 设置。
请注意，LVGL 的 Grid（网格布局）功能需要打开 lv_conf.h 中的宏 LV_USE_GRID 启用。
Terms（约定）
显示原文
tracks: the rows or columns
free unit (FR): if set on track's size is set in
FRit will grow to fill the remaining space on the parent.gap: the space between the rows and columns or the items on a track
tracks（轨道）：行或列
空闲单元（FR）：如果在FR中设置了轨道的大小，它将增长以填充父级上的剩余空间。
gap（间隙）：行和列或轨道上的元素之间的空间
Simple interface（简单的接口）
显示原文
With the following functions you can easily set a Grid layout on any parent.
使用以下功能，可以轻松地在任何父级上设置网格布局。
Grid descriptors（网格描述符）
显示原文
First you need to describe the size of rows and columns. It can be done
by declaring 2 arrays and the track sizes in them. The last element must
be LV_GRID_TEMPLATE_LAST.
For example:
static int32_t column_dsc[] = {100, 400, LV_GRID_TEMPLATE_LAST}; /*2 columns with 100 and 400 ps width*/
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 lv_obj_set_grid_dsc_array(obj, col_dsc, row_dsc).
Besides simple settings the size in pixel you can use two special values:
LV_GRID_CONTENTset the size to fit the largest child on this trackLV_GRID_FR(X) tell what portion of the remaining space should be used by this track. Larger value means larger space.
首先，需要描述行和列的大小。这可以通过声明2个数组和其中的轨道大小来完成。最后一个元素必须是 LV_GRID_TEMPLATE_LAST 。
例如：
static int32_t column_dsc[] = {100, 400, LV_GRID_TEMPLATE_LAST}; /*2 columns with 100 and 400 ps width*/
static int32_t row_dsc[] = {100, 100, 100, LV_GRID_TEMPLATE_LAST}; /*3 100 px tall rows*/
要在父级上设置描述符，请使用 lv_obj_set_grid_dsc_array(obj, col_dsc, row_dsc) 。
除了简单地设置像素大小之外，还可以使用两个特殊值：
LV_GRID_CONTENT将大小设置为容纳这条轨道上最大的孩子LV_GRID_FR(X) 告诉这个轨道应该使用剩余空间的哪一部分。值越大，空间越大。
Grid items（网格项）
显示原文
By default, the children are not added to the grid. They need to be added manually to a cell.
To do this call 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:
LV_GRID_ALIGN_START: means left on a horizontally and top vertically (default)LV_GRID_ALIGN_END: means right on a horizontally and bottom verticallyLV_GRID_ALIGN_CENTER: simply centercolumn_posandrow_posmeans 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.
默认情况下，子项不会添加到网格中。 它们需要手动添加到网格的单元中。
为此需要调用接口 lv_obj_set_grid_cell(child, column_align, column_pos, column_span, row_align, row_pos, row_span) 添加。
column_align 和 row_align 确定如何对齐其单元格中的子项，可能的值有：
LV_GRID_ALIGN_START: 表示左侧水平，顶部垂直（默认）LV_GRID_ALIGN_END: 表示右侧水平，底部垂直LV_GRID_ALIGN_STRETCH: 平铺填充
column_pos 和 row_pos 表示要放置在网格中的元素的索引（从0开始）。
column_span 和 row_span 表示元素指定的网络索引开始应包含多少个轨道，必须 >= 1。
Grid align（对齐方式）
显示原文
If there are some empty space the track can be aligned several ways:
LV_GRID_ALIGN_START: means left on a horizontally and top vertically. (default)LV_GRID_ALIGN_END: means right on a horizontally and bottom verticallyLV_GRID_ALIGN_CENTER: simply centerLV_GRID_ALIGN_SPACE_EVENLY: items are distributed so that the spacing between any two items (and the space to the edges) is equal.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.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.
To set the track's alignment use lv_obj_set_grid_align(obj, column_align, row_align).
如果空间足够大，则可以通过多种方式对齐轨道：
LV_GRID_ALIGN_START: 表示左侧水平，顶部垂直（默认）LV_GRID_ALIGN_END: 表示右侧水平，底部垂直LV_GRID_ALIGN_CENTER: 居中摆放LV_GRID_ALIGN_SPACE_EVENLY: 元素的分布使得任意两个元素之间的间距（以及到边缘的间距）相等，包括首尾元素离容器边缘的距离。。LV_GRID_ALIGN_SPACE_AROUND: 元素在轨道上均匀分布，周围有相等的空间。请注意，从视觉上看，空间并不相等，因为所有元素的两侧都有相等的空间。第一个元素在容器边缘有一个单位的空间，但下一个元素之间有两个单位的间隔，因为下一个项有自己的适用间距。LV_GRID_ALIGN_SPACE_BETWEEN: 元素在轨道上彼此之间的间隔相等，首尾元素贴合容器边缘：第一个元素在开始行，最后一个元素在结束行。
要设置轨道的对齐方式，请使用接口 lv_obj_set_grid_align(obj, column_align, row_align) 设置。
Sub grid（子网格）
显示原文
If you set the column and/or row grid descriptors of the parent, the grid item will see 5 columns and 4 rows with the corresponding track size from the parent.
This way even if a wrapper item is used on the grid and can be made "transparent" from the grid's point of view.
Limitations:
The sub grid is resolved only in one level depth. That is a grid can have a sub grid children, but a sub grid can't have another sub grid.
LV_GRID_CONTENTtracks on the are not handled in the sub grid, only in the its own grid.
The sub grid feature works the same as in CSS. For further reference see this description.
如果设置父级的列、行网格描述符，则网格项将看到比如5列4行，其中包含父级对应的轨道大小。
这样，即使在网格上使用了包裹项，也可以从网格的角度使其“透明”。
局限性：
子网格仅在一个级别深度中解析。也就是说，一个网格可以有一个子网格，但一个子网格中不能有其它子网格。
LV_GRID_CONTENT轨道不在子网格中处理，只在其自己的网格中处理。
子网格功能的工作原理与CSS中的相同。如需进一步参考请参阅 这里的说明.
Style interface（样式接口）
显示原文
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:
GRID_COLUMN_DSC_ARRAYGRID_ROW_DSC_ARRAYGRID_COLUMN_ALIGNGRID_ROW_ALIGNGRID_CELL_X_ALIGNGRID_CELL_COLUMN_POSGRID_CELL_COLUMN_SPANGRID_CELL_Y_ALIGNGRID_CELL_ROW_POSGRID_CELL_ROW_SPAN
所有与 Grid 相关的值都是底层的样式属性，可以像使用任何其他样式属性那样使用它们。
下面是与网格相关的样式属性：
GRID_COLUMN_DSC_ARRAYGRID_ROW_DSC_ARRAYGRID_COLUMN_ALIGNGRID_ROW_ALIGNGRID_CELL_X_ALIGNGRID_CELL_COLUMN_POSGRID_CELL_COLUMN_SPANGRID_CELL_Y_ALIGNGRID_CELL_ROW_POSGRID_CELL_ROW_SPAN
Internal padding（内部填充）
显示原文
To modify the minimum space Grid inserts between objects, the following properties can be set on the Grid container style:
pad_rowSets the padding between the rows.pad_columnSets the padding between the columns.
要修改网格布局中对象之间的间隔，可以在给网格布局的容器修改下面所示的样式属性：
pad_row设置行之间的间距。pad_column设置列之间的间距。
Other features（其它功能）
RTL
显示原文
If the base direction of the container is set to LV_BASE_DIR_RTL,
the meaning of LV_GRID_ALIGN_START and LV_GRID_ALIGN_END is
swapped. I.e. START will mean right-most.
The columns will be placed from right to left.
如果容器的基本方向设置为 LV_BASE_DIR_RTL，那么 LV_GRID_ALIGN_START 和 LV_GRID_ALIGN_END 的作用就会互换，START 表示最右边。
列将从右到左放置。
Example
A simple grid
C code
View on GitHub#include "../../lv_examples.h"
#if LV_USE_GRID && LV_BUILD_EXAMPLES
/**
* A simple grid
*/
void lv_example_grid_1(void)
{
static int32_t col_dsc[] = {70, 70, 70, LV_GRID_TEMPLATE_LAST};
static int32_t row_dsc[] = {50, 50, 50, LV_GRID_TEMPLATE_LAST};
/*Create a container with grid*/
lv_obj_t * cont = lv_obj_create(lv_screen_active());
lv_obj_set_style_grid_column_dsc_array(cont, col_dsc, 0);
lv_obj_set_style_grid_row_dsc_array(cont, row_dsc, 0);
lv_obj_set_size(cont, 300, 220);
lv_obj_center(cont);
lv_obj_set_layout(cont, LV_LAYOUT_GRID);
lv_obj_t * label;
lv_obj_t * obj;
uint32_t i;
for(i = 0; i < 9; i++) {
uint8_t col = i % 3;
uint8_t row = i / 3;
obj = lv_button_create(cont);
/*Stretch the cell horizontally and vertically too
*Set span to 1 to make the cell 1 column/row sized*/
lv_obj_set_grid_cell(obj, LV_GRID_ALIGN_STRETCH, col, 1,
LV_GRID_ALIGN_STRETCH, row, 1);
label = lv_label_create(obj);
lv_label_set_text_fmt(label, "c%d, r%d", col, row);
lv_obj_center(label);
}
}
#endif
Demonstrate cell placement and span
C code
View on GitHub#include "../../lv_examples.h"
#if LV_USE_GRID && LV_BUILD_EXAMPLES
/**
* Demonstrate cell placement and span
*/
void lv_example_grid_2(void)
{
static int32_t col_dsc[] = {70, 70, 70, LV_GRID_TEMPLATE_LAST};
static int32_t row_dsc[] = {50, 50, 50, LV_GRID_TEMPLATE_LAST};
/*Create a container with grid*/
lv_obj_t * cont = lv_obj_create(lv_screen_active());
lv_obj_set_grid_dsc_array(cont, col_dsc, row_dsc);
lv_obj_set_size(cont, 300, 220);
lv_obj_center(cont);
lv_obj_t * label;
lv_obj_t * obj;
/*Cell to 0;0 and align to to the start (left/top) horizontally and vertically too*/
obj = lv_obj_create(cont);
lv_obj_set_size(obj, LV_SIZE_CONTENT, LV_SIZE_CONTENT);
lv_obj_set_grid_cell(obj, LV_GRID_ALIGN_START, 0, 1,
LV_GRID_ALIGN_START, 0, 1);
label = lv_label_create(obj);
lv_label_set_text(label, "c0, r0");
/*Cell to 1;0 and align to to the start (left) horizontally and center vertically too*/
obj = lv_obj_create(cont);
lv_obj_set_size(obj, LV_SIZE_CONTENT, LV_SIZE_CONTENT);
lv_obj_set_grid_cell(obj, LV_GRID_ALIGN_START, 1, 1,
LV_GRID_ALIGN_CENTER, 0, 1);
label = lv_label_create(obj);
lv_label_set_text(label, "c1, r0");
/*Cell to 2;0 and align to to the start (left) horizontally and end (bottom) vertically too*/
obj = lv_obj_create(cont);
lv_obj_set_size(obj, LV_SIZE_CONTENT, LV_SIZE_CONTENT);
lv_obj_set_grid_cell(obj, LV_GRID_ALIGN_START, 2, 1,
LV_GRID_ALIGN_END, 0, 1);
label = lv_label_create(obj);
lv_label_set_text(label, "c2, r0");
/*Cell to 1;1 but 2 column wide (span = 2).Set width and height to stretched.*/
obj = lv_obj_create(cont);
lv_obj_set_size(obj, LV_SIZE_CONTENT, LV_SIZE_CONTENT);
lv_obj_set_grid_cell(obj, LV_GRID_ALIGN_STRETCH, 1, 2,
LV_GRID_ALIGN_STRETCH, 1, 1);
label = lv_label_create(obj);
lv_label_set_text(label, "c1-2, r1");
/*Cell to 0;1 but 2 rows tall (span = 2).Set width and height to stretched.*/
obj = lv_obj_create(cont);
lv_obj_set_size(obj, LV_SIZE_CONTENT, LV_SIZE_CONTENT);
lv_obj_set_grid_cell(obj, LV_GRID_ALIGN_STRETCH, 0, 1,
LV_GRID_ALIGN_STRETCH, 1, 2);
label = lv_label_create(obj);
lv_label_set_text(label, "c0\nr1-2");
}
#endif
Demonstrate grid's -free unit-
C code
View on GitHub#include "../../lv_examples.h"
#if LV_USE_GRID && LV_BUILD_EXAMPLES
/**
* Demonstrate grid's "free unit"
*/
void lv_example_grid_3(void)
{
/*Column 1: fix width 60 px
*Column 2: 1 unit from the remaining free space
*Column 3: 2 unit from the remaining free space*/
static int32_t col_dsc[] = {60, LV_GRID_FR(1), LV_GRID_FR(2), LV_GRID_TEMPLATE_LAST};
/*Row 1: fix width 50 px
*Row 2: 1 unit from the remaining free space
*Row 3: fix width 50 px*/
static int32_t row_dsc[] = {50, LV_GRID_FR(1), 50, LV_GRID_TEMPLATE_LAST};
/*Create a container with grid*/
lv_obj_t * cont = lv_obj_create(lv_screen_active());
lv_obj_set_size(cont, 300, 220);
lv_obj_center(cont);
lv_obj_set_grid_dsc_array(cont, col_dsc, row_dsc);
lv_obj_t * label;
lv_obj_t * obj;
uint32_t i;
for(i = 0; i < 9; i++) {
uint8_t col = i % 3;
uint8_t row = i / 3;
obj = lv_obj_create(cont);
/*Stretch the cell horizontally and vertically too
*Set span to 1 to make the cell 1 column/row sized*/
lv_obj_set_grid_cell(obj, LV_GRID_ALIGN_STRETCH, col, 1,
LV_GRID_ALIGN_STRETCH, row, 1);
label = lv_label_create(obj);
lv_label_set_text_fmt(label, "%d,%d", col, row);
lv_obj_center(label);
}
}
#endif
Demonstrate track placement
C code
View on GitHub#include "../../lv_examples.h"
#if LV_USE_GRID && LV_BUILD_EXAMPLES
/**
* Demonstrate track placement
*/
void lv_example_grid_4(void)
{
static int32_t col_dsc[] = {60, 60, 60, LV_GRID_TEMPLATE_LAST};
static int32_t row_dsc[] = {45, 45, 45, LV_GRID_TEMPLATE_LAST};
/*Add space between the columns and move the rows to the bottom (end)*/
/*Create a container with grid*/
lv_obj_t * cont = lv_obj_create(lv_screen_active());
lv_obj_set_grid_align(cont, LV_GRID_ALIGN_SPACE_BETWEEN, LV_GRID_ALIGN_END);
lv_obj_set_grid_dsc_array(cont, col_dsc, row_dsc);
lv_obj_set_size(cont, 300, 220);
lv_obj_center(cont);
lv_obj_t * label;
lv_obj_t * obj;
uint32_t i;
for(i = 0; i < 9; i++) {
uint8_t col = i % 3;
uint8_t row = i / 3;
obj = lv_obj_create(cont);
/*Stretch the cell horizontally and vertically too
*Set span to 1 to make the cell 1 column/row sized*/
lv_obj_set_grid_cell(obj, LV_GRID_ALIGN_STRETCH, col, 1,
LV_GRID_ALIGN_STRETCH, row, 1);
label = lv_label_create(obj);
lv_label_set_text_fmt(label, "%d,%d", col, row);
lv_obj_center(label);
}
}
#endif
Demonstrate column and row gap
C code
View on GitHub#include "../../lv_examples.h"
#if LV_USE_GRID && 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 column and row gap
*/
void lv_example_grid_5(void)
{
/*60x60 cells*/
static int32_t col_dsc[] = {60, 60, 60, LV_GRID_TEMPLATE_LAST};
static int32_t row_dsc[] = {45, 45, 45, LV_GRID_TEMPLATE_LAST};
/*Create a container with grid*/
lv_obj_t * cont = lv_obj_create(lv_screen_active());
lv_obj_set_size(cont, 300, 220);
lv_obj_center(cont);
lv_obj_set_grid_dsc_array(cont, col_dsc, row_dsc);
lv_obj_t * label;
lv_obj_t * obj;
uint32_t i;
for(i = 0; i < 9; i++) {
uint8_t col = i % 3;
uint8_t row = i / 3;
obj = lv_obj_create(cont);
lv_obj_set_grid_cell(obj, LV_GRID_ALIGN_STRETCH, col, 1,
LV_GRID_ALIGN_STRETCH, row, 1);
label = lv_label_create(obj);
lv_label_set_text_fmt(label, "%d,%d", col, row);
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_duration(&a, 500);
lv_anim_set_playback_duration(&a, 500);
lv_anim_start(&a);
lv_anim_set_exec_cb(&a, column_gap_anim);
lv_anim_set_duration(&a, 3000);
lv_anim_set_playback_duration(&a, 3000);
lv_anim_start(&a);
}
#endif
Demonstrate RTL direction on grid
C code
View on GitHub#include "../../lv_examples.h"
#if LV_USE_GRID && LV_BUILD_EXAMPLES
/**
* Demonstrate RTL direction on grid
*/
void lv_example_grid_6(void)
{
static int32_t col_dsc[] = {60, 60, 60, LV_GRID_TEMPLATE_LAST};
static int32_t row_dsc[] = {45, 45, 45, LV_GRID_TEMPLATE_LAST};
/*Create a container with grid*/
lv_obj_t * cont = lv_obj_create(lv_screen_active());
lv_obj_set_size(cont, 300, 220);
lv_obj_center(cont);
lv_obj_set_style_base_dir(cont, LV_BASE_DIR_RTL, 0);
lv_obj_set_grid_dsc_array(cont, col_dsc, row_dsc);
lv_obj_t * label;
lv_obj_t * obj;
uint32_t i;
for(i = 0; i < 9; i++) {
uint8_t col = i % 3;
uint8_t row = i / 3;
obj = lv_obj_create(cont);
/*Stretch the cell horizontally and vertically too
*Set span to 1 to make the cell 1 column/row sized*/
lv_obj_set_grid_cell(obj, LV_GRID_ALIGN_STRETCH, col, 1,
LV_GRID_ALIGN_STRETCH, row, 1);
label = lv_label_create(obj);
lv_label_set_text_fmt(label, "%d,%d", col, row);
lv_obj_center(label);
}
}
#endif