Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
anchors.qdoc
Go to the documentation of this file.
1
// Copyright (C) 2017 The Qt Company Ltd.
2
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3
4
/*!
5
\page qtquick-positioning-anchors.html
6
\title Positioning with Anchors
7
\brief placing items with anchor properties
8
9
\keyword anchor-layout
10
In addition to the more traditional \l Grid, \l Row, and \l Column,
11
Qt Quick also provides a way to layout items using the concept of \e anchors.
12
Each item can be thought of as having a set of 7 invisible "anchor lines":
13
\l {Item::anchors.left}{left}, \l {Item::anchors.horizontalCenter}{horizontalCenter},
14
\l {Item::anchors.right}{right}, \l {Item::anchors.top}{top},
15
\l {Item::anchors.verticalCenter}{verticalCenter}, \l {Item::anchors.baseline}{baseline},
16
and \l {Item::anchors.bottom}{bottom}.
17
18
\image edges_qml.png
19
20
The baseline (not pictured above) corresponds to the imaginary line on which
21
text would sit. For items with no text it is the same as \e top.
22
23
The Qt Quick anchoring system allows you to define relationships between the anchor lines of different items. For example, you can write:
24
25
\code
26
Rectangle { id: rect1; ... }
27
Rectangle { id: rect2; anchors.left: rect1.right; ... }
28
\endcode
29
30
In this case, the left edge of \e rect2 is bound to the right edge of \e rect1, producing the following:
31
32
\image edge1.png
33
34
35
You can specify multiple anchors. For example:
36
37
\code
38
Rectangle { id: rect1; ... }
39
Rectangle { id: rect2; anchors.left: rect1.right; anchors.top: rect1.bottom; ... }
40
\endcode
41
42
\image edge3.png
43
44
By specifying multiple horizontal or vertical anchors you can control the size of an item. Below,
45
\e rect2 is anchored to the right of \e rect1 and the left of \e rect3. If either of the blue
46
rectangles are moved, \e rect2 will stretch and shrink as necessary:
47
48
\code
49
Rectangle { id: rect1; x: 0; ... }
50
Rectangle { id: rect2; anchors.left: rect1.right; anchors.right: rect3.left; ... }
51
Rectangle { id: rect3; x: 150; ... }
52
\endcode
53
54
\image edge4.png
55
56
There are also some convenience anchors. anchors.fill is a convenience that is the same as setting the left,right,top and bottom anchors
57
to the left,right,top and bottom of the target item. anchors.centerIn is another convenience anchor, and is the same as setting the verticalCenter
58
and horizontalCenter anchors to the verticalCenter and horizontalCenter of the target item.
59
60
\section1 Anchor Margins and Offsets
61
62
The anchoring system also allows \e margins and \e offsets to be specified for an item's anchors.
63
Margins specify the amount of empty space to leave to the outside of an item's anchor, while
64
offsets allow positioning to be manipulated using the center anchor lines. An item can
65
specify its anchor margins individually through \l {Item::anchors.leftMargin}{leftMargin},
66
\l {Item::anchors.rightMargin}{rightMargin}, \l {Item::anchors.topMargin}{topMargin} and
67
\l {Item::anchors.bottomMargin}{bottomMargin}, or use \l {Item::}{anchors.margins} to
68
specify the same margin value for all four edges. Anchor offsets are specified using
69
\l {Item::anchors.horizontalCenterOffset}{horizontalCenterOffset},
70
\l {Item::anchors.verticalCenterOffset}{verticalCenterOffset} and
71
\l {Item::anchors.baselineOffset}{baselineOffset}.
72
73
\image margins_qml.png
74
75
The following example specifies a left margin:
76
77
\code
78
Rectangle { id: rect1; ... }
79
Rectangle { id: rect2; anchors.left: rect1.right; anchors.leftMargin: 5; ... }
80
\endcode
81
82
In this case, a margin of 5 pixels is reserved to the left of \e rect2, producing the following:
83
84
\image edge2.png
85
86
\note Anchor margins only apply to anchors; they are \e not a generic means of applying margins to an \l Item.
87
If an anchor margin is specified for an edge but the item is not anchored to any item on that
88
edge, the margin is not applied.
89
90
\section1 Changing Anchors
91
92
Qt Quick provides the AnchorChanges type for specifying the anchors in a state.
93
94
\qml
95
State {
96
name: "anchorRight"
97
AnchorChanges {
98
target: rect2
99
anchors.right: parent.right
100
anchors.left: undefined //remove the left anchor
101
}
102
}
103
\endqml
104
105
AnchorChanges can be animated using the AnchorAnimation type.
106
107
\qml
108
Transition {
109
AnchorAnimation {} //animates any AnchorChanges in the corresponding state change
110
}
111
\endqml
112
113
Anchors can also be changed imperatively within JavaScript. However, these changes should be
114
carefully ordered, or they may produce unexpected outcomes. The following example illustrates the issue:
115
116
\table
117
\row
118
\li
119
\code
120
//bad code
121
Rectangle {
122
width: 50
123
anchors.left: parent.left
124
125
function reanchorToRight() {
126
anchors.right = parent.right
127
anchors.left = undefined
128
}
129
}
130
\endcode
131
\li
132
\image anchor_ordering_bad.png
133
\endtable
134
135
136
When \c reanchorToRight is called, the function first sets the right anchor. At that point, both left
137
and right anchors are set, and the item will be stretched horizontally to fill its parent. When the left
138
anchor is unset, the new width will remain. Thus when updating anchors within JavaScript, you should
139
first unset any anchors that are no longer required, and only then set any new anchors that are required,
140
as shown below:
141
142
\table
143
\row
144
\li
145
\qml
146
Rectangle {
147
width: 50
148
anchors.left: parent.left
149
150
function reanchorToRight() {
151
anchors.left = undefined
152
anchors.right = parent.right
153
}
154
}
155
\endqml
156
\li
157
\image anchor_ordering.png
158
\endtable
159
160
Because the evaluation order of bindings is not defined, it is not recommended to change anchors via
161
conditional bindings, as this can lead to the ordering issue described above. In the following example
162
the Rectangle will eventually grow to the full width of its parent, because both left and right anchors
163
will be simultaneously set during binding update.
164
165
\code
166
//bad code
167
Rectangle {
168
width: 50; height: 50
169
anchors.left: state == "right" ? undefined : parent.left;
170
anchors.right: state == "right" ? parent.right : undefined;
171
}
172
\endcode
173
174
This should be rewritten to use AnchorChanges instead, as AnchorChanges will automatically handle
175
ordering issues internally.
176
177
\section1 Restrictions
178
179
For performance reasons, you can only anchor an item to its siblings and direct parent. For example,
180
the following anchor is invalid and would produce a warning:
181
182
\code
183
//bad code
184
Item {
185
id: group1
186
Rectangle { id: rect1; ... }
187
}
188
Item {
189
id: group2
190
Rectangle { id: rect2; anchors.left: rect1.right; ... } // invalid anchor!
191
}
192
\endcode
193
194
Also, anchor-based layouts cannot be mixed with absolute positioning. If an item specifies its
195
\l {Item::}{x} position and also sets \l {Item::}{anchors.left},
196
or anchors its left and right edges but additionally sets a \l {Item::}{width}, the
197
result is undefined, as it would not be clear whether the item should use anchoring or absolute
198
positioning. The same can be said for setting an item's \l {Item::}{y} and \l {Item::}{height}
199
with \l {Item::}{anchors.top} and \l {Item::}{anchors.bottom}, or setting \l {Item::}{anchors.fill}
200
as well as \l {Item::}{width} or \l {Item::}{height}. The same applies when using positioners
201
such as Row and Grid, which may set the item's \l {Item::}{x} and \l {Item::}{y} properties.
202
If you wish to change from using
203
anchor-based to absolute positioning, you can clear an anchor value by setting it to \c undefined.
204
205
*/
qtdeclarative
src
quick
doc
src
concepts
positioning
anchors.qdoc
Generated on Sat Sep 28 2024 01:06:01 for Qt by
1.12.0