src/qml/doc/src/javascript/dynamicobjectcreation.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** GNU Free Documentation License
  10 ** Alternatively, this file may be used under the terms of the GNU Free
  11 ** Documentation License version 1.3 as published by the Free Software
  12 ** Foundation and appearing in the file included in the packaging of
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29 \page qtqml-javascript-dynamicobjectcreation.html
  30 \title Dynamic QML Object Creation from JavaScript
  31 \brief instantiating and managing QML objects from JavaScript
  32
  33 QML supports the dynamic creation of objects from within JavaScript.  This is
  34 useful to delay instantiation of objects until necessary, thereby improving
  35 application startup time.  It also allows visual objects to be dynamically
  36 created and added to the scene in reaction to user input or other events.
  37
  38 See the \l {declarative/toys/dynamicscene}{Dynamic Scene example} for a
  39 demonstration of the concepts discussed on this page.
  40
  41
  42 \section1 Creating Objects Dynamically
  43
  44 There are two ways to create objects dynamically from JavaScript. You can
  45 either call \l {QML:Qt::createComponent()}{Qt.createComponent()} to
  46 dynamically create a \l Component object, or use \l{QML:Qt::createQmlObject()}
  47 {Qt.createQmlObject()} to create an object from a string of QML.  Creating a
  48 component is better if you have an existing component defined in a QML document
  49 and you want to dynamically create instances of that component.  Otherwise,
  50 creating an object from a string of QML is useful when the object QML itself is
  51 generated at runtime.
  52
  53
  54 \section2 Creating a Component Dynamically
  55
  56 To dynamically load a component defined in a QML file, call the
  57 \l {QML:Qt::createComponent()}{Qt.createComponent()} function in the
  58 \l {QmlGlobalQtObject}{Qt object}.
  59 This function takes the URL of the QML file as its only argument and creates
  60 a \l Component object from this URL.
  61
  62 Once you have a \l Component, you can call its \l {Component::createObject()}
  63 {createObject()} method to create an instance of the component. This function
  64 can take one or two arguments:
  65 \list
  66 \li The first is the parent for the new object.  The parent can be a graphical
  67     object (QtQuick item) or non-graphical object (QtQml QtObject or C++
  68     QObject).  Only graphical objects with graphical parent objects will be
  69     rendered to the QtQuick visual canvas.  If you wish to set the parent later
  70     you can safely pass \c null to this function.
  71 \li The second is optional and is a map of property-value pairs that define
  72     initial any property values for the object.  Property values specified by
  73     this argument are applied to the object before its creation is finalized,
  74     avoiding binding errors that may occur if particular properties must be
  75     initialized to enable other property bindings.  Additionally, there are
  76     small performance benefits when compared to defining property values and
  77     bindings after the object is created.
  78 \endlist
  79
  80 Here is an example. First there is \c Sprite.qml, which defines a simple QML component:
  81
  82 \snippet qml/Sprite.qml 0
  83
  84 Our main application file, \c main.qml, imports a \c componentCreation.js
  85 JavaScript file that will create \c Sprite objects:
  86
  87 \snippet qml/createComponent.qml 0
  88
  89 Here is \c componentCreation.js. Notice it checks whether the component
  90 \l{Component::status}{status} is \c Component.Ready before calling
  91 \l {Component::createObject()}{createObject()} in case the QML file is loaded
  92 over a network and thus is not ready immediately.
  93
  94 \snippet qml/componentCreation.js vars
  95 \codeline
  96 \snippet qml/componentCreation.js func
  97 \snippet qml/componentCreation.js remote
  98 \snippet qml/componentCreation.js func-end
  99 \codeline
 100 \snippet qml/componentCreation.js finishCreation
 101
 102 If you are certain the QML file to be loaded is a local file, you could omit
 103 the \c finishCreation() function and call \l {Component::createObject()}
 104 {createObject()} immediately:
 105
 106 \snippet qml/componentCreation.js func
 107 \snippet qml/componentCreation.js local
 108 \snippet qml/componentCreation.js func-end
 109
 110 Notice in both instances, \l {Component::createObject()}{createObject()} is
 111 called with \c appWindow passed as the parent argument, since the dynamically
 112 created object is a visual (QtQuick) object.  The created object will become a
 113 child of the \c appWindow object in \c main.qml, and appear in the scene.
 114
 115 When using files with relative paths, the path should
 116 be relative to the file where \l {QML:Qt::createComponent()}
 117 {Qt.createComponent()} is executed.
 118
 119 To connect signals to (or receive signals from) dynamically created objects,
 120 use the signal \c connect() method. See
 121 \l{Signal and Handler Event System#Connecting Signals to Methods and Signals}
 122 {Connecting Signals to Methods and Signals} for more information.
 123
 124 It is also possible to instantiate components without blocking via the
 125 \l {Component::incubateObject()}{incubateObject()} function.
 126
 127 \section2 Creating an Object from a String of QML
 128
 129 If the QML is not defined until runtime, you can create a QML object from
 130 a string of QML using the \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()}
 131 function, as in the following example:
 132
 133 \snippet qml/createQmlObject.qml 0
 134
 135 The first argument is the string of QML to create. Just like in a new file,
 136 you will need to import any types you wish to use. The second argument is the
 137 parent object for the new object, and the parent argument semantics which apply
 138 to components are similarly applicable for \c createQmlObject().
 139 The third argument is the file path to associate with the new object; this is
 140 used for error reporting.
 141
 142 If the string of QML imports files using relative paths, the path should be
 143 relative to the file in which the parent object (the second argument to the
 144 method) is defined.
 145
 146
 147 \section1 Maintaining Dynamically Created Objects
 148
 149 When managing dynamically created objects, you must ensure the creation context
 150 outlives the created object. Otherwise, if the creation context is destroyed
 151 first, the bindings in the dynamic object will no longer work.
 152
 153 The actual creation context depends on how an object is created:
 154
 155 \list
 156 \li If \l {QML:Qt::createComponent()}{Qt.createComponent()} is used, the
 157     creation context is the QQmlContext in which this method is called
 158 \li If \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()} is called, the
 159     creation context is the context of the parent object passed to this method
 160 \li If a \c {Component{}} object is defined and \l {Component::createObject()}
 161     {createObject()} or \l {Component::incubateObject()}{incubateObject()} is
 162     called on that object, the creation context is the context in which the
 163     \c Component is defined
 164 \endlist
 165
 166 Also, note that while dynamically created objects may be used the same as other
 167 objects, they do not have an id in QML.
 168
 169
 170 \section1 Deleting Objects Dynamically
 171
 172 In many user interfaces, it is sufficient to set a visual object's opacity to 0
 173 or to move the visual object off the screen instead of deleting it. If you have
 174 lots of dynamically created objects, however, you may receive a worthwhile
 175 performance benefit if unused objects are deleted.
 176
 177 Note that you should never manually delete objects that were dynamically
 178 created by convenience QML object factories (such as \l Loader and
 179 \l Repeater).  Also, you should avoid deleting objects that you did not
 180 dynamically create yourself.
 181
 182 Items can be deleted using the \c destroy() method. This method has an optional
 183 argument (which defaults to 0) that specifies the approximate delay in
 184 milliseconds before the object is to be destroyed.
 185
 186 Here is an example. The \c application.qml creates five instances of the
 187 \c SelfDestroyingRect.qml component. Each instance runs a NumberAnimation,
 188 and when the animation has finished, calls \c destroy() on its root object to
 189 destroy itself:
 190
 191 \table
 192 \row
 193 \li \c application.qml
 194 \li \c SelfDestroyingRect.qml
 195
 196 \row
 197 \li \snippet qml/dynamicObjects-destroy.qml 0
 198 \li \snippet qml/SelfDestroyingRect.qml 0
 199
 200 \endtable
 201
 202 Alternatively, the \c application.qml could have destroyed the created object
 203 by calling \c object.destroy().
 204
 205 Note that it is safe to call destroy() on an object within that object. Objects
 206 are not destroyed the instant destroy() is called, but are cleaned up sometime
 207 between the end of that script block and the next frame (unless you specified a
 208 non-zero delay).
 209
 210 Note also that if a \c SelfDestroyingRect instance was created statically like
 211 this:
 212
 213 \qml
 214 Item {
 215     SelfDestroyingRect {
 216         // ...
 217     }
 218 }
 219 \endqml
 220
 221 This would result in an error, since objects can only be dynamically
 222 destroyed if they were dynamically created.
 223
 224 Objects created with \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()}
 225 can similarly be destroyed using \c destroy():
 226
 227 \snippet qml/createQmlObject.qml 0
 228 \snippet qml/createQmlObject.qml destroy
 229
 230 */