Fix references to createComponent() and createQmlObject() to

Qt.createComponent() and Qt.createQmlObject(). Also move code into
snippets/ for verification.

7 files changed, 151 insertions, 109 deletions

diff --git a/doc/src/declarative/advtutorial.qdoc b/doc/src/declarative/advtutorial.qdoc
index 2d05850..42ce246 100644
--- a/doc/src/declarative/advtutorial.qdoc
+++ b/doc/src/declarative/advtutorial.qdoc
@@ -174,7 +174,7 @@ The \c createBlock() function creates a block from the \c Block.qml file
 and moves the new block to its position on the game canvas. This involves several steps:
 
 \list
-\o \l {createComponent(url file)}{createComponent()} is called to generate an element from \c Block.qml.
+\o \l {Qt.createComponent(url file)}{Qt.createComponent()} is called to generate an element from \c Block.qml.
    If the component is ready, we can call \c createObject() to create an instance of the \c Block item.
 \o If \c createObject() returned null (i.e. if there was an error while
    loading the object), print the error information.
diff --git a/doc/src/declarative/dynamicobjects.qdoc b/doc/src/declarative/dynamicobjects.qdoc
index 4cb5198..a2b65a8 100644
--- a/doc/src/declarative/dynamicobjects.qdoc
+++ b/doc/src/declarative/dynamicobjects.qdoc
@@ -62,65 +62,49 @@ item which you want to manage dynamic instances of, and creating an item from
 a string of QML is intended for when the QML itself is generated at runtime.
 
 If you have a component specified in a QML file, you can dynamically load it with
-the \l {createComponent(url file)}{createComponent()} function on the \l{QML Global Object}. 
+the \l {Qt.createComponent(url file)}{Qt.createComponent()} function on the \l{QML Global Object}. 
 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 \c createObject() method to create an instance of
-the component. Example QML script is below. Remember that QML files that might be loaded
-    over the network cannot be expected to be ready immediately.
-    \code
-        var component;
-        var sprite;
-        function finishCreation() {
-            if(component.isReady()) {
-                sprite = component.createObject();
-                if(sprite == 0) {
-                    // Error Handling
-                } else {
-                    sprite.parent = page;
-                    sprite.x = 200;
-                    //...
-                }
-            } else if(component.isError()) {
-                // Error Handling
-            }
-        }
+the component. 
 
-        component = createComponent("Sprite.qml");
-        if(component.isReady()) {
-            finishCreation();
-        } else {
-            component.statusChanged.connect(finishCreation);
-        }
-    \endcode
-
-    If you are certain the files will be local, you could simplify to
-
-    \code
-        component = createComponent("Sprite.qml");
-        sprite = component.createObject();
-        if(sprite == 0) {
-            // Error Handling
-            console.log(component.errorsString());
-        } else {
-            sprite.parent = page;
-            sprite.x = 200;
-            //...
-        }
-    \endcode
+Here is an example. Here is a simple QML component defined in \c Sprite.qml:
+
+\quotefile doc/src/snippets/declarative/Sprite.qml
+
+Our main application file, \c main.qml, imports a \c componentCreation.js JavaScript file
+that will create \c Sprite objects:
+
+\quotefile doc/src/snippets/declarative/createComponent.qml
+
+Here is \c componentCreation.js. Remember that QML files that might be loaded
+over the network cannot be expected to be ready immediately:
+
+\snippet doc/src/snippets/declarative/componentCreation.js 0
+\codeline
+\snippet doc/src/snippets/declarative/componentCreation.js 1
+\snippet doc/src/snippets/declarative/componentCreation.js 2
+\snippet doc/src/snippets/declarative/componentCreation.js 4
+\codeline
+\snippet doc/src/snippets/declarative/componentCreation.js 5
+
+If you are certain the files will be local, you could simplify to:
+
+\snippet doc/src/snippets/declarative/componentCreation.js 3
+
+Notice that once a \c Sprite object is created, its parent is set to \c appWindow (defined
+in \c main.qml). After creating an item, you must set its parent to an item within the scene.
+Otherwise your dynamically created item will not appear in the scene.
+
+When using files with relative paths, the path should
+be relative to the file where \l {Qt.createComponent(url file)}{Qt.createComponent()} is executed.
 
-After creating the item, remember to set its parent to an item within the scene.
-Otherwise your dynamically created item will not appear in the scene. When using files with relative paths, the path should
-be relative to the file where \c createComponent() is executed.
+If the QML component does not exist until runtime, you can create a QML item from
+a string of QML using the \l{Qt.createQmlObject(string qml, object parent, string filepath)}{Qt.createQmlObject()} function, as in the following example:
 
