Functions¶

qjsEngine(object)¶

Parameters:: object – QObject
Return type:: QJSEngine

Returns the QJSEngine associated with object, if any.

This function is useful if you have exposed a QObject to the JavaScript environment and later in your program would like to regain access. It does not require you to keep the wrapper around that was returned from newQObject() .

qmlClearTypeRegistrations()¶

Clears all stored type registrations, such as those produced with qmlRegisterType() .

Do not call this function while a QQmlEngine exists or behavior will be undefined. Any existing QQmlEngines must be deleted before calling this function. This function only affects the application global cache. Delete the QQmlEngine to clear all cached data relating to that engine.

qmlContext(arg__1)¶

Parameters:: arg__1 – QObject
Return type:: QQmlContext

qmlEngine(arg__1)¶

Parameters:: arg__1 – QObject
Return type:: QQmlEngine

qmlProtectModule(uri, majVersion)¶

Parameters:

uri – str
majVersion – int

Return type:

bool

This function protects a module from further modification. This can be used to prevent other plugins from injecting types into your module. It can also be a performance improvement, as it allows the engine to skip checking for the possibility of new types or plugins when this import is reached.

Once qmlProtectModule has been called, a QML engine will not search for a new qmldir file to load the module anymore. It will re-use any qmldir files it has loaded before, though. Therefore, types present at this point continue to work. Mind that different QML engines may load different modules. The module protection, however, is global and affects all engines. The overhead of locating qmldir files and loading plugins may be noticeable with slow file systems. Therefore, protecting a module once you are sure you won’t need to load it anymore can be a good optimization. Mind also that the module lock not only affects plugins but also any other qmldir directives, like import or prefer, as well as any composite types or scripts declared in a qmldir file.

In addition, after this function is called, any attempt to register C++ types into this uri, major version combination will lead to a runtime error.

Returns true if the module with uri as a module identifier and majVersion as a major version number was found and locked, otherwise returns false. The module must contain exported types in order to be found.

qmlRegisterModule(uri, versionMajor, versionMinor)¶

Parameters:

uri – str
versionMajor – int
versionMinor – int

This function registers a module in a particular uri with a version specified in versionMajor and versionMinor.

This can be used to make a certain module version available, even if no types are registered for that version. This is particularly useful for keeping the versions of related modules in sync.

qmlRegisterSingletonType(url, uri, versionMajor, versionMinor, qmlName)¶

Parameters:

url – QUrl
uri – str
versionMajor – int
versionMinor – int
qmlName – str

Return type:

int

This function may be used to register a singleton type with the name qmlName, in the library imported from uri having the version number composed from versionMajor and versionMinor. The type is defined by the QML file located at url. The url must be an absolute URL, i.e. url.isRelative() == false.

In addition the type’s QML file must have pragma Singleton statement among its import statements.

A singleton type may be referenced via the type name with which it was registered, and this typename may be used as the target in a Connections type or otherwise used as any other type id would. One exception to this is that a singleton type property may not be aliased (because the singleton type name does not identify an object within the same component as any other item).

Usage:

// Second, register the QML singleton type by calling this function in an initialization function.
qmlRegisterSingletonType(QUrl("file:///absolute/path/SingletonType.qml"), "Qt.example.qobjectSingleton", 1, 0, "RegisteredSingleton");

In order to use the registered singleton type in QML, you must import the singleton type.

It is also possible to have QML singleton types registered without using the qmlRegisterSingletonType function. That can be done by adding a pragma Singleton statement among the imports of the type’s QML file. In addition the type must be defined in a qmldir file with a singleton keyword and the qmldir must be imported by the QML files using the singleton.

See also

QML_SINGLETON()

qmlRegisterType(url, uri, versionMajor, versionMinor, qmlName)¶

Parameters:

url – QUrl
uri – str
versionMajor – int
versionMinor – int
qmlName – str

Return type:

int

