Класс QQmlIncubator

Класс QQmlIncubator позволяет асинхронно создавать объекты QML. Подробнее...

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

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

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

Защищенные функции

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

Создание объектов QML — например, делегатов в представлении или новой страницы в приложении — может занимать заметное количество времени, особенно на мобильных устройствах с ограниченными ресурсами. Когда приложение напрямую использует QQmlComponent::create(), экземпляр объекта QML создаётся синхронно, что, в зависимости от сложности объекта, может вызывать заметные задержки или пропуски в работе приложения.

Использование QQmlIncubator предоставляет больший контроль над созданием объекта QML, включая возможность асинхронного создания с использованием свободного времени приложения. Следующий пример демонстрирует простое использование QQmlIncubator.

QQmlIncubator incubator;
component->create(incubator);

while (!incubator.isReady()) {
    QCoreApplication::processEvents(QEventLoop::AllEvents, 50);
}

QObject *object = incubator.object();

Асинхронные инкубаторы управляются QQmlIncubationController, который настроен в QQmlEngine, позволяя движку знать, когда приложение бездействует, и объекты должны обрабатываться в процессе инкубации. Если контроллер инкубации не настроен в QQmlEngine, QQmlIncubator создаёт объекты синхронно независимо от заданного IncubationMode.

QQmlIncubator поддерживает три режима инкубации:

• Синхронный Создание происходит синхронно. То есть, как только вызов QQmlComponent::create() возвращается, инкубатор уже будет в состоянии Ошибка или Готово. Синхронный инкубатор не имеет реальных преимуществ по сравнению с использованием синхронных методов создания в QQmlComponent напрямую, но может упростить реализацию приложения, используя один и тот же API для синхронного и асинхронного создания.
• Асинхронный (по умолчанию) Создание происходит асинхронно, предполагая, что QQmlIncubatorController настроен в QQmlEngine.

  Инкубатор останется в состоянии Загрузка, пока создание не будет завершено или не произойдёт ошибка. Обратный вызов statusChanged() можно использовать для получения уведомлений о изменениях статуса.

  Приложения должны использовать режим асинхронной инкубации для создания объектов, которые не нужны немедленно. Например, тип ListView использует асинхронную инкубацию для создания объектов, которые немного за пределами области экрана, в то время как список прокручивается. Если в процессе асинхронного создания объект нужен немедленно, можно вызвать метод QQmlIncubator::forceCompletion() для синхронного завершения процесса создания.

• АсинхронныйЕслиВложенный Создание будет происходить асинхронно, если оно является частью вложенного асинхронного создания, или синхронно, если нет.

  В большинстве сценариев, где QML-компонент хочет имитировать синхронное создание, он должен использовать этот режим.

  Этот режим лучше всего объясняется на примере. Когда тип ListView создаётся впервые, ему необходимо заполнить себя начальным набором делегатов для отображения. Если ListView имеет высоту 400 пикселей, а каждый делегат — высоту 100 пикселей, ему нужно создать четыре начальных экземпляра делегата. Если ListView использовал режим асинхронной инкубации, ListView всегда создавался пустым, а затем, через некоторое время, появлялись четыре начальных элемента.

  Напротив, если ListView использовал режим синхронной инкубации, он бы работал правильно, но это может привести к задержкам в приложении. Поскольку QML должен был останавливаться и синхронно создавать делегатов ListView, если ListView был частью QML-компонента, который создавался асинхронно, это сведёт на нет многие преимущества асинхронного создания.

  Режим АсинхронныйЕслиВложенный согласует эту проблему. Используя АсинхронныйЕслиВложенный, делегаты ListView создаются асинхронно, если сам ListView уже является частью асинхронного создания, и синхронно в противном случае. В случае вложенного асинхронного создания внешнее асинхронное создание не завершится, пока не завершатся все вложенные создания. Это гарантирует, что к моменту завершения внешнего асинхронного создания внутренние элементы, такие как ListView, уже завершили загрузку своих начальных делегатов.

  Практически всегда неправильно использовать режим синхронной инкубации — элементы или компоненты, которые хотят имитировать синхронное создание, но без недостатков введения замораживаний или задержек в приложении, должны использовать режим инкубации АсинхронныйЕслиВложенный.

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

Перечисление QQmlIncubator::IncubationMode

Определяет режим работы инкубатора. Независимо от режима инкубации, QQmlIncubator будет вести себя синхронно, если в QQmlEngine не задан QQmlIncubationController.

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

Определяет состояние QQmlIncubator.

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

QQmlIncubator::QQmlIncubator(QQmlIncubator::IncubationMode mode = Asynchronous)

Создаёт новый инкубатор со заданным mode

void QQmlIncubator::clear()

Очищает инкубатор. Любая выполняющаяся инкубация прерывается. Если инкубатор находится в состоянии Ready, созданный объект не удаляется.

QList<QQmlError> QQmlIncubator::errors() const

Возвращает список ошибок, возникших во время инкубации объекта.

void QQmlIncubator::forceCompletion()

Принудительно завершает любую выполняющуюся инкубацию синхронно. После этого вызова инкубатор больше не будет находиться в состоянии Loading.

QQmlIncubator::IncubationMode QQmlIncubator::incubationMode() const

Возвращает режим инкубации, переданный в конструктор QQmlIncubator.

bool QQmlIncubator::isError() const

Возвращает true, если состояние инкубатора status() равно Error.

bool QQmlIncubator::isLoading() const

Возвращает true, если состояние инкубатора status() равно Loading.

bool QQmlIncubator::isNull() const

Возвращает true, если состояние инкубатора status() равно Null.

bool QQmlIncubator::isReady() const

Возвращает true, если состояние инкубатора status() равно Ready.

QObject *QQmlIncubator::object() const

Возвращает инкубированный объект, если состояние равно Ready, иначе 0.

[since 5.15] void QQmlIncubator::setInitialProperties(const QVariantMap &initialProperties)

Хранит отображение от имён свойств к начальным значениям, содержащимся в initialProperties, с которыми будет инициализирован инкубируемый компонент.

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

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

[virtual protected] void QQmlIncubator::setInitialState(QObject *object)

Вызывается после первого создания object, но перед оценкой связей свойств и, при необходимости, вызовом QQmlParserStatus::componentComplete(). Это эквивалентно моменту между QQmlComponent::beginCreate() и QQmlComponent::completeCreate(), и может быть использовано для присвоения начальных значений свойствам объекта.

По умолчанию ничего не делает.

QQmlIncubator::Status QQmlIncubator::status() const

Возвращает текущее состояние инкубатора.

[virtual protected] void QQmlIncubator::statusChanged(QQmlIncubator::Status status)

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

По умолчанию ничего не делает.