Класс QQmlComponent

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

Этот класс был представлен в Qt 5.0.

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

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

Свойства

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

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

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

Сигналы

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

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

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

import QtQuick 2.0

Item {
    width: 200
    height: 200
}

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

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();
    }
}

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

enum QQmlComponent::CompilationMode

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

enum QQmlComponent::Status

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

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

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().

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 QString &fileName, QQmlComponent::CompilationMode mode, QObject *parent = nullptr)

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

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

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

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

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

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

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

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

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

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

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

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

Загружает QQmlComponent из предоставленного url.

Убедитесь, что предоставленный 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.

[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. Для завершения шагов 2 и 3 необходимо вызвать QQmlComponent::completeCreate().

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

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

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

[virtual] void QQmlComponent::completeCreate()

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

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

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

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

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

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

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

Если объект, создаваемый из этого компонента, является визуальным элементом, у него должен быть визуальный родитель, который можно установить, вызвав QQuickItem::setParentItem(). Подробнее см. Концепции - Визуальный родитель в 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.

QObject *QQmlComponent::createWithInitialProperties(const QVariantMap &initialProperties, QQmlContext *context = nullptr)

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

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

См. также QQmlComponent::create.

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.

void QQmlComponent::setInitialProperties(QObject *component, const QVariantMap &properties)

Устанавливает свойства верхнего уровня properties для component.

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

Используйте этот метод после beginCreate и перед completeCreate. Если предоставленное свойство не существует, выводится предупреждение.

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