doc/src/objectmodel/objecttrees.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:FDL$
  10 ** GNU Free Documentation License
  11 ** Alternatively, this file may be used under the terms of the GNU Free
  12 ** Documentation License version 1.3 as published by the Free Software
  13 ** Foundation and appearing in the file included in the packaging of
  14 ** this file.
  15 **
  16 ** Other Usage
  17 ** Alternatively, this file may be used in accordance with the terms
  18 ** and conditions contained in a signed written agreement between you
  19 ** and Nokia.
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \page objecttrees.html
  30     \title Object Trees & Ownership
  31     \ingroup qt-basic-concepts
  32     \brief Information about the parent-child pattern used to describe
  33     object ownership in Qt.
  34
  35     \section1 Overview
  36
  37     \link QObject QObjects\endlink organize themselves in object trees.
  38     When you create a QObject with another object as parent, it's added to
  39     the parent's \link QObject::children() children() \endlink list, and
  40     is deleted when the parent is. It turns out that this approach fits
  41     the needs of GUI objects very well. For example, a \l QShortcut
  42     (keyboard shortcut) is a child of the relevant window, so when the
  43     user closes that window, the shorcut is deleted too.
  44
  45     \l QWidget, the base class of everything that appears on the screen,
  46     extends the parent-child relationship. A child normally also becomes a
  47     child widget, i.e. it is displayed in its parent's coordinate system
  48     and is graphically clipped by its parent's boundaries. For example,
  49     when the application deletes a message box after it has been
  50     closed, the message box's buttons and label are also deleted, just as
  51     we'd want, because the buttons and label are children of the message
  52     box.
  53
  54     You can also delete child objects yourself, and they will remove
  55     themselves from their parents. For example, when the user removes a
  56     toolbar it may lead to the application deleting one of its \l QToolBar
  57     objects, in which case the tool bar's \l QMainWindow parent would
  58     detect the change and reconfigure its screen space accordingly.
  59
  60     The debugging functions \l QObject::dumpObjectTree() and \l
  61     QObject::dumpObjectInfo() are often useful when an application looks or
  62     acts strangely.
  63
  64     \target note on the order of construction/destruction of QObjects
  65     \section1 Construction/Destruction Order of QObjects
  66
  67     When \l {QObject} {QObjects} are created on the heap (i.e., created
  68     with \e new), a tree can be constructed from them in any order, and
  69     later, the objects in the tree can be destroyed in any order. When any
  70     QObject in the tree is deleted, if the object has a parent, the
  71     destructor automatically removes the object from its parent. If the
  72     object has children, the destructor automatically deletes each
  73     child. No QObject is deleted twice, regardless of the order of
  74     destruction.
  75
  76     When \l {QObject} {QObjects} are created on the stack, the same
  77     behavior applies. Normally, the order of destruction still doesn't
  78     present a problem. Consider the following snippet:
  79
  80     \snippet doc/src/snippets/code/doc_src_objecttrees.cpp 0
  81
  82     The parent, \c window, and the child, \c quit, are both \l {QObject}
  83     {QObjects} because QPushButton inherits QWidget, and QWidget inherits
  84     QObject. This code is correct: the destructor of \c quit is \e not
  85     called twice because the C++ language standard \e {(ISO/IEC 14882:2003)}
  86     specifies that destructors of local objects are called in the reverse
  87     order of their constructors. Therefore, the destructor of
  88     the child, \c quit, is called first, and it removes itself from its
  89     parent, \c window, before the destructor of \c window is called.
  90
  91     But now consider what happens if we swap the order of construction, as
  92     shown in this second snippet:
  93
  94     \snippet doc/src/snippets/code/doc_src_objecttrees.cpp 1
  95
  96     In this case, the order of destruction causes a problem. The parent's
  97     destructor is called first because it was created last. It then calls
  98     the destructor of its child, \c quit, which is incorrect because \c
  99     quit is a local variable. When \c quit subsequently goes out of scope,
 100     its destructor is called again, this time correctly, but the damage has
 101     already been done.
 102 */