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>

diff --git a/src/qml/qml/qqml.h b/src/qml/qml/qqml.h
index 633953c..6479aed 100644 (file)
--- a/src/qml/qml/qqml.h
+++ b/src/qml/qml/qqml.h
@@ -419,7 +419,9 @@ class QQmlEngine;
 class QJSValue;
 class QJSEngine;
 
+#ifndef Q_QDOC
 namespace QtQml {
+#endif
     // declared in namespace to avoid symbol conflicts with QtDeclarative
     Q_QML_EXPORT void qmlExecuteDeferred(QObject *);
     Q_QML_EXPORT QQmlContext *qmlContext(const QObject *);
@@ -427,7 +429,9 @@ namespace QtQml {
     Q_QML_EXPORT QObject *qmlAttachedPropertiesObjectById(int, const QObject *, bool create = true);
     Q_QML_EXPORT QObject *qmlAttachedPropertiesObject(int *, const QObject *,
                                                       const QMetaObject *, bool create);
+#ifndef Q_QDOC
 }
+#endif
 
 #ifdef Q_CC_CLANG
 #pragma clang diagnostic push

diff --git a/src/qml/qml/qqmlcomponent.cpp b/src/qml/qml/qqmlcomponent.cpp
index 084441a..6fe1377 100644 (file)
--- 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
 

diff --git a/src/qml/qml/qqmlengine.cpp b/src/qml/qml/qqmlengine.cpp
index 6336835..6554ddc 100644 (file)
--- a/src/qml/qml/qqmlengine.cpp
+++ b/src/qml/qml/qqmlengine.cpp
@@ -1209,6 +1209,8 @@ void QQmlEngine::setOutputWarningsToStandardError(bool enabled)
 
   When the QQmlEngine instantiates a QObject, the context is
   set automatically.
+
+  \sa qmlContext(), qmlEngine()
   */
 QQmlContext *QQmlEngine::contextForObject(const QObject *object)
 {
@@ -2370,6 +2372,8 @@ bool QQml_isFileCaseCorrect(const QString &fileName, int lengthIn /* = -1 */)
 
     Returns the QQmlEngine associated with \a object, if any.  This is equivalent to
     QQmlEngine::contextForObject(object)->engine(), but more efficient.
+
+    \sa {QQmlEngine::contextForObject()}{contextForObject()}, qmlContext()
 */
 
 /*!
@@ -2378,6 +2382,8 @@ bool QQml_isFileCaseCorrect(const QString &fileName, int lengthIn /* = -1 */)
 
     Returns the QQmlContext associated with \a object, if any.  This is equivalent to
     QQmlEngine::contextForObject(object).
+
+    \sa {QQmlEngine::contextForObject()}{contextForObject()}, qmlEngine()
 */
 
 QT_END_NAMESPACE