Labs / LVGL / 04 Quick Start Case - Layout and Space Management (Based on Web Simulator and LVGL v9.0

4.5 Layout System

Author: Li Zisheng · Source: FreakStudio open documentation, v1.0 · License: CC BY 4.0

4.5 Layout System

Layout is a core mechanism in LVGL that automatically arranges widgets. It can replace manually calling set_pos () to calculate coordinates, making the interface more structured and easier to maintain, which is especially suitable for GUI development with limited screen sizes in embedded scenarios.

The core concepts include the following. First, the layout container:

Layout types include:

Layout TypeApplicable scenariosCore characteristics
Flex layoutLinear arrangement (one row / one column), such as horizontal menus and vertical settings listsChild widgets are automatically arranged along a single direction (horizontal / vertical), with spacing handled automatically
Grid layoutTwo-dimensional table arrangement, such as number keypads and 3×3 function matricesDivides the container into cells of multiple rows and columns; child widgets can be precisely assigned to specified cells

The basic process of layout is as follows:

  1. Create Container: lv.obj (scr)—— Generates an empty container for holding the layout
  2. Enable Layout : set_layout (layout_type)—— Select Flex or Grid mode
  3. Configuration Rules: Set parameters such as direction, spacing, grid rows and columns, etc.
  4. Add Control: Add child controls such as buttons and labels to the container — the controls will be automatically arranged according to the rules
  5. Load Display: lv.screen_load (scr)—— Renders the layout to the screen
4.5 Layout System
4.5 Layout System

4.5.1 Row/Column Arrangement (Flex Layout)

The following code is a standard example of LVGL MicroPython flex layout, which implements horizontal row arrangement and vertical column arrangement of buttons:

import display_driver
import lvgl as lv

# Initialize LVGL
lv.init()
scr = lv.screen_active()

# Generic button callback function
def btn_cb(e):
    print("按钮点击")

# Minimal button creation
def make_btn(parent, text):
    btn = lv.button(parent)
    btn.set_size(70, 40)
    btn.add_event_cb(btn_cb, lv.EVENT.PRESSED, None)
    label = lv.label(btn)
    label.set_text(text)
    label.center()
    return btn

# ============== 1. Horizontal row layout (one horizontal row) ==============
row = lv.obj(scr)
row.set_size(320, 60)
row.set_pos(10, 10)
row.set_layout(lv.LAYOUT.FLEX)                # Correct: flex layout
row.set_style_flex_flow(lv.FLEX_FLOW.ROW, 0)  # Correct: horizontal row
row.set_style_pad_column(10, 0)               # Horizontal spacing between buttons

# Automatically arrange 3 buttons horizontally
make_btn(row, "A1")
make_btn(row, "A2")
make_btn(row, "A3")

# ============== 2. Vertical column layout (one vertical column) ==============
col = lv.obj(scr)
col.set_size(90, 220)
col.set_pos(10, 80)
col.set_layout(lv.LAYOUT.FLEX)                  # Correct: flex layout
col.set_style_flex_flow(lv.FLEX_FLOW.COLUMN, 0) # Correct: vertical column
col.set_style_pad_row(10, 0)                   # Vertical spacing between buttons

# Automatically arrange 4 buttons vertically
make_btn(col, "1A")
make_btn(col, "1B")
make_btn(col, "1C")
make_btn(col, "1D")

lv.screen_load(scr)
A1 A2 A3 1A 1B 1C 1D
A1 A2 A3 1A 1B 1C 1D
A1 A2 A3 1A 1B 1C 1D

In the code above, we performed the following operations on the layout container:

Among these, the core attribute settings of Flex layout include:

The layout direction attributes include:

Spacing control attributes include:

Core Fundamentals of Flex Layout

Layout Direction (Flow)

Controlling the arrangement direction of child controls is the core switch of Flex layout:

  • lv.FLEX_FLOW.ROW: Horizontal arrangement (left to right)
  • lv.FLEX_FLOW.COLUMN: Vertical and longitudinal arrangement (top to bottom)
Spacing Control

Avoid overcrowded controls and optimize the aesthetic appeal of the interface:

  • When arranged horizontally: set_style_pad_column (pixels, 0)—— Set the horizontal spacing between child controls
  • When arranged vertically: set_style_pad_row (pixels, 0)—— used to set the vertical spacing between child controls
Alignment Logic

Child controls automatically fill along the layout direction, and their position within the container can be adjusted via alignment properties (such as lv.FLEX_ALIGN.CENTER).

4.5.2 Two-Dimensional Grid Layout (Grid Layout)

The code below implements a 2D grid layout, and creates a regular button grid with 2 rows and 3 columns based on the officially revised API:

import display_driver
import lvgl as lv

# Initialize LVGL
lv.init()
scr = lv.screen_active()

# Click callback
def btn_cb(e):
    print("按钮点击")

# Create button
def make_btn(parent, text):
    btn = lv.button(parent)
    btn.set_size(70, 40)
    btn.add_event_cb(btn_cb, lv.EVENT.PRESSED, None)
    label = lv.label(btn)
    label.set_text(text)
    label.center()
    return btn

# ==================== 2D grid layout (2 rows, 3 columns) ====================
grid = lv.obj(scr)
grid.set_size(280, 150)
grid.set_pos(20, 20)
grid.set_layout(lv.LAYOUT.GRID)

# Define 3 columns + 2 rows
col_dsc = [80, 80, 80, lv.GRID_TEMPLATE_LAST]
row_dsc = [50, 50, lv.GRID_TEMPLATE_LAST]

# Correct API
grid.set_grid_dsc_array(col_dsc, row_dsc)

# Spacing
grid.set_style_pad_row(10, 0)
grid.set_style_pad_column(10, 0)

# Loop to create buttons + set grid positions strictly following your API
for i in range(6):
    col = i % 3   # Columns: 0,1,2
    row = i // 3  # Rows: 0,0,0,1,1,1
    
    btn = make_btn(grid, str(i+1))
    
    # ✅ Strictly matches the 6 parameters you provided!!!
    btn.set_grid_cell(
        lv.GRID_ALIGN.CENTER,  # 1. column_align: column alignment
        col,                   # 2. col_pos: column position
        1,                     # 3. col_span: spans 1 column
        lv.GRID_ALIGN.CENTER,  # 4. row_align: row alignment (must be passed in your API!)
        row,                   # 5. row_pos: row position
        1                      # 6. row_span: spans 1 row
    )

lv.screen_load(scr)
2 3 1 6

In the code above, after initializing the LVGL graphics library and the screen container, we encapsulated a general button creation function with click response. By enabling the GRID grid layout, defining row and column size descriptors, and setting the spacing, we then generated buttons in a loop and strictly followed the 6-parameter specification of set_grid_cell to specify the grid alignment, position and span of each button. Finally, we loaded the screen to implement a neatly arranged grid interface, which fully demonstrates the core usage of LVGL grid layout.

The core APIs and their properties are defined as follows:

Core Fundamentals of Grid Layout

Grid Descriptor (col_dsc / row_dsc)

Defining the column width and line-height of the grid forms the "skeleton" of Grid layout:

  • Format:[col_width_1, col_width_2,. .., lv.GRID_TEMPLATE_LAST], lv.GRID_TEMPLATE_LAST is a fixed end marker.
  • Example: col_dsc = [80,80,80, lv.GRID_TEMPLATE_LAST]→ Defines 3 columns, each with a width of 80px
Grid Frame Binding

set_grid_dsc_array (col_dsc, row_dsc)—— Apply the defined row and column dimensions to the container to complete the construction of the cell framework.

Precise Control Positioning (set_grid_cell)

Assign specific cells to child controls, with the 6 parameters strictly corresponding to the LVGL grid rules:

  1. column_align: column alignment (e. g. lv.GRID_ALIGN.CENTER for center alignment)
  2. col_pos: The index of the column where the element is located (starting from 0)
  3. col_span: the number of columns occupied (usually 1)
  4. row_align: Row alignment mode
  5. row_pos: the index of the row where the element is located (starting from 0)
  6. row_span: Number of occupied rows (usually 1)

Version Record

Version Number

Modifier

Time

Content

v1.0

Li Zisheng

2026/03/24

Initialize the document.