Fixes for Dynamic Object Management docs. Also adds links to

this page from other documentation.

Task-number: QTBUG-12446

4 files changed, 105 insertions, 28 deletions

diff --git a/doc/src/declarative/dynamicobjects.qdoc b/doc/src/declarative/dynamicobjects.qdoc
index 300799c..997f601 100644
--- a/doc/src/declarative/dynamicobjects.qdoc
+++ b/doc/src/declarative/dynamicobjects.qdoc
@@ -148,17 +148,47 @@ lots of dynamically created items, however, you may receive a worthwhile
 performance benefit if unused items are deleted.
 
 Note that you should never manually delete items that were dynamically created
-by QML elements (such as \l Loader and \l Repeater). Also, you should generally avoid deleting
+by QML elements (such as \l Loader and \l Repeater). Also, you should avoid deleting
 items that you did not dynamically create yourself.
 
 Items can be deleted using the \c destroy() method. This method has an optional
 argument (which defaults to 0) that specifies the approximate delay in milliseconds
-before the object is to be destroyed. This allows you to wait until the completion of
-an animation or transition. An example:
+before the object is to be destroyed. 
 
-\snippet doc/src/snippets/declarative/dynamicObjects.qml 0
+Here is an example. The \c application.qml creates five instances of the \c SelfDestroyingRect.qml
+component. Each instance runs a NumberAnimation, and when the animation has finished, calls
+\c destroy() on its root item to destroy itself:
+
+\table
+\row
+\o \c application.qml
+\o \c SelfDestroyingRect.qml
+
+\row
+\o \snippet doc/src/snippets/declarative/dynamicObjects-destroy.qml 0
+\o \snippet doc/src/snippets/declarative/SelfDestroyingRect.qml 0
+
+\endtable
+
+Alternatively, the \c application.qml could have destroyed the created object
+by calling \c object.destroy().
+
+Notice that if a \c SelfDestroyingRect instance was created statically like this:
+
+\qml
+Item {
+    SelfDestroyingRect { ... }
+}
+\endqml
+
+This would result in an error, since items can only be dynamically 
+destroyed if they were dynamically created.
+
+Objects created with \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()}
+can similarly be destroyed using \c destroy():
+
+\snippet doc/src/snippets/declarative/createQmlObject.qml 0
+\snippet doc/src/snippets/declarative/createQmlObject.qml destroy
 
-Here, \c Rectangle objects are destroyed one second after they are created, which is long
-enough for the \c NumberAnimation to be played before the object is destroyed.
 */
 
diff --git a/doc/src/snippets/declarative/dynamicObjects.qml b/doc/src/snippets/declarative/createComponent-simple.qml
index 3698499..9669580 100644
--- a/doc/src/snippets/declarative/dynamicObjects.qml
+++ b/doc/src/snippets/declarative/createComponent-simple.qml
@@ -37,33 +37,21 @@
 ** $QT_END_LICENSE$
 **
 ****************************************************************************/
-
-import Qt 4.7
-
 //![0]
-Rectangle {
-    id: rootItem
-    width: 300
-    height: 300
-
-    Component {
-        id: rectComponent
-
-        Rectangle {
-            id: rect
-            width: 40; height: 40;
-            color: "red"
+import Qt 4.7
 
-            NumberAnimation on opacity { from: 1; to: 0; duration: 1000 }
+Item {
+    id: container
+    width: 300; height: 300
 
-            Component.onCompleted: rect.destroy(1000);
+    function loadButton() {
+        var component = Qt.createComponent("Button.qml");
+        if (component.status == Component.Ready) {
+            var button = component.createObject(container);
+            button.color = "red";
         }
     }
 
-    function createRectangle() {
-        var object = rectComponent.createObject(rootItem);
-    } 
-
-    Component.onCompleted: createRectangle()
+    Component.onCompleted: loadButton()
 }
 //![0]
diff --git a/doc/src/snippets/declarative/createQmlObject.qml b/doc/src/snippets/declarative/createQmlObject.qml
index 64dd21d..a5f15f4 100644
--- a/doc/src/snippets/declarative/createQmlObject.qml
+++ b/doc/src/snippets/declarative/createQmlObject.qml
@@ -51,6 +51,10 @@ Rectangle {
 var newObject = Qt.createQmlObject('import Qt 4.7; Rectangle {color: "red"; width: 20; height: 20}',
     parentItem, "dynamicSnippet1");
 //![0]
+
+//![destroy]
+newObject.destroy(1000);
+//![destroy]
     }
 
     Component.onCompleted: createIt()
diff --git a/doc/src/snippets/declarative/dynamicObjects-destroy.qml b/doc/src/snippets/declarative/dynamicObjects-destroy.qml
new file mode 100644
index 0000000..2c0c2fb
--- /dev/null
+++ b/doc/src/snippets/declarative/dynamicObjects-destroy.qml
@@ -0,0 +1,55 @@
+/****************************************************************************
+**
+** 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 QtDeclarative module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+**     the names of its contributors may be used to endorse or promote
+**     products derived from this software without specific prior written
+**     permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+//![0]
+import Qt 4.7
+
+Item {
+    id: container
+    width: 500; height: 100
+
+    Component.onCompleted: {
+        var component = Qt.createComponent("SelfDestroyingRect.qml");
+        for (var i=0; i<5; i++) {
+            var object = component.createObject(container);
+            object.x = (object.width + 10) * i;
+        }
+    }
+}
+//![0]