QQmlComponent Class

Documentación de las funciones miembro

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

Crea un QQmlComponent sin datos y dale los especificados engine y parent. Establece los datos con setData().

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

Crea un QQmlComponent a partir del fileName dado y le da los parent y engine especificados.

Véase también loadUrl().

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

Crea un QQmlComponent a partir del url dado y dale los parent y engine especificados.

Asegúrese de que la URL proporcionada es completa y correcta, en particular, utilice QUrl::fromLocalFile() cuando cargue un archivo desde el sistema de archivos local.

Las rutas relativas se resolverán contra QQmlEngine::baseUrl(), que es el directorio de trabajo actual a menos que se especifique.

Véase también loadUrl().

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

Crea un QQmlComponent a partir del fileName dado y le da los parent y engine especificados. Si mode es Asynchronous, el componente será cargado y compilado asíncronamente.

Véase también loadUrl().

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

Crea un QQmlComponent a partir del url dado y le da los parent y engine especificados. Si mode es Asynchronous, el componente se cargará y compilará de forma asíncrona.

Asegúrese de que la URL proporcionada es completa y correcta, en particular, utilice QUrl::fromLocalFile() cuando cargue un archivo desde el sistema de archivos local.

Las rutas relativas se resolverán contra QQmlEngine::baseUrl(), que es el directorio de trabajo actual a menos que se especifique.

Véase también loadUrl().

[explicit, since 6.5] QQmlComponent::QQmlComponent(QQmlEngine *engine, QAnyStringView uri, QAnyStringView typeName, QObject *parent = nullptr)

Crea un QQmlComponent a partir de los campos uri y typeName y le asigna los campos parent y engine. Si es posible, el componente se cargará de forma sincrónica.

Esta función se introdujo en Qt 6.5.

Véase también loadFromModule().

[explicit, since 6.5] QQmlComponent::QQmlComponent(QQmlEngine *engine, QAnyStringView uri, QAnyStringView typeName, QQmlComponent::CompilationMode mode, QObject *parent = nullptr)

Crea un QQmlComponent a partir de los campos uri y typeName y le asigna los campos parent y engine. Si mode es Asynchronous, el componente se cargará y compilará de forma asíncrona.

Esta función se introdujo en Qt 6.5.

Véase también loadFromModule().

[override virtual noexcept] QQmlComponent::~QQmlComponent()

Destruye el QQmlComponent.

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

Crea una instancia de objeto a partir de este componente, dentro de la dirección context especificada. Devuelve nullptr si la creación falló.

Cuando QQmlComponent construye una instancia, lo hace en tres pasos:

1. Se crea la jerarquía de objetos y se asignan valores constantes.
2. Las propiedades se evalúan por primera vez.
3. Si procede, se llama a QQmlParserStatus::componentComplete() en los objetos.

QQmlComponent::beginCreate() difiere de QQmlComponent::create() en que sólo realiza el paso 1. Para completar los pasos 2 y 3 se debe llamar a QQmlComponent::completeCreate().

Este punto de ruptura es a veces útil cuando se utilizan propiedades adjuntas para comunicar información a un componente instanciado, ya que permite configurar sus valores iniciales antes de que los enlaces de propiedades surtan efecto.

La propiedad de la instancia de objeto devuelta se transfiere a la persona que realiza la llamada.

Véase también completeCreate() y QQmlEngine::ObjectOwnership.

[virtual] void QQmlComponent::completeCreate()

Este método proporciona un control avanzado sobre la creación de instancias de componentes. En general, los programadores deberían utilizar QQmlComponent::create() para crear un componente.

Esta función completa la creación del componente iniciada con QQmlComponent::beginCreate() y debe llamarse después.

Véase también beginCreate().

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

Crea una instancia de objeto a partir de este componente, dentro de la dirección context especificada. Devuelve nullptr si la creación falló.

Si context es nullptr (por defecto), creará la instancia en el root context del motor.

La propiedad de la instancia de objeto devuelta se transfiere a la persona que realiza la llamada.

Si el objeto que se crea desde este componente es un elemento visual, debe tener un padre visual, que puede establecerse llamando a QQuickItem::setParentItem(). Véase Conceptos - Visual Parent en Qt Quick para más detalles.

Véase también QQmlEngine::ObjectOwnership.

void QQmlComponent::create(QQmlIncubator &incubator, QQmlContext *context = nullptr, QQmlContext *forContext = nullptr)

Crea una instancia de objeto a partir de este componente utilizando el incubator proporcionado. context especifica el contexto en el que se creará la instancia de objeto.

Si context es nullptr (el valor predeterminado), creará la instancia en el root context del motor.

forContext especifica un contexto del que depende la creación de este objeto. Si forContext se está creando de forma asíncrona, y QQmlIncubator::IncubationMode es QQmlIncubator::AsynchronousIfNested, este objeto también se creará de forma asíncrona. Si forContext es nullptr (por defecto), se utilizará context para esta decisión.

El objeto creado y su estado de creación están disponibles a través de incubator.

