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
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
|
/****************************************************************************
**
** Copyright (C) 2021 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 quick-components.html
\if defined(qtdesignstudio)
\previouspage studio-flow-external-events.html
\else
\previouspage creator-using-qt-quick-designer.html
\endif
\nextpage quick-shapes.html
\title Creating Components
A \e component is a reusable building block for a UI.
\QDS comes with \e {preset components} that you can use in your UI by
creating instances of them.
The preset components are similar to \e Symbols in Sketch or \e Prefab in
Unity.
Some of the preset components represent simple shapes, text, or images,
while others represent complex UI controls with full functionality, such
as spin boxes or sliders. You can also add instances of preset
\l {Using 3D Components}{3D components} to your UIs.
To build your own components, you can modify the \e properties of the
component instances and combine them.
A component is specified within one file (with the file extension
\e ui.qml or \e .qml). For example, a Button component may be defined
in \e Button.ui.qml. Typically, the visual appearance of a component
is defined in a \e {UI file} (ui.qml). To create component files,
you can use \l{Creating Components from Scratch}{wizard templates}, or
\l{Moving Component Instances into Separate Files}
{move component instances into separate component files}.
Select \l Library > \uicontrol Components to view the preset components that
have been added to your project. If you cannot find the components you need,
add the relevant modules to your project, as described in
\l {Adding and Removing Modules}.
\image qtquick-components-tab.png "Components in Library"
\note Use as few components as possible. To minimize the number of
components, use \l{Adding Property Aliases}{alias properties} and
\l{Adding States}{states} to create the differences in your component
instances. Using component instances instead of duplicating the components
reduces the time needed to load and build the application, as well as the
size of the application package.
\section1 Creating Component Instances
\image qmldesigner-editing-components.png "Creating Component Instances"
\list 1
\li Drag-and-drop components from \uicontrol Library (1) to
\l Navigator (2), \l {Form Editor} (3), or \l {3D Editor} (4).
This creates instances of the components in the current
component file.
\li Select component instances in \uicontrol Navigator to edit the
values of their properties in \uicontrol Properties.
\image qmldesigner-properties-view.png "Properties view"
For more information, see \l {Specifying Component Properties}.
\li To change the appearance and behavior of the component instances
in ways that are not supported in \QDS by default, you can define
custom properties in \l {Connection View} > \uicontrol {Properties}.
\image qmldesigner-dynamicprops.png "Connection View Properties tab"
For more information, see \l{Specifying Dynamic Properties}.
\li To enable users to interact with the component instances, connect
the instances to signals in \uicontrol {Connection View} >
\uicontrol Connections. For example, you can specify what happens
when a component instance is clicked. For more information, see
\l{Connecting Components to Signals}.
\image qmldesigner-connections.png "Connection View Connections tab"
\li To dynamically change the behavior of a component instance when
another component instance changes, create bindings between them in
\uicontrol {Connection View} > \uicontrol Bindings.
For more information, see \l{Adding Bindings Between Properties}.
\image qmldesigner-bindings.png "Connection View Bindings tab"
\li Add states to apply sets of changes to the property values of one
or several component instances in the \uicontrol States view.
For more information, see \l{Adding States}.
\li Animate the properties of component instances in the \uicontrol
Timeline view. For more information, see \l{Creating Animations}.
\endlist
\section1 Creating Your Own Components
You can either use project wizard templates to create custom components and
controls or move component instances into separate files to turn them into
new components that you can create instances of. You can then use the
instances of the new components in other components.
\section2 Creating Components from Scratch
To use wizard templates to create custom components:
\list 1
\li Select \uicontrol File > \uicontrol {New File or Project} >
\if defined(qtcreator)
\uicontrol Qt > \uicontrol {QML File (Qt Quick 2)} >
\else
\uicontrol {Qt Quick Files} > \uicontrol {Qt Quick File} >
\endif
\uicontrol Choose to create a new .qml file.
\note Components are listed in the \uicontrol {My Components}
tab in the \uicontrol Library view only if the filename begins with
a capital letter.
\li Click \uicontrol Design to open the component file (ui.qml) in
\uicontrol {Form Editor}.
\li Drag-and-drop a component from \uicontrol Library to
\uicontrol Navigator or \uicontrol {Form Editor}.
\li Edit component properties in the \uicontrol Properties view.
\image qmldesigner-custom-component-properties.png
The available properties depend on the component type. You can
\l{Specifying Dynamic Properties}{add properties for
components} in \uicontrol {Connection View} > \uicontrol Properties.
\li To change the appearance and behavior of the component instances
in ways that are not supported in \QDS by default, you can define
custom properties in \uicontrol {Connection View} >
\uicontrol {Properties}.
\endlist
The following sections contain more information about how to use
\uicontrol {Form Editor} to edit 2D content and \uicontrol {3D Editor}
to edit 3D scenes, as well as examples of how to create UI controls
using instances of basic components:
\list
\li \l{Form Editor}
\li \l{3D Editor}
\li \l{Creating Buttons}
\li \l{Creating Scalable Buttons and Borders}
\endlist
\if defined(qtdesignstudio)
\include qtdesignstudio-components.qdocinc creating studio components
\endif
\section2 Moving Component Instances into Separate Files
An alternative way of creating reusable components is to move component
instances into separate component files (.ui.qml). Right-click a component
instance in \uicontrol Navigator or \uicontrol {Form Editor}, and select
\uicontrol {Move Component into Separate File} in the context menu.
\image qtcreator-move-component-into-separate-file.png
Give the new component a name, and select whether properties are set for
the new component or for the original one.
When you select \uicontrol OK, a new component file is created and an
instance of the component is added to the code in the current component
file. The look of your UI in \uicontrol {Form Editor} does not change.
To open the new component file for editing the properties that you want
to change for all instances of the component, right-click the component,
and then select \uicontrol {Go into Component} in the context menu. For
additional ways of opening base components, see \l{Moving Within Components}.
For an example of creating a reusable custom component, see
\if defined(qtcreator)
\l{Creating a Mobile Application}.
\else
\l{Progress Bar}.
\endif
Custom components are listed in \uicontrol Library > \uicontrol Components
> \uicontrol {My Components}, and you can use instances of them to build
more components.
\include qtquick-mcu-support.qdocinc mcu qtquick components
\section1 Merging Files with Templates
You can merge the current component file against an existing second
component file using the second file in a way similar to using a CSS
stylesheet.
To use this experimental feature, right-click a component in the
\uicontrol Navigator or \uicontrol {Form Editor} view and select
\uicontrol {Merge File with Template} in the context menu.
\image qmldesigner-merge-with-template.png "Merge with Template dialog"
In the \uicontrol Template field, select the file to use as a template.
*/
|
