Grid（网格布局）

Overview（概述）

查看原文

The Grid layout is a subset of CSS Flexbox.

It can arrange items into 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.

网格布局是 CSS Flexbox 的一个子集。

它可以将项目排列成具有行或列（轨道）的二维“表格”。 该项目可以跨越多个列或行。 轨道的大小可以设置为像素、最大项目（LV_GRID_CONTENT）或“空闲单元”（FR）以按比例分配空闲空间。

要使对象成为网格容器，请调用 lv_obj_set_layout(obj, LV_LAYOUT_GRID)。

请注意，LVGL 的网格布局功能需要通过 lv_conf.h 中的 LV_USE_GRID 全局启用。

Terms（约定）

查看原文

• tracks: the rows or columns

• free unit (FR): if set on track's size is set in FR it will grow to fill the remaining space on the parent.

• gap: the space between the rows and columns or the items on a track

• 轨道：行或列

• 空闲单元（FR）：如果在FR中设置了轨道的大小，它将增长以填充父级上的剩余空间。

• 间隙：行和列或轨道上的项目之间的空间

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:

首先，您需要描述行和列的大小。 可以通过声明 2 个数组和其中的轨道大小来完成。 最后一个元素必须是LV_GRID_TEMPLATE_LAST。

例如：

static lv_coord_t column_dsc[] = {100, 400, LV_GRID_TEMPLATE_LAST};   /*2 columns with 100 and 400 ps width*/
static lv_coord_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_CONTENT set the width to the largest children on this track

• LV_GRID_FR(X) tell what portion of the remaining space should be used by this track. Larger value means larger space.

要在父级上设置描述符，请使用 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 vertically

• LV_GRID_ALIGN_CENTER simply center

colum_pos and row_pos means the zero based index of the cell into the item should be placed.

colum_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_CENTER 只是居中

colum_pos 和 row_pos 表示应该放置项目中单元格的从零开始的索引。

colum_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 vertically

• LV_GRID_ALIGN_CENTER simply center

• 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.

• 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.

• 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 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 项目是分布的，因此任意两个项目之间的间距（以及到边缘的空间）是相等的。不适用于track_cross_place。

• LV_GRID_ALIGN_SPACE_AROUND 项目均匀分布在轨道中，它们周围的空间相等。 请注意，视觉上的空间并不相等，因为所有项目的两侧都有相等的空间。 第一个项目将与容器边缘有一个单位的空间，但下一个项目之间有两个单位的空间，因为下一个项目有自己的适用间距。不适用于track_cross_place。

• LV_GRID_ALIGN_SPACE_BETWEEN 项目均匀分布在轨道中：第一个项目在开始线上，最后一个项目在结束线上。不适用于track_cross_place。

要设置轨道的对齐方式，请使用 lv_obj_set_grid_align(obj, column_align, row_align)。

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_ARRAY

• GRID_ROW_DSC_ARRAY

• GRID_COLUMN_ALIGN

• GRID_ROW_ALIGN

• GRID_CELL_X_ALIGN

• GRID_CELL_COLUMN_POS

• GRID_CELL_COLUMN_SPAN

• GRID_CELL_Y_ALIGN

• GRID_CELL_ROW_POS

• GRID_CELL_ROW_SPAN

所有与 Grid 相关的值都是底层的样式属性，您可以像使用任何其他样式属性一样使用它们。 存在以下与网格相关的样式属性：

• GRID_COLUMN_DSC_ARRAY

• GRID_ROW_DSC_ARRAY

• GRID_COLUMN_ALIGN

• GRID_ROW_ALIGN

• GRID_CELL_X_ALIGN

• GRID_CELL_COLUMN_POS

• GRID_CELL_COLUMN_SPAN

• GRID_CELL_Y_ALIGN

• GRID_CELL_ROW_POS

• GRID_CELL_ROW_SPAN

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的含义互换。 IE。 START 表示最右边。

列将从右到左放置。

Example

API

Enums

enum lv_grid_align_t

Values:

enumerator LV_GRID_ALIGN_START

enumerator LV_GRID_ALIGN_CENTER

enumerator LV_GRID_ALIGN_END

enumerator LV_GRID_ALIGN_STRETCH

enumerator LV_GRID_ALIGN_SPACE_EVENLY

enumerator LV_GRID_ALIGN_SPACE_AROUND

enumerator LV_GRID_ALIGN_SPACE_BETWEEN

Functions

LV_EXPORT_CONST_INT(LV_GRID_CONTENT)

LV_EXPORT_CONST_INT(LV_GRID_TEMPLATE_LAST)

void lv_grid_init(void)

void lv_obj_set_grid_dsc_array(lv_obj_t *obj, const lv_coord_t col_dsc[], const lv_coord_t row_dsc[])

void lv_obj_set_grid_align(lv_obj_t *obj, lv_grid_align_t column_align, lv_grid_align_t row_align)

void lv_obj_set_grid_cell(lv_obj_t *obj, lv_grid_align_t column_align, uint8_t col_pos, uint8_t col_span, lv_grid_align_t row_align, uint8_t row_pos, uint8_t row_span)

