Класс 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 = 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 — новое состояние.

Реализация по умолчанию ничего не делает.