Dynamic Object Management in QML

Creating a Component Dynamically

To dynamically load a component defined in a QML file, call the Qt.createComponent() function on the QML Global Object. This function takes the URL of the QML file as its only argument and creates a Component object from this URL.

Once you have a Component, you can call its createObject() method to create an instance of the component. This function can take one or two arguments:

• The first is the parent for the new item. Since graphical items will not appear on the scene without a parent, it is recommended that you set the parent this way. However, if you wish to set the parent later you can safely pass null to this function.
• The second is optional and is a map of property-value items that define initial any property values for the item. Property values specified by this argument are applied to the object before its creation is finalized, avoiding binding errors that may occur if particular properties must be initialized to enable other property bindings. when certain properties have been bound to before they have been set by the code. Additionally, there are small performance benefits when compared to defining property values and bindings after the object is created.

Here is an example. First there is Sprite.qml, which defines a simple QML component:

 import QtQuick 1.0

 Rectangle { width: 80; height: 50; color: "red" }

Our main application file, main.qml, imports a componentCreation.js JavaScript file that will create Sprite objects:

 import QtQuick 1.0
 import "componentCreation.js" as MyScript

 Rectangle {
     id: appWindow
     width: 300; height: 300

     Component.onCompleted: MyScript.createSpriteObjects();
 }

Here is componentCreation.js. Notice it checks whether the component status is Component.Ready before calling createObject() in case the QML file is loaded over a network and thus is not ready immediately.

 var component;
 var sprite;

 function createSpriteObjects() {
     component = Qt.createComponent("Sprite.qml");
     if (component.status == Component.Ready)
         finishCreation();
     else
         component.statusChanged.connect(finishCreation);
 }

 function finishCreation() {
     if (component.status == Component.Ready) {
         sprite = component.createObject(appWindow, {"x": 100, "y": 100});
         if (sprite == null) {
             // Error Handling
             console.log("Error creating object");
         }
     } else if (component.status == Component.Error) {
         // Error Handling
         console.log("Error loading component:", component.errorString());
     }
 }

If you are certain the QML file to be loaded is a local file, you could omit the finishCreation() function and call createObject() immediately:

 function createSpriteObjects() {
     component = Qt.createComponent("Sprite.qml");
     sprite = component.createObject(appWindow, {"x": 100, "y": 100});

     if (sprite == null) {
         // Error Handling
         console.log("Error creating object");
     }
 }

Notice in both instances, createObject() is called with appWindow passed as an argument so that the created object will become a child of the appWindow item in main.qml. Otherwise, the new item will not appear in the scene.

When using files with relative paths, the path should be relative to the file where Qt.createComponent() is executed.

To connect signals to (or receive signals from) dynamically created objects, use the signal connect() method. See Connecting Signals to Methods and Signals for more information.

 var newObject = Qt.createQmlObject('import QtQuick 1.0; Rectangle {color: "red"; width: 20; height: 20}',
     parentItem, "dynamicSnippet1");

 import QtQuick 1.0

 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;
         }
     }
 }

 import QtQuick 1.0

 Rectangle {
     id: rect
     width: 80; height: 80
     color: "red"

     NumberAnimation on opacity {
         to: 0
         duration: 1000

         onRunningChanged: {
             if (!running) {
                 console.log("Destroying...")
                 rect.destroy();
             }
         }
     }
 }

 Item {
     SelfDestroyingRect {
         // ...
     }
 }

 var newObject = Qt.createQmlObject('import QtQuick 1.0; Rectangle {color: "red"; width: 20; height: 20}',
     parentItem, "dynamicSnippet1");
 newObject.destroy(1000);