diff options
Diffstat (limited to 'src/declarative/qml/qdeclarativeengine.cpp')
| -rw-r--r-- | src/declarative/qml/qdeclarativeengine.cpp | 248 |
1 files changed, 132 insertions, 116 deletions
diff --git a/src/declarative/qml/qdeclarativeengine.cpp b/src/declarative/qml/qdeclarativeengine.cpp index ddbe433..2f0ec24 100644 --- a/src/declarative/qml/qdeclarativeengine.cpp +++ b/src/declarative/qml/qdeclarativeengine.cpp @@ -114,16 +114,16 @@ QT_BEGIN_NAMESPACE DEFINE_BOOL_CONFIG_OPTION(qmlImportTrace, QML_IMPORT_TRACE) /*! - \qmlclass QtObject QObject + \qmlclass QtObject QObject \since 4.7 - \brief The QtObject element is the most basic element in QML + \brief The QtObject element is the most basic element in QML - The QtObject element is a non-visual element which contains only - the objectName property. It is useful for when you need an extremely - lightweight element to place your own custom properties in. + The QtObject element is a non-visual element which contains only the + objectName property. It is useful for when you need an extremely + lightweight element to place your own custom properties in. - It can also be useful for C++ integration, as it is just a plain QObject. See - the QObject documentation for further details. + It can also be useful for C++ integration, as it is just a plain + QObject. See the QObject documentation for further details. */ /*! \qmlproperty string QtObject::objectName @@ -371,37 +371,38 @@ QDeclarativeWorkerScriptEngine *QDeclarativeEnginePrivate::getWorkerScriptEngine } /*! - \class QDeclarativeEngine + \class QDeclarativeEngine \since 4.7 - \brief The QDeclarativeEngine class provides an environment for instantiating QML components. - \mainclass - - Each QML component is instantiated in a QDeclarativeContext. QDeclarativeContext's are - essential for passing data to QML components. In QML, contexts are arranged - hierarchically and this hierarchy is managed by the QDeclarativeEngine. - - Prior to creating any QML components, an application must have created a - QDeclarativeEngine to gain access to a QML context. The following example shows how - to create a simple Text item. - - \code - QDeclarativeEngine engine; - QDeclarativeComponent component(&engine); - component.setData("import Qt 4.6\nText { text: \"Hello world!\" }", QUrl()); - QDeclarativeItem *item = qobject_cast<QDeclarativeItem *>(component.create()); - - //add item to view, etc - ... - \endcode - - In this case, the Text item will be created in the engine's - \l {QDeclarativeEngine::rootContext()}{root context}. - - \sa QDeclarativeComponent QDeclarativeContext + \brief The QDeclarativeEngine class provides an environment for instantiating QML components. + \mainclass + + Each QML component is instantiated in a QDeclarativeContext. + QDeclarativeContext's are essential for passing data to QML + components. In QML, contexts are arranged hierarchically and this + hierarchy is managed by the QDeclarativeEngine. + + Prior to creating any QML components, an application must have + created a QDeclarativeEngine to gain access to a QML context. The + following example shows how to create a simple Text item. + + \code + QDeclarativeEngine engine; + QDeclarativeComponent component(&engine); + component.setData("import Qt 4.6\nText { text: \"Hello world!\" }", QUrl()); + QDeclarativeItem *item = qobject_cast<QDeclarativeItem *>(component.create()); + + //add item to view, etc + ... + \endcode + + In this case, the Text item will be created in the engine's + \l {QDeclarativeEngine::rootContext()}{root context}. + + \sa QDeclarativeComponent QDeclarativeContext */ /*! - Create a new QDeclarativeEngine with the given \a parent. + Create a new QDeclarativeEngine with the given \a parent. */ QDeclarativeEngine::QDeclarativeEngine(QObject *parent) : QObject(*new QDeclarativeEnginePrivate(this), parent) @@ -411,10 +412,11 @@ QDeclarativeEngine::QDeclarativeEngine(QObject *parent) } /*! - Destroys the QDeclarativeEngine. + Destroys the QDeclarativeEngine. - Any QDeclarativeContext's created on this engine will be invalidated, but not - destroyed (unless they are parented to the QDeclarativeEngine object). + Any QDeclarativeContext's created on this engine will be + invalidated, but not destroyed (unless they are parented to the + QDeclarativeEngine object). */ QDeclarativeEngine::~QDeclarativeEngine() { @@ -430,8 +432,9 @@ QDeclarativeEngine::~QDeclarativeEngine() /*! Clears the engine's internal component cache. - Normally the QDeclarativeEngine caches components loaded from qml files. This method - clears this cache and forces the component to be reloaded. + Normally the QDeclarativeEngine caches components loaded from qml + files. This method clears this cache and forces the component to be + reloaded. */ void QDeclarativeEngine::clearComponentCache() { @@ -440,14 +443,15 @@ void QDeclarativeEngine::clearComponentCache() } /*! - Returns the engine's root context. + Returns the engine's root context. - The root context is automatically created by the QDeclarativeEngine. Data that - should be available to all QML component instances instantiated by the - engine should be put in the root context. + The root context is automatically created by the QDeclarativeEngine. + Data that should be available to all QML component instances + instantiated by the engine should be put in the root context. - Additional data that should only be available to a subset of component - instances should be added to sub-contexts parented to the root context. + Additional data that should only be available to a subset of + component instances should be added to sub-contexts parented to the + root context. */ QDeclarativeContext *QDeclarativeEngine::rootContext() { @@ -456,14 +460,14 @@ QDeclarativeContext *QDeclarativeEngine::rootContext() } /*! - Sets the \a factory to use for creating QNetworkAccessManager(s). + Sets the \a factory to use for creating QNetworkAccessManager(s). - QNetworkAccessManager is used for all network access by QML. - By implementing a factory it is possible to create custom - QNetworkAccessManager with specialized caching, proxy and - cookie support. + QNetworkAccessManager is used for all network access by QML. By + implementing a factory it is possible to create custom + QNetworkAccessManager with specialized caching, proxy and cookie + support. - The factory must be set before exceuting the engine. + The factory must be set before exceuting the engine. */ void QDeclarativeEngine::setNetworkAccessManagerFactory(QDeclarativeNetworkAccessManagerFactory *factory) { @@ -473,9 +477,9 @@ void QDeclarativeEngine::setNetworkAccessManagerFactory(QDeclarativeNetworkAcces } /*! - Returns the current QDeclarativeNetworkAccessManagerFactory. + Returns the current QDeclarativeNetworkAccessManagerFactory. - \sa setNetworkAccessManagerFactory() + \sa setNetworkAccessManagerFactory() */ QDeclarativeNetworkAccessManagerFactory *QDeclarativeEngine::networkAccessManagerFactory() const { @@ -505,15 +509,16 @@ QNetworkAccessManager *QDeclarativeEnginePrivate::getNetworkAccessManager() cons } /*! - Returns a common QNetworkAccessManager which can be used by any QML element - instantiated by this engine. + Returns a common QNetworkAccessManager which can be used by any QML + element instantiated by this engine. - If a QDeclarativeNetworkAccessManagerFactory has been set and a QNetworkAccessManager - has not yet been created, the QDeclarativeNetworkAccessManagerFactory will be used - to create the QNetworkAccessManager; otherwise the returned QNetworkAccessManager - will have no proxy or cache set. + If a QDeclarativeNetworkAccessManagerFactory has been set and a + QNetworkAccessManager has not yet been created, the + QDeclarativeNetworkAccessManagerFactory will be used to create the + QNetworkAccessManager; otherwise the returned QNetworkAccessManager + will have no proxy or cache set. - \sa setNetworkAccessManagerFactory() + \sa setNetworkAccessManagerFactory() */ QNetworkAccessManager *QDeclarativeEngine::networkAccessManager() const { @@ -522,26 +527,27 @@ QNetworkAccessManager *QDeclarativeEngine::networkAccessManager() const } /*! - Sets the \a provider to use for images requested via the \e image: url - scheme, with host \a providerId. - QDeclarativeImageProvider allows images to be provided to QML asynchronously. - The image request will be run in a low priority thread. This allows - potentially costly image loading to be done in the background, without - affecting the performance of the UI. + Sets the \a provider to use for images requested via the \e + image: url scheme, with host \a providerId. + + QDeclarativeImageProvider allows images to be provided to QML + asynchronously. The image request will be run in a low priority + thread. This allows potentially costly image loading to be done in + the background, without affecting the performance of the UI. - Note that images loaded from a QDeclarativeImageProvider are cached by - QPixmapCache, similar to any image loaded by QML. + Note that images loaded from a QDeclarativeImageProvider are cached + by QPixmapCache, similar to any image loaded by QML. - The QDeclarativeEngine assumes ownership of the provider. + The QDeclarativeEngine assumes ownership of the provider. - This example creates a provider with id \e colors: + This example creates a provider with id \e colors: - \snippet examples/declarative/imageprovider/imageprovider.cpp 0 + \snippet examples/declarative/imageprovider/imageprovider.cpp 0 - \snippet examples/declarative/imageprovider/imageprovider.qml 0 + \snippet examples/declarative/imageprovider/imageprovider-example.qml 0 - \sa removeImageProvider() + \sa removeImageProvider() */ void QDeclarativeEngine::addImageProvider(const QString &providerId, QDeclarativeImageProvider *provider) { @@ -551,7 +557,7 @@ void QDeclarativeEngine::addImageProvider(const QString &providerId, QDeclarativ } /*! - Returns the QDeclarativeImageProvider set for \a providerId. + Returns the QDeclarativeImageProvider set for \a providerId. */ QDeclarativeImageProvider *QDeclarativeEngine::imageProvider(const QString &providerId) const { @@ -561,11 +567,11 @@ QDeclarativeImageProvider *QDeclarativeEngine::imageProvider(const QString &prov } /*! - Removes the QDeclarativeImageProvider for \a providerId. + Removes the QDeclarativeImageProvider for \a providerId. - Returns the provider if it was found; otherwise returns 0. + Returns the provider if it was found; otherwise returns 0. - \sa addImageProvider() + \sa addImageProvider() */ void QDeclarativeEngine::removeImageProvider(const QString &providerId) { @@ -585,13 +591,14 @@ QImage QDeclarativeEnginePrivate::getImageFromProvider(const QUrl &url) } /*! - Return the base URL for this engine. The base URL is only used to resolve - components when a relative URL is passed to the QDeclarativeComponent constructor. + Return the base URL for this engine. The base URL is only used to + resolve components when a relative URL is passed to the + QDeclarativeComponent constructor. - If a base URL has not been explicitly set, this method returns the - application's current working directory. + If a base URL has not been explicitly set, this method returns the + application's current working directory. - \sa setBaseUrl() + \sa setBaseUrl() */ QUrl QDeclarativeEngine::baseUrl() const { @@ -604,9 +611,9 @@ QUrl QDeclarativeEngine::baseUrl() const } /*! - Set the base URL for this engine to \a url. + Set the base URL for this engine to \a url. - \sa baseUrl() + \sa baseUrl() */ void QDeclarativeEngine::setBaseUrl(const QUrl &url) { @@ -615,9 +622,11 @@ void QDeclarativeEngine::setBaseUrl(const QUrl &url) } /*! - Returns the QDeclarativeContext for the \a object, or 0 if no context has been set. + Returns the QDeclarativeContext for the \a object, or 0 if no + context has been set. - When the QDeclarativeEngine instantiates a QObject, the context is set automatically. + When the QDeclarativeEngine instantiates a QObject, the context is + set automatically. */ QDeclarativeContext *QDeclarativeEngine::contextForObject(const QObject *object) { @@ -642,7 +651,8 @@ QDeclarativeContext *QDeclarativeEngine::contextForObject(const QObject *object) If the \a object already has a context, a warning is output, but the context is not changed. - When the QDeclarativeEngine instantiates a QObject, the context is set automatically. + When the QDeclarativeEngine instantiates a QObject, the context is + set automatically. */ void QDeclarativeEngine::setContextForObject(QObject *object, QDeclarativeContext *context) { @@ -660,37 +670,43 @@ void QDeclarativeEngine::setContextForObject(QObject *object, QDeclarativeContex } /*! -\enum QDeclarativeEngine::ObjectOwnership - -Ownership controls whether or not QML automatically destroys the QObject when the object -is garbage collected by the JavaScript engine. The two ownership options are: - -\list -\o CppOwnership - The object is owned by C++ code, and will never be deleted by QML. The -JavaScript destroy() method cannot be used on objects with CppOwnership. This option -is similar to QScriptEngine::QtOwnership. - -\o JavaScriptOwnership - The object is owned by JavaScript. When the object is returned to QML -as the return value of a method call or property access, QML will delete the object if there -are no remaining JavaScript references to it and it has no QObject::parent(). This option -is similar to QScriptEngine::ScriptOwnership. -\endlist - -Generally an application doesn't need to set an object's ownership explicitly. QML uses -a heuristic to set the default object ownership. By default, an object that is created by -QML has JavaScriptOwnership. The exception to this are the root objects created by calling -QDeclarativeCompnent::create() or QDeclarativeComponent::beginCreate() which have -CppOwnership by default. The ownership of these root-level objects is considered to have -been transfered to the C++ caller. - -Objects not-created by QML have CppOwnership by default. The exception to this is objects -returned from a C++ method call. The ownership of these objects is passed to JavaScript. - -Calling setObjectOwnership() overrides the default ownership heuristic used by QML. + \enum QDeclarativeEngine::ObjectOwnership + + Ownership controls whether or not QML automatically destroys the + QObject when the object is garbage collected by the JavaScript + engine. The two ownership options are: + + \value CppOwnership The object is owned by C++ code, and will + never be deleted by QML. The JavaScript destroy() method cannot be + used on objects with CppOwnership. This option is similar to + QScriptEngine::QtOwnership. + + \value JavaScriptOwnership The object is owned by JavaScript. + When the object is returned to QML as the return value of a method + call or property access, QML will delete the object if there are no + remaining JavaScript references to it and it has no + QObject::parent(). This option is similar to + QScriptEngine::ScriptOwnership. + + Generally an application doesn't need to set an object's ownership + explicitly. QML uses a heuristic to set the default object + ownership. By default, an object that is created by QML has + JavaScriptOwnership. The exception to this are the root objects + created by calling QDeclarativeCompnent::create() or + QDeclarativeComponent::beginCreate() which have CppOwnership by + default. The ownership of these root-level objects is considered to + have been transfered to the C++ caller. + + Objects not-created by QML have CppOwnership by default. The + exception to this is objects returned from a C++ method call. The + ownership of these objects is passed to JavaScript. + + Calling setObjectOwnership() overrides the default ownership + heuristic used by QML. */ /*! -Sets the \a ownership of \a object. + Sets the \a ownership of \a object. */ void QDeclarativeEngine::setObjectOwnership(QObject *object, ObjectOwnership ownership) { @@ -703,7 +719,7 @@ void QDeclarativeEngine::setObjectOwnership(QObject *object, ObjectOwnership own } /*! -Returns the ownership of \a object. + Returns the ownership of \a object. */ QDeclarativeEngine::ObjectOwnership QDeclarativeEngine::objectOwnership(QObject *object) { |