This function registers a type in the QML system with the name qmlName, in the library imported from uri having the version number composed from versionMajor and versionMinor. The type is defined by the QML file located at url. The url must be an absolute URL, i.e. url.isRelative() == false.

Normally QML files can be loaded as types directly from other QML files, or using a qmldir file. This function allows registration of files to types from C++ code, such as when the type mapping needs to be procedurally determined at startup.

Returns -1 if the registration was not successful.

qmlRegisterUncreatableMetaObject(staticMetaObject, uri, versionMajor, versionMinor, qmlName, reason)¶

Parameters:

staticMetaObject – QMetaObject
uri – str
versionMajor – int
versionMinor – int
qmlName – str
reason – str

Return type:

int

This function registers the staticMetaObject and its extension in the QML system with the name qmlName in the library imported from uri having version number composed from versionMajor and versionMinor.

An instance of the meta object cannot be created. An error message with the given reason is printed if the user attempts to create it.

This function is useful for registering Q_NAMESPACE namespaces.

Returns the QML type id.

For example:

namespace MyNamespace {
  Q_NAMESPACE
  enum MyEnum {
      Key1,
      Key2,
  };
  Q_ENUM_NS(MyEnum)
}

//...
qmlRegisterUncreatableMetaObject(MyNamespace::staticMetaObject, "io.qt", 1, 0, "MyNamespace", "Access to enums & flags only");

On the QML side, you can now use the registered enums:

Component.onCompleted: console.log(MyNamespace.Key2)
See also

QML_ELEMENT() QML_NAMED_ELEMENT() QML_UNCREATABLE()

qmlTypeId(uri, versionMajor, versionMinor, qmlName)¶

Parameters:

uri – str
versionMajor – int
versionMinor – int
qmlName – str

Return type:

int

Returns the QML type id of a type that was registered with the name qmlName in a particular uri and a version specified in versionMajor and versionMinor.

This function returns the same value as the QML type registration functions such as qmlRegisterType() and qmlRegisterSingletonType() .

If qmlName, uri and versionMajor match a registered type, but the specified minor version in versionMinor is higher, then the id of the type with the closest minor version is returned.

Returns -1 if no matching type was found or one of the given parameters was invalid.

Note

: qmlTypeId tries to make modules available, even if they were not accessed by any engine yet. This can introduce overhead the first time a module is accessed. Trying to find types from a module which does not exist always introduces this overhead.

See also

QML_ELEMENT() QML_NAMED_ELEMENT() QML_SINGLETON() qmlRegisterType() qmlRegisterSingletonType()

qmlAttachedPropertiesObject(type_obj, arg__2[, arg__3=true])¶

Parameters:

type_obj – PyTypeObject
arg__2 – QObject
arg__3 – bool

Return type:

QObject

qmlRegisterType(pytype: type, uri: str, versionMajor: int, versionMinor: int, qmlName: str) → int¶

Parameters:

pytype (type) – Python class
uri (str) – uri to use while importing the component in QML
versionMajor (int) – major version
versionMinor (int) – minor version
qmlName (str) – name exposed to QML

Returns:

int (the QML type id)

This function registers the Python type in the QML system with the name qmlName, in the library imported from uri having the version number composed from versionMajor and versionMinor. For example, this registers a Python class ‘MySliderItem’ as a QML type named ‘Slider’ for version ‘1.0’ of a module called ‘com.mycompany.qmlcomponents’:

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.0

Slider { ... }

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.

qmlRegisterSingletonType(pytype: type, uri: str, versionMajor: int, versionMinor: int, typeName: str, callback: object) → int¶

Parameters:

pytype (type) – Python class
uri (str) – uri to use while importing the component in QML
versionMajor (int) – major version
versionMinor (int) – minor version
typeName (str) – name exposed to QML
callback (object) – Python callable (to handle Python type)

Returns:

int (the QML type id)

