/****************************************************************************

**

** Copyright (C) 2009 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.

*/