QQmlIncubator Class Reference

The QQmlIncubator class allows QML objects to be created asynchronously. More...

#include <qqmlincubator.h>

Inheritance diagram for QQmlIncubator:

Collaboration diagram for QQmlIncubator:

Public Types
enum	IncubationMode { Asynchronous , AsynchronousIfNested , Synchronous }
	Specifies the mode the incubator operates in. More...
enum	Status { Null , Ready , Loading , Error }
	Specifies the status of the QQmlIncubator. More...

Public Member Functions
	QQmlIncubator (IncubationMode=Asynchronous)
	Create a new incubator with the specified mode.
virtual	~QQmlIncubator ()
void	clear ()
	Clears the incubator.
void	forceCompletion ()
	Force any in-progress incubation to finish synchronously.
bool	isNull () const
	Returns true if the incubator's status() is Null.
bool	isReady () const
	Returns true if the incubator's status() is Ready.
bool	isError () const
	Returns true if the incubator's status() is Error.
bool	isLoading () const
	Returns true if the incubator's status() is Loading.
QList< QQmlError >	errors () const
	Return the list of errors encountered while incubating the object.
IncubationMode	incubationMode () const
	Return the incubation mode passed to the QQmlIncubator constructor.
Status	status () const
	Return the current status of the incubator.
QObject *	object () const
	Return the incubated object if the status is Ready, otherwise 0.
void	setInitialProperties (const QVariantMap &initialProperties)
	Stores a mapping from property names to initial values, contained in initialProperties, with which the incubated component will be initialized.

Protected Member Functions
virtual void	statusChanged (Status)
	Called when the status of the incubator changes.
virtual void	setInitialState (QObject *)
	Called after the object is first created, but before complex property bindings are evaluated and, if applicable, QQmlParserStatus::componentComplete() is called.

Friends
class	QQmlComponent
class	QQmlEnginePrivate
class	QQmlIncubatorPrivate

Detailed Description

The QQmlIncubator class allows QML objects to be created asynchronously.

\inmodule QtQml

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.

// 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 \l{QQuickWindow}, or you may want to run a \l{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 \l{QQmlIncubationController} that is set on the \l{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 \l{QQmlEngine}, \l{QQmlIncubator} creates objects synchronously regardless of the specified IncubationMode. By default, no incubation controller is set. However, \l{QQuickView}, \l{QQuickWindow} and \l{QQuickWidget} all set incubation controllers on their respective \l{QQmlEngine}s. These incubation controllers space out incubations across multiple frames while the view is being rendered.

QQmlIncubator supports three incubation modes: \list

• 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. \endlist

Definition at line 19 of file qqmlincubator.h.

Member Enumeration Documentation

IncubationMode

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.

\value Asynchronous The object will be created asynchronously. \value AsynchronousIfNested 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. \value Synchronous The object will be created synchronously.

Enumerator
Asynchronous
AsynchronousIfNested
Synchronous

Definition at line 23 of file qqmlincubator.h.

Status

enum QQmlIncubator::Status

Specifies the status of the QQmlIncubator.

\value Null Incubation is not in progress. Call QQmlComponent::create() to begin incubating. \value Ready The object is fully created and can be accessed by calling object(). \value Loading The object is in the process of being created. \value Error An error occurred. The errors can be access by calling errors().

Enumerator
Null
Ready
Loading
Error

Definition at line 28 of file qqmlincubator.h.

Constructor & Destructor Documentation

QQmlIncubator()

QQmlIncubator::QQmlIncubator

(

IncubationMode

mode = Asynchronous

)

Create a new incubator with the specified mode.

Definition at line 552 of file qqmlincubator.cpp.

~QQmlIncubator()

QQmlIncubator::~QQmlIncubator ( )

virtual

Definition at line 559 of file qqmlincubator.cpp.

Member Function Documentation

clear()

void QQmlIncubator::clear

(

)

Clears the incubator.

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

Definition at line 599 of file qqmlincubator.cpp.

errors()

QList< QQmlError > QQmlIncubator::errors

(

)

const

Return the list of errors encountered while incubating the object.

Definition at line 683 of file qqmlincubator.cpp.

forceCompletion()

void QQmlIncubator::forceCompletion

(

)

Force any in-progress incubation to finish synchronously.

Once this call returns, the incubator will not be in the Loading state.

Definition at line 642 of file qqmlincubator.cpp.

incubationMode()

QQmlIncubator::IncubationMode QQmlIncubator::incubationMode

(

)

const

Return the incubation mode passed to the QQmlIncubator constructor.

Definition at line 691 of file qqmlincubator.cpp.

isError()

bool QQmlIncubator::isError

(

)

const

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

Definition at line 667 of file qqmlincubator.cpp.

isLoading()

bool QQmlIncubator::isLoading

(

)

const

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

Definition at line 675 of file qqmlincubator.cpp.

isNull()

bool QQmlIncubator::isNull

(

)

const

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

Definition at line 651 of file qqmlincubator.cpp.

isReady()

bool QQmlIncubator::isReady

(

)

const

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

Definition at line 659 of file qqmlincubator.cpp.

object()

QObject * QQmlIncubator::object

(

)

const

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

Definition at line 707 of file qqmlincubator.cpp.

setInitialProperties()

void QQmlIncubator::setInitialProperties

(

const QVariantMap &

initialProperties

)

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

See also

QQmlComponent::setInitialProperties

Since

5.15

Definition at line 747 of file qqmlincubator.cpp.

setInitialState()

void QQmlIncubator::setInitialState ( QObject * object )

protectedvirtual

Called after the object is first created, but before complex property bindings are evaluated and, if applicable, QQmlParserStatus::componentComplete() is called.

This is equivalent to the point between QQmlComponent::beginCreate() and QQmlComponent::completeCreate(), 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 \l{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"}.

Reimplemented in QQDMIncubationTask, QQmlComponentIncubator, QQmlComponentIncubator, QQmlTableInstanceModelIncubationTask, QQuick3DLoaderIncubator, QQuickLoaderIncubator, QQuickStackIncubator, and QQuickStackIncubator.

Definition at line 781 of file qqmlincubator.cpp.

status()

QQmlIncubator::Status QQmlIncubator::status

(

)

const

Return the current status of the incubator.

Definition at line 699 of file qqmlincubator.cpp.

statusChanged()

void QQmlIncubator::statusChanged ( Status status )

protectedvirtual

Called when the status of the incubator changes.

status is the new status.

The default implementation does nothing.

Reimplemented in QQDMIncubationTask, QQmlComponentIncubator, QQmlComponentIncubator, QQmlTableInstanceModelIncubationTask, QQuick3DLoaderIncubator, and QQuickLoaderIncubator.

Definition at line 757 of file qqmlincubator.cpp.

Friends And Related Symbol Documentation

QQmlComponent

friend class QQmlComponent

friend

Definition at line 61 of file qqmlincubator.h.

QQmlEnginePrivate

friend class QQmlEnginePrivate

friend

Definition at line 62 of file qqmlincubator.h.

Referenced by QQmlExpressionPrivate::value().

QQmlIncubatorPrivate

friend class QQmlIncubatorPrivate

friend

Definition at line 63 of file qqmlincubator.h.

---

The documentation for this class was generated from the following files:

• qtdeclarative/src/qml/qml/qqmlincubator.h (0dc4fd240a2897c5c443a0ef6d84c416843e4938)
• qtdeclarative/src/qml/qml/qqmlincubator.cpp (2f35c7036e468d97ace2a5b3987674a30d29d532)