From ceeb0fc0327c99de55d4dd6114908ec389dc58eb Mon Sep 17 00:00:00 2001 From: Bea Lam Date: Wed, 28 Jul 2010 16:21:42 +1000 Subject: Fixes for Dynamic Object Management docs. Also adds links to this page from other documentation. Task-number: QTBUG-12446 --- doc/src/declarative/dynamicobjects.qdoc | 42 +++++++++++-- .../declarative/createComponent-simple.qml | 57 ++++++++++++++++++ doc/src/snippets/declarative/createQmlObject.qml | 4 ++ .../declarative/dynamicObjects-destroy.qml | 55 +++++++++++++++++ doc/src/snippets/declarative/dynamicObjects.qml | 69 ---------------------- src/declarative/qml/qdeclarativecomponent.cpp | 3 + src/declarative/qml/qdeclarativeengine.cpp | 27 ++++----- 7 files changed, 165 insertions(+), 92 deletions(-) create mode 100644 doc/src/snippets/declarative/createComponent-simple.qml create mode 100644 doc/src/snippets/declarative/dynamicObjects-destroy.qml delete mode 100644 doc/src/snippets/declarative/dynamicObjects.qml 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/createComponent-simple.qml b/doc/src/snippets/declarative/createComponent-simple.qml new file mode 100644 index 0000000..9669580 --- /dev/null +++ b/doc/src/snippets/declarative/createComponent-simple.qml @@ -0,0 +1,57 @@ +/**************************************************************************** +** +** 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: 300; height: 300 + + function loadButton() { + var component = Qt.createComponent("Button.qml"); + if (component.status == Component.Ready) { + var button = component.createObject(container); + button.color = "red"; + } + } + + 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] diff --git a/doc/src/snippets/declarative/dynamicObjects.qml b/doc/src/snippets/declarative/dynamicObjects.qml deleted file mode 100644 index 3698499..0000000 --- a/doc/src/snippets/declarative/dynamicObjects.qml +++ /dev/null @@ -1,69 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -import Qt 4.7 - -//![0] -Rectangle { - id: rootItem - width: 300 - height: 300 - - Component { - id: rectComponent - - Rectangle { - id: rect - width: 40; height: 40; - color: "red" - - NumberAnimation on opacity { from: 1; to: 0; duration: 1000 } - - Component.onCompleted: rect.destroy(1000); - } - } - - function createRectangle() { - var object = rectComponent.createObject(rootItem); - } - - Component.onCompleted: createRectangle() -} -//![0] diff --git a/src/declarative/qml/qdeclarativecomponent.cpp b/src/declarative/qml/qdeclarativecomponent.cpp index 7bc6184..e8e237f 100644 --- a/src/declarative/qml/qdeclarativecomponent.cpp +++ b/src/declarative/qml/qdeclarativecomponent.cpp @@ -609,6 +609,9 @@ QDeclarativeComponent::QDeclarativeComponent(QDeclarativeComponentPrivate &dd, Q the \a parent value. Note that if the returned object is to be displayed, you must provide a valid \a parent value or set the returned object's \l{Item::parent}{parent} property, or else the object will not be visible. + + Dynamically created instances can be deleted with the \c destroy() method. + See \l {Dynamic Object Management} for more information. */ /*! diff --git a/src/declarative/qml/qdeclarativeengine.cpp b/src/declarative/qml/qdeclarativeengine.cpp index 346a2f4..8eb0939 100644 --- a/src/declarative/qml/qdeclarativeengine.cpp +++ b/src/declarative/qml/qdeclarativeengine.cpp @@ -1104,29 +1104,20 @@ QString QDeclarativeEnginePrivate::urlToLocalFileOrQrc(const QUrl& url) \qmlmethod object Qt::createComponent(url) Returns a \l Component object created using the QML file at the specified \a url, -or \c null if there was an error in creating the component. +or \c null if an empty string was given. + +The returned component's \l Component::status property indicates whether the +component was successfully created. If the status is \c Component.Error, +see \l Component::errorString() for an error description. Call \l {Component::createObject()}{Component.createObject()} on the returned component to create an object instance of the component. -Here is an example. Notice it checks whether the component \l{Component::status}{status} is -\c Component.Ready before calling \l {Component::createObject()}{createObject()} -in case the QML file is loaded over a network and thus is not ready immediately. - -\snippet doc/src/snippets/declarative/componentCreation.js vars -\codeline -\snippet doc/src/snippets/declarative/componentCreation.js func -\snippet doc/src/snippets/declarative/componentCreation.js remote -\snippet doc/src/snippets/declarative/componentCreation.js func-end -\codeline -\snippet doc/src/snippets/declarative/componentCreation.js finishCreation +For example: -If you are certain the QML file to be loaded is a local file, you could omit the \c finishCreation() -function and call \l {Component::createObject()}{createObject()} immediately: +\snippet doc/src/snippets/declarative/createComponent-simple.qml 0 -\snippet doc/src/snippets/declarative/componentCreation.js func -\snippet doc/src/snippets/declarative/componentCreation.js local -\snippet doc/src/snippets/declarative/componentCreation.js func-end +See \l {Dynamic Object Management} for more information on using this function. To create a QML object from an arbitrary string of QML (instead of a file), use \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()}. @@ -1177,6 +1168,8 @@ Each object in this array has the members \c lineNumber, \c columnNumber, \c fil Note that this function returns immediately, and therefore may not work if the \a qml string loads new components (that is, external QML files that have not yet been loaded). If this is the case, consider using \l{QML:Qt::createComponent()}{Qt.createComponent()} instead. + +See \l {Dynamic Object Management} for more information on using this function. */ QScriptValue QDeclarativeEnginePrivate::createQmlObject(QScriptContext *ctxt, QScriptEngine *engine) -- cgit v0.12