En esta página

QQmlListReference Class

La clase `QQmlListReference` permite manipular las propiedades de ` QQmlListProperty `. Más información...

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

Funciones públicas

QQmlListReference()
(since 6.1) QQmlListReference(const QVariant &variant)
QQmlListReference(QObject *object, const char *property)
bool append(QObject *object) const
QObject *at(qsizetype index) const
bool canAppend() const
bool canAt() const
bool canClear() const
bool canCount() const
bool canRemoveLast() const
bool canReplace() const
bool clear() const
qsizetype count() const
bool isManipulable() const
bool isReadable() const
bool isValid() const
const QMetaObject *listElementType() const
QObject *object() const
bool removeLast() const
bool replace(qsizetype index, QObject *object) const
(since 6.2) qsizetype size() const
bool operator==(const QQmlListReference &other) const

Descripción detallada

QQmlListReference permite a los programas en C++ leer y asignar valores a una propiedad de lista QML de forma sencilla y segura en cuanto a tipos. La principal ventaja respecto al uso directo de ` QQmlListProperty ` es su borrado de tipos: `QQmlListReference` no es una plantilla, pero puede utilizarse para propiedades `QQmlListProperty` de cualquier tipo. Además, supervisa si el objeto propietario ha sido eliminado y no permite acceder a ` QQmlListProperty ` si su propietario ha sido eliminado.

Se puede crear una `QQmlListReference` a partir de un objeto y un nombre de propiedad, o bien a partir de una ` QVariant`. Ambas opciones son equivalentes:

QQmlListReference ref1(object, "children");

const QVariant var = object->property("children");
QQmlListReference ref2(var);

No todas las QQmlListReferences admiten todas las operaciones. Métodos como canAppend(), canAt(), canClear() y canCount() permiten a los programas consultar si una propiedad determinada admite una operación concreta. La disponibilidad de los métodos depende de los métodos implementados por el ` QQmlListProperty` subyacente. Al construir un ` QQmlListProperty ` pasando manualmente las funciones de acceso, puedes restringir el acceso a la lista pasando `nullptr` a algunas de ellas. `QQmlListReference` las reconocerá y las indicará como no disponibles.

QQmlListReferenceLas listas son seguras en cuanto al tipo. Solo se pueden añadir a la lista los ` QObject` que deriven de la clase base correcta. El método ` listElementType()` se puede utilizar para consultar la ` QMetaObject ` del tipo ` QObject ` que se puede añadir. Intentar añadir objetos de un tipo incorrecto a una propiedad de lista dará error.

Al igual que con otras listas, al acceder a un elemento de la lista por índice, es responsabilidad del llamante asegurarse de que no se solicite un elemento fuera de rango. Para ello, utilice el método ` count()` antes de llamar a ` at()`.

Documentación de las funciones de miembro

QQmlListReference::QQmlListReference()

Crea una instancia no válida.

[explicit, since 6.1] QQmlListReference::QQmlListReference(const QVariant &variant)

Crea un objeto `QQmlListReference` a partir de un ` QVariant ` ` variant ` que contenga un ` QQmlListProperty`. Si ` variant ` no contiene una propiedad de lista, se crea un objeto `QQmlListReference` no válido. Si el objeto propietario de la propiedad de lista se destruye después de crear la referencia, esta dejará de ser válida automáticamente. Es decir, es seguro conservar instancias de `QQmlListReference` incluso después de que el objeto haya sido eliminado.

Esta función se introdujo en Qt 6.1.

QQmlListReference::QQmlListReference(QObject *object, const char *property)

Crea un objeto `QQmlListReference` para ` property` de ` object`. Si ` property ` no es una propiedad de lista, se crea un objeto `QQmlListReference` no válido. Si ` object ` se destruye después de crear la referencia, esta dejará de ser válida automáticamente. Es decir, es seguro conservar instancias de `QQmlListReference` incluso después de que se haya eliminado ` object `.

bool QQmlListReference::append(QObject *object) const

Añade object a la lista. Devuelve «true» si la operación se ha realizado correctamente; en caso contrario, devuelve «false».

Véase también canAppend().

QObject *QQmlListReference::at(qsizetype index) const

