Класс 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 предназначены для плагинов, специфичных для приложения, или для плагинов типа библиотек. Плагины библиотек должны ограничивать себя регистрацией типов, поскольку любое изменение корневого контекста движка может вызвать конфликты или другие проблемы в коде пользователя библиотеки.

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

void qml_register_types_my_module();
\code

Then add the following snippet of code in the implementation of any function
that's part of the same binary as the registration:

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

\section1 TimeExample QML extension plugin

Suppose there is a new \c TimeModel C++ class that should be made available
as a new QML type. It provides the current time through \c hour and \c minute
properties. It declares a QML type called \c Time via \l QML_NAMED_ELEMENT().

\snippet qmlextensionplugins/timemodel.h 0
\dots

To make this type available, we create a plugin class named \c QExampleQmlPlugin
which is a subclass of \l QQmlEngineExtensionPlugin. It uses the
Q_PLUGIN_METADATA() macro in the class definition to register the plugin with the
Qt meta object system using a unique identifier for the plugin.

\snippet qmlextensionplugins/plugin.cpp plugin

\section1 Project settings for the plugin

Additionally, the project file (\c .pro) defines the project as a plugin library,
specifies it should be built into the \c imports/TimeExample directory, and registers
the plugin target name and various other details:

\code
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

Наконец, в каталоге imports/TimeExample требуется файл qmldir для описания плагина и типов, которые он экспортирует. Плагин включает файл 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 в качестве свойств контекста в корневом контексте движка.