Set the cell of an object. The object's parent needs to have grid layout, else nothing will happen

参数

• obj -- pointer to an object

• column_align -- the vertical alignment in the cell. LV_GRID_START/END/CENTER/STRETCH

• col_pos -- column ID

• col_span -- number of columns to take (>= 1)

• row_align -- the horizontal alignment in the cell. LV_GRID_START/END/CENTER/STRETCH

• row_pos -- row ID

• row_span -- number of rows to take (>= 1)

static inline lv_coord_t lv_grid_fr(uint8_t x)

Just a wrapper to LV_GRID_FR for bindings.

void lv_style_set_grid_row_dsc_array(lv_style_t *style, const lv_coord_t value[])

void lv_style_set_grid_column_dsc_array(lv_style_t *style, const lv_coord_t value[])

void lv_style_set_grid_row_align(lv_style_t *style, lv_grid_align_t value)

void lv_style_set_grid_column_align(lv_style_t *style, lv_grid_align_t value)

void lv_style_set_grid_cell_column_pos(lv_style_t *style, lv_coord_t value)

void lv_style_set_grid_cell_column_span(lv_style_t *style, lv_coord_t value)

void lv_style_set_grid_cell_row_pos(lv_style_t *style, lv_coord_t value)

void lv_style_set_grid_cell_row_span(lv_style_t *style, lv_coord_t value)

void lv_style_set_grid_cell_x_align(lv_style_t *style, lv_coord_t value)

void lv_style_set_grid_cell_y_align(lv_style_t *style, lv_coord_t value)

void lv_obj_set_style_grid_row_dsc_array(lv_obj_t *obj, const lv_coord_t value[], lv_style_selector_t selector)

void lv_obj_set_style_grid_column_dsc_array(lv_obj_t *obj, const lv_coord_t value[], lv_style_selector_t selector)

void lv_obj_set_style_grid_row_align(lv_obj_t *obj, lv_grid_align_t value, lv_style_selector_t selector)

void lv_obj_set_style_grid_column_align(lv_obj_t *obj, lv_grid_align_t value, lv_style_selector_t selector)

void lv_obj_set_style_grid_cell_column_pos(lv_obj_t *obj, lv_coord_t value, lv_style_selector_t selector)

void lv_obj_set_style_grid_cell_column_span(lv_obj_t *obj, lv_coord_t value, lv_style_selector_t selector)

void lv_obj_set_style_grid_cell_row_pos(lv_obj_t *obj, lv_coord_t value, lv_style_selector_t selector)

void lv_obj_set_style_grid_cell_row_span(lv_obj_t *obj, lv_coord_t value, lv_style_selector_t selector)

void lv_obj_set_style_grid_cell_x_align(lv_obj_t *obj, lv_coord_t value, lv_style_selector_t selector)

void lv_obj_set_style_grid_cell_y_align(lv_obj_t *obj, lv_coord_t value, lv_style_selector_t selector)

static inline const lv_coord_t *lv_obj_get_style_grid_row_dsc_array(const lv_obj_t *obj, uint32_t part)

static inline const lv_coord_t *lv_obj_get_style_grid_column_dsc_array(const lv_obj_t *obj, uint32_t part)

static inline lv_grid_align_t lv_obj_get_style_grid_row_align(const lv_obj_t *obj, uint32_t part)

static inline lv_grid_align_t lv_obj_get_style_grid_column_align(const lv_obj_t *obj, uint32_t part)

static inline lv_coord_t lv_obj_get_style_grid_cell_column_pos(const lv_obj_t *obj, uint32_t part)

static inline lv_coord_t lv_obj_get_style_grid_cell_column_span(const lv_obj_t *obj, uint32_t part)

static inline lv_coord_t lv_obj_get_style_grid_cell_row_pos(const lv_obj_t *obj, uint32_t part)

static inline lv_coord_t lv_obj_get_style_grid_cell_row_span(const lv_obj_t *obj, uint32_t part)

static inline lv_coord_t lv_obj_get_style_grid_cell_x_align(const lv_obj_t *obj, uint32_t part)

static inline lv_coord_t lv_obj_get_style_grid_cell_y_align(const lv_obj_t *obj, uint32_t part)

Variables

uint32_t LV_LAYOUT_GRID

lv_style_prop_t LV_STYLE_GRID_COLUMN_DSC_ARRAY

lv_style_prop_t LV_STYLE_GRID_COLUMN_ALIGN

lv_style_prop_t LV_STYLE_GRID_ROW_DSC_ARRAY

lv_style_prop_t LV_STYLE_GRID_ROW_ALIGN

lv_style_prop_t LV_STYLE_GRID_CELL_COLUMN_POS

lv_style_prop_t LV_STYLE_GRID_CELL_COLUMN_SPAN

lv_style_prop_t LV_STYLE_GRID_CELL_X_ALIGN

lv_style_prop_t LV_STYLE_GRID_CELL_ROW_POS

lv_style_prop_t LV_STYLE_GRID_CELL_ROW_SPAN

lv_style_prop_t LV_STYLE_GRID_CELL_Y_ALIGN