Класс QQmlEngineExtensionPlugin

Класс QQmlEngineExtensionPlugin предоставляет абстрактную базу для пользовательских плагинов расширения QML. Подробнее...

• Список всех членов, включая унаследованные

Открытые функции

Переопределенные открытые функции

Подробное описание

QQmlEngineExtensionPlugin — это интерфейс плагина, который позволяет создавать расширения QML, которые можно динамически загружать в приложения QML. Эти расширения позволяют предоставлять типы пользовательского QML движку QML.

Для написания плагина расширения QML:

1. Подклассируйте QQmlEngineExtensionPlugin и используйте макрос Q_PLUGIN_METADATA(), чтобы зарегистрировать плагин в системе метаобъектов Qt.
2. Используйте макросы QML_ELEMENT и QML_NAMED_ELEMENT(), чтобы объявить типы QML.
3. Напишите файл проекта для плагина. Добавьте:
   • CONFIG += qmltypes для указания системе сборки, чтобы сгенерировать типы QML.
   • QML_IMPORT_NAME = <my.import.name> для указания имени импорта.
   • QML_IMPORT_MAJOR_VERSION = <version> для указания главной версии импорта.
4. Создайте файл qmldir, чтобы описать плагин.

Плагины расширения QML предназначены для плагинов, специфичных для приложения или похожих на библиотеки. Плагины библиотек должны ограничиваться регистрацией типов, так как любое изменение корневого контекста движка может вызвать конфликты или другие проблемы в коде пользователя библиотеки.

Компилятор может ошибочно удалить сгенерированную функцию регистрации типов как оптимизацию. Вы можете предотвратить это, объявив синтетический указатель на функцию volatile где-то в вашем коде. Если ваш модуль называется "my.module", вы добавите объявление вперед в глобальном пространстве имен:

void qml_register_types_my_module();

Затем добавьте следующий фрагмент кода в реализацию любой функции, которая является частью того же двоичного файла, что и регистрация:

volatile auto registration = &qml_register_types_my_module;
Q_UNUSED(registration);

Плагин расширения QML TimeExample

Предположим, есть новый TimeModel класс C++, который должен быть доступен как новый тип QML. Он предоставляет текущее время через hour и minute свойства. Он объявляет тип QML Time через QML_NAMED_ELEMENT().

class TimeModel : public QObject
{
    Q_OBJECT
    Q_PROPERTY(int hour READ hour NOTIFY timeChanged)
    Q_PROPERTY(int minute READ minute NOTIFY timeChanged)
    QML_NAMED_ELEMENT(Time)
    ...

Для того, чтобы сделать этот тип доступным, мы создаем класс плагина QExampleQmlPlugin, который является подклассом QQmlEngineExtensionPlugin. Он использует макрос Q_PLUGIN_METADATA() в определении класса, чтобы зарегистрировать плагин в системе метаобъектов Qt с уникальным идентификатором для плагина.

class QExampleQmlPlugin : public QQmlEngineExtensionPlugin
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID QQmlEngineExtensionInterface_iid)
};

Настройки проекта для плагина

Кроме того, файл проекта (.pro) определяет проект как библиотеку плагинов, указывает, что он должен быть скомпилирован в директорию imports/TimeExample, и регистрирует имя целевого плагина и различные другие детали:

TEMPLATE = lib
CONFIG += qt plugin qmltypes
QT += qml

QML_IMPORT_NAME = TimeExample
QML_IMPORT_MAJOR_VERSION = 1

DESTDIR = imports/$$QML_IMPORT_NAME
TARGET  = qmlqtimeexampleplugin

SOURCES += qexampleqmlplugin.cpp

Это регистрирует класс TimeModel с импортом TimeExample 1.0, как тип QML Time. Статья Определение типов QML из C++ содержит дополнительную информацию о регистрации типов C++ для использования в QML.

Определение плагина в qmldir

Наконец, требуется файл qmldir в директории imports/TimeExample для описания плагина и экспортируемых типов. Плагин включает в себя файл Clock.qml вместе с файлом qmlqtimeexampleplugin, который создаётся проектом (как показано выше в файле .pro). Поэтому оба файла должны быть указаны в файле qmldir.

module TimeExample
Clock 1.0 Clock.qml
plugin qmlqtimeexampleplugin

Для упрощения этого примера, директория исходного кода TimeExample находится в imports/TimeExample, и мы производим сборку в исходном коде. Однако структура директории исходного кода не так важна, так как файл qmldir может указывать пути к установленным файлам QML.

Важно имя директории, в которую устанавливается qmldir. Когда пользователь импортирует наш модуль, движок QML использует идентификатор модуля (TimeExample) для поиска плагина, и поэтому директория, в которой он установлен, должна соответствовать идентификатору модуля.

После сборки и установки проекта новый компонент Time доступен для любого компонента QML, импортирующего модуль TimeExample.

import TimeExample 1.0 // import types from the plugin

Clock { // this class is defined in QML (imports/TimeExample/Clock.qml)

    Time { // this class is defined in C++ (plugin.cpp)
        id: time
    }

    hours: time.hour
    minutes: time.minute

}

Полный исходный код доступен в примере плагинов.

В руководстве Создание расширений QML с помощью C++ также есть глава по созданию плагинов QML.

См. также QQmlEngine::importPlugin() и Как создать плагины Qt.

Документация по членам функций

QQmlEngineExtensionPlugin::QQmlEngineExtensionPlugin(QObject *parent = nullptr)

Конструирует плагин расширения QML с заданным parent.

Обратите внимание, что этот конструктор вызывается автоматически макросом Q_PLUGIN_METADATA(), поэтому нет необходимости вызывать его явно.

[override virtual] void QQmlEngineExtensionPlugin::initializeEngine(QQmlEngine *engine, const char *uri)

Инициализирует расширение из uri с использованием engine. Здесь плагин приложения может, например, экспортировать некоторые данные или объекты в QML в качестве свойств контекста в корневом контексте движка.