-If the QML does not exist until runtime, you can create a QML item from
-a string of QML using the \l{createQmlObject(string qml, object parent, string filepath)}{createQmlObject()} function, as in the following example:
+\snippet doc/src/snippets/declarative/createQmlObject.qml 0
 
-    \code
-    newObject = createQmlObject('import Qt 4.7; Rectangle { color: "red"; width: 20; height: 20 }',
-        targetItem, "dynamicSnippet1");
-    \endcode
 The first argument is the string of QML to create. Just like in a new file, you will need to
 import any types you wish to use. For importing files with relative paths, the path should
 be relative to the file where the item in the second argument is defined. Remember to set the parent after
@@ -135,9 +119,9 @@ will not have an id in QML.
 
 A restriction which you need to manage with dynamically created items,
 is that the creation context must outlive the
-created item. The creation context is the QDeclarativeContext in which \c createComponent()
+created item. The creation context is the QDeclarativeContext in which \c Qt.createComponent()
 was called, or the context in which the Component element, or the item used as the
-second argument to \c createQmlObject(), was specified. If the creation
+second argument to \c Qt.createQmlObject(), was specified. If the creation
 context is destroyed before the dynamic item is, then bindings in the dynamic item will
 fail to work.
 
diff --git a/doc/src/declarative/globalobject.qdoc b/doc/src/declarative/globalobject.qdoc
index 57eaae7..6e6d253 100644
--- a/doc/src/declarative/globalobject.qdoc
+++ b/doc/src/declarative/globalobject.qdoc
@@ -211,86 +211,57 @@ The following functions on the global object allow you to dynamically create QML
 items from files or strings. See \l{Dynamic Object Management} for an overview
 of their use.
 
-\section2 createComponent(url file)
+\section2 Qt.createComponent(url file)
     This function takes the URL of a QML file as its only argument. It returns
     a component object which can be used to create and load that QML file.
 
-    Example QML script is below. Remember that QML files that might be loaded
+    Here is an example. Remember that QML files that might be loaded
     over the network cannot be expected to be ready immediately.
-    \code
-        var component;
-        var sprite;
-        function finishCreation(){
-            if(component.isReady()){
-                sprite = component.createObject();
-                if(sprite == null){
-                    // Error Handling
-                }else{
-                    sprite.parent = page;
-                    sprite.x = 200;
-                    //...
-                }
-            }else if(component.isError()){
-                // Error Handling
-            }
-        }
-
-        component = createComponent("Sprite.qml");
-        if(component.isReady()){
-            finishCreation();
-        }else{
-            component.statusChanged.connect(finishCreation);
-        }
-    \endcode
-
-    If you are certain the files will be local, you could simplify to
-
-    \code
-        component = createComponent("Sprite.qml");
-        sprite = component.createObject();
-        if(sprite == null){
-            // Error Handling
-            console.log(component.errorsString());
-        }else{
-            sprite.parent = page;
-            sprite.x = 200;
-            //...
-        }
-    \endcode
+
+    \snippet doc/src/snippets/declarative/componentCreation.js 0
+    \codeline
+    \snippet doc/src/snippets/declarative/componentCreation.js 1
+    \snippet doc/src/snippets/declarative/componentCreation.js 2
+    \snippet doc/src/snippets/declarative/componentCreation.js 4
+    \codeline
+    \snippet doc/src/snippets/declarative/componentCreation.js 5
+
+    If you are certain the files will be local, you could simplify to:
+
+    \snippet doc/src/snippets/declarative/componentCreation.js 3
 
     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.
-    Component.createObject() returns the created object or null if there is an error.
-    If there is an error, Component.errorsString() describes what the error was.
+    \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.
 
     If you want to just create an arbitrary string of QML, instead of
-    loading a QML file, consider the createQmlObject() function.
+    loading a QML file, consider the \l{Qt.createQmlObject(string qml, object parent, string filepath)}{Qt.createQmlObject()} function.
 
-\section2 createQmlObject(string qml, object parent, string filepath)
+\section2 Qt.createQmlObject(string qml, object parent, string filepath)
     Creates a new object from the specified string of QML. It requires a
     second argument, which is the id of an existing QML object to use as
     the new object's parent. If a third argument is provided, this is used
     for error reporting as the filepath that the QML came from.
 
