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
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
|
/****************************************************************************
**
** Copyright (C) 2017 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.
// **********************************************************************
/*!
\contentspage {Qt Creator Manual}
\previouspage creator-quick-ui-forms.html
\page creator-using-qt-quick-designer.html
\nextpage qmldesigner-pathview-editor.html
\title Editing QML Files in Design Mode
\QC opens \l{Qt Quick UI Forms}{UI forms} (ui.qml files) in the
\uicontrol {Form Editor} tab in the Design mode. It is
recommended that you use UI forms for components that you want to
edit in the Design mode.
\image qmldesigner-visual-editor.png "Visual editor"
To manage your project in the Design mode:
\list
\li \uicontrol Canvas (1) is the working area where you create QML
components and design applications. In the \uicontrol {Form Editor}
tab, you can use a visual editor to design UIs, and in the
\uicontrol {Text Editor} tab, you can use a code editor to edit the
QML code generated by the visual editor.
\li Use the sidebars to select QML types to use in the project, to
specify properties for them, and to
view them in a tree structure, as well as to create connections
and browse projects and files. You can select the content of the
sidebars in the sidebar menu:
\list
\li \uicontrol {Library} (2) displays the building blocks that you
can use to design applications: predefined QML types, your own
QML components, or Qt Quick Controls 2 that you import to the
project, and other resources.
\li \uicontrol {Navigator} (3) displays the items in the current QML
file as a tree structure.
\li \uicontrol {Properties} (4) organizes the properties of the
selected item. You can change the properties also in the
\uicontrol {Text Editor}.
\li \uicontrol Connections (5) enables you to create connections
between objects, signals, and object properties. For more
information, see \l{Adding Connections}.
\li \uicontrol {File System} shows all files in the currently
selected directory. For more information, see
\l{Viewing the File System}.
\li \uicontrol {Open Documents} shows currently open files.
\li \uicontrol {Projects} shows a list of projects open in the
current session. For more information, see
\l{Viewing Project Files}.
\endlist
\li \uicontrol {State} pane (6) displays the different states of the item.
QML states typically describe user interface configurations, such as
the UI controls, their properties and behavior and the available
actions. For more information, see \l{Adding States}.
\endlist
\section1 Managing Item Hierarchy
The \uicontrol Navigator displays the items in the current QML file and their
relationships.
Items (1) are listed in a tree structure, below their parent (2).
\image qmldesigner-navigator.png "Navigator"
You can select items in the \uicontrol Navigator to edit their properties
in the \uicontrol Properties pane. Items can access the properties of their
parent item. To select items on the canvas, right-click an item,
and select another type in the context menu.
Typically, child items are located within the parent item on the
canvas. However, they do not necessarily have to fit inside the parent
item. For example, you might want to make a mouse area larger than the
rectangle or image beneath it (1).
\image qmldesigner-element-size.png "Mouse area for a button"
When you copy an item, all its child items are also copied. When
you remove an item, the child items are also removed.
You can show and hide items on the canvas to focus on specific parts of the
application. Click the \inlineimage icon_color_none.png
(\uicontrol Transparent) button to change the visibility of an item on the
canvas. To change the
visibility of an item in the application, select the \uicontrol Visibility
check box in the \uicontrol Properties pane or select \uicontrol Edit >
\uicontrol Visibility in the context menu.
You can also set the \uicontrol Opacity field to 0 to hide items that you
want to apply animation to.
As all properties, visibility and opacity are inherited from the parent
item. To hide or show child items, edit the properties of the parent item.
To hide invisible items in the navigator, click \inlineimage filtericon.png
(\uicontrol {Filter Tree}) and select \uicontrol {Show only visible items}.
To reset item size, position, or anchors, select context menu commands. To
change the source of an Image type, select \uicontrol {Change Source URL} in
the context menu.
To view lists of files or projects, instead, select \uicontrol {File System},
\uicontrol {Open Documents}, or \uicontrol Projects in the menu.
To view several types of content at a time, split the sidebars by clicking
the \inlineimage splitbutton_horizontal.png
(\uicontrol Split) button.
\section2 Setting the Stacking Order
The \c z property of an \l Item determines its position in relation to its
sibling items in the
type hierarchy. By default, items with a higher stacking value are
drawn on top of siblings with a lower stacking value. Items with the same
stacking value are drawn in the order they are listed, from the last item
up.
To raise or lower the stack value of an item, select \inlineimage raise.png
(\uicontrol Raise) or \inlineimage lower.png
(\uicontrol Lower) on the toolbar.
To move an item to the front or back of all its siblings, right-click it in
the navigator or the \uicontrol {Form Editor} and select
\uicontrol {Stack (z)}. To remove the \c z property, select
\uicontrol {Reset z Property}.
You can also use a \uicontrol StackLayout item (Qt Quick Controls 2) to
create a stacked view. For more information, see \l {Using Layouts}.
\section2 Switching Parent Items
When you drag and drop instances of QML types to the canvas, the new item
is added as a child of the item beneath it. When you move items on the
canvas, it is not possible to determine
whether you want to adjust their position or attach them to a new
parent item. Therefore, the parent item is not automatically
changed. To change the parent of the item, press down the \key Shift
key before you drag and drop the item into a new position. The topmost
item under the cursor becomes the new parent of the item.
You can change the parent of an item also in the \uicontrol Navigator.
Drag and drop the item to another position in the tree or use the arrow
buttons (1) to move the item in the tree.
\image qmldesigner-navigator-arrows.png "Navigator arrow buttons"
\section1 QML Type Library
The \uicontrol {Library} enables you to select QML types, UI components, and
resources, as well as to manage imports.
\uicontrol {QML Types} displays the QML types grouped by category: your own QML
components, basic types, layouts, positioner types, and views.
Sets of UI components with the look and feel of a particular mobile device
platform have been defined for Qt Quick 1. Since Qt 5.1, ready-made Qt
Quick Controls, Dialogs, and Layouts are available for creating user
interfaces using Qt Quick 2.1. The components and controls are based on
standard QML types. To view the components and controls in the
\uicontrol {Library}, import the component sets in \uicontrol Imports.
The \uicontrol {Qt Quick Application} wizards for a particular platform add the
import statements automatically. You can remove import statements in
\uicontrol Imports
\image qmldesigner-qml-components.png "QML Components"
\uicontrol {Resources} displays the images and other files that you copy
to the project folder (to the same subfolder as the QML files).
\section1 Specifying Item Properties
The \uicontrol Properties pane displays all the properties of the selected item.
The properties are grouped by type. The top part of the pane
displays properties that are common to all QML types, such as
position, size, and visibility.
The bottom part of the pane displays properties that are specific to each
QML type. For example, the following image displays the properties you
can set for \uicontrol Rectangle (1) and \uicontrol Text (2) items.
\image qmldesigner-element-properties.png
To change the item type, double-click the \uicontrol Type field in the
\uicontrol Properties pane, and enter the name of another QML type in the
field. If you have specified properties for the item that are not supported
for the new type, the type cannot be changed and an error message is
displayed. Remove the properties in the \uicontrol {Text Editor} and try
again.
To return an item to its implicit position after moving it, select the
\inlineimage qtcreator-reset-position-icon.png
(\uicontrol {Reset Position}) button on the toolbar. To return it to its
implicit size, select \inlineimage qtcreator-reset-size-icon.png
(\uicontrol {Reset Size}) button.
To set the visibility of the item, select \uicontrol {Edit > Visibility} in the context menu.
To specify the color of the selected item in the \uicontrol {Select Color}
dialog, select \uicontrol {Edit Color} in the context menu.
For more information on the properties available for an item, press
\key {F1}.
\section2 Viewing Changes in Properties
The default values of properties are displayed in white color, while the
values that you specify explicitly are highlighted with blue color. In
addition, property changes in states are highlighted with blue.
This allows you to easily see which values are set in the UI form or
QML file and
which values are default characteristics of a QML type or a component.
When editing states, you can easily see which values are explicitly set in
the current state and which values are derived from the base state.
The following images illustrate this. In the base state, the \uicontrol Size (1)
and \uicontrol Colors (2) values are explicitly set and highlighted.
\image qmldesigner-properties-explicit-base.png "Explicitly set properties"
In \uicontrol State1, only the color (1) is explicitly set and highlighted.
\image qmldesigner-properties-explicit-state1.png "Explicitly set properties"
Resetting a property sets it back to the default value and removes the value
from the UI form or QML file.
\note As a result, all boolean values can be visualized in four different
ways.
For example, visibility can be visualized as follows:
\table
\row
\li \image qmldesigner-boolean-true.png
\li TRUE
\li The QML type is visible by default. The visibility might be
overridden by the visibility set in the base state.
\row
\li \image qmldesigner-boolean-true-blue.png
\li TRUE (highlighted)
\li The QML type is explicitly set to visible.
\row
\li \image qmldesigner-boolean-false.png
\li FALSE
\li The QML type is hidden by default. The visibility might be
overridden by the visibility set in the base state.
\row
\li \image qmldesigner-boolean-false-blue.png
\li FALSE (hightlighted)
\li The type is explicitly set to hidden.
\endtable
\section2 Marking Text Items for Translation
To support translators, mark each text item that should be translated.
In the \uicontrol Properties pane, \uicontrol Text field, select \uicontrol tr (1).
\image qmldesigner-text-property-tr.png "Text properties"
By default, the text string is enclosed in a \c qsTr() call.
\image qml-translate.png "Text marked for translation"
If you use text IDs instead of plain text, change the default call to
\c qsTrId(). Select \uicontrol Tools > \uicontrol Options >
\uicontrol {Qt Quick} > \uicontrol {\QMLD}, and then select the
\uicontrol {qsTrId()} radio button in the \uicontrol Internationalization
group. For more information about text ID based translations, see
\l {Qt Linguist Manual: Text ID Based Translations}.
To preserve the context when editing the text or to change the context
by setting a binding on the text property, change the default call to
\c qsTranslate() by selecting the \uicontrol {qsTranslate()} radio button.
For more information, see
\l {Internationalization and Localization with Qt Quick}.
\section2 Loading Placeholder Data
The Design mode supports views, models, and delegates, so that when you add
a Grid View, List View, or Path View item, the ListModel and the delegate
item are added automatically.
However, the missing context of the application presents a challenge.
Specific models defined in C++ are the most obvious case. Often,
the context is missing simple properties, which are either defined in C++,
or in other QML files. A typical example is an item that uses the
properties of its parent, such as \c parent.width.
\section3 Using Dummy Models
If you open a file in the Design mode that references a C++ model, you see
nothing on
the canvas. If the data in the model is fetched from the internet, you have
no control over it. To get reliable data, \e {dummy data} was introduced.
For example, the following code snippet describes the file example.qml that
contains a ListView that in turn specifies a C++ model:
\qml
ListView {
model: dataModel
delegate: ContactDelegate {
name: name
}
}
\endqml
Create a directory named \e dummydata in the root directory of the project,
so that it is not deployed to the device. In the \c dummydata directory,
create a QML file that has the same name as the value of \c model:
\code
qml/exampleapp/example.qml
dummydata/dataModel.qml
\endcode
Then create the dataModel.qml file that contains the dummy data:
\qml
import QtQuick 1.0
ListModel {
ListElement {
name: "Ariane"
}
ListElement {
name: "Bella"
}
ListElement {
name: "Corinna"
}
}
\endqml
\section3 Creating Dummy Context
The following example presents a common pattern in QML:
\qml
Item {
width: parent.width
height: parent.height
}
\endqml
This works nicely for applications but the Design mode displays a zero-sized
item. A parent for the opened file does not exist, because the context is
missing. To get around the missing context, the idea of a \e {dummy
context} is introduced. If you place a file with the same name as the
application (here, example.qml) in the \c {dummydata/context} directory,
you can fake a parent context:
\qml
import QtQuick 1.0
import QmlDesigner 1.0
DummyContextObject {
parent: Item {
width: 640
height: 300
}
}
\endqml
\section2 Building Transformations on Items
The \uicontrol Advanced pane allows you to configure advanced transformations,
such as rotation, scale, and translation. You can assign any number of
transformations to an item. Each transformation is applied in order, one at
a time.
For more information on Transform types, see \l{Transform}.
\section2 Editing Properties Inline
You can double-click objects on the canvas to edit their text, color, or
source properties inline.
Because you can specify several of these properties for some QML types, such
as \l [QML]{TextEdit}{Text Edit}, you can also right-click objects to open
the inline editors from a context-menu.
\image qmldesigner-inline-editing.png
\section1 Working with QML Types on Canvas
You design applications on the canvas by placing items on it.
\section2 Snapping to Parent and Sibling Items
When you are working on a design, you can use snapping to align
items on the canvas. Click the \inlineimage snapping.png
button to have the items snap to their parent or sibling items. Snapping
lines automatically appear to help you position the items.
Click the \inlineimage snapping_and_anchoring.png
button to anchor the item to the items that you snap to.
Choose \uicontrol Tools > \uicontrol Options > \uicontrol {Qt Quick} >
\uicontrol {\QMLD} to specify settings for snapping. In the
\uicontrol {Parent item padding} field, specify the
distance in pixels between the parent item and the snapping lines. In the
\uicontrol {Sibling item spacing} field, specify the distance in pixels between
sibling items and the snapping lines.
The following image shows the snapping lines when \uicontrol {Parent item padding}
is set to 5 pixels.
\image qmldesigner-snap-margins.png "Snapping lines on canvas"
\section2 Hiding Item Boundaries
The Design mode displays the boundaries of items on the canvas. To hide
the boundaries, click the \inlineimage boundingrect.png
button.
\section2 Selecting Items
When you point the mouse to overlapping items, the frontmost item is
selected by default. However, items that do not have any content, such as
the mouse area, are typically located in front of items that do have
content, such as rectangles or border images. To select items with content
by default, click the
\inlineimage qmldesigner-only-select-items-with-content.png
button.
\section2 Previewing Component Size
The width and height of the root item in a QML file determine the size of
the component. You can reuse components, such as buttons, in different
sizes in other QML files and design screens for use with different device
profiles, screen resolution, or screen orientation. The component size
might also be zero (0,0) if its final size is determined by property
bindings.
To experiment with different component sizes, enter values in the
\uicontrol {Override Width} and \uicontrol {Override Height} fields (1) on
the canvas toolbar. The changes are
displayed in the \uicontrol State pane (2) and on the canvas (3), but the property
values are not changed permanently in the QML file. You can permanently
change the property values in the \uicontrol Properties pane (4).
\image qmldesigner-preview-size.png "Canvas width and height"
\section2 Specifying Canvas Size
To change the canvas size, select \uicontrol Tools > \uicontrol Options >
\uicontrol {Qt Quick} > \uicontrol {\QMLD} and
specify the canvas width and height in the \uicontrol Canvas group.
\section2 Refreshing the Canvas
When you open QML files in the Design mode, the items in the file are drawn
on the canvas. When you edit the item properties, the QML file and
the image on the canvas might get out of sync. For example, when you change
the position of an item within a column or a row, the new position might
not be displayed correctly on the canvas.
To refresh the image on the canvas, press \key R or select the
\inlineimage qmldesigner-reset-view.png
(\uicontrol {Reset View}) button.
*/
|