From fd070c35d95d61e895d35e84d2620ffd02c07caf Mon Sep 17 00:00:00 2001 From: Gabor Kiss-Vamosi Date: Wed, 1 Oct 2025 23:39:52 +0200 Subject: [PATCH] docs(editor): add missing intro pages and minor tweaks (#8983) --- docs/src/details/libs/frogfs.rst | 4 +- docs/src/details/xml/editor/index.rst | 24 +----- docs/src/details/xml/editor/install.rst | 28 ++----- .../details/xml/editor/nesting_projects.rst | 9 -- docs/src/details/xml/editor/overview.rst | 68 ++++++--------- docs/src/details/xml/editor/substitutions.txt | 2 +- .../src/details/xml/editor/user_interface.rst | 33 +++----- docs/src/details/xml/index.rst | 7 +- docs/src/details/xml/intro.rst | 32 +++++++- docs/src/details/xml/learn_by_examples.rst | 14 +++- docs/src/details/xml/license/editor.rst | 7 -- docs/src/details/xml/license/index.rst | 13 --- docs/src/details/xml/license/xml.rst | 82 ------------------- docs/src/details/xml/xml/index.rst | 1 + docs/src/details/xml/xml/overview.rst | 67 ++++++++------- 15 files changed, 125 insertions(+), 266 deletions(-) delete mode 100644 docs/src/details/xml/editor/nesting_projects.rst delete mode 100644 docs/src/details/xml/license/editor.rst delete mode 100644 docs/src/details/xml/license/index.rst delete mode 100644 docs/src/details/xml/license/xml.rst diff --git a/docs/src/details/libs/frogfs.rst b/docs/src/details/libs/frogfs.rst index 9050ac58ff..e6f917231f 100644 --- a/docs/src/details/libs/frogfs.rst +++ b/docs/src/details/libs/frogfs.rst @@ -8,7 +8,7 @@ FrogFS is a read-only :ref:`filesystem ` for packing a directory tree of files into a single "blob" which can be distributed easily or built into a firmware. It is suitable for packaging XML files into your -app. See the intro to :ref:`XML in LVGL ` if you are +app. See the intro to :ref:`XML in LVGL ` if you are interested in using XML. A copy of the frogfs source is inside LVGL. It has been @@ -119,7 +119,7 @@ all comments and insignificant whitespace. This is a form of compression that does not require a decompression step. The only drawback is that the incorrect line number relative to the un-minified version will be logged if there is a parse failure. -See the intro to :ref:`XML in LVGL `. +See the intro to :ref:`XML in LVGL `. You can prepare a frogfs blob with minified XML files. In your ``frogfs`` clone directory make a copy of ``tools/transform-html-minifier.js`` called diff --git a/docs/src/details/xml/editor/index.rst b/docs/src/details/xml/editor/index.rst index bb48309bf6..6f416a1e21 100644 --- a/docs/src/details/xml/editor/index.rst +++ b/docs/src/details/xml/editor/index.rst @@ -1,33 +1,17 @@ .. include:: substitutions.txt .. _editor: -.. _lvgl pro: -========= -|lvglpro| -========= - -What is |lvglpro|? -****************** - -|lvglpro| is the visual UI editor for LVGL-based firmware projects in which -you can build UIs in XML, preview them in real time in a pixel-perfect preview, -effectively making UI development much faster than writing C code. - -Its output is in the form of XML files that you create (with the help of -|lvglpro|'s smart editor) and/or generated C code, either or both of which can be -reused in any number of LVGL projects. +====== +Editor +====== .. toctree:: - :class: toctree-1-deep :maxdepth: 2 overview install user_interface hotkeys - nesting_projects + license -.. TODO: Online Preview? - -.. TODO: CLI? diff --git a/docs/src/details/xml/editor/install.rst b/docs/src/details/xml/editor/install.rst index 493b20a000..e16fa9b9eb 100644 --- a/docs/src/details/xml/editor/install.rst +++ b/docs/src/details/xml/editor/install.rst @@ -5,9 +5,7 @@ Installation ============ -Here are the guides to download and install |lvglpro| appropriate for your platform: - - +Here are the guides to download and install |lvglpro| Editor appropriate for your platform: Windows ******* @@ -17,27 +15,16 @@ resulting image to your workstation. Then execute the downloaded installer to i |lvglpro|. -Troubleshooting ---------------- - - - Linux ***** -Installing |lvglpro| on Linux is as simple as downloading the AppImage, making it -executable (``chmod +x LVGLPro.AppImage``), and running it. - - +Installing |lvglpro| Editor on Linux is as simple as downloading the AppImage, making it +executable (``chmod +x LVGL_Pro_Editor.AppImage``), and running it. Troubleshooting --------------- -Launching on Linux -~~~~~~~~~~~~~~~~~~ - -:Problem: Some users have experienced trouble launching |lvglpro| on some Linux - +:Problem: Some users have experienced trouble launching Editor on some Linux distributions. If you double click the ``.AppImage`` file and nothing happens, try running it from the terminal. If you see this error: @@ -58,8 +45,5 @@ Launching on Linux MacOS ***** -.. TODO Gabor - - -Troubleshooting ---------------- +Just download either the ARM for Apple Silicon (AMD) version) and drag the application +to your Applications folder in Finder. \ No newline at end of file diff --git a/docs/src/details/xml/editor/nesting_projects.rst b/docs/src/details/xml/editor/nesting_projects.rst deleted file mode 100644 index 2824b340ac..0000000000 --- a/docs/src/details/xml/editor/nesting_projects.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. include:: substitutions.txt -.. _nesting projects: - -================ -Nesting Projects -================ - - -.. TODO Gabor diff --git a/docs/src/details/xml/editor/overview.rst b/docs/src/details/xml/editor/overview.rst index b97b925747..340744ae4b 100644 --- a/docs/src/details/xml/editor/overview.rst +++ b/docs/src/details/xml/editor/overview.rst @@ -6,61 +6,43 @@ Overview ======== -|lvglpro| accelerates UI development by -- giving you an instant view of your additions and changes, -- converting Figma_ designs to LVGL, -- making it easy to share your UI screens online with collaborators and stakeholders, -- helping you to write UI tests, and -- integrating your UI via command-line interface (CLI). -Because |lvglpro| allows you to build a UI with a smart XML editor with powerful -auto-completion, it allows UI designers to efficiently contribute finished UI -components to firmware projects without having to be C programmers. +Introduction +************ -Simultaneously, |lvglpro| reduces turn-around time between UI changes and seeing the -actual results to mere seconds, making it practical for UI designer, developers and -business teams to collaborate on UI content in real time. +|lvglpro|'s Editor is an XML editor to simplify and speed up building embedded UIs. -LVGL itself can load created UI from the generated C code, or load its parts from the -XML files directly at runtime, requiring no re-flashing. Assets (images, fonts, -etc.) and XML UI component definitions can be read from an SD card, Wi-Fi, serial -port, or any other input source. +Its core part is a powerful XML editor with a real-time pixel-perfect preview. Besides +supporting the creation and preview of components and screens, it also supports +describing UI tests, animations, translations, and basically everything defined in XML. -Use the LVGL Figma_ plug-in to import style properties and images as XML code. It -also supports automatic downloading of linked styles and images. +From the XML files, the Editor can export C code that can be embedded into the firmware +just like any handwritten C code. -Tests of the resulting UI can be built in, simulating clicks, waits, and screenshot -comparisons to instantly prove the UI is working as expected, or quickly highlighting -anything that needs attention. This way is a great way to build up an automated and -thorough regression-testing pipeline for the UI, supporting high confidence with -every firmware release, small or large. +The Editor can also recompile its preview from LVGL and custom widgets written in C. -All parts of the development sequence, including code-generation, Figma_ sync, XML -validation, and test execution, are available in a CLI tool, ready to integrate into -your workflow. - -|lvglpro| comes with a simple, scalable and royalty-free licensing model that works -for open-source projects, startups, and enterprises alike. `See all plans`_. - -|lvglpro| comes in Linux, Windows, and macOS flavors so your team will have few, if -any, technical barriers to begin using it. - -It can be run as: - -- a stand-alone application on Windows, Linux, and macOS; -- a VSCode Extension; and -- on-line (via a web browser). +This section of the documentation describes how the Editor can be installed and used. To +learn more about the XML format itself, visit :ref:`this page `. -Login and Licensing -******************* - -.. TODO Gabor (trial, buy licence on pro.lvgl.io, read more on the licences page) - +Advantages +********** +Using the Editor of |lvglpro| instead of writing XML by hand has several advantages: +- see the components instantly in the preview, +- use an inspector tool to visualize widget sizes, paddings, etc., +- autocompletion speeds up writing XML, +- accelerate the reimplementation of Figma_ designs with the help of a :ref:`Figma + plugin `, +- support writing and running :ref:`UI tests ` in seconds, +- support adjusting the subject to test :ref:`Data bindings `. +The Editor can run as: +- a stand-alone desktop application on Windows, Linux, and macOS; +- a VSCode extension; and +- online (via a web browser). diff --git a/docs/src/details/xml/editor/substitutions.txt b/docs/src/details/xml/editor/substitutions.txt index 5e8c1b5e20..2b4ba085e1 100644 --- a/docs/src/details/xml/editor/substitutions.txt +++ b/docs/src/details/xml/editor/substitutions.txt @@ -1,4 +1,4 @@ .. -------- Custom Substitutions -------- .. |nbsp| unicode:: U+000A0 .. NO-BREAK SPACE :trim: -.. |lvglpro| replace:: UI |nbsp| Editor +.. |lvglpro| replace:: LVGL |nbsp| Pro diff --git a/docs/src/details/xml/editor/user_interface.rst b/docs/src/details/xml/editor/user_interface.rst index ce29e261ae..6bb1722481 100644 --- a/docs/src/details/xml/editor/user_interface.rst +++ b/docs/src/details/xml/editor/user_interface.rst @@ -33,7 +33,7 @@ Login hints: - enter your email address -- you will recevie an email with an OTP (On Time Password) +- you will receive an email with an OTP (On Time Password) - it will create a user for you - no password is needed @@ -48,8 +48,8 @@ After logging in you need select a licence for the list. -Initial Display -*************** +Launch Screen +************* .. figure:: /_static/images/editor_initial_ui.png :align: center @@ -60,29 +60,16 @@ Initial Display |lvglpro| Opening User Interface -Component Libraries vs Regular Projects ---------------------------------------- +The Launch Screen opens up every time you start the Editor and are already logged in. -A Component Library is a set of 1 or more XML files that can be used in any -|lvglpro| Project. +Here you can: -|lvglpro| UI Projects use Component Libraries, but Component Libraries do not -use UI Projects. +- Open an existing project +- Create a new project +- Open any recent project - -The Difference Between the Two ------------------------------- - -The difference between the directory structures of the two types of |lvglpro| projects -(UI Projects vs Component Libraries) is that a UIProject has a ``project.xml`` file -in it (which ties together all of its parts), and a Component Library does not. - -.. TODO: Gabor elaborate on what ``project.xml`` describes - - - -User Interface with Open Project -******************************** +Working on a Project +******************** .. figure:: /_static/images/editor_interface.png :align: center diff --git a/docs/src/details/xml/index.rst b/docs/src/details/xml/index.rst index f7974a0328..bb614a6f85 100644 --- a/docs/src/details/xml/index.rst +++ b/docs/src/details/xml/index.rst @@ -1,8 +1,8 @@ .. _editor_and_xml: -================= -UI Editor and XML -================= +================ +LVGL Pro and XML +================ .. toctree:: @@ -17,4 +17,3 @@ UI Editor and XML assets/index features/index tools/index - license/index diff --git a/docs/src/details/xml/intro.rst b/docs/src/details/xml/intro.rst index 23a3489966..46d13e33cd 100644 --- a/docs/src/details/xml/intro.rst +++ b/docs/src/details/xml/intro.rst @@ -1,8 +1,34 @@ -.. _xml_intro: +.. _lvglpro_intro: + ============ Introduction ============ -3-4 paragraph about what is the Editor and XML, for what it can be used, why is it good, -tools, etc. All with link. No subsections. +LVGL Pro is a complete toolkit to build, test, share, and ship embedded UIs +efficiently. + +It consists of 4 main tools: + +- **An XML Editor** with powerful autocomplete features to describe UI components, + screens, tests, animations, data bindings, and many more. A pixel-perfect preview + shows the UI as you type the XMLs. The Editor is also capable of exporting C code and + even recompiling its preview to run custom C code. On these pages you can learn more + about :ref:`XML ` and the :ref:`Editor `. + +- **Online Share** is an online version of the Editor which can load the XML files from + a GitHub repository to easily share the developed UIs without setting up any + development environments. Learn more :ref:`here `. + +- **CLI** (command-line interface) is a tool capable of validating the XML files and + generating C code from them, or running the UI tests in CI/CD environments. Learn more + :ref:`here `. + +- **Figma Plugin** that allows you to extract the style properties from Figma elements + and also synchronize them in the Editor or with the CLI. Learn more :ref:`here + `. + +These tools together allow developers to build UIs effectively, test them in a simple +and reliable way, and collaborate with the rest of the team and customers. + +This section of the documentation teaches all the details of each tool. diff --git a/docs/src/details/xml/learn_by_examples.rst b/docs/src/details/xml/learn_by_examples.rst index 84cd0570ac..f90e373fff 100644 --- a/docs/src/details/xml/learn_by_examples.rst +++ b/docs/src/details/xml/learn_by_examples.rst @@ -4,8 +4,16 @@ Learn by Examples ================= -.. TODO +We have prepared several tutorials in +https://github.com/lvgl/lvgl_editor/tree/master/tutorials\ . -Add 1 paragraph of description for each folder in lvgl/examples/xml -and button to open them in the online preview +By using https://viewer.lvgl.io/ you can easily try them out right in your browser. +1. **Hello World** See how to create a styled button with a label in XML. +2. **New Component** Create new components and build a screen from them. +3. **Assets** Learn how to use images and fonts. +4. **Screens** Try out the screen load and screen create events. +5. **Layouts** Check out the nested flex layouts in action. +6. **Data Binding** See the power of data bindings. +7. **Translations** Learn how to translate texts and preview them. +8. **Animations** Create timeline-based animations and play them on button click. diff --git a/docs/src/details/xml/license/editor.rst b/docs/src/details/xml/license/editor.rst deleted file mode 100644 index 552ae1201f..0000000000 --- a/docs/src/details/xml/license/editor.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _editor_license: - -============== -Editor license -============== - -.. TODO: describe the pricing models and conditions diff --git a/docs/src/details/xml/license/index.rst b/docs/src/details/xml/license/index.rst deleted file mode 100644 index 78d4d67310..0000000000 --- a/docs/src/details/xml/license/index.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. _xml_editor_licences: - -======== -Licenses -======== - - -.. toctree:: - :class: toctree-1-deep - :maxdepth: 1 - - xml - editor diff --git a/docs/src/details/xml/license/xml.rst b/docs/src/details/xml/license/xml.rst deleted file mode 100644 index 1d23d2e8a8..0000000000 --- a/docs/src/details/xml/license/xml.rst +++ /dev/null @@ -1,82 +0,0 @@ -.. _lvgl_xml_license: - -=========== -XML License -=========== - -**Version 1.0 – June 2025** - -**Copyright (c) 2025 LVGL LLC** - - -1. Overview -=========== - -The LVGL XML Specification (the "Specification") defines an XML-based language for describing user interfaces within the LVGL ecosystem. - -This Specification is protected by copyright. It is provided with limited rights of use as outlined below. - -The purpose of this license is to ensure that the Specification remains freely usable for application developers working with LVGL, -while restricting its use in third-party UI editors or design tools. -This protects the long-term integrity and sustainability of the LVGL ecosystem by preventing unlicensed tools -from reusing or replicating the Specification in ways that compete with official LVGL offerings. - - -2. Permitted Usage -================== - -You are permitted to: - -- Use this Specification in **any firmware or embedded application** built on top of the official `LVGL library `_ (MIT-licensed). -- Use the LVGL XML loader freely in accordance with its MIT license. -- Use the Specification with the **LVGL UI editor** and **official LVGL tools such as the CLI or XML loader**. -- Write, load, edit, or generate user interfaces described in the LVGL XML Specification for **internal use** only, including automation or configuration tools used solely inside your organization. -- Create **internal scripts or plugins** that help your own developers use or manage this Specification, as long as these are **not shared outside your organization or made publicly available**. -- Share XML-based UI files within customer firmware or projects that target LVGL-based embedded systems. - - -3. Restrictions -=============== - -You are **not permitted** to: - -- Create, release, or distribute any **UI editor, visual builder, layout designer, code generator, or tool** that reads, writes, or interprets XML files using this Specification — **whether commercial, open-source, or intended for public use, use by customers or partners, or any use outside your own organization** — without written permission from LVGL LLC. -- Implement or extend this Specification in any **software or platform that provides UI creation, editing, or design capabilities similar to those in the LVGL UI Editor**. -- Build public APIs, plugins, converters, or SDKs based on this Specification. -- Share or publish internal tooling built around this Specification. -- Use this Specification into general-purpose design tools or frameworks outside the LVGL ecosystem. - -These restrictions apply regardless of whether the software is commercial, free, or open-source. - -4. Clarification for LVGL Users -=============================== - -You are **explicitly permitted** to: - -- Use XML files with this Specification in your own projects. -- Load XMLs at runtime using LVGL’s XML loader. -- Generate XMLs using the LVGL UI editor. -- Customize XMLs manually or with internal utilities. -- Share LVGL-based projects with XML files as part of a commercial product or firmware. - -If you are building embedded software using LVGL, **this license does not affect you**. -This license only applies to **UI development tools** that **read, generate, or process XML files using this Specification for UI development purposes** in a public or commercial manner. - -You may create **internal tools** to aid development using the Specification, but these must not be published, sold, or shared externally without a license. - - -5. Trademarks -============= - -This license does not grant any rights to use the LVGL name, logo, or trademarks. - - -6. Licensing and Permissions -============================ - -To request permission for broader use or commercial licensing (e.g. using this Specification in your own UI tool), contact: - -**lvgl@lvgl.io** - -All rights not expressly granted herein are reserved by LVGL LLC. - diff --git a/docs/src/details/xml/xml/index.rst b/docs/src/details/xml/xml/index.rst index 58c781c9fd..3b58bff708 100644 --- a/docs/src/details/xml/xml/index.rst +++ b/docs/src/details/xml/xml/index.rst @@ -10,3 +10,4 @@ XML Overview overview syntax + license diff --git a/docs/src/details/xml/xml/overview.rst b/docs/src/details/xml/xml/overview.rst index f8cb0e5164..b4e117bb35 100644 --- a/docs/src/details/xml/xml/overview.rst +++ b/docs/src/details/xml/xml/overview.rst @@ -8,28 +8,28 @@ Overview .. |nbsp| unicode:: U+000A0 .. NO-BREAK SPACE :trim: -LVGL's XML Module implements LVGL's Declarative UI by making it possible to -describe UIs in XML. +Introduction +************ -Describing the UI in XML in a declarative manner offers several advantages: +LVGL's XML Module implements LVGL's Declarative UI by making it possible to describe +UIs in XML. -- XML files can be loaded at runtime (e.g., from an SD card), allowing you to change - the application's UI without changing the firmware. -- XML files can also be loaded dynamically, enabling use cases such as creating - UIs from plugins or apps downloaded by the firmware. -- XML is simpler to write than C, enabling people with different skill sets to create LVGL UIs. -- XML is textual data, making it easy to parse and manipulate with a large number of - programming and scripting languages. -- XML can be used to generate LVGL code in any language. -- XML helps separate the view from the internal logic. -- The XML syntax uses the same properties as the C API, so it's easy to learn. E.g., - style properties like ``bg_color``, ``line_width``, or widget properties like ``width``, - ``height``, label ``text``, etc. -- A powerful data binding engine allows you to easily bind widgets to global data. +Using XML instead of pure drag-and-drop editing has several advantages: -The XML file can be written by hand, but it's highly recommended to use `LVGL's -UI editor `__ to write the XML files. This UI editor -makes UI development much faster by providing features like: +- **Familiar syntax** works like HTML, easy to learn and read +- **Version control friendly** plain text with human-readable diffs, no binary files +- **Easy to share** copy, paste, and send as text +- **Reusable patterns** copy and reuse snippets across projects +- **Automation ready** scripts and CI/CD can process XML effortlessly +- **AI compatible** AI tools can read, generate, and refactor XML +- **Modular by design** create reusable components for structured UIs +- **Fast to edit** quicker to type than to drag and drop with a mouse +- **Runtime loading** parse XML at runtime without recompiling +- **Cross-platform** the same XML works across all LVGL targets + +The XML file can be written by hand, but it's highly recommended to use `LVGL Pro's +Editor ` to write the XML files. The Editor makes UI development much faster by +providing features like: - Instant preview of the XML files (components, screens) - Inspector mode to visualize widget sizes, paddings, etc. @@ -38,21 +38,6 @@ makes UI development much faster by providing features like: - Online share/preview for collaboration and testing - `Figma `__ integration to easily reimplement Figma designs - - -Using the XML files -******************* - -If writing XMLs by hand, the concept is very simple: - -1. When ``LV_USE_XML`` is enabled, LVGL's built-in widgets and other XML parsers for styles, events, - data bindings, etc., are registered automatically. -2. The XML files created by the user (such as Screens, Components, Images, Fonts, etc.) can be - registered (loaded) at runtime, and screen or component instances can also be created based on the - XML "blueprints". -3. The UI elements created from XML look like any normal widgets, so functions of the C API can be applied - to them. E.g., start an animation, add a special style, etc. - UI Elements *********** @@ -119,3 +104,17 @@ can be defined. Multiple ``globals.xml`` files can be loaded if needed, but each will be saved in the same global scope, meaning duplicated items will be added only once. + + +Using the XML Files +******************* + +The XML files can be used in two ways: + +1. Load them directly at runtime +2. Convert them to C code by using the Editor or the CLI + +Both use cases are covered in detail in the :ref:`Integration ` +section. + +