<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- anchors.qdoc -->
<title>Positioning with Anchors | Qt Quick 5.12.6</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td >Qt 5.12</td><td ><a href="qtquick-index.html">Qt Quick</a></td><td >Positioning with Anchors</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right"><a href="qtquick-index.html">Qt 5.12.6 Reference Documentation</a></td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#anchor-margins-and-offsets">Anchor Margins and Offsets</a></li>
<li class="level1"><a href="#changing-anchors">Changing Anchors</a></li>
<li class="level1"><a href="#restrictions">Restrictions</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Positioning with Anchors</h1>
<span class="subtitle"></span>
<!-- $$$qtquick-positioning-anchors.html-description -->
<div class="descr"> <a name="details"></a>
<p>In addition to the more traditional <a href="qml-qtquick-grid.html">Grid</a>, <a href="qml-qtquick-row.html">Row</a>, and <a href="qml-qtquick-column.html">Column</a>, Qt Quick also provides a way to layout items using the concept of <i>anchors</i>. Each item can be thought of as having a set of 7 invisible "anchor lines": <a href="qml-qtquick-item.html#anchors.left-prop">left</a>, <a href="qml-qtquick-item.html#anchors.horizontalCenter-prop">horizontalCenter</a>, <a href="qml-qtquick-item.html#anchors.right-prop">right</a>, <a href="qml-qtquick-item.html#anchors.top-prop">top</a>, <a href="qml-qtquick-item.html#anchors.verticalCenter-prop">verticalCenter</a>, <a href="qml-qtquick-item.html#anchors.baseline-prop">baseline</a>, and <a href="qml-qtquick-item.html#anchors.bottom-prop">bottom</a>.</p>
<p class="centerAlign"><img src="images/edges_qml.png" alt="" /></p><p>The baseline (not pictured above) corresponds to the imaginary line on which text would sit. For items with no text it is the same as <i>top</i>.</p>
<p>The Qt Quick anchoring system allows you to define relationships between the anchor lines of different items. For example, you can write:</p>
<pre class="cpp">
Rectangle { id: rect1; <span class="operator">.</span><span class="operator">.</span><span class="operator">.</span> }
Rectangle { id: rect2; anchors<span class="operator">.</span>left: rect1<span class="operator">.</span>right; <span class="operator">.</span><span class="operator">.</span><span class="operator">.</span> }
</pre>
<p>In this case, the left edge of <i>rect2</i> is bound to the right edge of <i>rect1</i>, producing the following:</p>
<p class="centerAlign"><img src="images/edge1.png" alt="" /></p><p>You can specify multiple anchors. For example:</p>
<pre class="cpp">
Rectangle { id: rect1; <span class="operator">.</span><span class="operator">.</span><span class="operator">.</span> }
Rectangle { id: rect2; anchors<span class="operator">.</span>left: rect1<span class="operator">.</span>right; anchors<span class="operator">.</span>top: rect1<span class="operator">.</span>bottom; <span class="operator">.</span><span class="operator">.</span><span class="operator">.</span> }
</pre>
<p class="centerAlign"><img src="images/edge3.png" alt="" /></p><p>By specifying multiple horizontal or vertical anchors you can control the size of an item. Below, <i>rect2</i> is anchored to the right of <i>rect1</i> and the left of <i>rect3</i>. If either of the blue rectangles are moved, <i>rect2</i> will stretch and shrink as necessary:</p>
<pre class="cpp">
Rectangle { id: rect1; x: <span class="number">0</span>; <span class="operator">.</span><span class="operator">.</span><span class="operator">.</span> }
Rectangle { id: rect2; anchors<span class="operator">.</span>left: rect1<span class="operator">.</span>right; anchors<span class="operator">.</span>right: rect3<span class="operator">.</span>left; <span class="operator">.</span><span class="operator">.</span><span class="operator">.</span> }
Rectangle { id: rect3; x: <span class="number">150</span>; <span class="operator">.</span><span class="operator">.</span><span class="operator">.</span> }
</pre>
<p class="centerAlign"><img src="images/edge4.png" alt="" /></p><p>There are also some convenience anchors. anchors.fill is a convenience that is the same as setting the left,right,top and bottom anchors 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 and horizontalCenter anchors to the verticalCenter and horizontalCenter of the target item.</p>
<a name="anchor-margins-and-offsets"></a>
<h2 id="anchor-margins-and-offsets">Anchor Margins and Offsets</h2>
<p>The anchoring system also allows <i>margins</i> and <i>offsets</i> to be specified for an item's anchors. Margins specify the amount of empty space to leave to the outside of an item's anchor, while offsets allow positioning to be manipulated using the center anchor lines. An item can specify its anchor margins individually through <a href="qml-qtquick-item.html#anchors.leftMargin-prop">leftMargin</a>, <a href="qml-qtquick-item.html#anchors.rightMargin-prop">rightMargin</a>, <a href="qml-qtquick-item.html#anchors.topMargin-prop">topMargin</a> and <a href="qml-qtquick-item.html#anchors.bottomMargin-prop">bottomMargin</a>, or use <a href="qml-qtquick-item.html#anchors.margins-prop">anchors.margins</a> to specify the same margin value for all four edges. Anchor offsets are specified using <a href="qml-qtquick-item.html#anchors.horizontalCenterOffset-prop">horizontalCenterOffset</a>, <a href="qml-qtquick-item.html#anchors.verticalCenterOffset-prop">verticalCenterOffset</a> and <a href="qml-qtquick-item.html#anchors.baselineOffset-prop">baselineOffset</a>.</p>
<p class="centerAlign"><img src="images/margins_qml.png" alt="" /></p><p>The following example specifies a left margin:</p>
<pre class="cpp">
Rectangle { id: rect1; <span class="operator">.</span><span class="operator">.</span><span class="operator">.</span> }
Rectangle { id: rect2; anchors<span class="operator">.</span>left: rect1<span class="operator">.</span>right; anchors<span class="operator">.</span>leftMargin: <span class="number">5</span>; <span class="operator">.</span><span class="operator">.</span><span class="operator">.</span> }
</pre>
<p>In this case, a margin of 5 pixels is reserved to the left of <i>rect2</i>, producing the following:</p>
<p class="centerAlign"><img src="images/edge2.png" alt="" /></p><p><b>Note: </b>Anchor margins only apply to anchors; they are <i>not</i> a generic means of applying margins to an <a href="qml-qtquick-item.html">Item</a>. If an anchor margin is specified for an edge but the item is not anchored to any item on that edge, the margin is not applied.</p><a name="changing-anchors"></a>
<h2 id="changing-anchors">Changing Anchors</h2>
<p>Qt Quick provides the <a href="qml-qtquick-anchorchanges.html">AnchorChanges</a> type for specifying the anchors in a state.</p>
<pre class="qml">
</pre>
<p><a href="qml-qtquick-anchorchanges.html">AnchorChanges</a> can be animated using the <a href="qml-qtquick-anchoranimation.html">AnchorAnimation</a> type.</p>
<pre class="qml">
</pre>
<p>Anchors can also be changed imperatively within JavaScript. However, these changes should be carefully ordered, or they may produce unexpected outcomes. The following example illustrates the issue:</p>
<div class="table"><table class="generic">
<tr valign="top" class="odd"><td ><pre class="cpp">
<span class="comment">//bad code</span>
Rectangle {
width: <span class="number">50</span>
anchors<span class="operator">.</span>left: parent<span class="operator">.</span>left
function reanchorToRight() {
anchors<span class="operator">.</span>right <span class="operator">=</span> parent<span class="operator">.</span>right
anchors<span class="operator">.</span>left <span class="operator">=</span> undefined
}
}
</pre>
</td><td ><p class="centerAlign"><img src="images/anchor_ordering_bad.png" alt="" /></p></td></tr>
</table></div>
<p>When <code>reanchorToRight</code> is called, the function first sets the right anchor. At that point, both left and right anchors are set, and the item will be stretched horizontally to fill its parent. When the left anchor is unset, the new width will remain. Thus when updating anchors within JavaScript, you should first unset any anchors that are no longer required, and only then set any new anchors that are required, as shown below:</p>
<div class="table"><table class="generic">
<tr valign="top" class="odd"><td ><pre class="qml">
</pre>
</td><td ><p class="centerAlign"><img src="images/anchor_ordering.png" alt="" /></p></td></tr>
</table></div>
<p>Because the evaluation order of bindings is not defined, it is not recommended to change anchors via conditional bindings, as this can lead to the ordering issue described above. In the following example the Rectangle will eventually grow to the full width of its parent, because both left and right anchors will be simultaneously set during binding update.</p>
<pre class="cpp">
<span class="comment">//bad code</span>
Rectangle {
width: <span class="number">50</span>; height: <span class="number">50</span>
anchors<span class="operator">.</span>left: state <span class="operator">=</span><span class="operator">=</span> <span class="string">"right"</span> <span class="operator">?</span> undefined : parent<span class="operator">.</span>left;
anchors<span class="operator">.</span>right: state <span class="operator">=</span><span class="operator">=</span> <span class="string">"right"</span> <span class="operator">?</span> parent<span class="operator">.</span>right : undefined;
}
</pre>
<p>This should be rewritten to use <a href="qml-qtquick-anchorchanges.html">AnchorChanges</a> instead, as <a href="qml-qtquick-anchorchanges.html">AnchorChanges</a> will automatically handle ordering issues internally.</p>
<a name="restrictions"></a>
<h2 id="restrictions">Restrictions</h2>
<p>For performance reasons, you can only anchor an item to its siblings and direct parent. For example, the following anchor is invalid and would produce a warning:</p>
<pre class="cpp">
<span class="comment">//bad code</span>
Item {
id: group1
Rectangle { id: rect1; <span class="operator">.</span><span class="operator">.</span><span class="operator">.</span> }
}
Item {
id: group2
Rectangle { id: rect2; anchors<span class="operator">.</span>left: rect1<span class="operator">.</span>right; <span class="operator">.</span><span class="operator">.</span><span class="operator">.</span> } <span class="comment">// invalid anchor!</span>
}
</pre>
<p>Also, anchor-based layouts cannot be mixed with absolute positioning. If an item specifies its <a href="qml-qtquick-item.html#x-prop">x</a> position and also sets <a href="qml-qtquick-item.html#anchors.left-prop">anchors.left</a>, or anchors its left and right edges but additionally sets a <a href="qml-qtquick-item.html#width-prop">width</a>, the result is undefined, as it would not be clear whether the item should use anchoring or absolute positioning. The same can be said for setting an item's <a href="qml-qtquick-item.html#y-prop">y</a> and <a href="qml-qtquick-item.html#height-prop">height</a> with <a href="qml-qtquick-item.html#anchors.top-prop">anchors.top</a> and <a href="qml-qtquick-item.html#anchors.bottom-prop">anchors.bottom</a>, or setting <a href="qml-qtquick-item.html#anchors.fill-prop">anchors.fill</a> as well as <a href="qml-qtquick-item.html#width-prop">width</a> or <a href="qml-qtquick-item.html#height-prop">height</a>. The same applies when using positioners such as Row and Grid, which may set the item's <a href="qml-qtquick-item.html#x-prop">x</a> and <a href="qml-qtquick-item.html#y-prop">y</a> properties. If you wish to change from using anchor-based to absolute positioning, you can clear an anchor value by setting it to <code>undefined</code>.</p>
</div>
<!-- @@@qtquick-positioning-anchors.html -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2019 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br/> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br/> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
distrib
>
Mageia
>
7
>
i586
>
media
>
core-updates
>
by-pkgid
>
6e2327ca1c896c6d674ae53117299f21
>
files
>
1583
