From 0468f947531656078bc49b7269d2b7f5e1b856bc Mon Sep 17 00:00:00 2001 From: Pranta Dastider Date: Tue, 11 Feb 2025 18:31:21 +0100 Subject: [PATCH] QmlDesigner: Update the workflow to include new information This update includes the differences between old and new project structure in Qt Design Studio. It also mentions a way to convert the old Qt Design Studio Projects to the new structure. Fixes: QDS-13960 Fixes: QDS-12522 Fixes: QDS-14705 Change-Id: I03e0cc88dfca974a132ea3100b54e41ace21ea3d Reviewed-by: Mats Honkamaa Reviewed-by: Johanna Vanhatapio --- .../images/studio-cmake-dependencies.webp | Bin 0 -> 5846 bytes .../studio-designer-developer-workflow.qdoc | 145 ++++++++++++++---- 2 files changed, 113 insertions(+), 32 deletions(-) create mode 100644 doc/qtdesignstudio/images/studio-cmake-dependencies.webp diff --git a/doc/qtdesignstudio/images/studio-cmake-dependencies.webp b/doc/qtdesignstudio/images/studio-cmake-dependencies.webp new file mode 100644 index 0000000000000000000000000000000000000000..ec35bcb697a99d17f0367028ddebd5a6725287e2 GIT binary patch literal 5846 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 literal 0 HcmV?d00001 diff --git a/doc/qtdesignstudio/src/developers/studio-designer-developer-workflow.qdoc b/doc/qtdesignstudio/src/developers/studio-designer-developer-workflow.qdoc index 0b6e133d0b8..998f89b74d2 100644 --- a/doc/qtdesignstudio/src/developers/studio-designer-developer-workflow.qdoc +++ b/doc/qtdesignstudio/src/developers/studio-designer-developer-workflow.qdoc @@ -14,8 +14,8 @@ \QDS enables designers and developers to work together on common projects to develop applications. Designers use the \l{Design views}{views} - in the \uicontrol Design mode to modify \l{UI files} (\e .ui.qml), - whereas developers use Qt Creator to work on the Qt Quick (\e .qml) and + in the \uicontrol Design mode to modify \l{UI files} (\c .ui.qml), + whereas developers use Qt Creator to work on the Qt Quick (\c .qml) and other files that are needed to implement the application logic and to prepare the application for production. @@ -23,13 +23,13 @@ working Qt 6 application that you can build and run in Qt Creator using CMake. Therefore, you can open, build, and run the projects with Qt Creator. - \QDS continues to use the \e .qmlproject file format, while Qt Creator uses a - \e CMakeLists.txt file as the project file. This enables you to share + \QDS continues to use the \c .qmlproject file format, while Qt Creator uses a + \c CMakeLists.txt file as the project file. This enables you to share your project as a fully working C++ application with developers. You can also enable \QDS projects for Python development. When enabled, \QDS creates a Python folder within the project folder with the file - \e {main.py}. Use this file to start the development in Python for the UI + \c {main.py}. Use this file to start the development in Python for the UI made with \QDS. \section1 Exporting a \QDS project for C++ development @@ -52,7 +52,7 @@ \li Go to \uicontrol {File} > \uicontrol {Export Project} > \uicontrol {Enable CMake Generator}. This creates a - \e {CMakeLists.txt} file in your project folder. + \c {CMakeLists.txt} file in your project folder. \note Enabling this option tracks the changes made to the project in \QDS and automatically updates in Qt Creator. The connection works unless you @@ -63,11 +63,11 @@ \section1 Opening the \QDS project in Qt Creator - Open the \e {CMakeLists.txt} file in Qt Creator: + Open the \c {CMakeLists.txt} file in Qt Creator: \list 1 \li In Qt Creator, select \uicontrol File > \uicontrol {Open File or Project}. - \li Browse through your project directory and select the \e {CMakeLists.txt}. + \li Browse through your project directory and select \c {CMakeLists.txt}. Then select \uicontrol Open. \image studio-project-cmake-generation.webp "Project folder after CMake generation" @@ -85,7 +85,7 @@ \endlist \note \QDS 4.4 and earlier versions have a project structure where - different explicit import paths such as \e imports or \e asset_imports + different explicit import paths such as \c imports or \c asset_imports reference assets such as images or mesh files separately in their own scope. So, linking them from one module to another does not work in the generated CMake-based C++ application. Such cross-modular references are @@ -93,30 +93,27 @@ All the import assets are now bundled in the same folder, so the CMake generation works properly. - \section1 CMake Generator - \details {FAQ} + \section1 Learn more about the CMake Generator - Learn how the CMake generator works. - - \section2 What does the CMake Generator convert? - The CMake Generator converts the contents of the \e .qmlproject file + \section2 Converted contents of the CMake Generator + The CMake Generator converts the contents of the \c .qmlproject file to CMake. \note A \QDS project can run with a missing path or file filter. However, CMake generation can fail due to missing elements in the - \e .qmlproject file. + \c .qmlproject file. - \section2 Which changes are tracked by the CMake Generator? - All the files that are listed in \e .qmlproject are tracked by the - CMake Generator. Editing the \e .qmlproject file triggers a CMake + \section2 Changes tracked by the CMake Generator + All the files that are listed in \c .qmlproject are tracked by the + CMake Generator. Editing the \c .qmlproject file triggers a CMake generation. Adding, removing, and renaming files are tracked. - \section2 Why do you need Stubb or Mock QML data for \QDS? + \section2 Stubb or mock QML data for \QDS \QDS doesn't understand C++ code, so the CMake Generator ignores any components or properties made with C++. If you want a similar representation in \QDS for the components or properties created with C++, add a QML mock file for \QDS. Keep these mock files in a dedicated folder within your project folder. You can later add a \c mockImports - variable within the \e .qmlproject file and include the folder path + variable within the \c .qmlproject file and include the folder path with mock files in the \c mockImports variable. CMake ignores all folders and files included in the \c mockImports variable. So they only stay in the \QDS space and are not converted with CMake Generator. @@ -126,17 +123,101 @@ mockImports: [ "MockDatas" ] \endcode Here, MockDatas is a folder in your project folder with all the files - with QML mock data. If you include this code in the \e .qmlproject file, + with QML mock data. If you include this code in the \c .qmlproject file, the CMake Generator ignores everything inside the MockDatas folder. - \section2 Is it possible to manually change the contents of the \e CMakeLists.txt files? - Yes, you can make changes to the \e CMakeLists.txt files existing in the - App and the Root folders of your project. The \e CMakeLists.txt files + \section2 Manually changing the contents of the \c CMakeLists.txt files + You can change the \c CMakeLists.txt files existing in the + App and the Root folders of your project. The \c CMakeLists.txt files in other folders of your project are overwritten as soon as the - CMake generator runs next time. Only the \e CMakeLists.txt files in + CMake generator runs next time. Only the \c CMakeLists.txt files in the App and the Root folders of your project are not overwritten. - \enddetails + \section2 Changes in the project structure since \QDS 4.5 + \QDS project structure has been changed since \QDS 4.5. Now, there is + only a common import path (./) at the root of the project. This makes + the project in line with the QML compiler and tooling. Learn more about + the \l {Qt Quick Compiler} {QML compiler}. + + Find the difference between the project structures from the table below: + + \table + \header + \li Project structure before \QDS 4.5 + \li Project structure since \QDS 4.5 + \row + \li Two import folders: \c imports and \c assets_imports. + \li Imports directly to the root project folder. + \row + \li 2D assets imported to \c assets imports. + \li 2D assets imported to \c Generated. + \row + \li 3D assets imported to \c assets_imports/QtQuick3DAssets. + \li 3D assets imported to \c Generated/QtQuick3D. + \endtable + + \section2 Converting a project to the current \QDS project structure + + To convert the structure of a project created with a \QDS version + earlier than 4.5 to the current project structure: + \list 1 + \li Move the project files from \c ./import/ProjectName to the + \c ./ProjectName folder. If you have additional modules in + \c {./import/}, move them similarly. You do not need to adjust the URI. + \li Move the project files from \c ./assets_imports to the + \c ./Generated folder. Adjust the import URIs throughout the project. + \li Rename \c ./content to \c ./ProjectNameContent. + Adjust the import URIs throughout the project. + \li Make sure that URIs in \c qmldir files match the folder structure. + \note A qmldir defined in \c ./Generated/QtQuick3D/DangerArrow/qmldir + should be defined as \c {module Generated.QtQuick3D.DangerArrow}. + This ensures the same URIs between \QDS and the generated + \c CMakeLists files. Ensure that \c import in \c .qml files + matches these URIs. + \li Add missing filters to the \c .qmlproject file. + \list + \li If a folder contains \c QML and \c JavaScript files, define + \c QMLFiles and \c JavaScriptFiles in the \c .qmlproject file. + \li For the files that don't have dedicated keywords, such as + \c ImageFiles or \c FontFiles, add them to the + \c .qmlproject as a filter. To add \c WAV or \c MP3 files, + define filters in the \c .qmlproject file like this: + \code + Files { + filter: "*.wav;*.mp3" + } + \endcode + To learn more about the defined file formats, see + \l {https://doc.qt.io/archives/QtForMCUs-2.5/qtul-qmlproject-reference.html#imagefiles} {here}. + \endlist + \li Remove all the \c CMakeLists.txt files. The \e CMakeLists.txt files are + automatically generated when you access CMake generation using + \uicontrol File > \uicontrol {Export Project} > + \uicontrol {Enable CMake Generator}. + \li In the \c examples/dataImports/DataModels/ folder, update the + \c ExamplesModel.qml and \c ExamplesModelV2.qml files to reflect + \c qmlFileName correctly after a successful CMake generation. + \li If the project uses shaders, add the following snippet to the + \c .qmlproject file: + \code + ShaderTool { + args: "-s --glsl \"100 es,120,150\" --hlsl 50 --msl 12" + files: [ "UntitledProject3DContent/shaders/*" ] + } + \endcode + \endlist + + \section2 Importing Qt Quick Designer Components with CMake Generator + Some Qt Quick components, such as \uicontrol {Pie}, \uicontrol {Regular Polygon}, + \uicontrol Star, and others are exclucive to \QDS. For more information, see + \l {https://doc.qt.io/qtquickstudiocomponents/qtquickstudio-components-index.html}{here}. + These components get bundled within the \c Dependencies + folder after the CMake generation. + In the previous versions of \QDS, you had to manually include these components + from a \l {https://github.com/qt-labs/qtquickdesigner-components}{git repository} + after the CMake generation. + + \image studio-cmake-dependencies.webp "Dependencies folder having all the exclusive Qt Design Studio components after CMake generation" \section1 Exporting a \QDS project for Python development @@ -150,10 +231,10 @@ \li Go to \uicontrol {File} > \uicontrol {Export Project} > \uicontrol {Enable Python Generator}. This creates a Python folder in your project folder. You can find the - \e {main.py} file in the Python folder. This file is + \c {main.py} file in the Python folder. This file is necessary for working in Python. - \note Do not modify the contents of the \e {autogen} folder inside + \note Do not modify the contents of the \c {autogen} folder inside the Python folder manually; they are overwritten with each change you make in the project. @@ -162,7 +243,7 @@ \section1 Opening the \QDS project with Python - After your project have the Python folder and the \e {main.py} file + After your project have the Python folder and the \c {main.py} file available, you can start setting up your Python environment for developing with \QDS projects. @@ -196,13 +277,13 @@ \endcode \li Run the command below in the command prompt to open the - \e {main.py} file from your project. + \c {main.py} file from your project. \code python Python\main.py \endcode \note Any extra data or Python files you add to the project and, - import from \e {main.py} must remain inside the \c {Python} folder. + import from \c {main.py} must remain inside the \c {Python} folder. \endlist Your \QDS project now runs in Python. Use Python to add more