Make component.createObject require a parent argument

For graphical objects (the common case) a common mistake is to not
parent a dynamically created item. Since you almost always want to add a
parent, and it's hard for a beginner to diagnose this problem, a parent
is now a required argument and dealt with by the createObject function.

Task-number: QTBUG-10110

4 files changed, 10 insertions, 10 deletions

diff --git a/doc/src/declarative/dynamicobjects.qdoc b/doc/src/declarative/dynamicobjects.qdoc
index dc0277d..2688ee5 100644
--- a/doc/src/declarative/dynamicobjects.qdoc
+++ b/doc/src/declarative/dynamicobjects.qdoc
@@ -69,7 +69,9 @@ This function takes the URL of the QML file as its only argument and returns
 a component object which can be used to create and load that QML file.
 
 Once you have a component you can use its \l {Component::createObject()}{createObject()} method to create an instance of
-the component. 
+the component. This function takes exactly one argument, which 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.
 
 Here is an example. Here is a \c Sprite.qml, which defines a simple QML component:
 
diff --git a/doc/src/declarative/globalobject.qdoc b/doc/src/declarative/globalobject.qdoc
index 7c27ae4..bc9830a 100644
--- a/doc/src/declarative/globalobject.qdoc
+++ b/doc/src/declarative/globalobject.qdoc
@@ -258,7 +258,10 @@ The methods and properties of the Component element are defined in its own
 page, but when using it dynamically only two methods are usually used.
 \c Component.createObject() returns the created object or \c null if there is an error.
 If there is an error, \l {Component::errorsString()}{Component.errorsString()} describes
-the error that occurred.
+the error that occurred. Note that createObject() takes exactly one argument, which is set
+to the parent of the created object. Graphical objects without a parent will not appear
+on the scene, but if you do not wish to parent the item at this point you can safely pass
+in null.
 
 If you want to just create an arbitrary string of QML, instead of
 loading a QML file, consider the \l{Qt.createQmlObject(string qml, object parent, string filepath)}{Qt.createQmlObject()} function.
diff --git a/doc/src/snippets/declarative/componentCreation.js b/doc/src/snippets/declarative/componentCreation.js
index be928f0..f6fb379 100644
--- a/doc/src/snippets/declarative/componentCreation.js
+++ b/doc/src/snippets/declarative/componentCreation.js
@@ -4,11 +4,10 @@ var sprite;
 
 function finishCreation() {
     if (component.status == Component.Ready) {
-        sprite = component.createObject();
+        sprite = component.createObject(appWindow);
         if (sprite == null) {
             // Error Handling
         } else {
-            sprite.parent = appWindow;
             sprite.x = 100;
             sprite.y = 100;
             // ...
@@ -32,13 +31,12 @@ else
 
 //![2]
 component = Qt.createComponent("Sprite.qml");
-sprite = component.createObject();
+sprite = component.createObject(appWindow);
 
 if (sprite == null) {
     // Error Handling
     console.log("Error loading component:", component.errorsString());
 } else {
-    sprite.parent = appWindow;
     sprite.x = 100;
     sprite.y = 100;
     // ...
@@ -47,5 +45,3 @@ if (sprite == null) {
 
 }
 
-createSpriteObjects();
-
diff --git a/doc/src/snippets/declarative/dynamicObjects.qml b/doc/src/snippets/declarative/dynamicObjects.qml
index dd55d78..6a8c927 100644
--- a/doc/src/snippets/declarative/dynamicObjects.qml
+++ b/doc/src/snippets/declarative/dynamicObjects.qml
@@ -21,8 +21,7 @@ Rectangle {
     }
 
     function createRectangle() {
-        var object = rectComponent.createObject();
-        object.parent = rootItem;
+        var object = rectComponent.createObject(rootItem);
     } 
 
     Component.onCompleted: createRectangle()