mirror of
https://github.com/lvgl/lvgl.git
synced 2026-05-24 00:07:03 +08:00
docs(editor): add docs specific to editor (#8972)
This commit is contained in:
Victor Wheeler
GitHub
Binary file not shown.
|
After Width: | Height: | Size: 47 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 100 KiB |
@@ -0,0 +1,3 @@
|
||||
.. _VSCode Simulator: https://github.com/lvgl/lv_port_pc_vscode
|
||||
.. _Figma: https://www.figma.com/
|
||||
.. _see all plans: https://pro.lvgl.io/pricing
|
||||
@@ -1,22 +1,55 @@
|
||||
.. _editor_hotkeys:
|
||||
|
||||
========
|
||||
Overview
|
||||
========
|
||||
=======
|
||||
Hotkeys
|
||||
=======
|
||||
|
||||
TODO: describe the purpose and advantages, it's related to XML, has tools (CLI, online share, figma), 3-4 paragraph
|
||||
Activate Auto-Completion
|
||||
************************
|
||||
|
||||
Getting started
|
||||
***************
|
||||
While the cursor is anywhere within the :ref:`Editor Pane`:
|
||||
|
||||
TODO Work on Windows, Linux, MacOS and VSCode. Link the guides.
|
||||
|
||||
Check out the examples (Learn by examples page)
|
||||
or laern more about XML
|
||||
|
||||
Project
|
||||
*******
|
||||
|
||||
What is a project? What can you describe in project.xml? How does nested projects work?
|
||||
:Ctrl+Space: Pop-up auto-completion list
|
||||
|
||||
|
||||
|
||||
Value Modification
|
||||
******************
|
||||
|
||||
While the cursor is within an attribute's value:
|
||||
|
||||
:Ctrl+Up:
|
||||
:Ctrl+Down: Modify value by 1 (with live update in preview)
|
||||
|
||||
:Ctrl+Shift+Up:
|
||||
:Ctrl+Shift+Down: Modify value by 10 (with live update in preview)
|
||||
|
||||
|
||||
|
||||
Export and Build
|
||||
****************
|
||||
|
||||
:Ctrl+E: Export code only
|
||||
:Ctrl+B: Export code and recompile
|
||||
:Ctrl+Shift+B: Clean and rebuild
|
||||
|
||||
|
||||
|
||||
Preview Pane
|
||||
************
|
||||
|
||||
:Ctrl+mousewheel: Zoom in and out
|
||||
:Ctrl++: Zoom in
|
||||
:Ctrl+-: Zoom out
|
||||
:Ctrl+0: Reset zoom
|
||||
:Ctrl+Shift+0: Fit to screen
|
||||
:Two-Fingered Scroll: Pan preview
|
||||
|
||||
|
||||
Pressing the Ctrl key also allows you to:
|
||||
|
||||
- visualise bounding box, padding, margins and click area,
|
||||
- check size and position by dragging,
|
||||
- perform measurement,
|
||||
- double click to jump to the XML file,
|
||||
- single click to change editor focus to the matching XML element.
|
||||
|
||||
@@ -1,14 +1,33 @@
|
||||
.. include:: substitutions.txt
|
||||
.. _editor:
|
||||
.. _lvgl pro:
|
||||
|
||||
=========
|
||||
UI Editor
|
||||
|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.
|
||||
|
||||
|
||||
.. toctree::
|
||||
:class: toctree-1-deep
|
||||
:maxdepth: 2
|
||||
|
||||
overview
|
||||
install
|
||||
vscode
|
||||
user_interface
|
||||
hotkeys
|
||||
nesting_projects
|
||||
|
||||
.. TODO: Online Preview?
|
||||
|
||||
.. TODO: CLI?
|
||||
|
||||
@@ -1,28 +1,65 @@
|
||||
.. include:: substitutions.txt
|
||||
.. _editor_install:
|
||||
|
||||
============
|
||||
Installation
|
||||
============
|
||||
|
||||
Works on Windows, Linux, MacOS and VSCode (Link the guides).
|
||||
Here are the guides to download and install |lvglpro| appropriate for your platform:
|
||||
|
||||
|
||||
|
||||
Windows
|
||||
*******
|
||||
|
||||
Instructions
|
||||
Navigate to https://pro.lvgl.io/#download and press the [Download] button and save the
|
||||
resulting image to your workstation. Then execute the downloaded installer to install
|
||||
|lvglpro|.
|
||||
|
||||
|
||||
Troubleshooting
|
||||
---------------
|
||||
|
||||
|
||||
|
||||
Linux
|
||||
*****
|
||||
|
||||
Installing |lvglpro| on Linux is as simple as downloading the AppImage, making it
|
||||
executable (``chmod +x LVGLPro.AppImage``), and running it.
|
||||
|
||||
|
||||
|
||||
Troubleshooting
|
||||
---------------
|
||||
|
||||
Launching on Linux
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
:Problem: Some users have experienced trouble launching |lvglpro| 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:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
(process:3943): Gtk-ERROR **: 11:45:01.301: GTK 2/3 symbols detected.
|
||||
Using GTK 2/3 and GTK 4 in the same process is not supported
|
||||
Trace/breakpoint trap (core dumped)
|
||||
|
||||
:Solution: Specify the gtk version of the application with ``--gtk-version=3``.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
./path/to/editor.AppImage --gtk-version=3
|
||||
|
||||
|
||||
|
||||
MacOS
|
||||
*****
|
||||
|
||||
.. TODO Gabor
|
||||
|
||||
|
||||
Troubleshooting
|
||||
---------------
|
||||
|
||||
@@ -0,0 +1,9 @@
|
||||
.. include:: substitutions.txt
|
||||
.. _nesting projects:
|
||||
|
||||
================
|
||||
Nesting Projects
|
||||
================
|
||||
|
||||
|
||||
.. TODO Gabor
|
||||
@@ -1,63 +1,66 @@
|
||||
.. include:: external_links.txt
|
||||
.. include:: substitutions.txt
|
||||
.. _editor_overview:
|
||||
|
||||
========
|
||||
Overview
|
||||
========
|
||||
|
||||
TODO: describe the purpose and advantages, it's related to XML, has tools (CLI, online share, figma), 3-4 paragraph
|
||||
|lvglpro| accelerates UI development by
|
||||
|
||||
Getting started
|
||||
***************
|
||||
- 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).
|
||||
|
||||
TODO Work on Windows, Linux, MacOS and VSCode. Link the guides.
|
||||
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.
|
||||
|
||||
Login and Licences (trial, buy licence on pro.lvgl.io, read more on the licences page)
|
||||
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.
|
||||
|
||||
Check out the examples (Learn by examples page)
|
||||
or learn more about XML
|
||||
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.
|
||||
|
||||
User Interface
|
||||
**************
|
||||
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.
|
||||
|
||||
Screen shot, briefly describe the main parts
|
||||
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.
|
||||
|
||||
XML Editor
|
||||
----------
|
||||
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.
|
||||
|
||||
Autocomplete, validation
|
||||
|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).
|
||||
|
||||
|
||||
|
||||
Login and Licensing
|
||||
*******************
|
||||
|
||||
.. TODO Gabor (trial, buy licence on pro.lvgl.io, read more on the licences page)
|
||||
|
||||
Inspector
|
||||
---------
|
||||
|
||||
- What is it? (show the rendered content, the user click on it to try out)
|
||||
- How to use? (Press Ctrl or turn on by the button)
|
||||
|
||||
- visualise bounding box, padding, maring and click area
|
||||
- chege size and position by dragging
|
||||
- measurement
|
||||
- double click jumps to the XML file
|
||||
- single click focuses the matching XML
|
||||
|
||||
20 sec video to show all these
|
||||
|
||||
|
||||
How does it work?
|
||||
*****************
|
||||
|
||||
- LVGL has a built-in XML parser that can create UIs at runtime
|
||||
- the inspector uses LVGL as it is
|
||||
- the editor sends the XML files to LVGL
|
||||
- the editor ask LVGL to create an instance of the opened XML file
|
||||
- when the xml changes only the opened XML file is uploaded, the screen is cleared, and a new instance is created
|
||||
- the XML editor parses the XML files of the LVGL widgets and the user's XML files to validate the XMLs
|
||||
- code is also exported by parsing the XML files
|
||||
|
||||
Project
|
||||
*******
|
||||
|
||||
- What is a project?
|
||||
- What can you describe in project.xml?
|
||||
- How does nested projects work?
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,4 @@
|
||||
.. -------- Custom Substitutions --------
|
||||
.. |nbsp| unicode:: U+000A0 .. NO-BREAK SPACE
|
||||
:trim:
|
||||
.. |lvglpro| replace:: UI |nbsp| Editor
|
||||
@@ -0,0 +1,191 @@
|
||||
.. include:: substitutions.txt
|
||||
.. _user interface:
|
||||
|
||||
==============
|
||||
User Interface
|
||||
==============
|
||||
|
||||
|
||||
|
||||
First Run
|
||||
*********
|
||||
|
||||
The first time you launch |lvglpro|, it will pop up a window with the message
|
||||
|
||||
"Pulling Container image for LVGL, this may take a few minutes...".
|
||||
|
||||
This message means the Editor is downloading a pre-configured container image that
|
||||
includes all the necessary tools and dependencies for building LVGL projects.
|
||||
|lvglpro| handles (and updates) the container automatically in the background. The
|
||||
process can take a few minutes the first time, depending on your internet speed, but
|
||||
it only happens once. After that, the container is reused for future sessions.
|
||||
|
||||
When a new version of the container is published (e.g. with updated toolchains, build
|
||||
logic, etc.), the Editor automatically checks for and pulls the latest version. You
|
||||
won’t need to do anything manually, it stays up-to-date in the background.
|
||||
|
||||
|
||||
|
||||
Login
|
||||
*****
|
||||
|
||||
.. TODO
|
||||
|
||||
hints:
|
||||
- enter your email address
|
||||
- you will recevie an email with an OTP (On Time Password)
|
||||
- it will create a user for you
|
||||
- no password is needed
|
||||
|
||||
|
||||
|
||||
Licence Selection
|
||||
*****************
|
||||
|
||||
.. TODO
|
||||
|
||||
After logging in you need select a licence for the list.
|
||||
|
||||
|
||||
|
||||
Initial Display
|
||||
***************
|
||||
|
||||
.. figure:: /_static/images/editor_initial_ui.png
|
||||
:align: center
|
||||
:alt: |lvglpro| Opening User Interface
|
||||
|
||||
..
|
||||
|
||||
|lvglpro| Opening User Interface
|
||||
|
||||
|
||||
Component Libraries vs Regular Projects
|
||||
---------------------------------------
|
||||
|
||||
A Component Library is a set of 1 or more XML files that can be used in any
|
||||
|lvglpro| Project.
|
||||
|
||||
|lvglpro| UI Projects use Component Libraries, but Component Libraries do not
|
||||
use UI Projects.
|
||||
|
||||
|
||||
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
|
||||
********************************
|
||||
|
||||
.. figure:: /_static/images/editor_interface.png
|
||||
:align: center
|
||||
:alt: |lvglpro| User Interface
|
||||
|
||||
..
|
||||
|
||||
|lvglpro| User Interface
|
||||
|
||||
|
||||
Menu
|
||||
----
|
||||
|
||||
|lvglpro| has the usual File / View / Edit / etc. application menu.
|
||||
|
||||
|
||||
.. _project files pane:
|
||||
|
||||
Project Files Pane
|
||||
------------------
|
||||
|
||||
The left panel is a typical "project-tree" navigation panel. It allows you to
|
||||
efficiently and conveniently create, open and rename files and manage your project.
|
||||
|
||||
The subdirectories shown in the project are for the respective type of UI components
|
||||
(i.e. Screens, Widgets, Components, Fonts and Images).
|
||||
|
||||
|
||||
.. _editor pane:
|
||||
|
||||
Editor Pane
|
||||
-----------
|
||||
|
||||
The Editor Pane appears in the middle of the window. This is where you make
|
||||
|lvglpro| do valuable work for you, building your UI or Component Library. It is here
|
||||
that you can observe and edit the contents of any file in your project, but its
|
||||
specialty is editing XML that defines UI components (:ref:`xml_widgets`,
|
||||
:ref:`xml_components` and :ref:`xml_screens`). While editing XML, |lvglpro| has a
|
||||
powerful auto-completion-enabled user interface, which makes defining, editing and
|
||||
validating UI components a breeze. Similar to context-sensitive assistance
|
||||
available in other "smart editors", the Editor Pane assists you with almost every
|
||||
keystroke, considerably shortening the learning curve required to produce finished,
|
||||
professional-quality UIs with |lvglpro|.
|
||||
|
||||
|
||||
.. _right panel:
|
||||
|
||||
Right Panel
|
||||
-----------
|
||||
|
||||
.. _preview pane:
|
||||
.. _inspector:
|
||||
|
||||
Preview Pane and Inspector
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
When the Editor Pane is editing an XML file defining a Component or Widget, the
|
||||
Preview Pane shows a live preview of the XML UI definition being edited, pushed
|
||||
through *real LVGL rendering* so you can instantly see the results of your work, that
|
||||
will match the final result produced by firmware, accurate down to the pixel.
|
||||
|
||||
Simultaneously, it allows you to interact with that UI to see how it will look and
|
||||
feel at runtime.
|
||||
|
||||
How it Works:
|
||||
|
||||
- LVGL has a built-in XML parser that can create UIs at runtime
|
||||
- the inspector uses LVGL as it is
|
||||
- the editor sends the XML files to LVGL
|
||||
- the editor asks LVGL to create an instance of the opened XML file
|
||||
- when the xml changes only the opened XML file is uploaded, the screen is cleared,
|
||||
and a new instance is created
|
||||
- the XML editor parses the XML files of the LVGL widgets and the user's XML files to
|
||||
validate the XMLs
|
||||
- code is also exported by parsing the XML files
|
||||
|
||||
Turn the Preview Pane into an Inspector by holding down the [Ctrl] key. The Inspector
|
||||
allows you to:
|
||||
|
||||
- visualise bounding box, padding, margins and click area
|
||||
- check size and position by dragging
|
||||
- perform measurement
|
||||
- double click to jump to the XML file
|
||||
- single click to change editor focus to the matching XML element
|
||||
|
||||
.. TODO Gabor 20 sec video to show all these
|
||||
|
||||
.. _console/subjects pane:
|
||||
|
||||
Output Pane
|
||||
~~~~~~~~~~~
|
||||
|
||||
The Output Pane contains a number of tabs where you can see various results, and
|
||||
manage certain lists as part of your project.
|
||||
|
||||
:Console Tab: contains "log output" of the internal actions taken and their results.
|
||||
|
||||
:Subjects Tab: contains list of the Observer-Pattern Subjects implemented in your XML
|
||||
source files. Each Subject represents a single "datum" in the
|
||||
application, that UI elements (Widgets and Components) can "observe"
|
||||
and reflect visually. See :ref:`xml_subjects` for more details.
|
||||
|
||||
:Test Tab: TODO: Description of Test Tab
|
||||
|
||||
Tabs Coming Soon: Tests, Translations, Animations
|
||||
|
||||
@@ -1,19 +0,0 @@
|
||||
.. _editor_vscode:
|
||||
|
||||
================
|
||||
VSCode extension
|
||||
================
|
||||
|
||||
|
||||
Overview
|
||||
*********
|
||||
|
||||
General overview
|
||||
|
||||
Works on Windows, Linux, MacOS too (Link the guides).
|
||||
|
||||
Usage
|
||||
*****
|
||||
|
||||
Troubleshooting
|
||||
***************
|
||||
@@ -4,7 +4,7 @@
|
||||
Learn by Examples
|
||||
=================
|
||||
|
||||
TODO
|
||||
.. TODO
|
||||
|
||||
Add 1 paragraph of description for each folder in lvgl/examples/xml
|
||||
and button to open them in the online preview
|
||||
|
||||
@@ -4,4 +4,4 @@
|
||||
Editor license
|
||||
==============
|
||||
|
||||
TODO: describe the pricing models and conditions
|
||||
.. TODO: describe the pricing models and conditions
|
||||
|
||||
@@ -1,4 +1,3 @@
|
||||
|
||||
.. _editor_figma:
|
||||
|
||||
=================
|
||||
@@ -8,17 +7,45 @@ Figma integration
|
||||
Overview
|
||||
********
|
||||
|
||||
When Figma is used to create a UI design, parts of it can be directly imported (or
|
||||
updated).
|
||||
|
||||
|
||||
Usage
|
||||
*****
|
||||
|
||||
To enable sync-ing with a Figma project, add a ``project_local.xml`` file if it isn't
|
||||
already there and add this to its content:
|
||||
|
||||
LVGL Figma plugin
|
||||
.. code-block:: xml
|
||||
|
||||
<project_local>
|
||||
<figma document="XXXXXX" token="YYYYY"/>
|
||||
</project_local>
|
||||
|
||||
where:
|
||||
|
||||
:XXXXXX: is the string after "design" in the Figma URL. For example, if the Figma
|
||||
URL is ``https://www.figma.com/design/P8NM0qOqgWfYpbENhAKqYb``, then the
|
||||
XXXXXX would be "P8NM0qOqgWfYpbENhAKqYb".
|
||||
|
||||
:YYYYY: is the Personal Access Token that you can generate as described in the
|
||||
`Manage Personal Access Tokens <https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens>`__
|
||||
article in Figma documentation.
|
||||
|
||||
Then, for each target style you want to be linked to a style from the Figma design,
|
||||
include a ``figma_node_id=...`` attribute in it. Thereafter, clicking the FigmaSync
|
||||
button will update each respective style from the updated Figma design.
|
||||
|
||||
|
||||
LVGL Figma Plugin
|
||||
-----------------
|
||||
|
||||
Connect Figma to the Editor
|
||||
---------------------------
|
||||
|
||||
Connecting Figma to the Editor
|
||||
------------------------------
|
||||
|
||||
|
||||
Sync data
|
||||
---------
|
||||
Synchronizing Data
|
||||
------------------
|
||||
|
||||
|
||||
Reference in New Issue
Block a user