QQmlEngine¶
The
QQmlEngine
class provides an environment for instantiating QML components. More…
Inherited by: QQmlApplicationEngine
Synopsis¶
Functions¶
def
addImageProvider
(id, arg__2)def
addImportPath
(dir)def
addNamedBundle
(name, fileName)def
addPluginPath
(dir)def
baseUrl
()def
clearComponentCache
()def
imageProvider
(id)def
importPathList
()def
importPlugin
(filePath, uri, errors)def
incubationController
()def
networkAccessManager
()def
networkAccessManagerFactory
()def
offlineStorageDatabaseFilePath
(databaseName)def
offlineStoragePath
()def
pluginPathList
()def
removeImageProvider
(id)def
rootContext
()def
setBaseUrl
(arg__1)def
setImportPathList
(paths)def
setIncubationController
(arg__1)def
setNetworkAccessManagerFactory
(arg__1)def
setOfflineStoragePath
(dir)def
setOutputWarningsToStandardError
(arg__1)def
setPluginPathList
(paths)def
setUrlInterceptor
(urlInterceptor)def
trimComponentCache
()def
urlInterceptor
()
Slots¶
def
retranslate
()
Signals¶
Static functions¶
def
contextForObject
(arg__1)def
objectOwnership
(arg__1)def
setContextForObject
(arg__1, arg__2)def
setObjectOwnership
(arg__1, arg__2)
Detailed Description¶
Each QML component is instantiated in a
QQmlContext
.QQmlContext
‘s are essential for passing data to QML components. In QML, contexts are arranged hierarchically and this hierarchy is managed by theQQmlEngine
.Prior to creating any QML components, an application must have created a
QQmlEngine
to gain access to a QML context. The following example shows how to create a simple Text item.QQmlEngine engine; QQmlComponent component(&engine); component.setData("import QtQuick 2.0\nText { text: \"Hello world!\" }", QUrl()); QQuickItem *item = qobject_cast<QQuickItem *>(component.create()); //add item to view, etc ...In this case, the Text item will be created in the engine’s
root context
.See also
QQmlComponent
QQmlContext
QML Global Object
- class PySide2.QtQml.QQmlEngine([p=None])¶
- param p:
Create a new
QQmlEngine
with the givenparent
.
- PySide2.QtQml.QQmlEngine.ObjectOwnership¶
controls whether or not QML automatically destroys the
QObject
when the corresponding JavaScript object is garbage collected by the engine. The two ownership options are:Constant
Description
QQmlEngine.CppOwnership
The object is owned by C++ code and QML will never delete it. The JavaScript destroy() method cannot be used on these objects. This option is similar to QScriptEngine::QtOwnership.
QQmlEngine.JavaScriptOwnership
The object is owned by JavaScript. When the object is returned to QML as the return value of a method call, QML will track it and delete it if there are no remaining JavaScript references to it and it has no
parent()
. An object tracked by oneQQmlEngine
will be deleted during thatQQmlEngine
‘s destructor. Thus, JavaScript references between objects with from two different engines will not be valid if one of these engines is deleted. 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 ownership. By default, an object that is created by QML has . The exception to this are the root objects created by calling
create()
orbeginCreate()
, which have 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 by default. The exception to this are objects returned from C++ method calls; their ownership will be set to . This applies only to explicit invocations of
Q_INVOKABLE
methods or slots, but not to property getter invocations.Calling
setObjectOwnership()
overrides the default ownership heuristic used by QML.
- PySide2.QtQml.QQmlEngine.addImageProvider(id, arg__2)¶
- Parameters:
id – str
arg__2 –
PySide2.QtQml.QQmlImageProviderBase
Sets the
provider
to use for images requested via the image : url scheme, with hostproviderId
. TheQQmlEngine
takes ownership ofprovider
.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
- PySide2.QtQml.QQmlEngine.addImportPath(dir)¶
- Parameters:
dir – str
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 Qt Resource path (:/imports
), a 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 theimportPathList()
.See also
setImportPathList()
QML Modules
- PySide2.QtQml.QQmlEngine.addNamedBundle(name, fileName)¶
- Parameters:
name – str
fileName – str
- Return type:
bool
- PySide2.QtQml.QQmlEngine.addPluginPath(dir)¶
- Parameters:
dir – str
Adds
path
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 added
path
will be first in thepluginPathList()
.See also
- PySide2.QtQml.QQmlEngine.baseUrl()¶
- Return type:
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
- PySide2.QtQml.QQmlEngine.clearComponentCache()¶
Clears the engine’s internal component cache.
This function causes the property metadata of all components previously loaded by the engine to be destroyed. All previously loaded components and the property bindings for all extant objects created from those components will cease to function.
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
- static PySide2.QtQml.QQmlEngine.contextForObject(arg__1)¶
- Parameters:
arg__1 –
PySide2.QtCore.QObject
- Return type:
Returns the
QQmlContext
for theobject
, or 0 if no context has been set.When the
QQmlEngine
instantiates aQObject
, the context is set automatically.See also
setContextForObject()
qmlContext()
qmlEngine()
- PySide2.QtQml.QQmlEngine.exit(retCode)¶
- Parameters:
retCode – int
- PySide2.QtQml.QQmlEngine.imageProvider(id)¶
- Parameters:
id – str
- Return type:
Returns the image provider set for
providerId
if found; otherwise returnsNone
.See also
QQuickImageProvider
- PySide2.QtQml.QQmlEngine.importPathList()¶
- Return type:
list of strings
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 theQQmlEngine
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 QML extensions plugins.By default, the list contains the directory of the application executable, paths specified in the
QML2_IMPORT_PATH
environment variable, and the builtinQml2ImportsPath
fromQLibraryInfo
.See also
- PySide2.QtQml.QQmlEngine.importPlugin(filePath, uri, errors)¶
- Parameters:
filePath – str
uri – str
errors –
QList
- Return type:
bool
Imports the plugin named
filePath
with theuri
provided. Returns true if the plugin was successfully imported; otherwise returns false.On failure and if non-null, the
errors
list will have any errors which occurred prepended to it.The plugin has to be a Qt plugin which implements the
QQmlEngineExtensionPlugin
interface.
- PySide2.QtQml.QQmlEngine.incubationController()¶
- Return type:
Returns the currently set incubation controller, or 0 if no controller has been set.
See also
- PySide2.QtQml.QQmlEngine.networkAccessManager()¶
- Return type:
Returns a common
QNetworkAccessManager
which can be used by any QML type instantiated by this engine.If a
QQmlNetworkAccessManagerFactory
has been set and aQNetworkAccessManager
has not yet been created, theQQmlNetworkAccessManagerFactory
will be used to create theQNetworkAccessManager
; otherwise the returnedQNetworkAccessManager
will have no proxy or cache set.See also
- PySide2.QtQml.QQmlEngine.networkAccessManagerFactory()¶
- Return type:
Returns the current
QQmlNetworkAccessManagerFactory
.See also
- static PySide2.QtQml.QQmlEngine.objectOwnership(arg__1)¶
- Parameters:
arg__1 –
PySide2.QtCore.QObject
- Return type:
Returns the ownership of
object
.See also
- PySide2.QtQml.QQmlEngine.offlineStorageDatabaseFilePath(databaseName)¶
- Parameters:
databaseName – str
- Return type:
str
Returns the file path where a Local Storage database with the identifier
databaseName
is (or would be) located.See also
LocalStorage.openDatabaseSync()
- PySide2.QtQml.QQmlEngine.offlineStoragePath()¶
- Return type:
str
This property holds the directory for storing offline user data.
Returns the directory where SQL and other offline storage is placed.
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
mkpath()
.
- PySide2.QtQml.QQmlEngine.outputWarningsToStandardError()¶
- Return type:
bool
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
- PySide2.QtQml.QQmlEngine.pluginPathList()¶
- Return type:
list of strings
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 theqmldir
file itself.See also
- PySide2.QtQml.QQmlEngine.quit()¶
- PySide2.QtQml.QQmlEngine.removeImageProvider(id)¶
- Parameters:
id – str
Removes the image provider for
providerId
.See also
addImageProvider()
QQuickImageProvider
- PySide2.QtQml.QQmlEngine.retranslate()¶
Refreshes all binding expressions that use strings marked for translation.
Call this function after you have installed a new translator with
installTranslator
, to ensure that your user-interface shows up-to-date translations.Note
Due to a limitation in the implementation, this function refreshes all the engine’s bindings, not only those that use strings marked for translation. This may be optimized in a future release.
- PySide2.QtQml.QQmlEngine.rootContext()¶
- Return type:
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.
- PySide2.QtQml.QQmlEngine.setBaseUrl(arg__1)¶
- Parameters:
arg__1 –
PySide2.QtCore.QUrl
Set the base URL for this engine to
url
.See also
- static PySide2.QtQml.QQmlEngine.setContextForObject(arg__1, arg__2)¶
- Parameters:
arg__1 –
PySide2.QtCore.QObject
arg__2 –
PySide2.QtQml.QQmlContext
Sets the
QQmlContext
for theobject
tocontext
. If theobject
already has a context, a warning is output, but the context is not changed.When the
QQmlEngine
instantiates aQObject
, the context is set automatically.See also
- PySide2.QtQml.QQmlEngine.setImportPathList(paths)¶
- Parameters:
paths – list of strings
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
QML2_IMPORT_PATH
environment variable, and the builtinQml2ImportsPath
fromQLibraryInfo
.See also
- PySide2.QtQml.QQmlEngine.setIncubationController(arg__1)¶
- Parameters:
Sets the engine’s incubation
controller
. The engine can only have one active controller and it does not take ownership of it.See also
- PySide2.QtQml.QQmlEngine.setNetworkAccessManagerFactory(arg__1)¶
- Parameters:
Sets the
factory
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.
Note
QQmlEngine
does not take ownership of the factory.See also
- static PySide2.QtQml.QQmlEngine.setObjectOwnership(arg__1, arg__2)¶
- Parameters:
arg__1 –
PySide2.QtCore.QObject
arg__2 –
ObjectOwnership
Sets the
ownership
ofobject
.See also
- PySide2.QtQml.QQmlEngine.setOfflineStoragePath(dir)¶
- Parameters:
dir – str
This property holds the directory for storing offline user data.
Returns the directory where SQL and other offline storage is placed.
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
mkpath()
.
- PySide2.QtQml.QQmlEngine.setOutputWarningsToStandardError(arg__1)¶
- Parameters:
arg__1 – bool
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 thewarnings()
signal. Ifenabled
is false, only thewarnings()
signal will be emitted. This allows applications to handle warning output themselves.The default value is true.
See also
- PySide2.QtQml.QQmlEngine.setPluginPathList(paths)¶
- Parameters:
paths – list of strings
Sets the list of directories where the engine searches for native plugins for imported modules (referenced in the
qmldir
file) topaths
.By default, the list contains only
.
, i.e. the engine searches in the directory of theqmldir
file itself.See also
- PySide2.QtQml.QQmlEngine.setUrlInterceptor(urlInterceptor)¶
- Parameters:
urlInterceptor –
PySide2.QtQml.QQmlAbstractUrlInterceptor
This API is private for 5.1
Sets the
urlInterceptor
to be used when resolving URLs in QML. This also applies to URLs used for loading script files and QML types. This should not be modifed while the engine is loading files, or URL selection may be inconsistent.
- PySide2.QtQml.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
- PySide2.QtQml.QQmlEngine.urlInterceptor()¶
- Return type:
This API is private for 5.1
Returns the current
QQmlAbstractUrlInterceptor
. It must not be modified outside the GUI thread.
- PySide2.QtQml.QQmlEngine.warnings(warnings)¶
- Parameters:
warnings –
© 2022 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.