/****************************************************************************+
−
**+
−
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).+
−
** All rights reserved.+
−
** Contact: Nokia Corporation (qt-info@nokia.com)+
−
**+
−
** This file is part of the documentation of the Qt Toolkit.+
−
**+
−
** $QT_BEGIN_LICENSE:LGPL$+
−
** No Commercial Usage+
−
** This file contains pre-release code and may not be distributed.+
−
** You may use this file in accordance with the terms and conditions+
−
** contained in the Technology Preview License Agreement accompanying+
−
** this package.+
−
**+
−
** GNU Lesser General Public License Usage+
−
** Alternatively, this file may be used under the terms of the GNU Lesser+
−
** General Public License version 2.1 as published by the Free Software+
−
** Foundation and appearing in the file LICENSE.LGPL included in the+
−
** packaging of this file.  Please review the following information to+
−
** ensure the GNU Lesser General Public License version 2.1 requirements+
−
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.+
−
**+
−
** In addition, as a special exception, Nokia gives you certain additional+
−
** rights.  These rights are described in the Nokia Qt LGPL Exception+
−
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.+
−
**+
−
** If you have questions regarding the use of this file, please contact+
−
** Nokia at qt-info@nokia.com.+
−
**+
−
**+
−
**+
−
**+
−
**+
−
**+
−
**+
−
**+
−
** $QT_END_LICENSE$+
−
**+
−
****************************************************************************/+
−
+
−
/*!+
−
    \page objecttrees.html+
−
    \title Object Trees and Object Ownership+
−
    \brief Information about the parent-child pattern used to describe+
−
    object ownership in Qt.+
−
+
−
    \section1 Overview+
−
+
−
    \link QObject QObjects\endlink organize themselves in object trees.+
−
    When you create a QObject with another object as parent, it's added to+
−
    the parent's \link QObject::children() children() \endlink list, and+
−
    is deleted when the parent is. It turns out that this approach fits+
−
    the needs of GUI objects very well. For example, a \l QShortcut+
−
    (keyboard shortcut) is a child of the relevant window, so when the+
−
    user closes that window, the shorcut is deleted too.+
−
+
−
    \l QWidget, the base class of everything that appears on the screen,+
−
    extends the parent-child relationship. A child normally also becomes a+
−
    child widget, i.e. it is displayed in its parent's coordinate system+
−
    and is graphically clipped by its parent's boundaries. For example,+
−
    when the application deletes a message box after it has been+
−
    closed, the message box's buttons and label are also deleted, just as+
−
    we'd want, because the buttons and label are children of the message+
−
    box.+
−
+
−
    You can also delete child objects yourself, and they will remove+
−
    themselves from their parents. For example, when the user removes a+
−
    toolbar it may lead to the application deleting one of its \l QToolBar+
−
    objects, in which case the tool bar's \l QMainWindow parent would+
−
    detect the change and reconfigure its screen space accordingly.+
−
+
−
    The debugging functions \l QObject::dumpObjectTree() and \l+
−
    QObject::dumpObjectInfo() are often useful when an application looks or+
−
    acts strangely.+
−
+
−
    \target note on the order of construction/destruction of QObjects+
−
    \section1 Construction/Destruction Order of QObjects+
−
+
−
    When \l {QObject} {QObjects} are created on the heap (i.e., created+
−
    with \e new), a tree can be constructed from them in any order, and+
−
    later, the objects in the tree can be destroyed in any order. When any+
−
    QObject in the tree is deleted, if the object has a parent, the+
−
    destructor automatically removes the object from its parent. If the+
−
    object has children, the destructor automatically deletes each+
−
    child. No QObject is deleted twice, regardless of the order of+
−
    destruction.+
−
+
−
    When \l {QObject} {QObjects} are created on the stack, the same+
−
    behavior applies. Normally, the order of destruction still doesn't+
−
    present a problem. Consider the following snippet:+
−
+
−
    \snippet doc/src/snippets/code/doc_src_objecttrees.qdoc 0+
−
+
−
    The parent, \c window, and the child, \c quit, are both \l {QObject}+
−
    {QObjects} because QPushButton inherits QWidget, and QWidget inherits+
−
    QObject. This code is correct: the destructor of \c quit is \e not+
−
    called twice because the C++ language standard \e {(ISO/IEC 14882:2003)}+
−
    specifies that destructors of local objects are called in the reverse+
−
    order of their constructors. Therefore, the destructor of+
−
    the child, \c quit, is called first, and it removes itself from its+
−
    parent, \c window, before the destructor of \c window is called.+
−
+
−
    But now consider what happens if we swap the order of construction, as+
−
    shown in this second snippet:+
−
+
−
    \snippet doc/src/snippets/code/doc_src_objecttrees.qdoc 1+
−
+
−
    In this case, the order of destruction causes a problem. The parent's+
−
    destructor is called first because it was created last. It then calls+
−
    the destructor of its child, \c quit, which is incorrect because \c+
−
    quit is a local variable. When \c quit subsequently goes out of scope,+
−
    its destructor is called again, this time correctly, but the damage has+
−
    already been done.+
−
*/+
−