1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
|
/****************************************************************************
**
** Copyright (C) 2022 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Creator documentation.
**
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
**
****************************************************************************/
// **********************************************************************
// NOTE: the sections are not ordered by their logical order to avoid
// reshuffling the file each time the index order changes (i.e., often).
// Run the fixnavi.pl script to adjust the links to the index order.
// **********************************************************************
/*!
\page creator-qml-modules-with-plugins.html
\if defined(qtdesignstudio)
\previouspage studio-simulink.html
\nextpage qtquick-adding-dynamics.html
\else
\previouspage creator-quick-ui-forms.html
\nextpage creator-using-qt-designer.html
\endif
\title Using QML Modules with Plugins
\l{Defining a QML Module}{QML modules} may use \l{Creating C++ Plugins for QML}
{C++ plugins} to expose components defined in C++ to QML applications.
To create a QML
\if defined(qtdesignstudio)
module and make it appear in the \l Components view:
\else
module:
\endif
\list 1
\li Create custom components and place all the \c .qml files in a
directory dedicated to your module. For example:
\c {imports\asset_imports}.
\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, as instructed in
\l {Generating Type Description Files}.
\li Create a directory named \c designer in your module directory.
\li Create a \c .metainfo file for your module and place it in the
\c designer directory.
\if defined(qtdesignstudio)
Meta information is needed to display the components in
\uicontrol Components.
\endif
Use a metainfo file delivered with Qt, such as
\c qtquickcontrols2.metainfo, as an example.
\if defined(qtcreator)
\li Import the module into the project, as instructed in
\l {Importing QML Modules}.
\endlist
\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}.
\endlist
Your module should now appear in \uicontrol Components. Your components
should appear in a subsection of \uicontrol Components if a valid
\c .metainfo file is in place.
\endif
\section1 Generating Type Description Files
When \l{Defining QML Types from C++}{registering QML types}, make sure that
the QML module has a \c{plugins.qmltypes} file. Ideally, it should be located
in the same directory as the \c qmldir file. The \c qmltypes file contains a
description of the components exported by the module's plugins and is loaded
by \QC when the module is imported.
For more information, see \l{Type Description Files}.
\section2 Dumping Plugins Automatically
If a module with plugins lacks the \c qmltypes file, \QC tries to generate
a temporary file itself by running the \c qmldump program in the background.
However, this automatic dumping is a fallback mechanism with many points of
failure and you cannot rely upon it.
\section1 Importing QML Modules
By default, \QC will look in the QML import path of Qt for QML modules.
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:
\code
set(QML_IMPORT_PATH ${CMAKE_SOURCE_DIR}/qml ${CMAKE_BINARY_DIR}/imports CACHE STRING "" FORCE)
\endcode
The import path affects all the targets built by the CMake project.
\if defined(qtdesignstudio)
\section1 Running QML Modules in Design Mode
A QML emulation layer (also called QML Puppet) is used in the
\uicontrol Design mode to render and preview images and to collect
data. To be able to render custom components correctly from QML modules,
the emulation layer must be built with the same Qt version and compiler
as the QML modules.
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)}.
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 \uicontrol 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 \uicontrol Design mode.
If you want to use a different module in the \uicontrol Design mode
than in your actual application for example to mockup C++ items,
you can use \c{QML_DESIGNER_IMPORT_PATH}
in the \c{.pro} file (for qmake projects), or declare and set the property
\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 \uicontrol Design mode.
For an example, see \l {Qt Quick Controls - Contact List}.
\endif
*/
|