-    Example (where targetItem is the id of an existing QML item):
-    \code
-    newObject = createQmlObject('import Qt 4.7; Rectangle {color: "red"; width: 20; height: 20}',
-        targetItem, "dynamicSnippet1");
-    \endcode
+    Example (where \c targetItem is the id of an existing QML item):
+
+    \snippet doc/src/snippets/declarative/createQmlObject.qml 0
 
     This function is intended for use inside QML only. It is intended to behave
     similarly to eval, but for creating QML elements.
 
-    Returns the created object, or null if there is an error. In the case of an
+    Returns the created object, \c or null if there is an error. In the case of an
     error, a QtScript Error object is thrown. This object has the additional property,
     qmlErrors, which is an array of all the errors encountered when trying to execute the
-    QML. Each object in the array has the members: lineNumber, columnNumber, fileName and message.
+    QML. Each object in the array has the members \c lineNumber, \c columnNumber, \c fileName and \c message.
 
     Note that this function returns immediately, and therefore may not work if
     the QML loads new components. If you are trying to load a new component,
-    for example from a QML file, consider the createComponent() function
+    for example from a QML file, consider the \l{Qt.createComponent(url file)}{Qt.createComponent()} function
     instead. 'New components' refers to external QML files that have not yet
-    been loaded, and so it is safe to use createQmlObject to load built-in
+    been loaded, and so it is safe to use \c Qt.createQmlObject() to load built-in
     components.
 
 \section1 XMLHttpRequest
diff --git a/doc/src/snippets/declarative/Sprite.qml b/doc/src/snippets/declarative/Sprite.qml
new file mode 100644
index 0000000..6670703
--- /dev/null
+++ b/doc/src/snippets/declarative/Sprite.qml
@@ -0,0 +1,3 @@
+import Qt 4.7
+
+Rectangle { width: 80; height: 50; color: "red" }
diff --git a/doc/src/snippets/declarative/componentCreation.js b/doc/src/snippets/declarative/componentCreation.js
new file mode 100644
index 0000000..be3e4d6
--- /dev/null
+++ b/doc/src/snippets/declarative/componentCreation.js
@@ -0,0 +1,57 @@
+//![0]
+var component;
+var sprite;
+
+function finishCreation() {
+    if (component.isReady) {
+        sprite = component.createObject();
+        if (sprite == null) {
+            // Error Handling
+        } else {
+            sprite.parent = appWindow;
+            sprite.x = 100;
+            sprite.y = 100;
+            // ...
+        }
+    } else if (component.isError()) {
+        // Error Handling
+        console.log("Error loading component:", component.errorsString());
+    }
+}
+//![0]
+
+//![1]
+function createSpriteObjects() {
+//![1]
+
+    //![2]
+    component = Qt.createComponent("Sprite.qml");
+    if (component.isReady)
+        finishCreation();
+    else
+        component.statusChanged.connect(finishCreation);
+    //![2]
+
+    //![3]
+    component = Qt.createComponent("Sprite.qml");
+    sprite = component.createObject();
+
+    if (sprite == null) {
+        // Error Handling
+        console.log("Error loading component:", component.errorsString());
+    } else {
+        sprite.parent = appWindow;
+        sprite.x = 100;
+        sprite.y = 100;
+        // ...
+    }
+    //![3]
+
+//![4]
+}
+//![4]
+
+//![5]
+createSpriteObjects();
+//![5]
+
diff --git a/doc/src/snippets/declarative/createComponent.qml b/doc/src/snippets/declarative/createComponent.qml
new file mode 100644
index 0000000..c4a1617
--- /dev/null
+++ b/doc/src/snippets/declarative/createComponent.qml
@@ -0,0 +1,9 @@
+import Qt 4.7
+import "componentCreation.js" as MyModule
+
+Rectangle {
+    id: appWindow
+    width: 300; height: 300
+
+    Component.onCompleted: MyModule.createSpriteObjects();
+}
diff --git a/doc/src/snippets/declarative/createQmlObject.qml b/doc/src/snippets/declarative/createQmlObject.qml
new file mode 100644
index 0000000..6b331c4
--- /dev/null
+++ b/doc/src/snippets/declarative/createQmlObject.qml
@@ -0,0 +1,18 @@
+import Qt 4.7
+
+Rectangle {
+    id: targetItem
+    property QtObject newObject
+
+    width: 100
+    height: 100
+    
+    function createIt() {
+//![0]
+newObject = Qt.createQmlObject('import Qt 4.7; Rectangle {color: "red"; width: 20; height: 20}',
+    targetItem, "dynamicSnippet1");
+//![0]
+    }
+
+    Component.onCompleted: createIt()
+}