feedc0de/qt-creator
1
0
Fork 0
forked from qt-creator/qt-creator
Code Pull Requests Activity

Doc: Show "Using QML Modules with Plugins" in QDS Manual

Browse Source 
This topic is also interesting to QDS users, who want to use
C++ plugins to simulate data in their applications.

Show and hide parts of the topic depending on whether the
QC Manual or QDS Manual is built.

Fixes: QDS-3126
Change-Id: Iba55de73cda265f3261bf6f790103251a6ef01db
Reviewed-by: Thomas Hartmann <thomas.hartmann@qt.io>
This commit is contained in:
Leena Miettinen
2020-11-24 13:45:43 +01:00
parent ecfa623ee8
commit c01711435f
4 changed files with 63 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
doc/qtcreator/src/qtquick/creator-only/qtquick-modules-with-plugins.qdoc → doc/qtcreator/src/qtquick/qtquick-modules-with-plugins.qdoc
View File

@@ -1,6 +1,6 @@
/****************************************************************************
**
** Copyright (C) 2019 The Qt Company Ltd.
** Copyright (C) 2020 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Creator documentation.
@@ -30,9 +30,14 @@
// **********************************************************************
/*!
\previouspage creator-quick-ui-forms.html
\page creator-qml-modules-with-plugins.html
\if defined(qtdesignstudio)
\previouspage studio-simulink.html
\nextpage studio-debugging.html
\else
\previouspage qtquick-iso-icon-browser.html
\nextpage quick-converting-ui-projects.html
\endif
\title Using QML Modules with Plugins
@@ -41,16 +46,23 @@
the contained components, and therefore, the modules must provide extra type
information for code completion and the semantic checks to work correctly.
To create a QML module and make it appear in the \uicontrol Library in
To create a QML module and make it appear in the \uicontrol Library view in
the Design mode:
\list 1
\li Create custom QML controls and place all the \c .qml files in a
directory dedicated to your module.
directory dedicated to your module. For example:
\c {imports\asset_imports}.
\li Create a \c qmldir file for your module and place it in the module
directory. For more information, see
\li For Qt Quick UI projects (.qmlproject), specify the path to
the directory that contains the module in the .qmlproject file
of the application where you want to use the module
as a value of the \c importPaths variable. For example
\c{importPaths: [ "imports", "asset_imports" ]}.
\li Create a \c qmldir file for your module and place it
in the module directory. For more information, see
\l {Module Definition qmldir Files}.
\li Create a \c qmltypes file, preferably using \c qmlplugindump.
@@ -60,39 +72,45 @@
\li Create a \c .metainfo file for your module and place it in the
\c designer directory. Meta information is needed to display the
components in the \uicontrol {QML Types} tab in the \uicontrol
components in the \uicontrol {QML Types} tab in \uicontrol
Library. Use a metainfo file delivered with Qt, such as
\c qtquickcontrols2.metainfo, as an example.
\li Import your module into a project using \c QML_IMPORT_PATH in the
.pro file: \c {QML_IMPORT_PATH += path/to/module}.
For more information, see \l {Importing QML Modules}.
\if defined(qtcreator)
\li Import the module into the project, as instructed in
\l {Importing QML Modules}.
\li Make sure that the QML emulation layer used in the Design mode is built with
the same Qt version as your QML modules. For more information, see
\l {Running QML Modules in Design Mode}. You can also try
skipping this step and take it later, if necessary.
\else
\li Build your module using the same Qt version and compiler as \QDS.
For more information, see \l {Running QML Modules in Design Mode}.
\endif
\endlist
Your module should now appear in the \uicontrol {QML Imports} tab in the
Your module should now appear in the \uicontrol {QML Imports} tab in
\uicontrol Library in the Design mode. Your components should appear in the
\uicontrol {QML Types} tab if a valid \c .metainfo file is in place.
\if defined(qtcreator)
\section1 Registering QML Types
When you write a QML module or use QML from a C++ application, you typically
register new types with the qmlRegisterType() function or expose some
class instances with \l{QQmlContext::setContextProperty()}. The \QC C++
code model now scans for these calls and
tells the QML code model about them. This means that properties are
displayed during code completion and the JavaScript code checker does not
When you write a QML module or use QML from a C++ application, and the C++
is a part of your qmake project, you typically register new types with the
\c qmlRegisterType() function or expose some class instances with
\l{QQmlContext::setContextProperty()}. The \QC C++ code model now scans for
these calls and tells the QML code model about them. This means that properties
are displayed during code completion and the JavaScript code checker does not
complain about unknown types. However, this works only when the source code
is available, and therefore, you must explicitly generate type information
for QML modules with plugins before distributing them.
Classes registered with \c qmlRegisterType() can be used as backend objects
in the Design mode. For more information, see \l {Adding Connections}.
\endif
\section1 Generating qmltypes Files
@@ -122,9 +140,11 @@
You can safely ignore the debug output.
\if defined(qtcreator)
For Qt 4.7.x, you can compile a version of the tool called \c qmldump from
the sources in \c{<QtCreator>/share/qtcreator/qml/qmldump} if the Qt version
contains private headers.
\endif
\section2 Dumping Plugins Automatically
@@ -133,12 +153,14 @@
However, this automatic dumping is a fallback mechanism with many points of
failure and you cannot rely upon it.
\if defined(qtcreator)
\section1 Importing QML Modules
By default, \QC will look in the QML import path of Qt for QML modules.
If your applications adds additional import paths that \QC should use,
then you can specify those using \c{QML_IMPORT_PATH} in the \c{.pro} file of your
application.
If you use qmake and your application adds additional import paths that
\QC should use, specify them using \c{QML_IMPORT_PATH} in the \c{.pro}
file of your application: \c {QML_IMPORT_PATH += path/to/module}.
If you use CMake, add the following command to the CMakeLists.txt file to
set the QML import path:
@@ -148,14 +170,16 @@
\endcode
The import path affects all the targets built by the CMake project.
\endif
\section1 Running QML Modules in Design Mode
A QML emulation layer (also called QML Puppet) is used in the Design mode to
render and preview images and to collect data. To be able to render custom types
correctly from QML modules, the emulation layer must be built with the same
Qt version as the QML modules.
Qt version and compiler as the QML modules.
\if defined(qtcreator)
By default, a fallback emulation layer is provided by \QC and built with the same
Qt version as \QC. Therefore, your QML modules will mostly not work out of
the box.
@@ -165,17 +189,27 @@
\uicontrol Options > \uicontrol {Qt Quick} > \uicontrol {Qt Quick Designer} >
\uicontrol {Use QML emulation layer which is built by the selected Qt} radio button.
\QC builds the emulation layer when you select the Design mode.
\else
On Windows, select \uicontrol Help > \uicontrol {About Qt Design Studio} to
check the Qt version and compiler that you need to use to build your plugin.
For example: \c {Based on Qt 5.15.2 (MSVC 2019, 64 bit)}.
On macOS, select \uicontrol {Qt Design Studio} >
\uicontrol {About Qt Design Studio} to see something like:
\c {Based on Qt 5.15.2 (Clang 10.0 (Apple), 64 bit)}.
\endif
A plugin should behave differently depending on whether it is run by the
emulation layer or an application. For example, animations should not be run
in the Design mode. You can use the value of the QML_PUPPET_MODE
in the Design mode. You can use the value of the \c QML_PUPPET_MODE
environment variable to check whether the plugin is currently being run
by an application or edited in the Design mode.
If you want to use a different module in the Design mode than in your actual
application for example to mockup C++ items, then you can use \c{QML_DESIGNER_IMPORT_PATH}
in the \c{.pro} file (for qmake projects), or declare and set the property
qmlDesignerImportPaths in your product (for Qbs projects).
\c qmlDesignerImportPaths in your product (for Qbs projects).
Modules in the import paths defined in \c{QML_DESIGNER_IMPORT_PATH} will be
used only in the Design mode.
For an example, see \l {Qt Quick Controls - Contact List}.

4
doc/qtdesignstudio/src/qtdesignstudio-simulation-overview.qdoc
View File

@@ -52,5 +52,9 @@
Use the Simulink connector to connect a Simulink Simulation Model to
your UI. Simulink is a MATLAB-based graphical programming environment
for modeling, simulating, and analyzing multi-domain dynamic systems.
\li \l{Using QML Modules with Plugins}
You can load C++ plugins for QML to simulate data.
\endlist
*/

2
doc/qtdesignstudio/src/qtdesignstudio-simulink.qdoc
View File

@@ -26,7 +26,7 @@
/*!
\previouspage studio-javascript.html
\page studio-simulink.html
\nextpage studio-debugging.html
\nextpage creator-qml-modules-with-plugins.html
\title Simulating Dynamic Systems

1
doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc
View File

@@ -170,6 +170,7 @@
\li \l{Loading Placeholder Data}
\li \l{Simulating Application Logic}
\li \l{Simulating Dynamic Systems}
\li \l{Using QML Modules with Plugins}
\endlist
\li \l{Debugging and Profiling}
\list