Класс 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 для синхронного и асинхронного создания.
• Асинхронный (по умолчанию). Создание происходит асинхронно, предполагая, что в QQmlEngine установлен QQmlIncubatorController.

  Инкубатор останется в состоянии Загрузка до тех пор, пока создание не будет завершено или не произойдет ошибка. Обратный вызов 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 = Асинхронно)

Создает новый инкубатор с указанным 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 — новое состояние.

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