Класс QQmlComponent

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

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

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

Свойства

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

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

Функции публичного доступа

• 34 функции публичного доступа унаследованы от QObject

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

• 1 слот публичного доступа унаследован от QObject

Сигналы

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

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

• 1 публичная переменная унаследована от QObject
• 10 статические публичные члены унаследованы от QObject
• 9 защищенные функции унаследованы от QObject
• 2 защищенные переменные унаследованы от 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() может быть ложным для сетевого компонента, если компонент был кэширован и готов сразу.

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 = 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() для создания экземпляров объектов.

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

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

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

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

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

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

void QQmlComponent::create(QQmlIncubator &incubator, QQmlContext *context = nullptr, QQmlContext *forContext = 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(), при загрузке файла из локальной файловой системы.

Относительные пути будут разрешаться относительно 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.