QQmlListProperty Class
template <typename T> class QQmlListPropertyLa clase `QQmlListProperty` permite a las aplicaciones exponer en QML propiedades de tipo lista de las clases derivadas de ` QObject`. Más información...
| Encabezado: | #include <QQmlListProperty> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Qml) target_link_libraries(mytarget PRIVATE Qt6::Qml) |
| qmake: | QT += qml |
Tipos públicos
Funciones públicas
| QQmlListProperty(QObject *object, QList<T *> *list) | |
| QQmlListProperty(QObject *object, void *data, QQmlListProperty<T>::CountFunction count, QQmlListProperty<T>::AtFunction at) | |
| QQmlListProperty(QObject *object, void *data, QQmlListProperty<T>::AppendFunction append, QQmlListProperty<T>::CountFunction count, QQmlListProperty<T>::AtFunction at, QQmlListProperty<T>::ClearFunction clear) | |
| QQmlListProperty(QObject *object, void *data, QQmlListProperty<T>::AppendFunction append, QQmlListProperty<T>::CountFunction count, QQmlListProperty<T>::AtFunction at, QQmlListProperty<T>::ClearFunction clear, QQmlListProperty<T>::ReplaceFunction replace, QQmlListProperty<T>::RemoveLastFunction removeLast) | |
| bool | operator==(const QQmlListProperty<T> &other) const |
Variables públicas
Macros
| QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_APPEND | |
| QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE | |
| QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE_IF_NOT_DEFAULT |
Descripción detallada
QML cuenta con numerosas propiedades de lista, a las que se puede asignar más de un valor de objeto. El uso de una propiedad de lista en QML tiene el siguiente aspecto:
FruitBasket {
fruit: [
Apple {},
Orange{},
Banana{}
]
}La clase `QQmlListProperty` encapsula un grupo de punteros a funciones que representan el conjunto de acciones que QML puede realizar sobre la lista: añadir elementos, recuperar elementos y vaciar la lista. En el futuro, es posible que se admitan operaciones adicionales. Todas las propiedades de lista deben implementar la operación de añadir elementos, pero el resto son opcionales.
Para proporcionar una propiedad de lista, una clase de C++ debe implementar las funciones de llamada de retorno de las operaciones y, a continuación, devolver un valor QQmlListProperty adecuado desde el getter de la propiedad. Las propiedades de lista no deben tener setter. En el ejemplo anterior, la declaración Q_PROPERTY() tendrá el siguiente aspecto:
Q_PROPERTY(QQmlListProperty<Fruit> fruit READ fruit)Las propiedades de lista de QML son seguras en cuanto al tipo. El parámetro de plantilla ` T ` especifica el tipo derivado de ` QObject` que se puede almacenar en la lista. En este caso, ` Fruit ` es un tipo ` QObject ` del que se derivan ` Apple`, ` Orange ` y ` Banana `.
Puedes utilizar QQmlListReference para manipular un QQmlListProperty desde C++ mediante una API ligeramente más ergonómica, a costa de una cierta sobrecarga.
Véase también el capítulo 5: Uso de tipos de propiedades de lista y QQmlListReference.
Documentación sobre los tipos de miembros
[alias] QQmlListProperty::AppendFunction
Sinónimo de void (*)(QQmlListProperty<T> *property, T *value).
Añade el value a la lista property.
[alias] QQmlListProperty::AtFunction
Sinónimo de « T *(*)(QQmlListProperty<T> *property, qsizetype index) ».
Devuelve el elemento situado en la posición index de la lista property.
[alias] QQmlListProperty::ClearFunction
Sinónimo de « void (*)(QQmlListProperty<T> *property) ».
Borrar la lista « property ».
[alias] QQmlListProperty::CountFunction
Sinónimo de « qsizetype (*)(QQmlListProperty<T> *property) ».
Devuelve el número de elementos de la lista property.
[alias] QQmlListProperty::RemoveLastFunction
Sinónimo de « void (*)(QQmlListProperty<T> *property) ».
Elimina el último elemento de la lista property.
[alias] QQmlListProperty::ReplaceFunction
Sinónimo de void (*)(QQmlListProperty<T> *property, qsizetype index, T *value).
Sustituye el elemento situado en la posición index de la lista property por value.
Documentación de funciones de miembro
QQmlListProperty::QQmlListProperty(QObject *object, QList<T *> *list)
Constructor de conveniencia para crear un valor de `QQmlListProperty` a partir de un ` QList ` ya existente list. Se deben proporcionar tanto el ` object ` que contiene la lista como el propio ` list `, y deben mantenerse activos mientras se mantenga una referencia a ellos mediante un `QQmlListProperty`.
Esta es la forma más sencilla y segura de proporcionar un `QQmlListProperty` respaldado por un ` QList ` y debería utilizarse en la mayoría de los casos. Una invocación típica tiene este aspecto:
QQmlListProperty<PieSlice> PieChart::slices()
{
return QQmlListProperty<PieSlice>(this, &m_slices);
}QQmlListProperty::QQmlListProperty(QObject *object, void *data, QQmlListProperty<T>::CountFunction count, QQmlListProperty<T>::AtFunction at)
Crea una propiedad QQmlListProperty de solo lectura a partir de un conjunto de funciones de operación count y at. Se puede pasar un identificador opaco data al que se puede acceder desde dentro de las funciones de operación. La propiedad de lista sigue siendo válida mientras exista el object propietario de dicha propiedad.
QQmlListProperty::QQmlListProperty(QObject *object, void *data, QQmlListProperty<T>::AppendFunction append, QQmlListProperty<T>::CountFunction count, QQmlListProperty<T>::AtFunction at, QQmlListProperty<T>::ClearFunction clear)
Crea una QQmlListProperty a partir de un conjunto de funciones de operación: append, count, at y clear. Se puede pasar un identificador opaco de data, al que se puede acceder desde dentro de las funciones de operación. La propiedad de lista sigue siendo válida mientras exista la object propietaria de dicha propiedad.
Se pueden pasar punteros nulos a cualquier función. Si se pasan punteros nulos, la lista no podrá ser diseñada ni modificada por el depurador. Se recomienda proporcionar punteros válidos para todas las funciones.
Nota: La propiedad QQmlListProperty resultante sintetizará los métodos `removeLast()` y `replace()` utilizando ` count`, ` at`, ` clear` y ` append ` si se proporcionan todos ellos. Este proceso es lento. Si pretendes manipular la lista más allá de borrarla, debes proporcionar explícitamente estos métodos.
QQmlListProperty::QQmlListProperty(QObject *object, void *data, QQmlListProperty<T>::AppendFunction append, QQmlListProperty<T>::CountFunction count, QQmlListProperty<T>::AtFunction at, QQmlListProperty<T>::ClearFunction clear, QQmlListProperty<T>::ReplaceFunction replace, QQmlListProperty<T>::RemoveLastFunction removeLast)
Crea una propiedad QQmlListProperty a partir de un conjunto de funciones de operación: append, count, at, clear, replace y removeLast. Se puede pasar un identificador opaco de data, al que se puede acceder desde el interior de las funciones de operación. La propiedad de lista sigue siendo válida mientras exista el object propietario de dicha propiedad.
Se pueden pasar punteros nulos a cualquier función, lo que hace que la función correspondiente se sintetice utilizando las demás, si es posible. QQmlListProperty puede sintetizarse
- clear utilizando count y removeLast
- replace count, , y at clear append
- replace using count, at, removeLast y append
- removeLast utilizando count, at, clear y append
si se proporcionan. Esto es lento, pero si tu lista no ofrece de forma nativa opciones más rápidas para estas primitivas, quizá te interese utilizar las sintetizadas.
Además, si ninguna de las siguientes funciones — count, at, append y clear — se proporciona explícitamente ni se sintetiza, la lista no podrá ser diseñada ni modificada por el depurador. Se recomienda proporcionar suficientes punteros válidos para evitar esta situación.
bool QQmlListProperty::operator==(const QQmlListProperty<T> &other) const
Devuelve «true» si este QQmlListProperty es igual a other; en caso contrario, devuelve «false».
Documentación de variables de miembro
void *QQmlListProperty::data
Este campo puede contener un puntero a datos arbitrarios
Si implementas manualmente los métodos de acceso y necesitas almacenar datos personalizados, puedes pasar un puntero arbitrario al constructor de ` QQmlListProperty ` y recuperarlo del campo `data ` cuando accedas posteriormente a ese mismo ` QQmlListProperty `.
Un ` QQmlListProperty constructed from a QList pointer ` utiliza este campo para almacenar el puntero a la propia lista, ya que no puede acceder directamente al contenido de la lista desde el propietario.
QObject *QQmlListProperty::object
Este campo contiene el propietario de la QQmlListProperty
Al implementar manualmente los métodos de acceso, es posible que necesites utilizar este campo para recuperar el contenido de la lista manipulada.
Documentación de macros
QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_APPEND
Esta macro define el comportamiento de las propiedades de lista de esta clase como «Append». Al asignar la propiedad en un tipo derivado, los valores se añaden a los de la clase base. Este es el comportamiento predeterminado.
class FruitBasket : QObject {
Q_OBJECT
QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_APPEND
Q_PROPERTY(QQmlListProperty<Fruit> fruit READ fruit)
public:
// ...
QQmlListProperty<Fruit> fruit();
// ...
};Véase también « QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE_IF_NOT_DEFAULT» , « QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE » y «Definición de tipos de objetos mediante documentos QML».
QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE
Esta macro define el comportamiento de las propiedades de lista de esta clase como «Reemplazar». Al asignar la propiedad en un tipo derivado, los valores sustituyen a los de la clase base.
class FruitBasket : QObject {
Q_OBJECT
QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE
Q_PROPERTY(QQmlListProperty<Fruit> fruit READ fruit)
public:
// ...
QQmlListProperty<Fruit> fruit();
// ...
};Véase también « QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_APPEND» , « QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE_IF_NOT_DEFAULT » y «Definición de tipos de objetos mediante documentos QML».
QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE_IF_NOT_DEFAULT
Esta macro define el comportamiento de las propiedades de lista de esta clase como «ReplaceIfNotDefault». Al asignar la propiedad en un tipo derivado, los valores sustituyen a los de la clase base, salvo que se trate de la propiedad por defecto. En el caso de la propiedad por defecto, los valores se añaden a los de la clase base.
class FruitBasket : QObject {
Q_OBJECT
QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE_IF_NOT_DEFAULT
Q_PROPERTY(QQmlListProperty<Fruit> fruit READ fruit)
public:
// ...
QQmlListProperty<Fruit> fruit();
// ...
};Véase también « QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_APPEND» , « QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE » y «Definición de tipos de objetos mediante documentos QML».
© 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.