Largely rewrite the Using QML in C++ Applications documentation. It

now has an overview of different approaches to QML/C++ integration
and demonstrates how to pass data between QML and C++ through
properties/functions/signals. The part in the old docs that focused
on QDeclarativeContext has been merged into the QDeclarativeContext
class docs (although most of the info was largely covered in there
already) and the part that covered Network Components has been
moved to the QDeclarativeComponent class docs. The custom enum
types example previously in extending-tutorial.qdoc has been
moved to these new docs.

Task-number: QTBUG-14923

2 files changed, 51 insertions, 7 deletions

diff --git a/src/declarative/qml/qdeclarativecomponent.cpp b/src/declarative/qml/qdeclarativecomponent.cpp
index 0a2a6db..2686ce3 100644
--- a/src/declarative/qml/qdeclarativecomponent.cpp
+++ b/src/declarative/qml/qdeclarativecomponent.cpp
@@ -98,6 +98,43 @@ class QByteArray;
     int width = item->width();  // width = 200
     \endcode
 
+
+    \section2 Network Components
+
+    If the URL passed to QDeclarativeComponent is a network resource, or if the QML document references a
+    network resource, the QDeclarativeComponent has to fetch the network data before it is able to create
+    objects.  In this case, the QDeclarativeComponent will have a \l {QDeclarativeComponent::Loading}{Loading}
+    \l {QDeclarativeComponent::status()}{status}.  An application will have to wait until the component
+    is \l {QDeclarativeComponent::Ready}{Ready} before calling \l {QDeclarativeComponent::create()}.
+
+    The following example shows how to load a QML file from a network resource.  After creating
+    the QDeclarativeComponent, it tests whether the component is loading.  If it is, it connects to the
+    QDeclarativeComponent::statusChanged() signal and otherwise calls the \c {continueLoading()} method
+    directly. Note that QDeclarativeComponent::isLoading() may be false for a network component if the
+    component has been cached and is ready immediately.
+
+    \code
+    MyApplication::MyApplication()
+    {
+        // ...
+        component = new QDeclarativeComponent(engine, QUrl("http://www.example.com/main.qml"));
+        if (component->isLoading())
+            QObject::connect(component, SIGNAL(statusChanged(QDeclarativeComponent::Status)),
+                             this, SLOT(continueLoading()));
+        else
+            continueLoading();
+    }
+
+    void MyApplication::continueLoading()
+    {
+        if (component->isError()) {
+            qWarning() << component->errors();
+        } else {
+            QObject *myObject = component->create();
+        }
+    }
+    \endcode
+
     \sa {Using QML in C++ Applications}, {Integrating QML with existing Qt UI code}
 */
 
diff --git a/src/declarative/qml/qdeclarativecontext.cpp b/src/declarative/qml/qdeclarativecontext.cpp
index 59d5cfa..1e58a71 100644
--- a/src/declarative/qml/qdeclarativecontext.cpp
+++ b/src/declarative/qml/qdeclarativecontext.cpp
@@ -86,9 +86,14 @@ QDeclarativeContextPrivate::QDeclarativeContextPrivate()
 
     QDeclarativeComponent component(&engine);
     component.setData("import QtQuick 1.0\nListView { model: myModel }", QUrl());
-    component.create(context);
+    QObject *window = component.create(context);
     \endcode
 
+    Note it is the responsibility of the creator to delete any QDeclarativeContext it
+    constructs. If the \c context object in the example is no longer needed when the
+    \c window component instance is destroyed, the \c context must be destroyed explicitly.
+    The simplest way to ensure this is to set \c window as the parent of \c context.
+
     To simplify binding and maintaining larger data sets, a context object can be set
     on a QDeclarativeContext.  All the properties of the context object are available
     by name in the context, as though they were all individually added through calls
@@ -119,11 +124,13 @@ QDeclarativeContextPrivate::QDeclarativeContextPrivate()
     All properties added explicitly by QDeclarativeContext::setContextProperty() take 
     precedence over the context object's properties.
 
-    Contexts form a hierarchy.  The root of this hierarchy is the QDeclarativeEngine's
-    \l {QDeclarativeEngine::rootContext()}{root context}.  A component instance can 
-    access the data in its own context, as well as all its ancestor contexts.  Data
-    can be made available to all instances by modifying the 
-    \l {QDeclarativeEngine::rootContext()}{root context}.
+    \section2 The Context Hierarchy
+
+    Contexts form a hierarchy. The root of this hierarchy is the QML engine's
+    \l {QDeclarativeEngine::rootContext()}{root context}. Child contexts inherit
+    the context properties of their parents; if a child context sets a context property
+    that already exists in its parent, the new context property overrides that of the
+    parent.
 
     The following example defines two contexts - \c context1 and \c context2.  The
     second context overrides the "b" context property inherited from the first with a
@@ -144,7 +151,7 @@ QDeclarativeContextPrivate::QDeclarativeContextPrivate()
     context, their bindings are.  If a context is destroyed, the property bindings of 
     outstanding QML objects will stop evaluating.
 
-    \note Setting the context object or adding new context properties after an object
+    \warning Setting the context object or adding new context properties after an object
     has been created in that context is an expensive operation (essentially forcing all bindings
     to reevaluate). Thus whenever possible you should complete "setup" of the context
     before using it to create any objects.