Struct qt_qml::QQmlIncubator

#[repr(C)]pub struct QQmlIncubator { /* fields omitted */ }

Creating QML objects - like delegates in a view, or a new page in an application - can take a noticeable amount of time, especially on resource constrained mobile devices. When an application uses QQmlComponent::create() directly, the QML object instance is created synchronously which, depending on the complexity of the object, can cause noticeable pauses or stutters in the application.

C++ class: QQmlIncubator.

C++ documentation:

Creating QML objects - like delegates in a view, or a new page in an application - can take a noticeable amount of time, especially on resource constrained mobile devices. When an application uses QQmlComponent::create() directly, the QML object instance is created synchronously which, depending on the complexity of the object, can cause noticeable pauses or stutters in the application.

The use of QQmlIncubator gives more control over the creation of a QML object, including allowing it to be created asynchronously using application idle time. The following example shows a simple use of QQmlIncubator.

QQmlIncubator incubator;
component->create(incubator);
while (!incubator.isReady()) {
      QCoreApplication::processEvents(QEventLoop::AllEvents, 50);
}
QObject *object = incubator.object();

Asynchronous incubators are controlled by a QQmlIncubationController that is set on the QQmlEngine, which lets the engine know when the application is idle and incubating objects should be processed. If an incubation controller is not set on the QQmlEngine, QQmlIncubator creates objects synchronously regardless of the specified IncubationMode.

QQmlIncubator supports three incubation modes:

• Synchronous The creation occurs synchronously. That is, once the QQmlComponent::create() call returns, the incubator will already be in either the Error or Ready state. A synchronous incubator has no real advantage compared to using the synchronous creation methods on QQmlComponent directly, but it may simplify an application's implementation to use the same API for both synchronous and asynchronous creations.
• Asynchronous (default) The creation occurs asynchronously, assuming a QQmlIncubatorController is set on the QQmlEngine.

  The incubator will remain in the Loading state until either the creation is complete or an error occurs. The statusChanged() callback can be used to be notified of status changes.

  Applications should use the Asynchronous incubation mode to create objects that are not needed immediately. For example, the ListView type uses Asynchronous incubation to create objects that are slightly off screen while the list is being scrolled. If, during asynchronous creation, the object is needed immediately the QQmlIncubator::forceCompletion() method can be called to complete the creation process synchronously.

• AsynchronousIfNested The creation will occur asynchronously if part of a nested asynchronous creation, or synchronously if not.

  In most scenarios where a QML component wants the appearance of a synchronous instantiation, it should use this mode.

  This mode is best explained with an example. When the ListView type is first created, it needs to populate itself with an initial set of delegates to show. If the ListView was 400 pixels high, and each delegate was 100 pixels high, it would need to create four initial delegate instances. If the ListView used the Asynchronous incubation mode, the ListView would always be created empty and then, sometime later, the four initial items would appear.

  Conversely, if the ListView was to use the Synchronous incubation mode it would behave correctly but it may introduce stutters into the application. As QML would have to stop and instantiate the ListView's delegates synchronously, if the ListView was part of a QML component that was being instantiated asynchronously this would undo much of the benefit of asynchronous instantiation.

  The AsynchronousIfNested mode reconciles this problem. By using AsynchronousIfNested, the ListView delegates are instantiated asynchronously if the ListView itself is already part of an asynchronous instantiation, and synchronously otherwise. In the case of a nested asynchronous instantiation, the outer asynchronous instantiation will not complete until after all the nested instantiations have also completed. This ensures that by the time the outer asynchronous instantitation completes, inner items like ListView have already completed loading their initial delegates.

  It is almost always incorrect to use the Synchronous incubation mode - elements or components that want the appearance of synchronous instantiation, but without the downsides of introducing freezes or stutters into the application, should use the AsynchronousIfNested incubation mode.

Methods

impl QQmlIncubator

pub unsafe fn clear(&self)

Clears the incubator. Any in-progress incubation is aborted. If the incubator is in the Ready state, the created object is not deleted.

Calls C++ function: void QQmlIncubator::clear().

C++ documentation:

Clears the incubator. Any in-progress incubation is aborted. If the incubator is in the Ready state, the created object is not deleted.

pub unsafe fn errors(&self) -> CppBox<QListOfQQmlError>

Return the list of errors encountered while incubating the object.

Calls C++ function: QList<QQmlError> QQmlIncubator::errors() const.

C++ documentation:

Return the list of errors encountered while incubating the object.

pub unsafe fn force_completion(&self)

Force any in-progress incubation to finish synchronously. Once this call returns, the incubator will not be in the Loading state.

Calls C++ function: void QQmlIncubator::forceCompletion().

C++ documentation:

Force any in-progress incubation to finish synchronously. Once this call returns, the incubator will not be in the Loading state.

pub unsafe fn incubation_mode(&self) -> IncubationMode

Return the incubation mode passed to the QQmlIncubator constructor.

Calls C++ function: QQmlIncubator::IncubationMode QQmlIncubator::incubationMode() const.

C++ documentation:

Return the incubation mode passed to the QQmlIncubator constructor.

pub unsafe fn is_error(&self) -> bool

Returns true if the incubator's status() is Error.

Calls C++ function: bool QQmlIncubator::isError() const.

C++ documentation:

Returns true if the incubator's status() is Error.

pub unsafe fn is_loading(&self) -> bool

Returns true if the incubator's status() is Loading.

