src/quick/doc/src/concepts/visualcanvas/visualparent.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** GNU Free Documentation License
  10 ** Alternatively, this file may be used under the terms of the GNU Free
  11 ** Documentation License version 1.3 as published by the Free Software
  12 ** Foundation and appearing in the file included in the packaging of
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29 \page qtquick-visualcanvas-visualparent.html
  30 \title Concepts - Visual Parent in Qt Quick
  31 \brief Description of the concept of visual parent in Qt Quick
  32
  33 \section1 Visual Parent
  34 The concept of visual parent in Qt Quick is separate but related to the concept of the QObject parent hierarchy. In QtQuick, the
  35 default property of Item is \l Item::data which can be any QObject derived type.
  36
  37 Any object that is assigned to an item's data property becomes a child of the item within its QObject hierarchy, for
  38 memory management purposes. Additionally, if an object added to the data property is of the Item type, it is also
  39 assigned to the \l Item::children property and becomes a child of the item within the visual scene hierarchy.
  40 (Most Qt Quick hierarchy crawling algorithms, especially the rendering algorithms, only consider the visual parent
  41 hierarchy.)
  42
  43 When an item becomes the child of another item:
  44
  45 \list
  46 \li The child's \l{Item::parent}{parent} refers to its parent item
  47 \li The parent's \l{Item::children}{children} and \l{Item::childrenRect}{childrenRect} properties takes that
  48     child into account
  49 \endlist
  50
  51 An item's visual parent can be changed at any time by setting its \l {Item::}{parent} property.
  52
  53 Declaring an item as a child of another does not automatically mean that the child item will be appropriately
  54 positioned or sized to fit within its parent. Some QML types may have in-built behaviors that affect the positioning
  55 of child items — for example, a \l Row object automatically re-positions its children into a horizontal formation —
  56 but these are behaviors enforced by the types' own specific implementations. Additionally, a parent item will not
  57 automatically clip its children to visually contain them within the parent's visual bounds, unless its \l{Item::}{clip}
  58 property is set to true.
  59
  60 The visual parent of an item may come under consideration in the following circumstances:
  61
  62 \section2 Item Coordinates
  63 As item coordinates are relative to the visual parent, they can be affected by changes to the visual hierarchy. See
  64 the \l{Visual Coordinates}{qtquick-visualcanvas-visualcoordinates.html} concept page for more detail.
  65
  66 \section2 Stacking Order
  67
  68 Qt Quick items use a recursive drawing algorithm for determining which items are drawn on top in case of collisions.
  69 In general items are drawn on top of their parent items, in the order they were created (or specified in the QML file).
  70 So in the following example, the blue rectangle will be drawn on top of the green rectangle:
  71
  72 \snippet qml/visualparent.qml 0
  73 \image visual-parent-example.png
  74
  75 Because the algorithm recurses through the visual item hierarchy, any children of the green rectangle will also be drawn beneath
  76 the blue rectangle and beneath any of the blue rectangle's children.
  77
  78 Stacking order can be influenced with the \Item::z property. Z values below 0 will stack below the parent, and if z
  79 values are assigned then siblings will stack in z-order (with creation order used to break ties). Z values only affect
  80 stacking compared to siblings and the parent item. If you have an item who is obscured by a subtree rooted above its
  81 parent item, no z value on that item will increase its stacking order to stack above that subtree. To stack that item
  82 above the other subtree you'll have to alter z values farther up in the hierarchy, or re-arrange the visual item
  83 hierarchy.
  84
  85 \snippet qml/visualparent2.qml 0
  86 \image visual-parent-example2.png
  87
  88 In the above example, the red rectangle has a high z value, but is still stacked below the blue rectangle. This is
  89 because it is a child of the green rectangle, and the green rectangle is a sibling of the blue rectangle. The z value
  90 of the green rectangle is lower than that of the blue rectangle, so the green rectangle and all children will be
  91 stacked beneath the blue rectangle.
  92
  93 \section2 Canvas Ownership
  94
  95 The definition of what is rendered in a Qt Quick scene is the visual item tree rooted at QQuickWindow::contentItem.
  96 Therefore to add an Item to a specific Qt Quick scene for rendering it needs to become a visual hierarchy child of an
  97 Item already in the visual item hierarchy, such as QQuickWindow::contentItem.
  98 */