QQmlEngineExtensionPlugin Class
The QQmlEngineExtensionPlugin class provides an abstract base for custom QML extension plugins. More...
| Header: | #include <QQmlEngineExtensionPlugin> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Qml) target_link_libraries(mytarget PRIVATE Qt6::Qml) |
| qmake: | QT += qml |
| Inherits: | QObject |
- List of all members, including inherited members
- QQmlEngineExtensionPlugin is part of Plugin Classes.
Public Functions
| QQmlEngineExtensionPlugin(QObject *parent = nullptr) |
Reimplemented Public Functions
| virtual void | initializeEngine(QQmlEngine *engine, const char *uri) override |
Macros
(since 6.2) | Q_IMPORT_QML_PLUGIN(PluginName) |
Detailed Description
QQmlEngineExtensionPlugin is a plugin interface that lets you create QML extensions that can be loaded dynamically into QML applications. These extensions allow custom QML types to be made available to the QML engine.
To write a QML extension plugin:
- Subclass QQmlEngineExtensionPlugin and use the Q_PLUGIN_METADATA() macro to register the plugin with the Qt meta object system.
- Use the QML_ELEMENT and QML_NAMED_ELEMENT() macros to declare QML types.
- Configure your build file.
CMake:
qt_add_qml_module(<target> URI <my.import.name> VERSION 1.0 QML_FILES <app.qml> NO_RESOURCE_TARGET_PATH )qmake:
CONFIG += qmltypes QML_IMPORT_NAME = <my.import.name> QML_IMPORT_MAJOR_VERSION = <version>
- If you're using qmake, create a qmldir file to describe the plugin. Note that CMake will, by default, automatically generate the qmldir file.
QML extension plugins are for either application-specific or library-like plugins. Library plugins should limit themselves to registering types, as any manipulation of the engine's root context may cause conflicts or other issues in the library user's code.
Note: When using the CMake qt_add_qml_module API, a plugin will be generated automatically for you. It will take care of type registration. You only need to write a custom plugin if you have special requirements, such as registering custom image providers. In that case, pass NO_GENERATE_PLUGIN_SOURCE to the qt_add_qml_module call to disable the generation of the default plugin.
The linker might erroneously remove the generated type registration function as an optimization. You can prevent that by declaring a synthetic volatile pointer to the function somewhere in your code. If your module is called "my.module", you would add the forward declaration in global scope:
void qml_register_types_my_module();
Then add the following snippet of code in the implementation of any function that's part of the same binary as the registration:
volatile auto registration = &qml_register_types_my_module; Q_UNUSED(registration);
The Writing QML Extensions with C++ tutorial also contains a chapter on creating QML plugins.
See also QQmlEngine::importPlugin() and How to Create Qt Plugins.
Member Function Documentation
[explicit] QQmlEngineExtensionPlugin::QQmlEngineExtensionPlugin(QObject *parent = nullptr)
Constructs a QML extension plugin with the given parent.
Note that this constructor is invoked automatically by the Q_PLUGIN_METADATA() macro, so there is no need for calling it explicitly.
[override virtual] void QQmlEngineExtensionPlugin::initializeEngine(QQmlEngine *engine, const char *uri)
Initializes the extension from the uri using the engine. Here an application plugin might, for example, expose some data or objects to QML, as context properties on the engine's root context.
Macro Documentation
[since 6.2] Q_IMPORT_QML_PLUGIN(PluginName)
Ensures the plugin whose metadata-declaring plugin extension class is named PluginName is linked into static builds. For the modules created using qt_add_qml_module, the default plugin extension class name is computed from the QML module URI by replacing dots with underscores, unless the CLASS_NAME argument is specified.
For example:
qt_add_qml_module(myplugin
# The plugin extension class name in this case is my_Company_QmlComponents.
URI my.Company.QmlComponents
...
)
This macro was introduced in Qt 6.2.
See also Q_IMPORT_PLUGIN.