Back to Qt.io
Contact Us Blog Download Qt
Sur cette page

QQmlListProperty Class

template <typename T> class QQmlListProperty

La classe `QQmlListProperty` permet aux applications d'exposer à QML les propriétés de type liste des classes dérivées de ` QObject`. En savoir plus...

En-tête : #include <QQmlListProperty>
CMake : find_package(Qt6 REQUIRED COMPONENTS Qml)
target_link_libraries(mytarget PRIVATE Qt6::Qml)
qmake : QT += qml

Types publics

AppendFunction
AtFunction
ClearFunction
CountFunction
RemoveLastFunction
ReplaceFunction

Fonctions publiques

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 publiques

void *data
QObject *object

Macros

QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_APPEND
QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE
QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE_IF_NOT_DEFAULT

Description détaillée

QML dispose de nombreuses propriétés de type liste, auxquelles il est possible d’attribuer plusieurs valeurs d’objet. L’utilisation d’une propriété de type liste en QML se présente comme suit :

FruitBasket {
    fruit: [
        Apple {},
        Orange{},
        Banana{}
    ]
}

La classe QQmlListProperty encapsule un ensemble de pointeurs de fonction représentant les actions que QML peut effectuer sur la liste : ajouter des éléments, récupérer des éléments et vider la liste. À l'avenir, d'autres opérations pourraient être prises en charge. Toutes les propriétés de liste doivent implémenter l'opération d'ajout, mais les autres sont facultatives.

Pour fournir une propriété de liste, une classe C++ doit implémenter les rappels d’opération, puis renvoyer une valeur QQmlListProperty appropriée via le getter de la propriété. Les propriétés de liste ne doivent pas comporter de setter. Dans l’exemple ci-dessus, la déclaration Q_PROPERTY() se présentera comme suit :

Q_PROPERTY(QQmlListProperty<Fruit> fruit READ fruit)

Les propriétés de liste QML sont sécurisées au niveau des types. Le paramètre de modèle T spécifie le type dérivé de QObject qui peut être stocké dans la liste. Dans ce cas, Fruit est un type QObject dont dérivent Apple, Orange et Banana.

Vous pouvez utiliser QQmlListReference pour manipuler un QQmlListProperty depuis C++ à l’aide d’une API légèrement plus ergonomique, au prix d’une légère surcharge.

Voir également le chapitre 5 : Utilisation des types de propriétés de liste et QQmlListReference.

Documentation sur les types de membres

[alias] QQmlListProperty::AppendFunction

Synonyme de « void (*)(QQmlListProperty<T> *property, T *value) ».

Ajouter l'value à la liste property.

[alias] QQmlListProperty::AtFunction

Synonyme de « T *(*)(QQmlListProperty<T> *property, qsizetype index) ».

Renvoie l'élément situé à la position index dans la liste property.

[alias] QQmlListProperty::ClearFunction

Synonyme de « void (*)(QQmlListProperty<T> *property) ».

Effacer la liste « property ».

[alias] QQmlListProperty::CountFunction

Synonyme de « qsizetype (*)(QQmlListProperty<T> *property) ».

Renvoie le nombre d'éléments de la liste property.

[alias] QQmlListProperty::RemoveLastFunction

Synonyme de « void (*)(QQmlListProperty<T> *property) ».

Supprimer le dernier élément de la liste property.

[alias] QQmlListProperty::ReplaceFunction

Synonyme de void (*)(QQmlListProperty<T> *property, qsizetype index, T *value).

Remplacer l'élément situé à la position index dans la liste property par value.

Documentation des fonctions membres

QQmlListProperty::QQmlListProperty(QObject *object, QList<T *> *list)

Constructeur pratique permettant de créer une valeur QQmlListProperty à partir d’un QList existant list. L’ object, qui contient la liste, et l’ list lui-même doivent être fournis et maintenus actifs tant que vous détenez une instance de QQmlListProperty qui y fait référence.

Il s'agit de la méthode la plus simple et la plus sûre pour fournir une propriété `QQmlListProperty` adossée à une ` QList ` ; elle doit être utilisée dans la plupart des cas. Un appel type se présente comme suit :

QQmlListProperty<PieSlice> PieChart::slices()
{
    return QQmlListProperty<PieSlice>(this, &m_slices);
}

QQmlListProperty::QQmlListProperty(QObject *object, void *data, QQmlListProperty<T>::CountFunction count, QQmlListProperty<T>::AtFunction at)

Construisez une propriété QQmlListProperty en lecture seule à partir d'un ensemble de fonctions d'opération count et at. Il est possible de passer un descripteur data opaque, accessible depuis les fonctions d'opération. La propriété de liste reste valide tant que l'object, propriétaire de cette propriété, existe.

QQmlListProperty::QQmlListProperty(QObject *object, void *data, QQmlListProperty<T>::AppendFunction append, QQmlListProperty<T>::CountFunction count, QQmlListProperty<T>::AtFunction at, QQmlListProperty<T>::ClearFunction clear)

