Класс QQmlComponent

Класс QQmlComponent инкапсулирует определение компонента QML. Подробнее...

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

Открытые типы

Свойства

• progress : const qreal
• status : const Status
• url : const QUrl

• 1 свойство унаследовано от QObject

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

• 31 открытая функция унаследована от QObject

Открытые слоты

• 1 открытый слот унаследован от QObject

Сигналы

• 2 сигнала унаследованы от QObject

Статические открытые члены

• 9 статических открытых членов унаследованы от QObject

Дополнительные унаследованные члены

• 9 защищенные функции унаследованы от QObject

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

Класс QQmlComponent инкапсулирует определение компонента QML.

Компоненты — это многократно используемые, инкапсулированные типы QML с хорошо определёнными интерфейсами.

Экземпляр QQmlComponent может быть создан из файла QML. Например, если есть main.qml файл следующего вида:

import QtQuick 2.0

Item {
    width: 200
    height: 200
}

Следующий код загружает этот файл QML в качестве компонента, создаёт экземпляр этого компонента с помощью create(), а затем запрашивает значение свойства width элемента Item:

QQmlEngine *engine = new QQmlEngine;
QQmlComponent component(engine, QUrl::fromLocalFile("main.qml"));

QObject *myObject = component.create();
QQuickItem *item = qobject_cast<QQuickItem*>(myObject);
int width = item->width();  // width = 200

Чтобы создать экземпляры компонента в коде, где экземпляр QQmlEngine недоступен, можно использовать qmlContext() или qmlEngine(). Например, в сценарии ниже дочерние элементы создаются внутри подкласса QQuickItem:

void MyCppItem::init()
{
    QQmlEngine *engine = qmlEngine(this);
    // Or:
    // QQmlEngine *engine = qmlContext(this)->engine();
    QQmlComponent component(engine, QUrl::fromLocalFile("MyItem.qml"));
    QQuickItem *childItem = qobject_cast<QQuickItem*>(component.create());
    childItem->setParentItem(this);
}

Обратите внимание, что эти функции вернут null при вызове внутри конструктора подкласса QObject, так как экземпляру ещё не будет доступен контекст или движок.

Компоненты сети

Если URL, переданный QQmlComponent, является сетевым ресурсом или если документ QML ссылается на сетевой ресурс, QQmlComponent должен извлечь сетевые данные, прежде чем сможет создать объекты. В этом случае у QQmlComponent будет статус Loading status. Приложение должно подождать, пока компонент не станет Ready, прежде чем вызывать QQmlComponent::create().

Следующий пример показывает, как загрузить файл QML из сетевого ресурса. После создания QQmlComponent проверяется, загружается ли компонент. Если да, то подключается к сигналу QQmlComponent::statusChanged(), в противном случае непосредственно вызывается метод continueLoading(). Обратите внимание, что QQmlComponent::isLoading() может быть false для сетевого компонента, если компонент кэширован и сразу готов.

MyApplication::MyApplication()
{
    // ...
    component = new QQmlComponent(engine, QUrl("http://www.example.com/main.qml"));
    if (component->isLoading())
        QObject::connect(component, SIGNAL(statusChanged(QQmlComponent::Status)),
                         this, SLOT(continueLoading()));
    else
        continueLoading();
}

void MyApplication::continueLoading()
{
    if (component->isError()) {
        qWarning() << component->errors();
    } else {
        QObject *myObject = component->create();
    }
}

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

перечисление QQmlComponent::CompilationMode

Указывает, должен ли QQmlComponent загрузить компонент немедленно или асинхронно.

перечисление QQmlComponent::Status

Определяет состояние загрузки компонента QQmlComponent.

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

QQmlComponent::QQmlComponent(QQmlEngine *engine, QObject *parent = nullptr)

Создаёт компонент QQmlComponent без данных и задаёт указанный engine и parent. Установите данные с помощью setData().

QQmlComponent::QQmlComponent(QQmlEngine *engine, const QString &fileName, QObject *parent = nullptr)

Создаёт компонент QQmlComponent из заданного fileName и задаёт указанные parent и engine.

См. также loadUrl().

QQmlComponent::QQmlComponent(QQmlEngine *engine, const QString &fileName, QQmlComponent::CompilationMode mode, QObject *parent = nullptr)

Создаёт компонент QQmlComponent из заданного fileName и задаёт указанные parent и engine. Если mode равен Asynchronous, компонент будет загружен и скомпилирован асинхронно.

См. также loadUrl().

QQmlComponent::QQmlComponent(QQmlEngine *engine, const QUrl &url, QObject *parent = nullptr)

Создаёт компонент QQmlComponent из заданного url и задаёт указанные parent и engine.

Убедитесь, что предоставленный URL полный и корректный, в частности, используйте QUrl::fromLocalFile(), при загрузке файла из локальной файловой системы.

Относительные пути будут разрешены относительно QQmlEngine::baseUrl(), который по умолчанию является текущей рабочей директорией.

См. также loadUrl().

QQmlComponent::QQmlComponent(QQmlEngine *engine, const QUrl &url, QQmlComponent::CompilationMode mode, QObject *parent = nullptr)

Создаёт компонент QQmlComponent из заданного url и задаёт указанные parent и engine. Если mode равен Asynchronous, компонент будет загружен и скомпилирован асинхронно.

Убедитесь, что предоставленный URL полный и корректный, в частности, используйте QUrl::fromLocalFile(), при загрузке файла из локальной файловой системы.

Относительные пути будут разрешены относительно QQmlEngine::baseUrl(), который по умолчанию является текущей рабочей директорией.

См. также loadUrl().

[override virtual] QQmlComponent::~QQmlComponent()

Деструктор компонента QQmlComponent.

