Export LVGL code

Overview

The SquareLine Vision exporter generates LVGL-based GUI code organized in a structured way to separate concerns and make the code maintainable. The exported code follows a modular architecture with clear separation between GUI initialization, screen management, events, styles, and animations.

Export types

The export is started with the Export option of the menu. The Export dialog offers two options:

• Project template - The full project, including the board-specific build files (build system, hardware abstraction layer, LVGL configuration) and the generated GUI sources. Choose this for your first export, or to start a new project from the exported code.

• UI files only - Only the generated GUI source files. Choose this to update the user interface in an existing project without touching the build files. The board selected in the project settings still determines the board-specific GUI framework include.

Click Export to start. The project is saved automatically before the export, and the export is blocked while the object naming settings produce conflicting names.

• In the web application the result is downloaded as a zip file, named <project>_ProjectTemplate.zip or <project>_UIFiles.zip.

• In the desktop application the export is extracted into a folder you choose. The folder is remembered for the project and can be changed later under Project settings → Export (project export root and UI files export path).

Project structure

A Project template export has the following structure. A UI files export contains only the generated GUI sources, i.e. the content of the GUI folder.

exported_project/
├── GUI/                    # Main GUI folder (or 'ui' for Studio format)
│   ├── Content/            # GUI content files
│   │   ├── screens/        # Individual screen source files
│   │   ├── images/         # Generated image source files
│   │   └── fonts/          # Font source files
│   ├── Behavior/           # Event and animation related files
│   │   ├── GUI_Events.c    # Event handler implementations
│   │   └── GUI_Animations.c # Animation and timeline definitions
│   ├── Framework/          # GUI framework files
│   │   └── LVGL/           # LVGL library files
│   ├── GUI.c               # Main GUI implementation
│   ├── GUI.h               # Main GUI header
│   ├── GUI_variables.c     # GUI object declarations
│   ├── GUI_GlobalStyles.c  # Global style definitions
│   ├── CMakeLists.txt      # CMake build configuration
│   └── filelist.txt        # List of all GUI source files
├── lv_conf.h               # LVGL configuration file
├── main.c                  # Application entry point
├── HAL.c                   # Hardware abstraction layer
├── CMakeLists.txt          # Main CMake configuration
├── build.sh                # Build script
└── run.sh                  # Run script

Key Components

GUI.h/GUI.c

Main interface for the GUI subsystem. Provides high-level functions for:

• GUI_load() : Complete GUI initialization including HAL and LVGL
• GUI_init() : Basic GUI initialization
• GUI_refresh() : Updates GUI state (calls LVGL handler)
• GUI_initContent() : Initializes screens and widgets
• GUI_initTheme() : Sets up the GUI theme
• GUI_loadFirstScreen() : Loads the initial screen

GUI_variables.c

Contains declarations for all GUI objects (screens, widgets) that can be accessed from the application code.

GUI_Events.c

Implements all event handlers for user interactions defined in the project. Contains functions like:

void GUI_event__Button1__Clicked(lv_event_t * event) {
    // Event handling code
}

GUI_Animations.c

Implements animations and timelines defined in the project:

static void createTimelinePhase(lv_anim_timeline_t * timeline, uint32_t start_time,
                              lv_anim_t * animation, lv_obj_t * target, ...) {
    // Animation setup code
}

Screen Files (screens/*.c)

Each screen has its own source file with three main functions:

void GUI_initScreen_Screen1(void);      // Creates screen and widgets
void GUI_initScreenTexts_Screen1(void); // Sets up text content
void GUI_initScreenStyles_Screen1(void); // Applies styles

Building the Project

The build process depends on the selected board configuration. For detailed build instructions specific to your target board, please refer to the README.md file included in the exported code package.

Usage Examples

Basic Application Integration

#include "GUI/GUI.h"

int main(void) {
    // Initialize GUI with all components
    GUI_load();

    while(1) {
        // Update GUI
        GUI_refresh();

        // Add your application logic here
    }
}

Accessing GUI Objects

#include "GUI/GUI.h"
#include "GUI/GUI_variables.h"

void updateLabel(void) {
    // Access declared label widget
    lv_label_set_text(ui_Label1, "New Text");
}

Custom Event Handler Integration

// In your application code
void handleCustomEvent(void) {
    // Call exported event handler
    GUI_event__Button1__Clicked(NULL);
}

Important Notes

1. The exported code supports both hierarchical and flat layouts based on export settings.
2. Default widget naming follows the pattern: GUI_<WidgetType>__<ScreenName>__<ParentName__><WidgetName>
3. All public functions and objects are prefixed with GUI_ (or ui_ for Studio format).
4. The build system automatically collects all source files from the GUI directory.
5. Style modifications can be made at runtime using the provided style functions without recreating widgets.

Troubleshooting

1. If build fails with missing LVGL files:

   • Ensure LVGL is properly copied to the Framework directory
   • Check lv_conf.h settings match your setup

2. If display doesn't initialize:

   • Verify HAL.c contains correct display configuration
   • Check SDL2 installation for PC simulation

3. For memory issues:

   • Adjust LV_MEM_SIZE in lv_conf.h
   • Review widget creation order in screen init functions