QQmlComponent Class

The QQmlComponent class makes objects from a QML document. More…

List of all members, including inherited members

Public Types

Public Functions

Public Slots

Signals

Detailed Description

A component reads a document once and makes objects from it as often as needed:

QQmlEngine engine;
engine.rootContext()->setContextProperty("greeting", QStringLiteral("hello"));
QObject::connect(&engine, &QQmlEngine::quit, &app, &QCoreApplication::quit);

QQmlComponent component(&engine);
component.setData(document, QUrl(QStringLiteral("file:///home.qml")));
QObject *home = component.create();
if (!home) {
    qWarning().noquote() << component.errorString();
    return 1;
}

create() makes the objects of the document in a new context, sets their bindings and completes them. beginCreate() and completeCreate() split this in two, to set properties in between. The caller owns the object.

A Component declared inside a document is a QQmlComponent too; scripts make its object with createObject().

See also QQmlEngine and QQmlContext.

Differences from Qt

Member Type Documentation

enum QQmlComponent::CompilationMode

enum QQmlComponent::Status

Member Function Documentation

[explicit] QQmlComponent::QQmlComponent(QObject *parent = nullptr)

Constructs a component without an engine or a document, with the given parent.

QQmlComponent::QQmlComponent(QQmlEngine *engine, QObject *parent = nullptr)

Constructs a component of engine without a document, with the given parent.

See also setData() and loadUrl().

QQmlComponent::QQmlComponent(QQmlEngine *engine, const QString &fileName, QObject *parent = nullptr)

Constructs a component of engine with the given parent that loads the file fileName.

QQmlComponent::QQmlComponent(QQmlEngine *engine, const QString &fileName, CompilationMode mode, QObject *parent = nullptr)

Constructs a component of engine with the given parent that loads the file fileName; mode is not used.

QQmlComponent::QQmlComponent(QQmlEngine *engine, const QUrl &url, QObject *parent = nullptr)

Constructs a component of engine with the given parent that loads the document at url.

QQmlComponent::QQmlComponent(QQmlEngine *engine, const QUrl &url, CompilationMode mode, QObject *parent = nullptr)

Constructs a component of engine with the given parent that loads the document at url; mode is not used.

[override] QQmlComponent::~QQmlComponent()

Destroys the component. The objects it made are not destroyed.

[virtual] QObject * QQmlComponent::beginCreate(QQmlContext *context)

Makes the objects of the document in a new context whose parent is context, without setting their bindings or completing them; completeCreate() does that. Returns the root object.

[virtual] void QQmlComponent::completeCreate()

Sets the bindings of the objects that beginCreate() made, and completes them.

[virtual] QObject * QQmlComponent::create(QQmlContext *context = nullptr)

Makes the objects of the document in a new context whose parent is context, or the creation context of the component, or the root context of the engine. Returns the root object, which the caller owns, or nullptr on error; see errors().

QObject * QQmlComponent::createObject(QObject *parent = nullptr, const QVariantMap &properties = QVariantMap())

Makes the object of the component, as scripts do with component.createObject(parent, properties): with the QObject parent and properties set before it is completed. An object made by a script without a parent belongs to the script engine, which deletes it when no script can reach it.

QObject * QQmlComponent::createWithInitialProperties(const QVariantMap &initialProperties, QQmlContext *context = nullptr)

Makes the objects as create() does, with initialProperties set on the root object before it is completed. context is the parent context.

QQmlContext * QQmlComponent::creationContext() const

Returns the context that a Component declared in a document was made in, or nullptr.

QQmlEngine * QQmlComponent::engine() const

Returns the engine of the component.

QList<QQmlError> QQmlComponent::errors() const

Returns the errors of loading the document and of the last creation.

QString QQmlComponent::errorString() const

Returns the errors as text, one per line.

bool QQmlComponent::isError() const

Returns true if the document could not be loaded or has errors; otherwise returns false.

bool QQmlComponent::isLoading() const

Returns false: Nt loads documents at once.

bool QQmlComponent::isNull() const

Returns true if no document is loaded; otherwise returns false.

bool QQmlComponent::isReady() const

Returns true if the component can make objects; otherwise returns false.

[slot] void QQmlComponent::loadFromModule(const QString &uri, const QString &typeName, CompilationMode mode = PreferSynchronous)

Loads the type typeName of the module uri; mode is not used. A type written in QML is loaded from its document; a C++ type is made directly.

[slot] void QQmlComponent::loadUrl(const QUrl &url)

Loads the document at url, resolved against the base URL of the engine.

[slot] void QQmlComponent::loadUrl(const QUrl &url, CompilationMode mode)

This is an overloaded function.

Loads the document at url; mode is not used.

qreal QQmlComponent::progress() const

Returns 1.0 if the component is ready or failed, and 0.0 otherwise.

[signal] void QQmlComponent::progressChanged(qreal progress)

This signal is emitted when the loading progress changes to progress.

[slot] void QQmlComponent::setData(const QByteArray &data, const QUrl &baseUrl)

Reads the document data, whose relative URLs are resolved against baseUrl.

void QQmlComponent::setInitialProperties(QObject *component, const QVariantMap &properties)

Sets the properties of component, an object made by beginCreate() and not yet completed.

Status QQmlComponent::status() const

Returns the status of the component.

[signal] void QQmlComponent::statusChanged(QQmlComponent::Status status)

This signal is emitted when the status of the component changes to status.

QUrl QQmlComponent::url() const

Returns the URL of the document.