QDeclarativeEngine Class Reference

The QDeclarativeEngine class provides an environment for instantiating QML components.

  1. #include <QDeclarativeEngine>

Inherits: QObject.

This class was introduced in Qt 4.7.

Detailed Description

The QDeclarativeEngine class provides an environment for instantiating QML components.

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.

  1. QDeclarativeEngine engine;
  2. QDeclarativeComponent component(&engine);
  3. component.setData("import QtQuick 1.0\nText  { text: \"Hello world!\" }", QUrl());
  4. QDeclarativeItem *item = qobject_cast<QDeclarativeItem *>(component.create());
  5.  
  6. //add item to view, etc
  7. ...

In this case, the Text item will be created in the engine's root context.

See also QDeclarativeComponent and QDeclarativeContext.

Public Types

Toggle detailsenum QDeclarativeEngine::

ObjectOwnershipObjectOwnership { CppOwnership , JavaScriptOwnership 1 ...} { CppOwnership , JavaScriptOwnership 1 }

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:

ConstantValueDescription
QDeclarativeEngine::CppOwnership 0 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.
QDeclarativeEngine::JavaScriptOwnership 1 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 transferred 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.

Look up this member in the source code.

    Properties

    Toggle detailsofflineStoragePathofflineStoragePath : QString

    This property holds the directory for storing offline user data

    Returns the directory where SQL and other offline storage is placed.

    QDeclarativeWebView and the SQL databases created with openDatabase() are stored here.

    The default is QML/OfflineStorage in the platform-standard user application data directory.

    Note that the path may not currently exist on the filesystem, so callers wanting to create new files at this location should create it first - see QDir::mkpath().

    Access functions:

    Look up this member in the source code.

      Public Functions

      Toggle details QDeclarativeEngine

      QDeclarativeEngineQDeclarativeEngine ( QObject *parent=0 ) ( QObject *parent=0 )

      Create a new QDeclarativeEngine with the given parent.

      Look up this member in the source code.

      Toggle details QDeclarativeEngine

      ~QDeclarativeEngine~QDeclarativeEngine () () [virtual]

      Destroys the QDeclarativeEngine.

      Any QDeclarativeContext's created on this engine will be invalidated, but not destroyed (unless they are parented to the QDeclarativeEngine object).

      Look up this member in the source code.

      Toggle details void QDeclarativeEngine

      addImageProvideraddImageProvider ( const QString &providerId , QDeclarativeImageProvider *provider ...) ( const QString &providerId , QDeclarativeImageProvider *provider )

      Sets the provider to use for images requested via the image: url scheme, with host providerId. The QDeclarativeEngine takes ownership of provider.

      Image providers enable support for pixmap and threaded image requests. See the QDeclarativeImageProvider documentation for details on implementing and using image providers.

      All required image providers should be added to the engine before any QML sources files are loaded.

      Note that images loaded from a QDeclarativeImageProvider are cached by QPixmapCache, similar to any image loaded by QML.

      See also removeImageProvider().

      Look up this member in the source code.

      Toggle details void QDeclarativeEngine

      addImportPathaddImportPath ( const QString &path ) ( const QString &path )

      Adds path as a directory where the engine searches for installed modules in a URL-based directory structure. The path may be a local filesystem directory or a URL.

      The newly added path will be first in the importPathList().

      See also setImportPathList() and QML Modules.

      Look up this member in the source code.

      Toggle details void QDeclarativeEngine

      addPluginPathaddPluginPath ( const QString &path ) ( const QString &path )

      Adds path as a directory where the engine searches for native plugins for imported modules (referenced in the qmldir file).

      By default, the list contains only ., i.e. the engine searches in the directory of the qmldir file itself.

      The newly added path will be first in the pluginPathList().

      See also setPluginPathList().

      Look up this member in the source code.

      Toggle details QUrl QDeclarativeEngine

      baseUrlbaseUrl () ()const

      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.

      See also setBaseUrl().

      Look up this member in the source code.

      Toggle details void QDeclarativeEngine

      clearComponentCacheclearComponentCache () ()

      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.

      Look up this member in the source code.

      Toggle details QDeclarativeContext * QDeclarativeEngine

      contextForObjectcontextForObject ( const QObject *object ...) ( const QObject *object ) [static]

      Returns the QDeclarativeContext for the object, or 0 if no context has been set.

      When the QDeclarativeEngine instantiates a QObject, the context is set automatically.

      See also setContextForObject().

      Look up this member in the source code.

      Toggle details QDeclarativeImageProvider * QDeclarativeEngine

      imageProviderimageProvider ( const QString &providerId ...) ( const QString &providerId )const

      Returns the QDeclarativeImageProvider set for providerId.

      Look up this member in the source code.

      Toggle details QStringList QDeclarativeEngine

      importPathListimportPathList () ()const

      Returns the list of directories where the engine searches for installed modules in a URL-based directory structure.

      For example, if /opt/MyApp/lib/imports is in the path, then QML that imports com.mycompany.Feature will cause the QDeclarativeEngine to look in /opt/MyApp/lib/imports/com/mycompany/Feature/ for the components provided by that module. A qmldir file is required for defining the type version mapping and possibly declarative extensions plugins.

      By default, the list contains the directory of the application executable, paths specified in the QML_IMPORT_PATH environment variable, and the builtin ImportsPath from QLibraryInfo.

      See also addImportPath() and setImportPathList().

      Look up this member in the source code.

      Toggle details bool QDeclarativeEngine

      importPluginimportPlugin ( const QString &filePath , const QString &uri , QString *errorString ...) ( const QString &filePath , const QString &uri , QString *errorString )

      Imports the plugin named filePath with the uri provided. Returns true if the plugin was successfully imported; otherwise returns false.

      On failure and if non-null, *errorString will be set to a message describing the failure.

      The plugin has to be a Qt plugin which implements the QDeclarativeExtensionPlugin interface.

      Look up this member in the source code.

      Toggle details QNetworkAccessManager * QDeclarativeEngine

      networkAccessManagernetworkAccessManager () ()const

      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.

      See also setNetworkAccessManagerFactory().

      Look up this member in the source code.

      Toggle details QDeclarativeNetworkAccessManagerFactory * QDeclarativeEngine

      networkAccessManagerFactorynetworkAccessManagerFactory (...) ()const

      Look up this member in the source code.

      Toggle details ObjectOwnership QDeclarativeEngine

      objectOwnershipobjectOwnership ( QObject *object ) ( QObject *object ) [static]

      Returns the ownership of object.

      See also setObjectOwnership().

      Look up this member in the source code.

      Toggle details bool QDeclarativeEngine

      outputWarningsToStandardErroroutputWarningsToStandardError () ()const

      Returns true if warning messages will be output to stderr in addition to being emitted by the warnings() signal, otherwise false.

      The default value is true.

      See also setOutputWarningsToStandardError().

      Look up this member in the source code.

      Toggle details QStringList QDeclarativeEngine

      pluginPathListpluginPathList () ()const

      Returns the list of directories where the engine searches for native plugins for imported modules (referenced in the qmldir file).

      By default, the list contains only ., i.e. the engine searches in the directory of the qmldir file itself.

      See also addPluginPath() and setPluginPathList().

      Look up this member in the source code.

      Toggle details void QDeclarativeEngine

      removeImageProviderremoveImageProvider ( const QString &providerId ...) ( const QString &providerId )

      Removes the QDeclarativeImageProvider for providerId.

      Returns the provider if it was found; otherwise returns 0.

      See also addImageProvider().

      Look up this member in the source code.

      Toggle details QDeclarativeContext * QDeclarativeEngine

      rootContextrootContext () ()const

      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.

      Additional data that should only be available to a subset of component instances should be added to sub-contexts parented to the root context.

      Look up this member in the source code.

      Toggle details void QDeclarativeEngine

      setBaseUrlsetBaseUrl ( const QUrl &url ) ( const QUrl &url )

      Set the base URL for this engine to url.

      See also baseUrl().

      Look up this member in the source code.

      Toggle details void QDeclarativeEngine

      setContextForObjectsetContextForObject ( QObject *object , QDeclarativeContext *context ...) ( QObject *object , QDeclarativeContext *context ) [static]

      Sets the QDeclarativeContext for the object to context. If the 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.

      See also contextForObject().

      Look up this member in the source code.

      Toggle details void QDeclarativeEngine

      setImportPathListsetImportPathList ( const QStringList &paths ) ( const QStringList &paths )

      Sets paths as the list of directories where the engine searches for installed modules in a URL-based directory structure.

      By default, the list contains the directory of the application executable, paths specified in the QML_IMPORT_PATH environment variable, and the builtin ImportsPath from QLibraryInfo.

      See also importPathList() and addImportPath().

      Look up this member in the source code.

      Toggle details void QDeclarativeEngine

      setNetworkAccessManagerFactorysetNetworkAccessManagerFactory ( QDeclarativeNetworkAccessManagerFactory *factory ...) ( QDeclarativeNetworkAccessManagerFactory *factory )

      Sets the 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.

      The factory must be set before executing the engine.

      See also networkAccessManagerFactory().

      Look up this member in the source code.

      Toggle details void QDeclarativeEngine

      setObjectOwnershipsetObjectOwnership ( QObject *object , ObjectOwnership ownership ...) ( QObject *object , ObjectOwnership ownership ) [static]

      Sets the ownership of object.

      See also objectOwnership().

      Look up this member in the source code.

      Toggle details void QDeclarativeEngine

      setOutputWarningsToStandardErrorsetOutputWarningsToStandardError ( bool enabled ...) ( bool enabled )

      Set whether warning messages will be output to stderr to enabled.

      If enabled is true, any warning messages generated by QML will be output to stderr and emitted by the warnings() signal. If enabled is false, on the warnings() signal will be emitted. This allows applications to handle warning output themselves.

      The default value is true.

      See also outputWarningsToStandardError().

      Look up this member in the source code.

      Toggle details void QDeclarativeEngine

      setPluginPathListsetPluginPathList ( const QStringList &paths ) ( const QStringList &paths )

      Sets the list of directories where the engine searches for native plugins for imported modules (referenced in the qmldir file) to paths.

      By default, the list contains only ., i.e. the engine searches in the directory of the qmldir file itself.

      See also pluginPathList() and addPluginPath().

      Look up this member in the source code.

        Signals

        Toggle details void QDeclarativeEngine

        quitquit () () [signal]

        This signal is emitted when the QML loaded by the engine would like to quit.

        Look up this member in the source code.

        Toggle details void QDeclarativeEngine

        warningswarnings ( const QList <QDeclarativeError > &warnings ...) ( const QList <QDeclarativeError > &warnings ) [signal]

        This signal is emitted when warnings messages are generated by QML.

        Look up this member in the source code.

          Macros

          Toggle detailsQML_DECLARE_TYPEQML_DECLARE_TYPE

          Equivalent to Q_DECLARE_METATYPE(TYPE *) and Q_DECLARE_METATYPE(QDeclarativeListProperty<TYPE>)

          #include <QtDeclarative> to use this macro.

          Toggle detailsQML_DECLARE_TYPEINFOQML_DECLARE_TYPEINFO ( Type , Flags )

          Declares additional properties of the given Type as described by the specified Flags.

          Current the only supported type info is QML_HAS_ATTACHED_PROPERTIES which declares that the Type supports Attached Properties.

          #include <QtDeclarative> to use this macro.

            Notes provided by the Qt Community
            Informative
            • 0

            Votes: 0

            Coverage: Qt library 4.7, 4.8

            Picture of sigrid sigrid

            Lab Rat
            20 notes

            This person works for Qt Development Frameworks. Nokia Certified Qt Developer

            Triggering of the garbage collector

            In the current implementation the garbage collector will be run when the engine decides that it is wise to do so, that means after a certain number of objects have been created. There is however no guarantee as to when the garbage collection will take place. The way this is currently implemented might change for future versions.

            Also see the following link [doc.qt.nokia.com] which states that there is no guarantee as to when the garbage collection will take place.

            [Revisions]