Contents

• Public Types
• Properties
• Public Functions
• Signals
• Static Public Members
• Related Non-Members
• Macros
• Detailed Description

Detailed Description

TheQDeclarativeEngine class provides an environment for instantiating QML components.

Each QML component is instantiated in aQDeclarativeContext.QDeclarativeContext's are essential for passing data to QML components. In QML, contexts are arranged hierarchically and this hierarchy is managed by theQDeclarativeEngine.

Prior to creating any QML components, an application must have created aQDeclarativeEngine to gain access to a QML context. The following example shows how to create a simple Text item.

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

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

Member Type Documentation

enum QDeclarativeEngine::ObjectOwnership

Ownership controls whether or not QML automatically destroys theQObject when the object is garbage collected by the JavaScript engine. The two ownership options are:

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() orQDeclarativeComponent::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.

CallingsetObjectOwnership() overrides the default ownership heuristic used by QML.

Property Documentation

offlineStoragePath :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 tocreate new files at this location should create it first - seeQDir::mkpath().

Access functions:

Member Function Documentation

QDeclarativeEngine::QDeclarativeEngine(QObject * parent = 0)

Create a newQDeclarativeEngine with the givenparent.

[virtual]QDeclarativeEngine::~QDeclarativeEngine()

Destroys theQDeclarativeEngine.

AnyQDeclarativeContext's created on this engine will be invalidated, but not destroyed (unless they are parented to theQDeclarativeEngine object).

void QDeclarativeEngine::addImageProvider(constQString & providerId,QDeclarativeImageProvider * provider)

Sets theprovider to use for images requested via theimage: url scheme, with hostproviderId. TheQDeclarativeEngine takes ownership ofprovider.

Image providers enable support for pixmap and threaded image requests. See theQDeclarativeImageProvider 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.

See alsoremoveImageProvider().

void QDeclarativeEngine::addImportPath(constQString & path)

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

The newly addedpath will be first in theimportPathList().

See alsosetImportPathList() andQML Modules.

void QDeclarativeEngine::addPluginPath(constQString & path)

Addspath as a directory where the engine searches for native plugins for imported modules (referenced in theqmldir file).

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

The newly addedpath will be first in thepluginPathList().

See alsosetPluginPathList().

QUrl QDeclarativeEngine::baseUrl() const

Return the base URL for this engine. The base URL is only used to resolve components when a relative URL is passed to theQDeclarativeComponent constructor.

If a base URL has not been explicitly set, this method returns the application's current working directory.

See alsosetBaseUrl().

void QDeclarativeEngine::clearComponentCache()

Clears the engine's internal component cache.

Normally theQDeclarativeEngine caches components loaded from qml files. This method clears this cache and forces the component to be reloaded.

[static]QDeclarativeContext * QDeclarativeEngine::contextForObject(constQObject * object)

Returns theQDeclarativeContext for theobject, or 0 if no context has been set.

When theQDeclarativeEngine instantiates aQObject, the context is set automatically.

See alsosetContextForObject().

QDeclarativeImageProvider * QDeclarativeEngine::imageProvider(constQString & providerId) const

Returns theQDeclarativeImageProvider set forproviderId.

QStringList QDeclarativeEngine::importPathList() 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 importscom.mycompany.Feature will cause theQDeclarativeEngine to look in/opt/MyApp/lib/imports/com/mycompany/Feature/ for the components provided by that module. Aqmldir 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 theQML_IMPORT_PATH environment variable, and the builtinImportsPath fromQLibraryInfo.

See alsoaddImportPath() andsetImportPathList().

bool QDeclarativeEngine::importPlugin(constQString & filePath, constQString & uri,QString * errorString)

Imports the plugin namedfilePath with theuri 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 theQDeclarativeExtensionPlugin interface.

QNetworkAccessManager * QDeclarativeEngine::networkAccessManager() const

Returns a commonQNetworkAccessManager which can be used by any QML element instantiated by this engine.

If aQDeclarativeNetworkAccessManagerFactory has been set and aQNetworkAccessManager has not yet been created, theQDeclarativeNetworkAccessManagerFactory will be used to create theQNetworkAccessManager; otherwise the returnedQNetworkAccessManager will have no proxy or cache set.

See alsosetNetworkAccessManagerFactory().

QDeclarativeNetworkAccessManagerFactory * QDeclarativeEngine::networkAccessManagerFactory() const

Returns the currentQDeclarativeNetworkAccessManagerFactory.

See alsosetNetworkAccessManagerFactory().

[static]ObjectOwnership QDeclarativeEngine::objectOwnership(QObject * object)

Returns the ownership ofobject.

See alsosetObjectOwnership().

bool QDeclarativeEngine::outputWarningsToStandardError() const

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

The default value is true.

See alsosetOutputWarningsToStandardError().

QStringList QDeclarativeEngine::pluginPathList() const

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

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

See alsoaddPluginPath() andsetPluginPathList().

[signal]void QDeclarativeEngine::quit()

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

void QDeclarativeEngine::removeImageProvider(constQString & providerId)

Removes theQDeclarativeImageProvider forproviderId.

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

See alsoaddImageProvider().

QDeclarativeContext * QDeclarativeEngine::rootContext() const

Returns the engine's root context.

The root context is automatically created by theQDeclarativeEngine. 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.

void QDeclarativeEngine::setBaseUrl(constQUrl & url)

Set the base URL for this engine tourl.

See alsobaseUrl().

[static]void QDeclarativeEngine::setContextForObject(QObject * object,QDeclarativeContext * context)

Sets theQDeclarativeContext for theobject tocontext. If theobject already has a context, a warning is output, but the context is not changed.

When theQDeclarativeEngine instantiates aQObject, the context is set automatically.

See alsocontextForObject().

