The QQmlEngine class provides an environment for instantiating QML components. More...

#include <qqmlengine.h>

Inheritance diagram for QQmlEngine:

Collaboration diagram for QQmlEngine:

Public Slots
void	retranslate ()
	Refreshes all binding expressions that use strings marked for translation.

Public Slots inherited from QObject
void	deleteLater ()
	\threadsafe

Signals
void	offlineStoragePathChanged ()
	This signal is emitted when \l offlineStoragePath changes.

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

void	exit (int retCode)
	This signal is emitted when the QML loaded by the engine would like to exit from the event loop with the specified return code retCode.

void	warnings (const QList< QQmlError > &warnings)
	This signal is emitted when warnings messages are generated by QML.

Signals inherited from QJSEngine
void	uiLanguageChanged ()

Signals inherited from QObject
void	destroyed (QObject *=nullptr)
	This signal is emitted immediately before the object obj is destroyed, after any instances of QPointer have been notified, and cannot be blocked.

void	objectNameChanged (const QString &objectName, QPrivateSignal)
	This signal is emitted after the object's name has been changed.

Public Member Functions
	QQmlEngine (QObject *p=nullptr)
	Create a new QQmlEngine with the given parent.

	~QQmlEngine () override
	Destroys the QQmlEngine.

QQmlContext *	rootContext () const
	Returns the engine's root context.

void	clearComponentCache ()
	Clears the engine's internal component cache.

void	trimComponentCache ()
	Trims the engine's internal component cache.

void	clearSingletons ()
	Clears all singletons the engine owns.

QStringList	importPathList () const
	Returns the list of directories where the engine searches for installed modules in a URL-based directory structure.

void	setImportPathList (const QStringList &paths)
	Sets paths as the list of directories where the engine searches for installed modules in a URL-based directory structure.

void	addImportPath (const QString &dir)
	Adds path as a directory where the engine searches for installed modules in a URL-based directory structure.

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

