Класс QQmlComponent

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

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

Типы публичного доступа

Свойства

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

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

Публичные функции

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

Свойства-слоты

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

Сигналы

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

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

• 11 статических публичных членов унаследованы от 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. Приложение должно подождать, пока компонент не станет 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();
    }
}

Обратите внимание, что версия Qt Quick 1 называется QDeclarativeComponent.

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

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

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

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

Указывает статус загрузки QQmlComponent.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[virtual] QQmlComponent::~QQmlComponent()

Уничтожает QQmlComponent.

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

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

Создаёт экземпляр объекта из этого компонента. Возвращает 0, если создание не удалось. 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 = Q_NULLPTR)

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

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

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

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

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

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

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

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

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

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

См. также QQmlIncubator.

QQmlContext *QQmlComponent::creationContext() const

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

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() при загрузке файла из локальной файловой системы.

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

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

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

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