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) 2013 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** 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 Digia. For licensing terms and
** conditions see http://qt.digia.com/licensing. For further information
** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qtquick-positioning-topic.html
\title Important Concepts In Qt Quick - Positioning
\brief Overview of positioning concepts
Visual items in QML can be positioned in a variety of ways. The most important
positioning-related concept is that of anchoring, a form of relative
positioning where items can be anchored (or attached) to each other at certain
boundaries. Other positioning concepts include absolute positioning,
positioning with coordinate bindings, positioners, and layouts.
\section1 Manual Positioning
Items can be positioned manually. If the user-interface is going to be
static, manual positioning provides the most efficient form of positioning.
In any user-interface, the visual types exist at a particular location in
the screen coordinates at any instant in time. While fluidly animated and
dynamic user-interfaces are a major focus of Qt Quick, statically-positioned
user interfaces are still a viable option. What's more, if the position of
those types does not change, it can often be more performant to specify
the position manually than to use the more dynamic positioning methods
documented in proceeding sections.
In Qt Quick, every visual object is positioned within the
\l{qtquick-visual-coordinates.html}{coordinate system}
provided by the Qt Quick visual canvas. As described in that document, the
x and y coordinates of a visual object are relative to those of its visual
parent, with the top-left corner having the coordinate (0, 0).
Thus, the following example will display two rectangles positioned manually:
\table
\header
\li Example Code
\li Resultant Layout
\row
\li
\qml
import QtQuick 2.0
Item {
width: 200
height: 200
Rectangle {
x: 50
y: 50
width: 100
height: 100
color: "green"
}
Rectangle {
x: 100
y: 100
width: 50
height: 50
color: "yellow"
}
}
\endqml
\li
\image manual-layout.png
\endtable
\section1 Positioning With Bindings
Items may also be positioned by assigning binding expressions to the properties
associated with their location in the visual canvas. This type of positioning
is the most highly dynamic, however some performance cost is associated with
positioning items in this manner.
The position and dimensions of a visual object can also be set through property
bindings. This has the advantage that the values will automatically be updated
as the dependencies of the bindings change. For example, the width of one
Rectangle might depend on the width of the Rectangle next to it.
While bindings provide a very flexible and intuitive way of creating dynamic
layouts, it should be noted that there is some performance cost associated with
them, and where possible, pristine Anchor layouts should be preferred.
\section1 Anchors
Anchors allows an item to be placed either adjacent to or inside of another,
by attaching one or more of the item's anchor-points (boundaries) to an
anchor-point of the other. These anchors will remain even if the dimensions
or location of one of the items changes, allowing for highly dynamic
user-interfaces.
A visual object can be thought of as having various anchor-points (or more
correctly, anchor-lines). Other items can be anchored to those points, which
means that as any object changes, the other objects which are anchored to it
will adjust automatically to maintain the anchoring.
Qt Quick provides anchors as a top-level concept. See the documentation about
\l{qtquick-positioning-anchors.html}{positioning with anchors}
for in-depth information on the topic.
It is important to note that anchor-based layouts are generally far more
performant than binding-based layouts, if pristine. A "pristine" anchor layout
is one which uses only anchors (with object nesting) to determine the
positioning, whereas a "contaminated" anchor layout is one which uses both
anchoring and bindings (either on position-related [x,y] properties or on
dimension-related [width,height] properties) to determine the position.
\section1 Positioners
Qt Quick also provides some built-in positioner items. For many use cases, the best
positioner to use is a simple grid, row, or column, and Qt Quick provides items which
will position children in these formations in the most efficient manner possible.
See the documentation on \l{qtquick-positioning-layouts.html}{item positioners types}
for more information about utilizing pre-defined positioners.
\section1 Layouts
From Qt 5.1, the module \l {Qt Quick Layouts} can also be used to arrange Qt Quick
items in a user interface. Unlike positioners, the types in Qt Quick Layouts manage
both the positions and sizes of items in a declarative interface. They are well
suited for resizable user interfaces.
\section1 Right-To-Left Support
The directionality of the written form of a language often has a great impact
on how the visual types of a user-interface should be positioned. Qt Quick
supports right-to-left positioning of types through the predefined-layouts
as well as right-to-left text layouts.
Please see the documentation about
\l{qtquick-positioning-righttoleft.html}
{right-to-left support in Qt Quick} for in-depth information on the topic.
*/
|