Calls C++ function: bool QQmlIncubator::isLoading() const.

C++ documentation:

Returns true if the incubator's status() is Loading.

pub unsafe fn is_null(&self) -> bool

Returns true if the incubator's status() is Null.

Calls C++ function: bool QQmlIncubator::isNull() const.

C++ documentation:

Returns true if the incubator's status() is Null.

pub unsafe fn is_ready(&self) -> bool

Returns true if the incubator's status() is Ready.

Calls C++ function: bool QQmlIncubator::isReady() const.

C++ documentation:

Returns true if the incubator's status() is Ready.

pub unsafe fn new_1a(arg1: IncubationMode) -> CppBox<QQmlIncubator>

Create a new incubator with the specified mode

Calls C++ function: [constructor] void QQmlIncubator::QQmlIncubator(QQmlIncubator::IncubationMode arg1 = …).

C++ documentation:

Create a new incubator with the specified mode

pub unsafe fn new_0a() -> CppBox<QQmlIncubator>

Creating QML objects - like delegates in a view, or a new page in an application - can take a noticeable amount of time, especially on resource constrained mobile devices. When an application uses QQmlComponent::create() directly, the QML object instance is created synchronously which, depending on the complexity of the object, can cause noticeable pauses or stutters in the application.

Calls C++ function: [constructor] void QQmlIncubator::QQmlIncubator().

C++ documentation:

Creating QML objects - like delegates in a view, or a new page in an application - can take a noticeable amount of time, especially on resource constrained mobile devices. When an application uses QQmlComponent::create() directly, the QML object instance is created synchronously which, depending on the complexity of the object, can cause noticeable pauses or stutters in the application.

The use of QQmlIncubator gives more control over the creation of a QML object, including allowing it to be created asynchronously using application idle time. The following example shows a simple use of QQmlIncubator.

QQmlIncubator incubator;
component->create(incubator);
while (!incubator.isReady()) {
      QCoreApplication::processEvents(QEventLoop::AllEvents, 50);
}
QObject *object = incubator.object();

Asynchronous incubators are controlled by a QQmlIncubationController that is set on the QQmlEngine, which lets the engine know when the application is idle and incubating objects should be processed. If an incubation controller is not set on the QQmlEngine, QQmlIncubator creates objects synchronously regardless of the specified IncubationMode.

QQmlIncubator supports three incubation modes:

• Synchronous The creation occurs synchronously. That is, once the QQmlComponent::create() call returns, the incubator will already be in either the Error or Ready state. A synchronous incubator has no real advantage compared to using the synchronous creation methods on QQmlComponent directly, but it may simplify an application's implementation to use the same API for both synchronous and asynchronous creations.
• Asynchronous (default) The creation occurs asynchronously, assuming a QQmlIncubatorController is set on the QQmlEngine.

  The incubator will remain in the Loading state until either the creation is complete or an error occurs. The statusChanged() callback can be used to be notified of status changes.

  Applications should use the Asynchronous incubation mode to create objects that are not needed immediately. For example, the ListView type uses Asynchronous incubation to create objects that are slightly off screen while the list is being scrolled. If, during asynchronous creation, the object is needed immediately the QQmlIncubator::forceCompletion() method can be called to complete the creation process synchronously.

• AsynchronousIfNested The creation will occur asynchronously if part of a nested asynchronous creation, or synchronously if not.

  In most scenarios where a QML component wants the appearance of a synchronous instantiation, it should use this mode.

  This mode is best explained with an example. When the ListView type is first created, it needs to populate itself with an initial set of delegates to show. If the ListView was 400 pixels high, and each delegate was 100 pixels high, it would need to create four initial delegate instances. If the ListView used the Asynchronous incubation mode, the ListView would always be created empty and then, sometime later, the four initial items would appear.

  Conversely, if the ListView was to use the Synchronous incubation mode it would behave correctly but it may introduce stutters into the application. As QML would have to stop and instantiate the ListView's delegates synchronously, if the ListView was part of a QML component that was being instantiated asynchronously this would undo much of the benefit of asynchronous instantiation.

  The AsynchronousIfNested mode reconciles this problem. By using AsynchronousIfNested, the ListView delegates are instantiated asynchronously if the ListView itself is already part of an asynchronous instantiation, and synchronously otherwise. In the case of a nested asynchronous instantiation, the outer asynchronous instantiation will not complete until after all the nested instantiations have also completed. This ensures that by the time the outer asynchronous instantitation completes, inner items like ListView have already completed loading their initial delegates.

  It is almost always incorrect to use the Synchronous incubation mode - elements or components that want the appearance of synchronous instantiation, but without the downsides of introducing freezes or stutters into the application, should use the AsynchronousIfNested incubation mode.

pub unsafe fn object(&self) -> QPtr<QObject>

Return the incubated object if the status is Ready, otherwise 0.

Calls C++ function: QObject* QQmlIncubator::object() const.

C++ documentation:

Return the incubated object if the status is Ready, otherwise 0.

pub unsafe fn status(&self) -> Status

Return the current status of the incubator.

Calls C++ function: QQmlIncubator::Status QQmlIncubator::status() const.

C++ documentation:

Return the current status of the incubator.

Trait Implementations

impl CppDeletable for QQmlIncubator

unsafe fn delete(&self)

Calls C++ function: virtual [destructor] void QQmlIncubator::~QQmlIncubator().