/usr/share/qt5/doc/qtquick/qtquick-visualcanvas-visualparent.html is in qtdeclarative5-doc-html 5.9.5-0ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- visualparent.qdoc -->
<title>Concepts - Visual Parent in Qt Quick | Qt Quick 5.9</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.9</td><td ><a href="qtquick-index.html">Qt Quick</a></td><td >Concepts - Visual Parent in Qt Quick</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.9.5 Reference Documentation</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="#visual-parent">Visual Parent</a></li>
<li class="level2"><a href="#item-coordinates">Item Coordinates</a></li>
<li class="level2"><a href="#stacking-order">Stacking Order</a></li>
<li class="level2"><a href="#canvas-ownership">Canvas Ownership</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Concepts - Visual Parent in Qt Quick</h1>
<span class="subtitle"></span>
<!-- $$$qtquick-visualcanvas-visualparent.html-description -->
<div class="descr"> <a name="details"></a>
<a name="visual-parent"></a>
<h2 id="visual-parent">Visual Parent</h2>
<p>When creating visual scenes with Qt Quick, it is important to understand the concept of the <i>visual parent</i>.</p>
<p>The concept of the visual parent in Qt Quick is separate from, but related to, the concept of the <i>object parent</i> within the <a href="../qtcore/qobject.html">QObject</a> parent hierarchy. All QML objects have an <i>object parent</i>, which is determined by the object hierarchy in which the object is declared. When working with the <code>QtQuick</code> module, the <a href="qml-qtquick-item.html">Item</a> type is the base type for all visual items provided by this module, and it provides the concept of an additional <i>visual parent</i>, as defined by an item's <a href="qml-qtquick-item.html#parent-prop">parent</a> property. Every item has a visual parent; if an item's <a href="qml-qtquick-item.html#parent-prop">parent</a> property value is <code>null</code>, the item will not be rendered in the scene.</p>
<p>Any object assigned to an item's <a href="qml-qtquick-item.html#data-prop">data</a> property becomes a child of the item within its <a href="../qtcore/qobject.html">QObject</a> hierarchy, for memory management purposes. Additionally, if an object added to the data property is of the <a href="qml-qtquick-item.html">Item</a> type, it is also assigned to the <a href="qml-qtquick-item.html#children-prop">Item::children</a> property and becomes a child of the item within the visual scene hierarchy. (Most Qt Quick hierarchy crawling algorithms, especially the rendering algorithms, only consider the visual parent hierarchy.)</p>
<p>For convenience, the Item <a href="qml-qtquick-item.html#data-prop">data</a> property is its default property. This means that any child item declared within an <a href="qml-qtquick-item.html">Item</a> object without being assigned to a specific property is automatically assigned to the <a href="qml-qtquick-item.html#data-prop">data</a> property and becomes a child of the item as described above. So, the two code blocks below produce the same result, and you will almost always see the form shown below left, rather than the explicit <code>data</code> assignment shown below right:</p>
<div class="table"><table class="generic">
<tr valign="top" class="odd"><td ><pre class="cpp">
import <span class="type"><a href="qtquick-module.html">QtQuick</a></span> <span class="number">2.0</span>
Item {
width: <span class="number">100</span>; height: <span class="number">100</span>
Rectangle { width: <span class="number">50</span>;
height: <span class="number">50</span>;
color: <span class="string">"red"</span> }
}
</pre>
</td><td ><pre class="cpp">
import <span class="type"><a href="qtquick-module.html">QtQuick</a></span> <span class="number">2.0</span>
Item {
width: <span class="number">100</span>; height: <span class="number">100</span>
data: <span class="operator">[</span>
Rectangle { width: <span class="number">50</span>;
height: <span class="number">50</span>;
color: <span class="string">"red"</span> }
<span class="operator">]</span>
}
</pre>
</td></tr>
</table></div>
<p>An item's visual parent can be changed at any time by setting its <a href="qml-qtquick-item.html#parent-prop">parent</a> property. Thus, an item's visual parent may not necessarily be the same as its object parent.</p>
<p>When an item becomes the child of another item:</p>
<ul>
<li>The child's <a href="qml-qtquick-item.html#parent-prop">parent</a> refers to its parent item</li>
<li>The parent's <a href="qml-qtquick-item.html#children-prop">children</a> and <a href="qml-qtquick-item.html#childrenRect.x-prop">childrenRect</a> properties takes that child into account</li>
</ul>
<p>Declaring an item as a child of another does not automatically mean that the child item will be appropriately positioned or sized to fit within its parent. Some QML types may have in-built behaviors that affect the positioning of child items — for example, a <a href="qtquick-positioning-layouts.html#row">Row</a> object automatically re-positions its children into a horizontal formation — but these are behaviors enforced by the types' own specific implementations. Additionally, a parent item will not automatically clip its children to visually contain them within the parent's visual bounds, unless its <a href="qml-qtquick-item.html#clip-prop">clip</a> property is set to true.</p>
<p>The visual parent of an item may come under consideration in particular circumstances, as described in the sections below.</p>
<a name="item-coordinates"></a>
<h3 >Item Coordinates</h3>
<p>As item coordinates are relative to the visual parent, they can be affected by changes to the visual hierarchy. See the <a href="qtquick-visualcanvas-coordinates.html">Visual Coordinates</a> concept page for more detail.</p>
<a name="stacking-order"></a>
<h3 >Stacking Order</h3>
<p>Qt Quick items use a recursive drawing algorithm for determining which items are drawn on top in case of collisions. In general items are drawn on top of their parent items, in the order they were created (or specified in the QML file). So in the following example, the blue rectangle will be drawn on top of the green rectangle:</p>
<pre class="qml">
<span class="type"><a href="qml-qtquick-rectangle.html">Rectangle</a></span> {
<span class="name">color</span>: <span class="string">"#272822"</span>
<span class="name">width</span>: <span class="number">320</span>
<span class="name">height</span>: <span class="number">480</span>
<span class="type"><a href="qml-qtquick-rectangle.html">Rectangle</a></span> {
<span class="name">y</span>: <span class="number">64</span>
<span class="name">width</span>: <span class="number">256</span>
<span class="name">height</span>: <span class="number">256</span>
<span class="name">color</span>: <span class="string">"green"</span>
}
<span class="type"><a href="qml-qtquick-rectangle.html">Rectangle</a></span> {
<span class="name">x</span>: <span class="number">64</span>
<span class="name">y</span>: <span class="number">172</span>
<span class="name">width</span>: <span class="number">256</span>
<span class="name">height</span>: <span class="number">256</span>
<span class="name">color</span>: <span class="string">"blue"</span>
}
}
</pre>
<p class="centerAlign"><img src="images/visual-parent-example.png" alt="" /></p><p>Because the algorithm recurses through the visual item hierarchy, any children of the green rectangle will also be drawn beneath the blue rectangle and beneath any of the blue rectangle's children.</p>
<p>Stacking order can be influenced with the <a href="qml-qtquick-item.html#z-prop">Item::z</a> property. Z values below 0 will stack below the parent, and if z values are assigned then siblings will stack in z-order (with creation order used to break ties). Z values only affect stacking compared to siblings and the parent item. If you have an item which is obscured by a subtree rooted above its parent item, no z value on that item will increase its stacking order to stack above that subtree. To stack that item above the other subtree you'll have to alter z values farther up in the hierarchy, or re-arrange the visual item hierarchy.</p>
<pre class="qml">
<span class="type"><a href="qml-qtquick-rectangle.html">Rectangle</a></span> {
<span class="name">color</span>: <span class="string">"#272822"</span>
<span class="name">width</span>: <span class="number">320</span>
<span class="name">height</span>: <span class="number">480</span>
<span class="type"><a href="qml-qtquick-rectangle.html">Rectangle</a></span> {
<span class="name">y</span>: <span class="number">64</span>
<span class="name">z</span>: <span class="number">1</span>
<span class="name">width</span>: <span class="number">256</span>
<span class="name">height</span>: <span class="number">256</span>
<span class="name">color</span>: <span class="string">"green"</span>
<span class="type"><a href="qml-qtquick-rectangle.html">Rectangle</a></span> {
<span class="name">x</span>: <span class="number">192</span>
<span class="name">y</span>: <span class="number">64</span>
<span class="name">z</span>: <span class="number">2000</span>
<span class="name">width</span>: <span class="number">128</span>
<span class="name">height</span>: <span class="number">128</span>
<span class="name">color</span>: <span class="string">"red"</span>
}
}
<span class="type"><a href="qml-qtquick-rectangle.html">Rectangle</a></span> {
<span class="name">x</span>: <span class="number">64</span>
<span class="name">y</span>: <span class="number">192</span>
<span class="name">z</span>: <span class="number">2</span>
<span class="name">width</span>: <span class="number">256</span>
<span class="name">height</span>: <span class="number">256</span>
<span class="name">color</span>: <span class="string">"blue"</span>
}
}
</pre>
<p class="centerAlign"><img src="images/visual-parent-example2.png" alt="" /></p><p>In the above example, the red rectangle has a high z value, but is still stacked below the blue rectangle. This is because it is a child of the green rectangle, and the green rectangle is a sibling of the blue rectangle. The z value of the green rectangle is lower than that of the blue rectangle, so the green rectangle and all children will be stacked beneath the blue rectangle.</p>
<a name="canvas-ownership"></a>
<h3 >Canvas Ownership</h3>
<p>The definition of what is rendered in a Qt Quick scene is the visual item tree rooted at <a href="qquickwindow.html#contentItem-prop">QQuickWindow::contentItem</a>. Therefore to add an Item to a specific Qt Quick scene for rendering it needs to become a visual hierarchy child of an Item already in the visual item hierarchy, such as <a href="qquickwindow.html#contentItem-prop">QQuickWindow::contentItem</a>.</p>
</div>
<!-- @@@qtquick-visualcanvas-visualparent.html -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2017 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>
|