Véase también QQmlIncubator.

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

Crea una instancia de objeto de este componente, dentro del context especificado, e inicializa sus propiedades de nivel superior con initialProperties.

Si alguna de las initialProperties no se puede establecer, se emite una advertencia. Si hay propiedades requeridas no establecidas, la creación del objeto falla y devuelve nullptr, en cuyo caso isError() devolverá true.

Si context es nullptr (el valor por defecto), creará la instancia en el root context del motor.

La propiedad de la instancia de objeto devuelta se transfiere a la persona que llama.

Véase también QQmlComponent::create.

QQmlContext *QQmlComponent::creationContext() const

Devuelve la dirección QQmlContext en la que se creó el componente. Esto sólo es válido para componentes creados directamente desde QML.

QQmlEngine *QQmlComponent::engine() const

Devuelve la dirección QQmlEngine de este componente.

QList<QQmlError> QQmlComponent::errors() const

Devuelve la lista de errores que se produjeron durante la última operación de compilación o creación. Se devuelve una lista vacía si no se establece isError().

[since 6.5] bool QQmlComponent::isBound() const

Devuelve true si el componente fue creado en un archivo QML que especifica pragma ComponentBehavior: Bound, de lo contrario devuelve false.

Esta función se introdujo en Qt 6.5.

bool QQmlComponent::isError() const

Devuelve true si status() == QQmlComponent::Error.

bool QQmlComponent::isLoading() const

Devuelve true si status() == QQmlComponent::Loading.

bool QQmlComponent::isNull() const

Devuelve true si status() == QQmlComponent::Null.

bool QQmlComponent::isReady() const

Devuelve true si status() == QQmlComponent::Ready.

[slot, since 6.5] void QQmlComponent::loadFromModule(QAnyStringView uri, QAnyStringView typeName, QQmlComponent::CompilationMode mode = PreferSynchronous)

Carga el QQmlComponent para typeName en el módulo uri. Si el tipo se implementa mediante un archivo QML, se utiliza mode para cargarlo. Los tipos respaldados por C++ siempre se cargan de forma sincrónica.

QQmlEngine engine;
QQmlComponent component(&engine);
component.loadFromModule("QtQuick", "Item");
// once the component is ready
std::unique_ptr<QObject> item(component.create());
Q_ASSERT(item->metaObject() == &QQuickItem::staticMetaObject);

Esta función se introdujo en Qt 6.5.

Véase también loadUrl().

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

Cargue el QQmlComponent desde el url proporcionado.

Asegúrese de que la URL proporcionada está completa y es correcta, en particular, utilice QUrl::fromLocalFile() cuando cargue un archivo desde el sistema de archivos local.

Las rutas relativas se resolverán contra QQmlEngine::baseUrl(), que es el directorio de trabajo actual a menos que se especifique.

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        qmlComponent, qOverload(&QQmlComponent::loadUrl));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        qmlComponent, [receiver = qmlComponent](const QUrl &url) { receiver->loadUrl(url); });

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

Carga el QQmlComponent desde el url proporcionado. Si mode es Asynchronous, el componente se cargará y compilará de forma asíncrona.

Asegúrese de que la URL proporcionada es completa y correcta, en particular, utilice QUrl::fromLocalFile() cuando cargue un archivo desde el sistema de archivos local.

Las rutas relativas se resolverán contra QQmlEngine::baseUrl(), que es el directorio de trabajo actual a menos que se especifique.

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        qmlComponent, qOverload(&QQmlComponent::loadUrl));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        qmlComponent, [receiver = qmlComponent](const QUrl &url, QQmlComponent::CompilationMode mode) { receiver->loadUrl(url, mode); });

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

Emitida cada vez que cambia el progreso de carga del componente. progress será el progreso actual entre 0.0 (nada cargado) y 1.0 (finalizado).

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

Establece el QQmlComponent para utilizar el QML data dado. Si se proporciona url, se utiliza para establecer el nombre del componente y proporcionar una ruta base para los elementos resueltos por este componente.

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

Establece el nivel superior properties del object que se creó a partir de un QQmlComponent.

Este método proporciona un control avanzado sobre la creación de instancias de componentes. En general, los programadores deberían utilizar QQmlComponent::createWithInitialProperties para crear una instancia de objeto a partir de un componente.

Utilice este método después de beginCreate y antes de llamar a completeCreate. Si una propiedad proporcionada no existe, se emite una advertencia.

Este método no permite establecer propiedades anidadas iniciales directamente. En su lugar, el establecimiento de un valor inicial para propiedades de tipo valor con propiedades anidadas puede conseguirse creando ese tipo de valor, asignando su propiedad anidada y, a continuación, pasando el tipo de valor como propiedad inicial del objeto que se va a construir.

Por ejemplo, para establecer fond.bold, se puede crear un QFont, establecer su peso a bold y luego pasar la fuente como propiedad inicial.

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

Emitida cada vez que cambia el estado del componente. status será el nuevo estado.