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
|
/****************************************************************************
**
** Copyright (c) 2013 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of Qt Creator
**
**
** GNU Free Documentation License
**
** 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.
**
**
****************************************************************************/
// **********************************************************************
// 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 index.html
\previouspage quick-scalable-image.html
\page quick-screens.html
\nextpage quick-export-to-qml.html
\title Creating Screens
You can use predefined QML types and your own components to create
screens. Typically, the main qml file in a Qt Quick project specifies the
main window of an application.
The QML files in the project folder are displayed in \gui {QML Components}
in the \gui Library pane.
You can also use ready-made Qt Quick 1 Components (for Qt 4) to create
screens with a native look and feel for a particular target platform.
Since Qt 5.1, a set of Qt Quick Controls is available for creating classic
desktop-style user interfaces using Qt Quick 2.1. You
can install Qt Quick 1 Components as part of the Qt 4 SDK and the Qt Quick
Controls as part of Qt 5.1, or later.
\section1 Adding Components to Screens
\list 1
\li Drag and drop components from the \gui Library pane to the editor.
\li Select components in the \gui Navigator pane to edit their
properties in the \gui Properties pane.
For example, you can anchor components to a position on the screen.
\endlist
\section1 Using Data Models
You can create the following types of views to organize items provided by
\l{http://qt-project.org/doc/qt-5.0/qtquick/qtquick-modelviewsdata-modelview.html}{data models}:
\list
\li \l{http://qt-project.org/doc/qt-5.0/qtquick/qml-qtquick2-gridview.html}{Grid View}
provides a grid vizualization of a model.
\li \l{http://qt-project.org/doc/qt-5.0/qtquick/qml-qtquick2-listview.html}{List View}
provides a list vizualization of a model.
\li \l{http://qt-project.org/doc/qt-5.0/qtquick/qml-qtquick2-pathview.html}{Path View}
visualizes the contents of a model along a path.
\endlist
When you add a Grid View, List View, or Path View, the
\l{http://qt-project.org/doc/qt-5.0/qtquick/qml-qtquick2-listmodel.html}{ListModel} and the
delegate component that creates an instance for each item in the model are
added automatically. You can edit item properties
in the \gui Properties pane or
in the code editor. You can also replace the default model and
delegate with other, more complex models and delegates in the code editor.
\section1 Positioning Items on Screens
The position of an item on the canvas can be either absolute or relative
to other items. If you are designing a static user interface,
\l{http://dev.qt-project.org/doc/qt-5.0/qtquick-positioning-topic.html#manual-positioning}
{manual positioning} provides the most efficient form of positioning items
on the screen. For a dynamic user interface, you can employ the following
positioning methods provided by Qt Quick:
\list
\li \l{Setting Bindings}
\li \l{Setting Anchors and Margins}
\li \l{Using Positioners}
\li \l{Using Layouts}
\li \l{Using Split Views}
\endlist
\section2 Setting Bindings
\l{http://qt-project.org/doc/qt-5.0/qtquick-positioning-topic.html#positioning-with-bindings}
{Property binding} is a declarative way of specifying the value of a property.
Binding allows a property value to be expressed as an JavaScript expression
that defines the value relative to other property values or data accessible
in the application. The property value is automatically kept up to date if
the other properties or data values change.
Property bindings are created implicitly in QML whenever a property is
assigned a JavaScript expression. To set JavaScript expressions as values of
properties in \QMLD, click the circle icon next to a property to open a
context menu, and select \gui {Set Binding}.
\image qmldesigner-set-expression.png "Type properties context menu"
To remove bindings, select \gui Reset in the context menu.
For more information on the JavaScript environment provided by QML, see
\l{http://qt-project.org/doc/qt-5.0/qtqml/qtqml-javascript-topic.html}
{Integrating QML and JavaScript}.
\QMLD cannot show bindings and using them might have a negative impact on
performance, so consider setting anchors and margins for items, instead.
For example, instead of setting \c {parent.width} for an item, you could
anchor the item to its sibling items on the left and the right.
\section2 Setting Anchors and Margins
In an
\l{http://qt-project.org/doc/qt-5.0/qtquick-positioning-anchors.html}
{anchor-based} layout, each QML type can be thought of as having a set of
invisible \e anchor lines: top, bottom, left, right, fill, horizontal
center, vertical center, and baseline.
In the \gui Layout pane you can set anchors and margins for items. To set
the anchors of an item, click the anchor buttons. You can combine the
top/bottom, left/right, and horizontal/vertical anchors to anchor items in
the corners of the parent item or center them horizontally or vertically
within the parent item.
\image qmldesigner-anchor-buttons.png "Anchor buttons"
Specifying the baseline anchor in \QMLD is not supported. You can specify it
using the code editor.
For performance reasons, you can only anchor an item to its siblings and
direct parent. By default, an item is anchored to its parent when you
use the anchor buttons. Select a sibling of the item in the \gui Target
field to anchor to it, instead.
Arbitrary anchoring is not supported. For example, you cannot specify:
\c {anchor.left: parent.right}. You have to specify: \c {anchor.left: parent.left}.
When you use the anchor buttons, anchors to the parent item are always
specified to the same side. However, anchors to sibling items are specified
to the opposite side: \c {anchor.left: sibling.right}. This allows you to keep
sibling items together.
In the following image, \gui{Rectangle 2} is anchored to \gui{Rectangle 1}
on its left and to the bottom of its parent.
\image qmldesigner-anchors.png "Anchoring sibling items"
The anchors for \gui{Rectangle 2} are specified as follows in code:
\qml
Rectangle {
id: rectangle2
anchors.left: rectangle1.right
anchors.leftMargin: 15
anchors.bottom: parent.bottom
anchors.bottomMargin: 15
//
}
\endqml
Margins specify the amount of empty space to leave to the outside of an item.
Margins only have meaning for anchors. They do not take any effect when using
other layouts or absolute positioning.
\section2 Using Positioners
\l{http://qt-project.org/doc/qt-5.0/qtquick-positioning-layouts.html}
{Positioner items} are container items that manage the positions of items in
a declarative user interface. Positioners behave in a similar way to the
layout managers used with standard Qt widgets, except that they are also
containers in their own right.
You can use the following positioners to arrange items on screens:
\list
\li \l{http://qt-project.org/doc/qt-5.0/qtquick/qml-qtquick2-column.html}{Column}
arranges its child items vertically.
\li \l{http://qt-project.org/doc/qt-5.0/qtquick/qml-qtquick2-row.html}{Row}
arranges its child items horizontally.
\li \l{http://qt-project.org/doc/qt-5.0/qtquick/qml-qtquick2-grid.html}{Grid}
arranges its child items so that they are aligned in a grid and
are not overlapping.
\li \l{http://qt-project.org/doc/qt-5.0/qtquick/qml-qtquick2-flow.html}{Flow}
arranges its child items side by side, wrapping as necessary.
\endlist
To lay out several items in a Column, Row, Grid, or Flow, select
the items on the canvas, and then select \gui Layout in the context
menu.
\section2 Using Layouts
From Qt 5.1, you can use QML types in the
\l{http://qt-project.org/doc/qt-5.1/qtquicklayouts/qtquicklayouts-index.html}
{Qt Quick Layouts module} to arrange Qt Quick items on screens. Unlike p
ositioners, they manage both the positions and sizes of items in a
declarative interface. They are well suited for resizable user interfaces.
You can use the following layout types to arrange items on screens:
\list
\li \l{http://qt-project.org/doc/qt-5.0/qml-qtquick-layouts-layout.html}
{Layout} provides attached properties for items pushed onto a
\gui {Column Layout}, \gui {Row Layout}, or \gui {Grid Layout}.
\li \l{http://qt-project.org/doc/qt-5.0/qml-qtquick-layouts-columnlayout.html}
{Column Layout} provides a grid layout with only one column.
\li \l{http://qt-project.org/doc/qt-5.0/qml-qtquick-layouts-rowlayout.html}
{Row Layout} provides a grid layout with only one row.
\li \l{http://qt-project.org/doc/qt-5.0/qml-qtquick-layouts-gridlayout.html}
{Grid Layout} provides a way of dynamically arranging items in a
grid.
\endlist
To lay out several items in a \gui {Column Layout}, \gui {Row Layout}, or
\gui {Grid Layout}, select the items on the canvas, and then select
\gui Layout in the context menu.
To make an item within a layout as wide as possible while respecting the
given constraints, select the item on the canvas and then select
\gui Layout > \gui {Fill Width} in the context menu. To make the item as
high as possible, select \gui {Fill Height}.
\section2 Using Split Views
From Qt 5.1, you can use the
\l{http://qt-project.org/doc/qt-5.1/qtquickcontrols/qml-qtquick-controls1-splitview.html}
{Split View} Qt Quick Control to arrange items horizontally or vertically
with a draggable splitter between each item.
\section1 Using States
Use states and transitions to navigate between screens.
QML states typically describe user interface configurations, such as the UI
controls, their properties and behavior and the available actions. For
example, you can use states to create two screens.
To add states, click the empty slot in the \gui States pane. Then modify the
new state in the visual editor.
\image qmldesigner-states.png "States pane"
The properties that you change in a state are highlighted with blue color.
In the code editor, you can see the changes recorded as changes to the base
state.
To keep the QML code clean, you should create a base state that contains all
the types you will need in the application. You can then create states,
in which you hide and show a set of items and modify their properties.
This allows you to:
\list
\li Align items on different screens with each other.
\li Avoid excessive property changes. If an item is invisible in the
base state, you must define all changes to its child types as
property changes, which leads to complicated QML code.
\li Minimize the differences between the base state and the other states
to keep the QML code short and readable and to improve performance.
\li Avoid problems when using transitions and animation when changing
states.
\endlist
To create screens for an application by using states:
\list 1
\li In the base state, add all items you will need in the
application (1).
While you work on one screen, you can click the
\inlineimage qmldesigner-show-hide-icon.png
icon to hide items on the canvas that are not part of a screen.
\li In the \gui States pane, click the empty slot to create a new state
and give it a name. For example, \c Normal.
\li In the \gui Properties pane (2), deselect the \gui Visibility check box
or set \gui Opacity to 0 for each item that is not needed in this
view. If you specify the setting for the parent item, all child
items inherit it and are also hidden.
\image qmldesigner-screen-design.png "Designing screens"
\li Create additional states for each screen and set the visibility
or opacity of the items in the screen.
\li To determine which view opens when the application starts, use the
code editor to set the state of the root item of the .qml file, as
specified by the following code snippet:
\qml
Item {
state: "Normal"
}
\endqml
\endlist
\section1 Animating Screens
To make movement between states smooth, you can specify transitions. You can
use different types of animated transitions. For example, you can animate
changes to property values and colors. You can use rotation animation to
control the direction of rotation. For more information, see
\l{http://qt-project.org/doc/qt-5.0/qtquick/qtquick-statesanimations-animations.html}
{Animation and Transitions in Qt Quick}.
You can use the \c ParallelAnimation type to start several animations at
the same time. Or use the \c SequentialAnimation type to run them one
after another.
You can use the code editor to specify transitions. For more information,
see \l{http://qt-project.org/doc/qt-5.0/qtquick/qml-qtquick2-transition.html}
{Transition}.
\section1 Adding User Interaction Methods
You can add the following basic interaction methods to scenes:
\list
\li \l{http://qt-project.org/doc/qt-5.0/qtquick/qml-qtquick2-flickable.html}{Flickable}
items can be flicked horizontally or vertically.
\li \l{http://qt-project.org/doc/qt-5.0/qtquick/qml-qtquick2-flipable.html}{Flipable}
items can be flipped between their front and back sides by using
rotation, state, and transition.
\li \l{http://qt-project.org/doc/qt-5.0/qtquick/qml-qtquick2-focusscope.html}{Focus Scope}
assists in keyboard focus handling when building reusable QML
components.
\li \l{http://qt-project.org/doc/qt-5.0/qtquick/qml-qtquick2-mousearea.html}{Mouse Area}
enables simple mouse handling.
\endlist
\section1 Implementing Application Logic
A user interface is only a part of an application, and not really useful by itself.
You can use Qt or JavaScript to implement the application logic. For more information on
using JavaScript, see
\l{http://qt-project.org/doc/qt-5.0/qtqml/qtqml-javascript-topic.html}
{Integrating QML and JavaScript}.
For an example of how to use JavaScript to develop a game, see the
\l{http://qt-project.org/doc/qt-5.0/qtquick/qtquick2-qml-advtutorial.html}
{QML Advanced Tutorial}.
*/
|