Visual hierarchy documentation

Task-number: QTBUG-26367
Change-Id: I4a782118e96aecfaf7cfa6921afcb6dd1f86d66b
Reviewed-by: Bea Lam <bea.lam@nokia.com>

5 files changed, 187 insertions, 1 deletions

diff --git a/src/quick/doc/images/visual-parent-example.png b/src/quick/doc/images/visual-parent-example.png
new file mode 100644
index 0000000000..48dbe925c3
--- /dev/null
+++ b/src/quick/doc/images/visual-parent-example.png
diff --git a/src/quick/doc/images/visual-parent-example2.png b/src/quick/doc/images/visual-parent-example2.png
new file mode 100644
index 0000000000..42a628f1fe
--- /dev/null
+++ b/src/quick/doc/images/visual-parent-example2.png
diff --git a/src/quick/doc/snippets/qml/visualparent.qml b/src/quick/doc/snippets/qml/visualparent.qml
new file mode 100644
index 0000000000..1f0f8eded0
--- /dev/null
+++ b/src/quick/doc/snippets/qml/visualparent.qml
@@ -0,0 +1,64 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+**     the names of its contributors may be used to endorse or promote
+**     products derived from this software without specific prior written
+**     permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+import QtQuick 2.0
+
+//![0]
+Rectangle {
+    color: "#272822"
+    width: 320
+    height: 480
+
+    Rectangle {
+        y: 64
+        width: 256
+        height: 256
+        color: "green"
+    }
+
+    Rectangle {
+        x: 64
+        y: 172
+        width: 256
+        height: 256
+        color: "blue"
+    }
+}
+//![0]
diff --git a/src/quick/doc/snippets/qml/visualparent2.qml b/src/quick/doc/snippets/qml/visualparent2.qml
new file mode 100644
index 0000000000..cb679e78a7
--- /dev/null
+++ b/src/quick/doc/snippets/qml/visualparent2.qml
@@ -0,0 +1,75 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+**     the names of its contributors may be used to endorse or promote
+**     products derived from this software without specific prior written
+**     permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+import QtQuick 2.0
+
+//![0]
+Rectangle {
+    color: "#272822"
+    width: 320
+    height: 480
+
+    Rectangle {
+        y: 64
+        z: 1
+        width: 256
+        height: 256
+        color: "green"
+
+        Rectangle {
+            x: 192
+            y: 64
+            z: 2000
+            width: 128
+            height: 128
+            color: "red"
+        }
+    }
+
+    Rectangle {
+        x: 64
+        y: 192
+        z: 2
+        width: 256
+        height: 256
+        color: "blue"
+    }
+}
+//![0]
diff --git a/src/quick/doc/src/concepts/visualcanvas/visualparent.qdoc b/src/quick/doc/src/concepts/visualcanvas/visualparent.qdoc
index 72658e53eb..dcaae3d438 100644
--- a/src/quick/doc/src/concepts/visualcanvas/visualparent.qdoc
+++ b/src/quick/doc/src/concepts/visualcanvas/visualparent.qdoc
@@ -30,6 +30,53 @@
 \title Concepts - Visual Parent in Qt Quick
 \brief Description of the concept of visual parent in Qt Quick
 
-XXX TODO - Fill with content.
+\section1 Visual Parent
+The concept of visual parent in Qt Quick is separate but related to the concept of the QObject parent hierarchy. In QtQuick, the
+default property of Item is \l Item::data which can take any QObject derived type.
 
+Any object that is assigned to an item's data property becomes a child of the item within its QObject hierarchy, for
+memory management purposes. Additionally, if an object added to the data property is of the Item type, it is also
+assigned to the \l Item::children 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.
+
+Visual parent comes up most often in the following three circumstances:
+
+\section2 Item Coordinates
+As item coordinates are relative to the visual parent, they can be affected by changes to the visual hierarchy. See
+the \l{Visual Coordinates}{qtquick-visualcanvas-visualcoordinates.html} concept page for more detail.
+
+\section2 Stacking Order
+
+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:
+
+\snippet qml/visualparent.qml 0
+\image visual-parent-example.png
+
+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.
+
+Stacking order can be influenced with the \Item::z 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 who 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.
+
+\snippet qml/visualparent2.qml 0
+\image visual-parent-example2.png
+
+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.
+
+\section2 Canvas Ownership
+
+The definition of what is rendered in a Qt Quick scene is the visual item tree rooted at QQuickWindow::contentItem.
+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 QQuickWindow::contentItem.
 */