Document qmlContext() and qmlEngine().

146b942d59cca446516652d42718197573d34e46 documented them (Qt 5), but
for some reason they aren't visible [1].
c74e4a74ba97d32df7406fb684527d415dd8a6ba (Qt 5.1) then moved them into
the QtQml namespace "to avoid symbol conflicts with QtDeclarative", and
then did the following trick so that they could be called without
qualifying the functions with the namespace:

using namespace QtQml;

For that reason, qdoc shouldn't see the namespace, so we #ifdef it out.

[1] project.org/doc/qt-5.0/qtqml/qqmlengine.html

Change-Id: Id815ae4de7f081c22755eef7c37a2bc6e812b440
Reviewed-by: Simon Hausmann <simon.hausmann@digia.com>
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>

1 files changed, 20 insertions, 0 deletions

diff --git a/src/qml/qml/qqmlcomponent.cpp b/src/qml/qml/qqmlcomponent.cpp
index 084441af01..6fe1377a7e 100644
--- a/src/qml/qml/qqmlcomponent.cpp
+++ b/src/qml/qml/qqmlcomponent.cpp
@@ -138,6 +138,26 @@ V8_DEFINE_EXTENSION(QQmlComponentExtension, componentExtension);
     int width = item->width();  // width = 200
     \endcode
 
+    To create instances of a component in code where a QQmlEngine instance is
+    not available, you can use \l qmlContext() or \l qmlEngine(). For example,
+    in the scenario below, child items are being created within a QQuickItem
+    subclass:
+
+    \code
+    void MyCppItem::init()
+    {
+        QQmlEngine *engine = qmlEngine(this);
+        // Or:
+        // QQmlEngine *engine = qmlContext(this)->engine();
+        QQmlComponent component(engine, QUrl::fromLocalFile("MyItem.qml"));
+        QQuickItem *childItem = qobject_cast<QQuickItem*>(component.create());
+        childItem->setParent(this);
+    }
+    \endcode
+
+    Note that these functions will return \c null when called inside the
+    constructor of a QObject subclass, as the instance will not yet have
+    a context nor engine.
 
     \section2 Network Components