The QQmlIncubator class allows QML objects to be created asynchronously.

Header:   #include <QQmlIncubator>  
CMake:   find_package(Qt6 REQUIRED COMPONENTS Qml)
target_link_libraries(mytarget PRIVATE Qt6::Qml)  
qmake:   QT += qml  

enum   { Asynchronous, AsynchronousIfNested, Synchronous }  
enum   { Null, Ready, Loading, Error }  

  (QQmlIncubator::IncubationMode mode = Asynchronous)  
void   ()  
QList<QQmlError>   () const  
void   ()  
QQmlIncubator::IncubationMode   () const  
bool   () const  
bool   () const  
bool   () const  
bool   () const  
QObject *   () const  
void   (const QVariantMap &initialProperties)  
QQmlIncubator::Status   () const  

virtual void   (QObject *object)  
virtual void   (QQmlIncubator::Status status)  

Detailed Description

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

// Initialize the incubator QQmlIncubator incubator; component->create(incubator);

Let the incubator run for a while (normally by returning control to the event loop), then poll it. There are a number of ways to get back to the incubator later. You may want to connect to one of the signals sent by QQuickWindow, or you may want to run a QTimer especially for that. You may also need the object for some specific purpose and poll the incubator when that purpose arises.

// Poll the incubator if (incubator.isReady()) { QObject *object = incubator.object(); // Use created 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 . By default, no incubation controller is set. However, QQuickView, QQuickWindow and QQuickWidget all set incubation controllers on their respective QQmlEngines. These incubation controllers space out incubations across multiple frames while the view is being rendered.

QQmlIncubator supports three incubation modes:

Member Type Documentation enum QQmlIncubator::IncubationMode

Specifies the mode the incubator operates in. Regardless of the incubation mode, a QQmlIncubator will behave synchronously if the QQmlEngine does not have a QQmlIncubationController set.

ConstantValueDescription
QQmlIncubator::Asynchronous   0   The object will be created asynchronously.  
QQmlIncubator::AsynchronousIfNested   1   If the object is being created in a context that is already part of an asynchronous creation, this incubator will join that existing incubation and execute asynchronously. The existing incubation will not become Ready until both it and this incubation have completed. Otherwise, the incubation will execute synchronously.  
QQmlIncubator::Synchronous   2   The object will be created synchronously.  

Specifies the status of the QQmlIncubator.

ConstantValueDescription
QQmlIncubator::Null   0   Incubation is not in progress. Call () to begin incubating.  
QQmlIncubator::Ready   1   The object is fully created and can be accessed by calling ().  
QQmlIncubator::Loading   2   The object is in the process of being created.  
QQmlIncubator::Error   3   An error occurred. The errors can be access by calling ().  

Member Function Documentation QQmlIncubator::QQmlIncubator( mode = Asynchronous)

Create a new incubator with the specified mode

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

Return the list of errors encountered while incubating the object.

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

Return the incubation mode passed to the QQmlIncubator constructor.

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

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

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

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

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

Stores a mapping from property names to initial values, contained in initialProperties, with which the incubated component will be initialized.

See also .

Called after the object is first created, but before complex property bindings are evaluated and, if applicable, () is called. This is equivalent to the point between () and (), and can be used to assign initial values to the object's properties.

The default implementation does nothing.

Note: Simple bindings such as numeric literals are evaluated before setInitialState() is called. The categorization of bindings into simple and complex ones is intentionally unspecified and may change between versions of Qt and depending on whether and how you are using qmlcachegen. You should not rely on any particular binding to be evaluated either before or after setInitialState() is called. For example, a constant expression like MyType.EnumValue may be recognized as such at compile time or deferred to be executed as binding. The same holds for constant expressions like -(5) or "a" + " constant string".

Return the current status of the incubator.

Called when the status of the incubator changes. status is the new status.

The default implementation does nothing.

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.