Construisez une propriété `QQmlListProperty` à partir d’un ensemble de fonctions d’opération : append, count, at et clear. Il est possible de passer un descripteur opaque ` data `, accessible depuis l’intérieur des fonctions d’opération. La propriété de liste reste valide tant que l’ object, propriétaire de cette propriété, existe.

Des pointeurs nuls peuvent être transmis à n’importe quelle fonction. Si des pointeurs nuls sont transmis, la liste ne pourra être ni modélisée ni modifiée par le débogueur. Il est recommandé de fournir des pointeurs valides pour toutes les fonctions.

Remarque : la propriété ` QQmlListProperty` résultante synthétisera les méthodes `removeLast()` et `replace()` à l’aide de ` count`, ` at`, ` clear` et ` append ` si toutes ces méthodes sont fournies. Ce processus est lent. Si vous avez l’intention de manipuler la liste au-delà de son effacement, vous devez fournir explicitement ces méthodes.

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)

Construire une propriété QQmlListProperty à partir d’un ensemble de fonctions d’opération : append, count, at, clear, replace et removeLast. Il est possible de passer un descripteur opaque data, accessible depuis l’intérieur des fonctions d’opération. La propriété de liste reste valide tant que l’ object, propriétaire de cette propriété, existe.

Des pointeurs nuls peuvent être transmis à n’importe quelle fonction, ce qui entraîne la synthèse de la fonction correspondante à l’aide des autres, si possible. QQmlListProperty peut synthétiser

  • clear à l’aide de count et removeLast
  • replace « using count », « at », « clear » et append
  • replace using count, at, removeLast et append
  • removeLast en utilisant count, at, clear, et append

si celles-ci sont fournies. Cette méthode est lente, mais si votre liste ne propose pas d’options plus rapides pour ces primitives, vous pouvez utiliser celles qui ont été synthétisées.

De plus, si l’une des fonctions suivantes : count, at, append ou clear n’est ni fournie explicitement ni synthétisée, la liste ne pourra être ni modifiée ni altérée par le débogueur. Il est recommandé de fournir suffisamment de pointeurs valides pour éviter cette situation.

bool QQmlListProperty::operator==(const QQmlListProperty<T> &other) const

Renvoie « true » si cette QQmlListProperty est égale à other, sinon « false ».

Documentation sur les variables membres

void *QQmlListProperty::data

Ce champ peut contenir un pointeur de données arbitraire

Si vous implémentez manuellement les méthodes d’accès et que vous avez besoin de stocker des données personnalisées, vous pouvez passer un pointeur arbitraire au constructeur de l’ QQmlListProperty et le récupérer à partir du champ « data » lorsque vous accédez à cette même QQmlListProperty ultérieurement.

Un ` QQmlListProperty constructed from a QList pointer ` utilise ce champ pour stocker le pointeur vers la liste elle-même, car il ne peut pas accéder directement au contenu de la liste à partir de son propriétaire.

QObject *QQmlListProperty::object

Ce champ contient le propriétaire de la QQmlListProperty

Lorsque vous implémentez manuellement les méthodes d'accès, vous pouvez avoir besoin d'utiliser ce champ pour récupérer le contenu de la liste manipulée.

Documentation sur les macros

QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_APPEND

Cette macro définit le comportement des propriétés de liste de cette classe sur « Append ». Lors de l'affectation de la propriété dans un type dérivé, les valeurs sont ajoutées à celles de la classe de base. Il s'agit du comportement par défaut.

class FruitBasket : QObject {
    Q_OBJECT
    QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_APPEND
    Q_PROPERTY(QQmlListProperty<Fruit> fruit READ fruit)

    public:
    // ...
    QQmlListProperty<Fruit> fruit();
    // ...
};

Voir également « QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE_IF_NOT_DEFAULT» ( Définition de types d'objets via des documents QML), « QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE » ( Définition de types d'objets via des documents QML) et «Defining Object Types through QML Documents» (Définition de types d'objets via des documents QML).

QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE

Cette macro définit le comportement des propriétés de liste de cette classe sur « Replace ». Lors de l'affectation de la propriété dans un type dérivé, les valeurs remplacent celles de la classe de base.

class FruitBasket : QObject {
    Q_OBJECT
    QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE
    Q_PROPERTY(QQmlListProperty<Fruit> fruit READ fruit)

    public:
    // ...
    QQmlListProperty<Fruit> fruit();
    // ...
};

Voir également « QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_APPEND », « QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE_IF_NOT_DEFAULT » et « Définition de types d'objets via des documents QML ».

QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE_IF_NOT_DEFAULT

Cette macro définit le comportement des propriétés de liste de cette classe sur « ReplaceIfNotDefault ». Lors de l'affectation d'une valeur à une propriété dans un type dérivé, celle-ci remplace celle de la classe de base, sauf s'il s'agit de la propriété par défaut. Dans le cas de la propriété par défaut, les valeurs sont ajoutées à celles de la classe de 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();
    // ...
};

Voir également « QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_APPEND» ( Définition de types d’objets via des documents QML), « QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE » ( Définition de types d’objets via des documents QML) et «Defining Object Types through QML Documents» (Définition de types d’objets via des documents 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.