[virtual] QObject *QQmlComponent::beginCreate(QQmlContext *publicContext)

Этот метод предоставляет расширенный контроль над созданием экземпляров компонентов. В общем случае программисты должны использовать QQmlComponent::create() для создания экземпляров объектов.

Создаёт экземпляр объекта из этого компонента. Возвращает nullptr в случае неудачи. publicContext задаёт контекст, в котором нужно создать экземпляр объекта.

При создании экземпляра компонентом QQmlComponent, происходит в три этапа:

1. Создаётся иерархия объектов, и присваиваются постоянные значения.
2. Впервые оцениваются привязки свойств.
3. Применимо, вызывается QQmlParserStatus::componentComplete() для объектов.

QQmlComponent::beginCreate() отличается от QQmlComponent::create() тем, что выполняет только этап 1. QQmlComponent::completeCreate() необходимо вызвать для завершения этапов 2 и 3.

Эта точка разрыва иногда полезна при использовании прикреплённых свойств для передачи информации создаваемому компоненту, так как она позволяет настроить их начальные значения до того, как привязки свойств вступят в силу.

Владение возвращаемым экземпляром объекта передаётся вызывающей стороне.

См. также completeCreate() и QQmlEngine::ObjectOwnership.

[virtual] void QQmlComponent::completeCreate()

Этот метод предоставляет расширенный контроль над созданием экземпляров компонентов. В общем случае программисты должны использовать QQmlComponent::create() для создания компонента.

Эта функция завершает создание компонента, начатого с QQmlComponent::beginCreate(), и должна вызываться после неё.

См. также beginCreate().

[virtual] QObject *QQmlComponent::create(QQmlContext *context = nullptr)

Создаёт экземпляр объекта из этого компонента. Возвращает nullptr в случае неудачи. context задаёт контекст, в котором нужно создать экземпляр объекта.

Если context равен null (по умолчанию), он создаст экземпляр в корневом контексте движка.

Владение возвращаемым экземпляром объекта передаётся вызывающей стороне.

Если создаваемый из этого компонента объект является визуальным элементом, у него должен быть родительский визуальный элемент, который можно установить, вызвав QQuickItem::setParentItem(). См. Понятие - Визуальный родитель в Qt Quick для получения более подробной информации.

См. также QQmlEngine::ObjectOwnership.

void QQmlComponent::create(QQmlIncubator &incubator, QQmlContext *context = nullptr, QQmlContext *forContext = nullptr)

Создаёт экземпляр объекта из этого компонента с помощью предоставленного incubator. context задаёт контекст, в котором нужно создать экземпляр объекта.

Если context равен 0 (по умолчанию), он создаст экземпляр в корневом контексте движка.

forContext указывает контекст, от которого зависит создание этого объекта. Если forContext создается асинхронно, и QQmlIncubator::IncubationMode равен QQmlIncubator::AsynchronousIfNested, этот объект также будет создан асинхронно. Если forContext равен 0 (по умолчанию), для принятия решения используется context.

Созданный объект и его состояние доступны через incubator.

См. также QQmlIncubator.

QQmlContext *QQmlComponent::creationContext() const

Возвращает QQmlContext, в котором был создан компонент. Это верно только для компонентов, созданных непосредственно из QML.

QQmlEngine *QQmlComponent::engine() const

Возвращает QQmlEngine этого компонента.

Эта функция была добавлена в Qt 5.12.

QList<QQmlError> QQmlComponent::errors() const

Возвращает список ошибок, возникших во время последней компиляции или операции создания. Возвращается пустой список, если isError() не установлено.

bool QQmlComponent::isError() const

Возвращает true, если status() == QQmlComponent::Error.

bool QQmlComponent::isLoading() const

Возвращает true, если status() == QQmlComponent::Loading.

bool QQmlComponent::isNull() const

Возвращает true, если status() == QQmlComponent::Null.

bool QQmlComponent::isReady() const

Возвращает true, если status() == QQmlComponent::Ready.

[slot] void QQmlComponent::loadUrl(const QUrl &url)

Загружает QQmlComponent из указанного url.

Убедитесь, что предоставленный URL-адрес полный и корректный, в частности, используйте QUrl::fromLocalFile(), при загрузке файла из локальной файловой системы.

Относительные пути будут разрешаться относительно QQmlEngine::baseUrl(), который по умолчанию соответствует текущей рабочей директории.

[slot] void QQmlComponent::loadUrl(const QUrl &url, QQmlComponent::CompilationMode mode)

Загружает QQmlComponent из предоставленного url. Если mode равен Asynchronous, компонент будет загружен и скомпилирован асинхронно.

Убедитесь, что предоставленный URL-адрес полный и корректный, в частности, используйте QUrl::fromLocalFile(), при загрузке файла из локальной файловой системы.

Относительные пути будут разрешаться относительно QQmlEngine::baseUrl(), который по умолчанию соответствует текущей рабочей директории.

[signal] void QQmlComponent::progressChanged(qreal progress)

Излучается всякий раз, когда изменяется степень загрузки компонента. progress будет текущей степенью загрузки от 0.0 (ничего не загружено) до 1.0 (загрузка завершена).

Примечание: Сигнал-уведомление для свойства progress.

[slot] void QQmlComponent::setData(const QByteArray &data, const QUrl &url)

Устанавливает QQmlComponent для использования заданных данных QML data. Если url предоставлен, он используется для установки имени компонента и для предоставления базового пути для элементов, разрешенных этим компонентом.

[signal] void QQmlComponent::statusChanged(QQmlComponent::Status status)

Излучается всякий раз, когда изменяется состояние компонента. status будет новым состоянием.

Примечание: Сигнал-уведомление для свойства status.