This function registers a Python type as a singleton in the QML system using the provided callback (which gets a QQmlEngine as a parameter) to generate the singleton.

qmlRegisterSingletonType(pytype: type, uri: str, versionMajor: int, versionMinor: int, typeName: str) → int¶

Parameters:

pytype (type) – Python class
uri (str) – uri to use while importing the component in QML
versionMajor (int) – major version
versionMinor (int) – minor version
typeName (str) – name exposed to QML

Returns:

int (the QML type id)

This function registers a Python type as a singleton in the QML system.

Alternatively, the QmlSingleton decorator can be used.

qmlRegisterSingletonType(uri: str, versionMajor: int, versionMinor: int, typeName: str, callback: object) → int¶

Parameters:

uri (str) – uri to use while importing the component in QML
versionMajor (int) – major version
versionMinor (int) – minor version
typeName (str) – name exposed to QML
callback (object) – Python callable (to handle QJSValue)

Returns:

int (the QML type id)

This function registers a QJSValue as a singleton in the QML system using the provided callback (which gets a QQmlEngine as a parameter) to generate the singleton.

qmlRegisterSingletonInstance(pytype: type, uri: str, versionMajor: int, versionMinor: int, typeName: str, instanceObject: object) → int¶

Parameters:

pytype (type) – Python class
uri (str) – uri to use while importing the component in QML
versionMajor (int) – major version
versionMinor (int) – minor version
typeName (str) – name exposed to QML
instanceObject (object) – singleton object to be registered

Returns:

int (the QML type id)

This function registers a singleton Python object instanceObject, with a particular uri and typeName. Its version is a combination of versionMajor and versionMinor. Use this function to register an object of the given type pytype as a singleton type.

qmlRegisterUncreatableType(pytype: type, uri: str, versionMajor: int, versionMinor: int, qmlName: str, noCreationReason: str) → int¶

Parameters:

pytype (type) – Python class
uri (str) – uri to use while importing the component in QML
versionMajor (int) – major version
versionMinor (int) – minor version
qmlName (str) – name exposed to QML
noCreationReason (str) – Error message shown when trying to create the QML type

Returns:

int (the QML type id)

This function registers the Python type in the QML system as an uncreatable type with the name qmlName, in the library imported from uri having the version number composed from versionMajor and versionMinor, showing noCreationReason as an error message when creating the type is attempted. For example, this registers a Python class ‘MySliderItem’ as a QML type named ‘Slider’ for version ‘1.0’ of a module called ‘com.mycompany.qmlcomponents’:

::
qmlRegisterUncreatableType(MySliderItem, “com.mycompany.qmlcomponents”, 1, 0, “Slider”, “Slider cannot be created.”)

Alternatively, the QmlUncreatable decorator can be used.

Enumerations¶

class QML_HAS_ATTACHED_PROPERTIES¶

class QQmlModuleImportSpecialVersions¶

Defines some special values that can be passed to the version arguments of qmlRegisterModuleImport() and qmlUnregisterModuleImport() .

Constant

Description

QQmlEngine.QQmlModuleImportModuleAny

When passed as majorVersion of the base module, signifies that the import is to be applied to any version of the module.

QQmlEngine.QQmlModuleImportLatest

When passed as major or minor version of the imported module, signifies that the latest overall, or latest minor version of a specified major version shall be imported.

QQmlEngine.QQmlModuleImportAuto

When passed as major version of the imported module, signifies that the version of the base module shall be forwarded.

Constant	Description
QQmlEngine.QQmlModuleImportModuleAny	When passed as majorVersion of the base module, signifies that the import is to be applied to any version of the module.
QQmlEngine.QQmlModuleImportLatest	When passed as major or minor version of the imported module, signifies that the latest overall, or latest minor version of a specified major version shall be imported.
QQmlEngine.QQmlModuleImportAuto	When passed as major version of the imported module, signifies that the version of the base module shall be forwarded.