void	setPluginPathList (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.

void	addPluginPath (const QString &dir)
	Adds path as a directory where the engine searches for native plugins for imported modules (referenced in the `qmldir` file).

void	addUrlInterceptor (QQmlAbstractUrlInterceptor *urlInterceptor)
	Adds a urlInterceptor to be used when resolving URLs in QML.

void	removeUrlInterceptor (QQmlAbstractUrlInterceptor *urlInterceptor)
	Remove a urlInterceptor that was previously added using \l addUrlInterceptor.

QList< QQmlAbstractUrlInterceptor * >	urlInterceptors () const
	Returns the list of currently active URL interceptors.

QUrl	interceptUrl (const QUrl &url, QQmlAbstractUrlInterceptor::DataType type) const
	Run the current URL interceptors on the given url of the given type and return the result.

void	addImageProvider (const QString &id, QQmlImageProviderBase *)
	Sets the provider to use for images requested via the image: url scheme, with host providerId.

QQmlImageProviderBase *	imageProvider (const QString &id) const
	Returns the image provider set for providerId if found; otherwise returns \nullptr.

void	removeImageProvider (const QString &id)
	Removes the image provider for providerId.

void	setIncubationController (QQmlIncubationController *)
	Sets the engine's incubation controller.

QQmlIncubationController *	incubationController () const
	Returns the currently set incubation controller, or 0 if no controller has been set.

void	setOfflineStoragePath (const QString &dir)

QString	offlineStoragePath () const

QString	offlineStorageDatabaseFilePath (const QString &databaseName) const
	Returns the file path where a \l{QtQuick.LocalStorage}{Local Storage} database with the identifier databaseName is (or would be) located.

QUrl	baseUrl () const
	Return the base URL for this engine.

void	setBaseUrl (const QUrl &)
	Set the base URL for this engine to url.

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

void	setOutputWarningsToStandardError (bool)
	Set whether warning messages will be output to stderr to enabled.

void	markCurrentFunctionAsTranslationBinding ()

template<typename T >
T	singletonInstance (int qmlTypeId)
	\qmlproperty string Qt::uiLanguage

template<typename T >
T	singletonInstance (QAnyStringView moduleName, QAnyStringView typeName)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Returns the instance of a singleton type named typeName from the module specified by uri.

void	captureProperty (QObject *object, const QMetaProperty &property) const

template<>
Q_QML_EXPORT QJSValue	singletonInstance (int qmlTypeId)

template<>
Q_QML_EXPORT QJSValue	singletonInstance (QAnyStringView uri, QAnyStringView typeName)

template<>
QJSValue	singletonInstance (int qmlTypeId)

template<>
QJSValue	singletonInstance (QAnyStringView uri, QAnyStringView typeName)

template<>
QJSValue	singletonInstance (int qmlTypeId)

template<>
QJSValue	singletonInstance (QAnyStringView uri, QAnyStringView typeName)

Public Member Functions inherited from QJSEngine
	QJSEngine ()
	Constructs a QJSEngine object.

	QJSEngine (QObject *parent)
	Constructs a QJSEngine object with the given parent.

	~QJSEngine () override
	Destroys this QJSEngine.

QJSValue	globalObject () const
	Returns this engine's Global Object.

QJSValue	evaluate (const QString &program, const QString &fileName=QString(), int lineNumber=1, QStringList *exceptionStackTrace=nullptr)
	Evaluates program, using lineNumber as the base line number, and returns the result of the evaluation.

QJSValue	importModule (const QString &fileName)
	Imports the module located at fileName and returns a module namespace object that contains all exported variables, constants and functions as properties.

bool	registerModule (const QString &moduleName, const QJSValue &value)
	Registers a QJSValue to serve as a module.

QJSValue	newObject ()
	Creates a JavaScript object of class Object.

QJSValue	newSymbol (const QString &name)

QJSValue	newArray (uint length=0)
	Creates a JavaScript object of class Array with the given length.

QJSValue	newQObject (QObject *object)
	Creates a JavaScript object that wraps the given QObject object, using JavaScriptOwnership.

QJSValue	newQMetaObject (const QMetaObject *metaObject)

template<typename T >
QJSValue	newQMetaObject ()

QJSValue	newErrorObject (QJSValue::ErrorType errorType, const QString &message=QString())

template<typename T >
QJSValue	toScriptValue (const T &value)
	Creates a QJSValue with the given value.

template<typename T >
QJSManagedValue	toManagedValue (const T &value)
	Creates a QJSManagedValue with the given value.

template<typename T >
QJSPrimitiveValue	toPrimitiveValue (const T &value)
	Creates a QJSPrimitiveValue with the given value.

template<typename T >
T	fromScriptValue (const QJSValue &value)
	Returns the given value converted to the template type {T}.

template<typename T >
T	fromManagedValue (const QJSManagedValue &value)
	Returns the given value converted to the template type {T}.

template<typename T >
T	fromPrimitiveValue (const QJSPrimitiveValue &value)
	Returns the given value converted to the template type {T}.

template<typename T >
T	fromVariant (const QVariant &value)
	Returns the given value converted to the template type {T}.

template<typename From , typename To >
To	coerceValue (const From &from)
	Returns the given from converted to the template type {To}.

void	collectGarbage ()
	Runs the garbage collector.

void	installExtensions (Extensions extensions, const QJSValue &object=QJSValue())

void	setInterrupted (bool interrupted)

bool	isInterrupted () const

QV4::ExecutionEngine *	handle () const

void	throwError (const QString &message)
	Throws a run-time error (exception) with the given message.

void	throwError (QJSValue::ErrorType errorType, const QString &message=QString())

void	throwError (const QJSValue &error)

bool	hasError () const
	Returns `true` if the last JavaScript execution resulted in an exception or if throwError() was called.

QJSValue	catchError ()
	If an exception is currently pending, catches it and returns it as a QJSValue.

QString	uiLanguage () const

void	setUiLanguage (const QString &language)

Public Member Functions inherited from QObject
Q_INVOKABLE	QObject (QObject *parent=nullptr)
	Constructs an object with parent object parent.

virtual	~QObject ()
	Destroys the object, deleting all its child objects.

virtual bool	eventFilter (QObject watched, QEvent event)
	Filters events if this object has been installed as an event filter for the watched object.

QString	objectName () const

Q_WEAK_OVERLOAD void	setObjectName (const QString &name)
	Sets the object's name to name.

void	setObjectName (QAnyStringView name)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

QBindable< QString >	bindableObjectName ()

bool	isWidgetType () const
	Returns `true` if the object is a widget; otherwise returns `false`.

bool	isWindowType () const
	Returns `true` if the object is a window; otherwise returns `false`.

bool	isQuickItemType () const
	Returns `true` if the object is a QQuickItem; otherwise returns `false`.

bool	signalsBlocked () const noexcept
	Returns `true` if signals are blocked; otherwise returns `false`.

bool	blockSignals (bool b) noexcept
	If block is true, signals emitted by this object are blocked (i.e., emitting a signal will not invoke anything connected to it).

QThread *	thread () const
	Returns the thread in which the object lives.

bool	moveToThread (QThread *thread QT6_DECL_NEW_OVERLOAD_TAIL)
	Changes the thread affinity for this object and its children and returns `true` on success.

int	startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer)
	This is an overloaded function that will start a timer of type timerType and a timeout of interval milliseconds.

int	startTimer (std::chrono::nanoseconds time, Qt::TimerType timerType=Qt::CoarseTimer)

void	killTimer (int id)
	Kills the timer with timer identifier, id.

void	killTimer (Qt::TimerId id)

