1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
6 \title Object Trees & Ownership
7 \ingroup qt-basic-concepts
8 \brief Information about the parent-child pattern used to describe
9 object ownership in Qt.
13 \l{QObject}{QObjects} organize themselves in object trees.
14 When you create a QObject with another object as parent, it's added to
15 the parent's \l{QObject::children()}{children()} list, and
16 is deleted when the parent is. It turns out that this approach fits
17 the needs of GUI objects very well. For example, a \l QShortcut
18 (keyboard shortcut) is a child of the relevant window, so when the
19 user closes that window, the shortcut is deleted too.
21 \l QQuickItem, the basic visual element of the Qt Quick module, inherits
22 from QObject, but has a concept of the \e {visual parent} which
23 differs from that of the \e {QObject parent}. An item's visual parent
24 may not necessarily be the same as its object parent. See
25 \l {Concepts - Visual Parent in Qt Quick} for more details.
27 \l QWidget, the fundamental class of the Qt Widgets module,
28 extends the parent-child relationship. A child normally also becomes a
29 child widget, i.e. it is displayed in its parent's coordinate system
30 and is graphically clipped by its parent's boundaries. For example,
31 when the application deletes a message box after it has been
32 closed, the message box's buttons and label are also deleted, just as
33 we'd want, because the buttons and label are children of the message
36 You can also delete child objects yourself, and they will remove
37 themselves from their parents. For example, when the user removes a
38 toolbar it may lead to the application deleting one of its \l QToolBar
39 objects, in which case the tool bar's \l QMainWindow parent would
40 detect the change and reconfigure its screen space accordingly.
42 The debugging functions \l QObject::dumpObjectTree() and \l
43 QObject::dumpObjectInfo() are often useful when an application looks or
46 \target note on the order of construction/destruction of QObjects
47 \section1 Construction/Destruction Order of QObjects
49 When \l {QObject} {QObjects} are created on the heap (i.e., created
50 with \e new), a tree can be constructed from them in any order, and
51 later, the objects in the tree can be destroyed in any order. When any
52 QObject in the tree is deleted, if the object has a parent, the
53 destructor automatically removes the object from its parent. If the
54 object has children, the destructor automatically deletes each
55 child. No QObject is deleted twice, regardless of the order of
58 When \l {QObject} {QObjects} are created on the stack, the same
59 behavior applies. Normally, the order of destruction still doesn't
60 present a problem. Consider the following snippet:
62 \snippet code/doc_src_objecttrees.cpp 0
64 The parent, \c window, and the child, \c quit, are both \l {QObject}
65 {QObjects} because QPushButton inherits QWidget, and QWidget inherits
66 QObject. This code is correct: the destructor of \c quit is \e not
67 called twice because the C++ language standard \e {(ISO/IEC 14882:2003)}
68 specifies that destructors of local objects are called in the reverse
69 order of their constructors. Therefore, the destructor of
70 the child, \c quit, is called first, and it removes itself from its
71 parent, \c window, before the destructor of \c window is called.
73 But now consider what happens if we swap the order of construction, as
74 shown in this second snippet:
76 \snippet code/doc_src_objecttrees.cpp 1
78 In this case, the order of destruction causes a problem. The parent's
79 destructor is called first because it was created last. It then calls
80 the destructor of its child, \c quit, which is incorrect because \c
81 quit is a local variable. When \c quit subsequently goes out of scope,
82 its destructor is called again, this time correctly, but the damage has
1.10.0