diff --git a/docs/src/_static/images/editor_initial_ui.png b/docs/src/_static/images/editor_initial_ui.png new file mode 100644 index 0000000000..15e58545ec Binary files /dev/null and b/docs/src/_static/images/editor_initial_ui.png differ diff --git a/docs/src/_static/images/editor_interface.png b/docs/src/_static/images/editor_interface.png new file mode 100644 index 0000000000..cb94321c88 Binary files /dev/null and b/docs/src/_static/images/editor_interface.png differ diff --git a/docs/src/details/xml/editor/external_links.txt b/docs/src/details/xml/editor/external_links.txt new file mode 100644 index 0000000000..fc2e396caa --- /dev/null +++ b/docs/src/details/xml/editor/external_links.txt @@ -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 diff --git a/docs/src/details/xml/editor/hotkeys.rst b/docs/src/details/xml/editor/hotkeys.rst index bfc7219535..7c18bae95e 100644 --- a/docs/src/details/xml/editor/hotkeys.rst +++ b/docs/src/details/xml/editor/hotkeys.rst @@ -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. diff --git a/docs/src/details/xml/editor/index.rst b/docs/src/details/xml/editor/index.rst index a3b78041eb..bb48309bf6 100644 --- a/docs/src/details/xml/editor/index.rst +++ b/docs/src/details/xml/editor/index.rst @@ -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? diff --git a/docs/src/details/xml/editor/install.rst b/docs/src/details/xml/editor/install.rst index 5aade8cb39..493b20a000 100644 --- a/docs/src/details/xml/editor/install.rst +++ b/docs/src/details/xml/editor/install.rst @@ -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 --------------- diff --git a/docs/src/details/xml/editor/nesting_projects.rst b/docs/src/details/xml/editor/nesting_projects.rst new file mode 100644 index 0000000000..2824b340ac --- /dev/null +++ b/docs/src/details/xml/editor/nesting_projects.rst @@ -0,0 +1,9 @@ +.. 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 12cf53e7c3..b97b925747 100644 --- a/docs/src/details/xml/editor/overview.rst +++ b/docs/src/details/xml/editor/overview.rst @@ -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? diff --git a/docs/src/details/xml/editor/substitutions.txt b/docs/src/details/xml/editor/substitutions.txt new file mode 100644 index 0000000000..5e8c1b5e20 --- /dev/null +++ b/docs/src/details/xml/editor/substitutions.txt @@ -0,0 +1,4 @@ +.. -------- Custom Substitutions -------- +.. |nbsp| unicode:: U+000A0 .. NO-BREAK SPACE + :trim: +.. |lvglpro| replace:: UI |nbsp| Editor diff --git a/docs/src/details/xml/editor/user_interface.rst b/docs/src/details/xml/editor/user_interface.rst new file mode 100644 index 0000000000..ce29e261ae --- /dev/null +++ b/docs/src/details/xml/editor/user_interface.rst @@ -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 + diff --git a/docs/src/details/xml/editor/vscode.rst b/docs/src/details/xml/editor/vscode.rst deleted file mode 100644 index e809171744..0000000000 --- a/docs/src/details/xml/editor/vscode.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. _editor_vscode: - -================ -VSCode extension -================ - - -Overview -********* - -General overview - -Works on Windows, Linux, MacOS too (Link the guides). - -Usage -***** - -Troubleshooting -*************** diff --git a/docs/src/details/xml/learn_by_examples.rst b/docs/src/details/xml/learn_by_examples.rst index 2a5c3b98dd..84cd0570ac 100644 --- a/docs/src/details/xml/learn_by_examples.rst +++ b/docs/src/details/xml/learn_by_examples.rst @@ -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 diff --git a/docs/src/details/xml/license/editor.rst b/docs/src/details/xml/license/editor.rst index 1e3ee4dde8..552ae1201f 100644 --- a/docs/src/details/xml/license/editor.rst +++ b/docs/src/details/xml/license/editor.rst @@ -4,4 +4,4 @@ Editor license ============== -TODO: describe the pricing models and conditions +.. TODO: describe the pricing models and conditions diff --git a/docs/src/details/xml/tools/figma.rst b/docs/src/details/xml/tools/figma.rst index c81afd36c7..62023f00b6 100644 --- a/docs/src/details/xml/tools/figma.rst +++ b/docs/src/details/xml/tools/figma.rst @@ -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 + + + + + +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 `__ + 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 +------------------