Overview

Master XML syntax rules, naming conventions, and property types used in LVGL Pro Editor for defining UI components.

LVGL Pro Editor uses standard XML syntax with special conventions for property names, values, and type definitions that follow LVGL API patterns.

Naming Conventions

• Attribute names use lowercase letters with _ separation (e.g., bg_color, font_size)
• Tag names must start with a letter or _ and can contain letters, _, and digits
• Compound names use - as separator (e.g., lv_chart-series)
• Color values support multiple formats like CSS:
  • Hex with prefix: 0x112233 or #112233
  • Hex without prefix: 112233
  • Short hex: 0x123, #123, or 123 (all equivalent to #112233)
• LVGL API alignment: Follow LVGL naming conventions (e.g., align="center", bg_color="0xff0000")
• Parameter references: Use $ prefix (e.g., $param_name)
• Constant references: Use # prefix (e.g., #const_name)

Property Names

Most XML properties use standard syntax without special formatting:

<some_tag prop="value" other_prop="other value"/>

Style selectors can be added to property names for advanced styling:

<lv_checkbox style_bg_color-indicator-checked-disabled="0xff0000"/>

Types

All types can be used as API property types. Some types are also supported for constants and observer subjects.

Simple Types

Name-Based Types

In XML files, fonts, images, styles, and other assets are referenced by name, not by pointer:

<style name="red" bg_color="0xff0000"/>

Automatic binding occurs for:

• Styles, fonts, images, animations
• Gradients and other visual components
• Components and globals registered in globals.xml

Manual binding is required for:

• Event callbacks (only available in code)
• Custom fonts or images stored in memory

To register name-data pairs, see the Editor Integration guide.

Arrays

Arrays can be defined in three ways:

The termination of the array is important only to

1. Validate the correctness of the XML files
2. Generate correct code

The items in the array are separated by spaces and the termination is not included. For example

If there is an <api> property like <prop name="values" type="int[3]"/> it can be used as <my_widget values="10 33 55"/>

String items need to be wrapped in ' because an item can be composed of multiple words, so a space alone can't be used as a separator. For example <prop name="list" type="string[NULL]"/> it can be used as: <my_widget values="'This is the first' 'The second' '3rd'"/>

Enums

Custom enums for Widgets can be created using enumdef (not supported for Components):

<api>
  <enumdef name="my_widget_mode" help="Possible modes">
    <enum name="normal" value="0x10" help="Normal mode"/>
    <enum name="inverted" help="Inverted mode"/>
  </enumdef>

  <prop name="mode" type="enum:my_widget_mode" help="Select mode"/>
</api>

Multiple enum values with + suffix allow OR'ing values:

type="axis+"  <!-- Allows selecting multiple axis values -->
axis="primary_x|secondary_y"  <!-- Separate with | -->

Compound Types

Types can be combined to allow multiple options. For example:

type="px|%|content"  <!-- Accepts pixels, percentage, or auto-size -->

Limiting Accepted Values

You can restrict possible values for enums, colors, and strings:

<!-- Enum with limited options -->
type="dir(top bottom)"

<!-- Color with color palette -->
type="color(0xff0000 0x00ff00 0x0000ff)"

<!-- String with fixed options -->
type="string('Ok' 'Cancel')"