Класс QQmlComponent

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

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

Типы public

Свойства

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

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

Функции public

• 32 функции public, унаследованные от QObject

Слот public

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

Сигналы

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

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

• 11 статических public членов унаследованы от 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();
    }
}

Обратите внимание, что версия 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(), когда загружаете файл из локальной файловой системы.

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

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

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

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

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

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

См. также 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 (по умолчанию), экземпляр будет создан в корневом контексте движка root context.

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

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

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

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

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

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

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

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

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

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

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

Относительные пути будут разрешаться относительно 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. Если url указан, он используется для установки имени компонента и для обеспечения базового пути для элементов, разрешённых этим компонентом.

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

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

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