1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the documentation of the Qt Toolkit.
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
16 ** Alternatively, this file may be used in accordance with the terms
17 ** and conditions contained in a signed written agreement between you
26 ****************************************************************************/
29 \page qdeclarativedynamicobjects.html
30 \inqmlmodule QtQuick 1
32 \contentspage {QML Features}
33 \previouspage {Integrating QML Code with Existing Qt UI Code}
34 \nextpage {Network Transparency}{Loading Resources in QML}
35 \title Dynamic Object Management in QML
37 QML provides a number of ways to dynamically create and manage QML objects.
38 The \l{Loader}, \l{Repeater}, \l{ListView}, \l{GridView} and \l{PathView} elements
39 all support dynamic object management. Objects can also be created and managed
40 from C++, and this is the preferred method for hybrid QML/C++ applications
41 (see \l{Using QML Bindings in C++ Applications}).
43 QML also supports the dynamic creation of objects from within JavaScript
44 code. This is useful if the existing QML elements do not fit the needs of your
45 application, and there are no C++ components involved.
47 See the \l {declarative/toys/dynamicscene}{Dynamic Scene example} for a demonstration
48 of the concepts discussed on this page.
51 \section1 Creating Objects Dynamically
53 There are two ways to create objects dynamically from JavaScript. You can either call
54 \l {QML:Qt::createComponent()}{Qt.createComponent()} to dynamically create
55 a \l Component object, or use \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()}
56 to create an item from a string of QML.
57 Creating a component is better if you have an existing component defined in a \c .qml
58 file, and you want to dynamically create instances of that component. Otherwise,
59 creating an item from a string of QML is useful when the item QML itself is generated
63 \section2 Creating a Component Dynamically
65 To dynamically load a component defined in a QML file, call the
66 \l {QML:Qt::createComponent()}{Qt.createComponent()} function on the \l{QML Global Object}.
67 This function takes the URL of the QML file as its only argument and creates
68 a \l Component object from this URL.
70 Once you have a \l Component, you can call its \l {Component::createObject()}{createObject()} method to create an instance of
71 the component. This function can take one or two arguments:
73 \o The first is the parent for the new item. Since graphical items will not appear on the scene without a parent, it is
74 recommended that you set the parent this way. However, if you wish to set the parent later you can safely pass \c null to
76 \o The second is optional and is a map of property-value items that define initial any property values for the item.
77 Property values specified by this argument are applied to the object before its creation is finalized, avoiding
78 binding errors that may occur if particular properties must be initialized to enable other property bindings.
79 when certain properties have been bound to before they have been set by the code. Additionally, there are small
80 performance benefits when compared to defining property values and bindings after the object is created.
83 Here is an example. First there is \c Sprite.qml, which defines a simple QML component:
85 \snippet doc/src/snippets/declarative/Sprite.qml 0
87 Our main application file, \c main.qml, imports a \c componentCreation.js JavaScript file
88 that will create \c Sprite objects:
90 \snippet doc/src/snippets/declarative/createComponent.qml 0
92 Here is \c componentCreation.js. Notice it checks whether the component \l{Component::status}{status} is
93 \c Component.Ready before calling \l {Component::createObject()}{createObject()}
94 in case the QML file is loaded over a network and thus is not ready immediately.
96 \snippet doc/src/snippets/declarative/componentCreation.js vars
98 \snippet doc/src/snippets/declarative/componentCreation.js func
99 \snippet doc/src/snippets/declarative/componentCreation.js remote
100 \snippet doc/src/snippets/declarative/componentCreation.js func-end
102 \snippet doc/src/snippets/declarative/componentCreation.js finishCreation
104 If you are certain the QML file to be loaded is a local file, you could omit the \c finishCreation()
105 function and call \l {Component::createObject()}{createObject()} immediately:
107 \snippet doc/src/snippets/declarative/componentCreation.js func
108 \snippet doc/src/snippets/declarative/componentCreation.js local
109 \snippet doc/src/snippets/declarative/componentCreation.js func-end
111 Notice in both instances, \l {Component::createObject()}{createObject()} is called with
112 \c appWindow passed as an argument so that the created object will become a child of the
113 \c appWindow item in \c main.qml. Otherwise, the new item will not appear in the scene.
115 When using files with relative paths, the path should
116 be relative to the file where \l {QML:Qt::createComponent()}{Qt.createComponent()} is executed.
118 To connect signals to (or receive signals from) dynamically created objects,
119 use the signal \c connect() method. See
120 \l{QML Signal and Handler Event System#Connecting Signals to Methods and Signals}
121 {Connecting Signals to Methods and Signals} for more information.
124 \section2 Creating an Object from a String of QML
126 If the QML is not defined until runtime, you can create a QML item from
127 a string of QML using the \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()} function, as in the following example:
129 \snippet doc/src/snippets/declarative/createQmlObject.qml 0
131 The first argument is the string of QML to create. Just like in a new file, you will need to
132 import any types you wish to use. The second argument is the parent item for the new item;
133 this should be an existing item in the scene. The third argument is the file path to associate
134 with the new item; this is used for error reporting.
136 If the string of QML imports files using relative paths, the path should be relative
137 to the file in which the parent item (the second argument to the method) is defined.
140 \section1 Maintaining Dynamically Created Objects
142 When managing dynamically created items, you must ensure the creation context
143 outlives the created item. Otherwise, if the creation context is destroyed first,
144 the bindings in the dynamic item will no longer work.
146 The actual creation context depends on how an item is created:
149 \o If \l {QML:Qt::createComponent()}{Qt.createComponent()} is used, the creation context
150 is the QDeclarativeContext in which this method is called
151 \o If \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()}
152 if called, the creation context is the context of the parent item passed to this method
153 \o If a \c {Component{}} item is defined and \l {Component::createObject()}{createObject()}
154 is called on that item, the creation context is the context in which the \c Component is defined
157 Also, note that while dynamically created objects may be used the same as other objects, they
158 do not have an id in QML.
161 \section1 Deleting Objects Dynamically
163 In many user interfaces, it is sufficient to set an item's opacity to 0 or
164 to move the item off the screen instead of deleting the item. If you have
165 lots of dynamically created items, however, you may receive a worthwhile
166 performance benefit if unused items are deleted.
168 Note that you should never manually delete items that were dynamically created
169 by QML elements (such as \l Loader and \l Repeater). Also, you should avoid deleting
170 items that you did not dynamically create yourself.
172 Items can be deleted using the \c destroy() method. This method has an optional
173 argument (which defaults to 0) that specifies the approximate delay in milliseconds
174 before the object is to be destroyed.
176 Here is an example. The \c application.qml creates five instances of the \c SelfDestroyingRect.qml
177 component. Each instance runs a NumberAnimation, and when the animation has finished, calls
178 \c destroy() on its root item to destroy itself:
182 \o \c application.qml
183 \o \c SelfDestroyingRect.qml
186 \o \snippet doc/src/snippets/declarative/dynamicObjects-destroy.qml 0
187 \o \snippet doc/src/snippets/declarative/SelfDestroyingRect.qml 0
191 Alternatively, the \c application.qml could have destroyed the created object
192 by calling \c object.destroy().
194 Note that it is safe to call destroy() on an object within that object. Objects are not destroyed the
195 instant destroy() is called, but are cleaned up sometime between the end of that script block and the next frame
196 (unless you specified a non-zero delay).
198 Note also that if a \c SelfDestroyingRect instance was created statically like this:
208 This would result in an error, since items can only be dynamically
209 destroyed if they were dynamically created.
211 Objects created with \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()}
212 can similarly be destroyed using \c destroy():
214 \snippet doc/src/snippets/declarative/createQmlObject.qml 0
215 \snippet doc/src/snippets/declarative/createQmlObject.qml destroy