void QDeclarativeEngine::setImportPathList(constQStringList & paths)

Setspaths 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 theQML_IMPORT_PATH environment variable, and the builtinImportsPath fromQLibraryInfo.

See alsoimportPathList() andaddImportPath().

void QDeclarativeEngine::setNetworkAccessManagerFactory(QDeclarativeNetworkAccessManagerFactory * factory)

Sets thefactory to use for creatingQNetworkAccessManager(s).

QNetworkAccessManager is used for all network access by QML. By implementing a factory it is possible to create customQNetworkAccessManager with specialized caching, proxy and cookie support.

The factory must be set before executing the engine.

See alsonetworkAccessManagerFactory().

[static]void QDeclarativeEngine::setObjectOwnership(QObject * object,ObjectOwnership ownership)

Sets theownership ofobject.

See alsoobjectOwnership().

void QDeclarativeEngine::setOutputWarningsToStandardError(bool enabled)

Set whether warning messages will be output to stderr toenabled.

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

The default value is true.

See alsooutputWarningsToStandardError().

void QDeclarativeEngine::setPluginPathList(constQStringList & paths)

Sets the list of directories where the engine searches for native plugins for imported modules (referenced in theqmldir file) topaths.

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

See alsopluginPathList() andaddPluginPath().

[signal]void QDeclarativeEngine::warnings(constQList<QDeclarativeError> & warnings)

This signal is emitted whenwarnings messages are generated by QML.

Related Non-Members

QDeclarativeInfoqmlInfo(constQObject * object)

Prints warning messages that include the file and line number for the specified QMLobject.

When QML types display warning messages, it improves traceability if they include the QML file and line number on which the particular instance was instantiated.

To include the file and line number, an object must be passed. If the file and line number is not available for that instance (either it was not instantiated by the QML engine or location information is disabled), "unknown location" will be used instead.

For example,

qmlInfo(object)<< tr("component property is a write-once property");

prints

QML MyCustomType (unknown location): component property is a write-once property

intqmlRegisterInterface(constchar * typeName)

This template function registers the C++ type in the QML system under the nametypeName.

#include <QtDeclarative> to use this function.

Returns the QML type id.

intqmlRegisterType(constchar * uri,int versionMajor,int versionMinor, constchar * qmlName)

This template function registers the C++ type in the QML system with the nameqmlName, in the library imported fromuri having the version number composed fromversionMajor andversionMinor.

Returns the QML type id.

There are two forms of this template function:

template<typename T>int qmlRegisterType(constchar*uri,int versionMajor,int versionMinor,constchar*qmlName);template<typename T,int metaObjectRevision>int qmlRegisterType(constchar*uri,int versionMajor,int versionMinor,constchar*qmlName);

The former is the standard form which registers the typeT as a new type. The latter allows a particular revision of a class to be registered in a specified version (seeQML Type Versioning).

For example, this registers a C++ classMySliderItem as a QML type namedSlider for version 1.0 of amodule called "com.mycompany.qmlcomponents":

#include <QtDeclarative>...qmlRegisterType<MySliderItem>("com.mycompany.qmlcomponents",1,0,"Slider");

Once this is registered, the type can be used in QML by importing the specified module name and version number:

import com.mycompany.qmlcomponents 1.0Slider {// ...}

Note that it's perfectly reasonable for a library to register types to older versions than the actual version of the library. Indeed, it is normal for the new library to allow QML written to previous versions to continue to work, even if more advanced versions of some of its types are available.

intqmlRegisterType()

This is an overloaded function.

This template function registers the C++ type in the QML system. Instances of this type cannot be created from the QML system.

#include <QtDeclarative> to use this function.

Returns the QML type id.

intqmlRegisterTypeNotAvailable(constchar * uri,int versionMajor,int versionMinor, constchar * qmlName, constQString & message)

This function registers a type in the QML system with the nameqmlName, in the library imported fromuri having the version number composed fromversionMajor andversionMinor, but any attempt to instantiate the type will produce the given errormessage.

Normally, the types exported by a module should be fixed. However, if a C++ type is not available, you should at least "reserve" the QML type name, and give the user of your module a meaningful error message.

Returns the QML type id.

Example:

#ifdef NO_GAMES_ALLOWEDqmlRegisterTypeNotAvailable("MinehuntCore",0,1,"Game","Get back to work, slacker!");#elseqmlRegisterType<MinehuntGame>("MinehuntCore",0,1,"Game");#endif

This will cause any QML which uses this module and attempts to use the type to produce an error message:

fun.qml: Get back to work, slacker!   Game {^

Without this, a generic "Game is not a type" message would be given.

#include <QtDeclarative> to use this function.

See alsoqmlRegisterUncreatableType().

intqmlRegisterUncreatableType(constchar * uri,int versionMajor,int versionMinor, constchar * qmlName, constQString & message)

This template function registers the C++ type in the QML system with the nameqmlName, in the library imported fromuri having the version number composed fromversionMajor andversionMinor.

While the type has a name and a type, it cannot be created, and the given errormessage will result if creation is attempted.

This is useful where the type is only intended for providing attached properties or enum values.

Returns the QML type id.

#include <QtDeclarative> to use this function.

See alsoqmlRegisterTypeNotAvailable().

Macro Documentation

QML_DECLARE_TYPE()

Equivalent toQ_DECLARE_METATYPE(TYPE *) andQ_DECLARE_METATYPE(QDeclarativeListProperty<TYPE>)

#include <QtDeclarative> to use this macro.

QML_DECLARE_TYPEINFO( Type, Flags)

Declares additional properties of the givenType as described by the specifiedFlags.

Current the only supported type info isQML_HAS_ATTACHED_PROPERTIES which declares that theType supportsAttached Properties.

#include <QtDeclarative> to use this macro.