Devuelve el elemento de la lista en index, o nullptr si la operación ha fallado.

Véase también canAt().

bool QQmlListReference::canAppend() const

Devuelve «true» si se pueden añadir elementos al final de la propiedad «list»; en caso contrario, devuelve «false». Devuelve «false» si la referencia no es válida.

Véase también ` append()`.

bool QQmlListReference::canAt() const

Devuelve «true» si la propiedad de la lista puede consultarse por índice; en caso contrario, devuelve «false». Devuelve «false» si la referencia no es válida.

Véase también ` at()`.

bool QQmlListReference::canClear() const

Devuelve «true» si la propiedad «list» se puede borrar; en caso contrario, devuelve «false». Devuelve «false» si la referencia no es válida.

Véase también clear().

bool QQmlListReference::canCount() const

Devuelve «true» si se puede consultar el número de elementos de la propiedad «list»; en caso contrario, devuelve «false». Devuelve «false» si la referencia no es válida.

Véase también count().

bool QQmlListReference::canRemoveLast() const

Devuelve «true» si se puede eliminar el último elemento de la propiedad «list»; en caso contrario, devuelve «false». Devuelve «false» si la referencia no es válida.

Véase también ` removeLast()`.

bool QQmlListReference::canReplace() const

Devuelve «true» si los elementos de la propiedad «list» se pueden sustituir; en caso contrario, devuelve «false». Devuelve «false» si la referencia no es válida.

Véase también replace().

bool QQmlListReference::clear() const

Borra la lista. Devuelve «true» si la operación se ha realizado correctamente; en caso contrario, devuelve «false».

Véase también canClear().

qsizetype QQmlListReference::count() const

Devuelve el número de elementos de la lista, o 0 si la operación ha fallado.

bool QQmlListReference::isManipulable() const

Devuelve «true» si se han implementado at(), count(), append() y, además, clear() o removeLast(), de modo que puedas manipular la lista.

Ten en cuenta que replace() y removeLast() pueden emularse guardando todos los elementos y reconstruyendo la lista mediante clear() y append(). Por lo tanto, no son necesarios para que la lista sea manipulable. Además, clear() puede emularse utilizando removeLast().

Véanse también isReadable(), at(), count(), append(), clear(), replace() y removeLast().

bool QQmlListReference::isReadable() const

Devuelve «true» si se han implementado las funciones at() y count(), de modo que se pueda acceder a los elementos.

Véase también isManipulable(), at() y count().

bool QQmlListReference::isValid() const

Devuelve «true» si la instancia hace referencia a una propiedad de lista válida; en caso contrario, devuelve «false».

const QMetaObject *QQmlListReference::listElementType() const

Devuelve el ` QMetaObject ` correspondiente a los elementos almacenados en la propiedad «list», o ` nullptr ` si la referencia no es válida.

El ` QMetaObject ` se puede utilizar con antelación para determinar si una instancia determinada se puede añadir a una lista. Si no se ha pasado un motor al crear la lista, esto puede devolver `nullptr`.

QObject *QQmlListReference::object() const

Devuelve el objeto de la propiedad «list». Devuelve « nullptr » si la referencia no es válida.

bool QQmlListReference::removeLast() const

Elimina el último elemento de la lista. Devuelve «true» si la operación se ha realizado correctamente; en caso contrario, devuelve «false».

Véase también canRemoveLast().

bool QQmlListReference::replace(qsizetype index, QObject *object) const

Sustituye el elemento de la lista que se encuentra en index por object. Devuelve «true» si la operación se ha realizado correctamente; en caso contrario, devuelve «false».

Véase también canReplace().

[since 6.2] qsizetype QQmlListReference::size() const

Devuelve el número de elementos de la lista, o 0 si la operación ha fallado.

Esta función se introdujo en Qt 6.2.

bool QQmlListReference::operator==(const QQmlListReference &other) const

Compara este objeto QQmlListReference con other y devuelve true si son iguales. Ambos se consideran iguales únicamente si uno se ha creado a partir del otro mediante una asignación por copia o una construcción por copia.

Nota: Las referencias creadasde forma independiente que apuntan al mismo objeto no se consideran iguales.

© 2026 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.