template<typename T >
T	findChild (QAnyStringView aName, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
	Returns the child of this object that can be cast into type T and that is called name, or \nullptr if there is no such object.

template<typename T >
QList< T >	findChildren (QAnyStringView aName, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
	Returns all children of this object with the given name that can be cast to type T, or an empty list if there are no such objects.

template<typename T >
T	findChild (Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<typename T >
QList< T >	findChildren (Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

const QObjectList &	children () const
	Returns a list of child objects.

void	setParent (QObject *parent)
	Makes the object a child of parent.

void	installEventFilter (QObject *filterObj)
	Installs an event filter filterObj on this object.

void	removeEventFilter (QObject *obj)
	Removes an event filter object obj from this object.

QMetaObject::Connection	connect (const QObject sender, const char signal, const char *member, Qt::ConnectionType type=Qt::AutoConnection) const

bool	disconnect (const char signal=nullptr, const QObject receiver=nullptr, const char *member=nullptr) const

bool	disconnect (const QObject receiver, const char member=nullptr) const

void	dumpObjectTree () const
	Dumps a tree of children to the debug output.

void	dumpObjectInfo () const
	Dumps information about signal connections, etc.

bool	setProperty (const char *name, const QVariant &value)
	Sets the value of the object's name property to value.

bool	setProperty (const char *name, QVariant &&value)

QVariant	property (const char *name) const
	Returns the value of the object's name property.

QList< QByteArray >	dynamicPropertyNames () const

QBindingStorage *	bindingStorage ()

const QBindingStorage *	bindingStorage () const

QObject *	parent () const
	Returns a pointer to the parent object.

bool	inherits (const char *classname) const
	Returns `true` if this object is an instance of a class that inherits className or a QObject subclass that inherits className; otherwise returns `false`.

Static Public Member Functions
static QQmlContext *	contextForObject (const QObject *)
	Returns the QQmlContext for the object, or nullptr if no context has been set.

static void	setContextForObject (QObject , QQmlContext )
	Sets the QQmlContext for the object to context.

Static Public Member Functions inherited from QJSEngine
static void	setObjectOwnership (QObject *, ObjectOwnership)
	Sets the ownership of object.

static ObjectOwnership	objectOwnership (QObject *)
	Returns the ownership of object.

Static Public Member Functions inherited from QObject
static QMetaObject::Connection	connect (const QObject sender, const char signal, const QObject receiver, const char member, Qt::ConnectionType=Qt::AutoConnection)
	\threadsafe

static QMetaObject::Connection	connect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method, Qt::ConnectionType type=Qt::AutoConnection)

template<typename Func1 , typename Func2 >
static QMetaObject::Connection	connect (const typename QtPrivate::FunctionPointer< Func1 >::Object sender, Func1 signal, const typename QtPrivate::ContextTypeForFunctor< Func2 >::ContextType context, Func2 &&slot, Qt::ConnectionType type=Qt::AutoConnection)

template<typename Func1 , typename Func2 >
static QMetaObject::Connection	connect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, Func2 &&slot)

static bool	disconnect (const QObject sender, const char signal, const QObject receiver, const char member)
	\threadsafe

static bool	disconnect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &member)

static bool	disconnect (const QMetaObject::Connection &)
	Disconnect a connection.

template<typename Func1 , typename Func2 >
static bool	disconnect (const typename QtPrivate::FunctionPointer< Func1 >::Object sender, Func1 signal, const typename QtPrivate::FunctionPointer< Func2 >::Object receiver, Func2 slot)

template<typename Func1 >
static bool	disconnect (const typename QtPrivate::FunctionPointer< Func1 >::Object sender, Func1 signal, const QObject receiver, void **zero)

Protected Member Functions
	QQmlEngine (QQmlEnginePrivate &dd, QObject *p)

bool	event (QEvent *) override
	\reimp

Protected Member Functions inherited from QJSEngine
	QJSEngine (QJSEnginePrivate &dd, QObject *parent=nullptr)

Protected Member Functions inherited from QObject
QObject *	sender () const
	Returns a pointer to the object that sent the signal, if called in a slot activated by a signal; otherwise it returns \nullptr.

int	senderSignalIndex () const

int	receivers (const char *signal) const
	Returns the number of receivers connected to the signal.

bool	isSignalConnected (const QMetaMethod &signal) const

virtual void	timerEvent (QTimerEvent *event)
	This event handler can be reimplemented in a subclass to receive timer events for the object.

virtual void	childEvent (QChildEvent *event)
	This event handler can be reimplemented in a subclass to receive child events.

virtual void	customEvent (QEvent *event)
	This event handler can be reimplemented in a subclass to receive custom events.

virtual void	connectNotify (const QMetaMethod &signal)

virtual void	disconnectNotify (const QMetaMethod &signal)

	QObject (QObjectPrivate &dd, QObject *parent=nullptr)

Properties
QString	offlineStoragePath
	the directory for storing offline user data

Properties inherited from QJSEngine
QString	uiLanguage
	the language to be used for translating user interface strings

Properties inherited from QObject
QString	objectName
	the name of this object

Related Symbols
(Note that these are not member symbols.)
void	qmlRegisterModuleImport (const char uri, int moduleMajor, const char import, int importMajor, int importMinor)
	Registers a qmldir-import for module uri of major version moduleMajor.

void	qmlUnregisterModuleImport (const char uri, int moduleMajor, const char import, int importMajor, int importMinor)
	Removes a module import previously registered with qmlRegisterModuleImport()

QQmlEngine *	qmlEngine (const QObject *object)
	Returns the QQmlEngine associated with object, if any.

QQmlContext *	qmlContext (const QObject *object)
	Returns the QQmlContext associated with object, if any.

Related Symbols inherited from QJSEngine
QJSEngine *	qjsEngine (const QObject *object)

Related Symbols inherited from QObject
template< class T > T	qobject_cast (const QObject *object)
	Returns the given object cast to type T if the object is of type T (or of a subclass); otherwise returns \nullptr.

template< typename T > T	qFindChildqFindChildren (const QObject *obj, const QString &name)()

template< typename T > QList< T >	qFindChildrenqFindChildren (const QObject *obj, const QString &name)()

	QObjectList
	\macro Q_CLASSINFO(Name, Value)

Additional Inherited Members
Public Types inherited from QJSEngine
enum	ObjectOwnership { CppOwnership , JavaScriptOwnership }
	ObjectOwnership controls whether or not the JavaScript memory manager automatically destroys the QObject when the corresponding JavaScript object is garbage collected by the engine. More...

enum	Extension { TranslationExtension = 0x1 , ConsoleExtension = 0x2 , GarbageCollectionExtension = 0x4 , AllExtensions = 0xffffffff }
	This enum is used to specify extensions to be installed via \l installExtensions(). More...

Protected Attributes inherited from QObject
QScopedPointer< QObjectData >	d_ptr

Detailed Description

The QQmlEngine class provides an environment for instantiating QML components.

Since: 5.0 \inmodule QtQml

A QQmlEngine is used to manage \l{QQmlComponent}{components} and objects created from them and execute their bindings and functions. QQmlEngine also inherits from \l{QJSEngine} which allows seamless integration between your QML components and JavaScript code.

Each QML component is instantiated in a QQmlContext. In QML, contexts are arranged hierarchically and this hierarchy is managed by the QQmlEngine. By default, components are instantiated in the \l {QQmlEngine::rootContext()}{root context}.

See also: QQmlComponent, QQmlContext, {QML Global Object}, QQmlApplicationEngine

Definition at line 56 of file qqmlengine.h.

Constructor & Destructor Documentation

◆ QQmlEngine() [1/2]

QQmlEngine::QQmlEngine ( QObject * p = nullptr )

explicit

Create a new QQmlEngine with the given parent.

Definition at line 507 of file qqmlengine.cpp.

◆ ~QQmlEngine()

QQmlEngine::~QQmlEngine ( )

override

Destroys the QQmlEngine.

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

See ~QJSEngine() for details on cleaning up the JS engine.

Definition at line 534 of file qqmlengine.cpp.

◆ QQmlEngine() [2/2]

QQmlEngine::QQmlEngine	(	QQmlEnginePrivate &	dd,
		QObject *	parent )

protected

Definition at line 518 of file qqmlengine.cpp.

Member Function Documentation

◆ addImageProvider()

void QQmlEngine::addImageProvider	(	const QString &	providerId,
		QQmlImageProviderBase *	provider )

Sets the provider to use for images requested via the image: url scheme, with host providerId.

The QQmlEngine takes ownership of provider.

Image providers enable support for pixmap and threaded image requests. See the QQuickImageProvider 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 also: removeImageProvider(), QQuickImageProvider, QQmlImageProviderBase

Definition at line 845 of file qqmlengine.cpp.

◆ addImportPath()

void QQmlEngine::addImportPath ( 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, a \l {The Qt Resource System}{Qt Resource} path ({:/imports}), a \l {The Qt Resource System}{Qt Resource} url ({qrc:/imports}) or a URL.

The path will be converted into canonical form before it is added to the import path list.

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

{See also} \l setImportPathList(), \l {QML Modules}, and \l [QtQml] {QML Import Path}

Definition at line 1622 of file qqmlengine.cpp.

◆ addPluginPath()

void QQmlEngine::addPluginPath ( 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()

Definition at line 1679 of file qqmlengine.cpp.

◆ addUrlInterceptor()

void QQmlEngine::addUrlInterceptor ( QQmlAbstractUrlInterceptor * urlInterceptor )

Adds a urlInterceptor to be used when resolving URLs in QML.

This also applies to URLs used for loading script files and QML types. The URL interceptors should not be modifed while the engine is loading files, or URL selection may be inconsistent. Multiple URL interceptors, when given, will be called in the order they were added for each URL.

QQmlEngine does not take ownership of the interceptor and won't delete it.

Definition at line 710 of file qqmlengine.cpp.

◆ baseUrl()

QUrl QQmlEngine::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 the QQmlComponent constructor.

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

See also: setBaseUrl()

Definition at line 890 of file qqmlengine.cpp.

◆ captureProperty()

void QQmlEngine::captureProperty	(	QObject *	object,
		const QMetaProperty &	property ) const

Capture the given property as part of a binding.

Definition at line 985 of file qqmlengine.cpp.

◆ clearComponentCache()

void QQmlEngine::clearComponentCache ( )

Clears the engine's internal component cache.

This function causes the property metadata of most components previously loaded by the engine to be destroyed. It does so by dropping unreferenced components from the engine's component cache. It does not drop components that are still referenced since that would almost certainly lead to crashes further down the line.

If no components are referenced, this function returns the engine to a state where it does not contain any loaded component data. This may be useful in order to reload a smaller subset of the previous component set, or to load a new version of a previously loaded component.

Once the component cache has been cleared, components must be loaded before any new objects can be created.

Note: Any existing objects created from QML components retain their types, even if you clear the component cache. This includes singleton objects. If you create more objects from the same QML code after clearing the cache, the new objects will be of different types than the old ones. Assigning such a new object to a property of its declared type belonging to an object created before clearing the cache won't work.

As a general rule of thumb, make sure that no objects created from QML components are alive when you clear the component cache.

See also: trimComponentCache(), clearSingletons()

Definition at line 609 of file qqmlengine.cpp.

◆ clearSingletons()

void QQmlEngine::clearSingletons ( )

Clears all singletons the engine owns.

This function drops all singleton instances, deleting any QObjects owned by the engine among them. This is useful to make sure that no QML-created objects are left before calling clearComponentCache().

QML properties holding QObject-based singleton instances become null if the engine owns the singleton or retain their value if the engine doesn't own it. The singletons are not automatically re-created by accessing existing QML-created objects. Only when new components are instantiated, the singletons are re-created.

See also: clearComponentCache()

Definition at line 662 of file qqmlengine.cpp.

◆ contextForObject()

QQmlContext * QQmlEngine::contextForObject ( const QObject * object )

static

Returns the QQmlContext for the object, or nullptr if no context has been set.

When the QQmlEngine instantiates a QObject, an internal context is assigned to it automatically. Such internal contexts are read-only. You cannot set context properties on them.

See also: qmlContext(), qmlEngine(), QQmlContext::setContextProperty()

Definition at line 1115 of file qqmlengine.cpp.

◆ event()

bool QQmlEngine::event ( QEvent * e )

overrideprotectedvirtual

\reimp

Reimplemented from QObject.

Definition at line 1155 of file qqmlengine.cpp.

◆ exit

void QQmlEngine::exit ( int retCode )

signal

This signal is emitted when the QML loaded by the engine would like to exit from the event loop with the specified return code retCode.

Since: 5.8

See also: quit()

◆ imageProvider()

QQmlImageProviderBase * QQmlEngine::imageProvider ( const QString & providerId ) const

Returns the image provider set for providerId if found; otherwise returns \nullptr.

See also: QQuickImageProvider

Definition at line 859 of file qqmlengine.cpp.

◆ importPathList()

QStringList QQmlEngine::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 imports com.mycompany.Feature will cause the QQmlEngine 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 QML extensions plugins.

By default, this list contains the paths mentioned in \l {QML Import Path}.

See also: addImportPath(), setImportPathList()

Definition at line 1643 of file qqmlengine.cpp.

◆ incubationController()

QQmlIncubationController * QQmlEngine::incubationController ( ) const

Returns the currently set incubation controller, or 0 if no controller has been set.

See also: setIncubationController()

Definition at line 87 of file qqmlincubator.cpp.

◆ interceptUrl()

QUrl QQmlEngine::interceptUrl	(	const QUrl &	url,
		QQmlAbstractUrlInterceptor::DataType	type ) const

Run the current URL interceptors on the given url of the given type and return the result.

Definition at line 734 of file qqmlengine.cpp.

◆ markCurrentFunctionAsTranslationBinding()

void QQmlEngine::markCurrentFunctionAsTranslationBinding ( )

Since: 6.6 If this method is called inside of a function that is part of a binding in QML, the binding will be treated as a translation binding.

class I18nAwareClass : public QObject {
 
  //...
 
   QString text() const
   {
        if (auto engine = qmlEngine(this))
            engine->markCurrentFunctionAsTranslationBinding();
        return tr("Hello, world!");
   }
};

Note: This function is mostly useful if you wish to provide your own alternative to the qsTr function. To ensure that properties exposed from C++ classes are updated on language changes, it is instead recommended to react to LanguageChange events. That is a more general mechanism which also works when the class is used in a non-QML context, and has slightly less overhead. However, using markCurrentFunctionAsTranslationBinding can be acceptable when the class is already closely tied to the QML engine. For more details, see \l {Prepare for Dynamic Language Changes}

See also: QQmlEngine::retranslate

Definition at line 973 of file qqmlengine.cpp.

◆ offlineStorageDatabaseFilePath()

QString QQmlEngine::offlineStorageDatabaseFilePath ( const QString & databaseName ) const

Returns the file path where a \l{QtQuick.LocalStorage}{Local Storage} database with the identifier databaseName is (or would be) located.

See also: {openDatabaseSync}{LocalStorage.openDatabaseSync()}

Since: 5.9

Definition at line 1802 of file qqmlengine.cpp.

◆ offlineStoragePath()

QString QQmlEngine::offlineStoragePath ( ) const

Definition at line 1777 of file qqmlengine.cpp.

◆ offlineStoragePathChanged

void QQmlEngine::offlineStoragePathChanged ( )

signal

This signal is emitted when \l offlineStoragePath changes.

Since: 6.5

◆ outputWarningsToStandardError()

bool QQmlEngine::outputWarningsToStandardError ( ) 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.

Definition at line 919 of file qqmlengine.cpp.

◆ pluginPathList()

QStringList QQmlEngine::pluginPathList ( ) 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(), setPluginPathList()

Definition at line 1694 of file qqmlengine.cpp.

◆ quit

void QQmlEngine::quit ( )

signal

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

See also: exit()

◆ removeImageProvider()

void QQmlEngine::removeImageProvider ( const QString & providerId )

Removes the image provider for providerId.

See also: addImageProvider(), QQuickImageProvider

Definition at line 872 of file qqmlengine.cpp.

◆ removeUrlInterceptor()

void QQmlEngine::removeUrlInterceptor ( QQmlAbstractUrlInterceptor * urlInterceptor )

Remove a urlInterceptor that was previously added using \l addUrlInterceptor.

The URL interceptors should not be modifed while the engine is loading files, or URL selection may be inconsistent.

This does not delete the interceptor, but merely removes it from the engine. You can re-use it on the same or a different engine afterwards.

Definition at line 724 of file qqmlengine.cpp.

◆ retranslate

void QQmlEngine::retranslate ( )

slot

Refreshes all binding expressions that use strings marked for translation.

Call this function after you have installed a new translator with QCoreApplication::installTranslator, to ensure that your user-interface shows up-to-date translations.

Since: 5.10

Definition at line 1099 of file qqmlengine.cpp.

◆ rootContext()

QQmlContext * QQmlEngine::rootContext ( ) const

Returns the engine's root context.

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

Definition at line 679 of file qqmlengine.cpp.

◆ setBaseUrl()

void QQmlEngine::setBaseUrl ( const QUrl & url )

Set the base URL for this engine to url.

See also: baseUrl()

Definition at line 907 of file qqmlengine.cpp.

◆ setContextForObject()

void QQmlEngine::setContextForObject	(	QObject *	object,
		QQmlContext *	context )

static

Sets the QQmlContext for the object to context.

If the object already has a context, a warning is output, but the context is not changed.

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

Definition at line 1135 of file qqmlengine.cpp.

◆ setImportPathList()

void QQmlEngine::setImportPathList ( 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, this list contains the paths mentioned in \l {QML Import Path}.

Warning: Calling setImportPathList does not preserve the default import paths.

See also: importPathList(), addImportPath()

Definition at line 1661 of file qqmlengine.cpp.

◆ setIncubationController()

void QQmlEngine::setIncubationController ( QQmlIncubationController * controller )

Sets the engine's incubation controller.

The engine can only have one active controller and it does not take ownership of it.

See also: incubationController()

Definition at line 73 of file qqmlincubator.cpp.

◆ setOfflineStoragePath()

void QQmlEngine::setOfflineStoragePath ( const QString & dir )

Definition at line 1768 of file qqmlengine.cpp.

◆ setOutputWarningsToStandardError()

void QQmlEngine::setOutputWarningsToStandardError ( 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, only the warnings() signal will be emitted. This allows applications to handle warning output themselves.

The default value is true.

Definition at line 935 of file qqmlengine.cpp.

◆ setPluginPathList()

void QQmlEngine::setPluginPathList ( 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(), addPluginPath()

Definition at line 1710 of file qqmlengine.cpp.

◆ singletonInstance() [1/8]

template<>

QJSValue QQmlEngine::singletonInstance ( int qmlTypeId )

Definition at line 1041 of file qqmlengine.cpp.

◆ singletonInstance() [2/8]

template<>

QJSValue QQmlEngine::singletonInstance ( int qmlTypeId )

Definition at line 1041 of file qqmlengine.cpp.

◆ singletonInstance() [3/8]

template<typename T >

T QQmlEngine::singletonInstance ( int qmlTypeId )

\qmlproperty string Qt::uiLanguage

Since: 5.15

The uiLanguage holds the name of the language to be used for user interface string translations. It is exposed in C++ as QQmlEngine::uiLanguage property.

You can set the value freely and use it in bindings. It is recommended to set it after installing translators in your application. By convention, an empty string means no translation from the language used in the source code is intended to occur.

If you're using QQmlApplicationEngine and the value changes, QQmlEngine::retranslate() will be called.

Returns the instance of a singleton type that was registered under qmlTypeId.

The template argument T may be either QJSValue or a pointer to a QObject-derived type and depends on how the singleton was registered. If no instance of T has been created yet, it is created now. If qmlTypeId does not represent a valid singleton type, either a default constructed QJSValue or a nullptr is returned.

QObject* example:

class MySingleton : public QObject {
    Q_OBJECT
 
    // Register as default constructed singleton.
    QML_ELEMENT
    QML_SINGLETON
 
    static int typeId;
    // ...
};

\codeline

MySingleton::typeId = qmlTypeId(...);

\codeline

    // Retrieve as QObject*
    QQmlEngine engine;
    MySingleton* instance = engine.singletonInstance<MySingleton*>(MySingleton::typeId);

QJSValue example:

// Register with QJSValue callback

int typeId = qmlRegisterSingletonType(...);

\codeline

    // Retrieve as QJSValue
    QQmlEngine engine;
    QJSValue instance = engine.singletonInstance<QJSValue>(typeId);

It is recommended to store the QML type id, e.g. as a static member in the singleton class. The lookup via qmlTypeId() is costly.

See also: QML_SINGLETON, qmlRegisterSingletonType(), qmlTypeId()

Since: 5.12

Definition at line 164 of file qqmlengine.h.

◆ singletonInstance() [4/8]

template<>

Q_QML_EXPORT QJSValue QQmlEngine::singletonInstance ( int qmlTypeId )

◆ singletonInstance() [5/8]

template<typename T >

T QQmlEngine::singletonInstance	(	QAnyStringView	uri,
		QAnyStringView	typeName )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Returns the instance of a singleton type named typeName from the module specified by uri.

This method can be used as an alternative to calling qmlTypeId followed by the id based overload of singletonInstance. This is convenient when one only needs to do a one time setup of a singleton; if repeated access to the singleton is required, caching its typeId will allow faster subsequent access via the \l {QQmlEngine::singletonInstance(int qmlTypeId)}{type-id based overload}.

The template argument T may be either QJSValue or a pointer to a QObject-derived type and depends on how the singleton was registered. If no instance of T has been created yet, it is created now. If typeName does not represent a valid singleton type, either a default constructed QJSValue or a nullptr is returned.

QQmlEngine engine;

MySingleton *singleton = engine.singletonInstance<MySingleton *>("mymodule", "MySingleton");

See also: QML_SINGLETON, qmlRegisterSingletonType(), qmlTypeId()

Since: 6.5

Definition at line 172 of file qqmlengine.h.

◆ singletonInstance() [6/8]

template<>

QJSValue QQmlEngine::singletonInstance	(	QAnyStringView	uri,
		QAnyStringView	typeName )

Definition at line 1076 of file qqmlengine.cpp.

◆ singletonInstance() [7/8]

template<>

QJSValue QQmlEngine::singletonInstance	(	QAnyStringView	uri,
		QAnyStringView	typeName )

Definition at line 1076 of file qqmlengine.cpp.

◆ singletonInstance() [8/8]

template<>

Q_QML_EXPORT QJSValue QQmlEngine::singletonInstance	(	QAnyStringView	uri,
		QAnyStringView	typeName )

◆ trimComponentCache()

void QQmlEngine::trimComponentCache ( )

Trims the engine's internal component cache.

This function causes the property metadata of any loaded components which are not currently in use to be destroyed.

A component is considered to be in use if there are any extant instances of the component itself, any instances of other components that use the component, or any objects instantiated by any of those components.

See also: clearComponentCache()

Definition at line 640 of file qqmlengine.cpp.

◆ urlInterceptors()

QList< QQmlAbstractUrlInterceptor * > QQmlEngine::urlInterceptors ( ) const

Returns the list of currently active URL interceptors.

Definition at line 746 of file qqmlengine.cpp.

◆ warnings

void QQmlEngine::warnings ( const QList< QQmlError > & warnings )

signal

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

Friends And Related Symbol Documentation

◆ qmlContext()

QQmlContext * qmlContext ( const QObject * object )

This is equivalent to QQmlEngine::contextForObject(object).

Note: Add {#include <QtQml>} to use this function.

See also: {QQmlEngine::contextForObject()}{contextForObject()}, qmlEngine()

◆ qmlEngine()

QQmlEngine * qmlEngine ( const QObject * object )

This is equivalent to QQmlEngine::contextForObject(object)->engine(), but more efficient.

Note: Add {#include <QtQml>} to use this function.

See also: {QQmlEngine::contextForObject()}{contextForObject()}, qmlContext()

◆ qmlRegisterModuleImport()

void qmlRegisterModuleImport	(	const char *	uri,
		int	moduleMajor,
		const char *	import,
		int	importMajor,
		int	importMinor )

This has the same effect as an import statement in a qmldir file: Whenever uri of version moduleMajor is imported, import of version importMajor. importMinor is automatically imported, too. If importMajor is \l QQmlModuleImportLatest the latest version available of that module is imported, and importMinor does not matter. If importMinor is \l QQmlModuleImportLatest the latest minor version of a importMajor is chosen. If importMajor is \l QQmlModuleImportAuto the version of import is version of uri being imported, and importMinor does not matter. If moduleMajor is \l QQmlModuleImportModuleAny the module import is applied for any major version of uri. For example, you may specify that whenever any version of MyModule is imported, the latest version of MyOtherModule should be imported. Then, the following call would be appropriate:

qmlRegisterModuleImport("MyModule", QQmlModuleImportModuleAny,

"MyOtherModule", QQmlModuleImportLatest);

QQmlEngine::qmlRegisterModuleImport

void qmlRegisterModuleImport(const char *uri, int moduleMajor, const char *import, int importMajor, int importMinor)

Registers a qmldir-import for module uri of major version moduleMajor.

Definition qqml.cpp:338

QQmlModuleImportLatest

@ QQmlModuleImportLatest

Definition qqml.h:649

QQmlModuleImportModuleAny

@ QQmlModuleImportModuleAny

Definition qqml.h:648

Or, you may specify that whenever major version 5 of "MyModule" is imported, then version 3.14 of "MyOtherModule" should be imported:

qmlRegisterModuleImport("MyModule", 5, "MyOtherModule", 3, 14);

Finally, if you always want the same version of "MyOtherModule" to be imported whenever "MyModule" is imported, specify the following:

qmlRegisterModuleImport("MyModule", QQmlModuleImportModuleAny,

"MyOtherModule", QQmlModuleImportAuto);

QQmlModuleImportAuto

@ QQmlModuleImportAuto

Definition qqml.h:650

See also: qmlUnregisterModuleImport()

Definition at line 338 of file qqml.cpp.

◆ qmlUnregisterModuleImport()

void qmlUnregisterModuleImport	(	const char *	uri,
		int	moduleMajor,
		const char *	import,
		int	importMajor,
		int	importMinor )

Calling this function makes sure that import of version {importMajor}.{importMinor} is not automatically imported anymore when uri of version moduleMajor is. The version resolution works the same way as with \l qmlRegisterModuleImport().

See also: qmlRegisterModuleImport()

Definition at line 358 of file qqml.cpp.

Property Documentation

◆ offlineStoragePath

QString QQmlEngine::offlineStoragePath

readwrite

the directory for storing offline user data

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

The SQL databases created with openDatabaseSync() 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().

See also: {Qt Quick Local Storage QML Types}

Definition at line 58 of file qqmlengine.h.

The documentation for this class was generated from the following files:

qtdeclarative/src/qml/qml/qqmlengine.h (59567e25f6d4fbab3f0aecb5f0ff1c1978cce681)
qtdeclarative/src/qml/qml/qqml.cpp (12fb7d27431a7db2a19e1954c85d5dc03264b356)
qtdeclarative/src/qml/qml/qqmlengine.cpp (85253dfa20babec2e56c07ab7e5ba68cc60c3176)
qtdeclarative/src/qml/qml/qqmlincubator.cpp (0bde414de5aa8b74275aa8770529e8facb01ac92)

Public Slots

Signals

Public Member Functions

Static Public Member Functions

Protected Member Functions

Properties

Related Symbols

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ QQmlEngine() [1/2]

◆ ~QQmlEngine()

◆ QQmlEngine() [2/2]

Member Function Documentation

◆ addImageProvider()

◆ addImportPath()

◆ addPluginPath()

◆ addUrlInterceptor()

◆ baseUrl()

◆ captureProperty()

◆ clearComponentCache()

◆ clearSingletons()

◆ contextForObject()

◆ event()

◆ exit

◆ imageProvider()

◆ importPathList()

◆ incubationController()

◆ interceptUrl()

◆ markCurrentFunctionAsTranslationBinding()

◆ offlineStorageDatabaseFilePath()

◆ offlineStoragePath()

◆ offlineStoragePathChanged

◆ outputWarningsToStandardError()

◆ pluginPathList()

◆ quit

◆ removeImageProvider()

◆ removeUrlInterceptor()

◆ retranslate

◆ rootContext()

◆ setBaseUrl()

◆ setContextForObject()

◆ setImportPathList()

◆ setIncubationController()

◆ setOfflineStoragePath()

◆ setOutputWarningsToStandardError()

◆ setPluginPathList()

◆ singletonInstance() [1/8]

◆ singletonInstance() [2/8]

◆ singletonInstance() [3/8]

◆ singletonInstance() [4/8]

◆ singletonInstance() [5/8]

◆ singletonInstance() [6/8]

◆ singletonInstance() [7/8]

◆ singletonInstance() [8/8]

◆ trimComponentCache()

◆ urlInterceptors()

◆ warnings

Friends And Related Symbol Documentation

◆ qmlContext()

◆ qmlEngine()

◆ qmlRegisterModuleImport()

◆ qmlUnregisterModuleImport()

Property Documentation

◆ offlineStoragePath