Back to Qt.io
Contact Us Blog Download Qt
Auf dieser Seite

QQmlListProperty Class

template <typename T> class QQmlListProperty

Die Klasse „QQmlListProperty“ ermöglicht es Anwendungen, listenähnliche Eigenschaften von Klassen, die von „ QObject “ abgeleitet sind, für QML verfügbar zu machen. Mehr...

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

Öffentliche Typen

AppendFunction
AtFunction
ClearFunction
CountFunction
RemoveLastFunction
ReplaceFunction

Öffentliche Funktionen

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

Öffentliche Variablen

void *data
QObject *object

Makros

QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_APPEND
QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE
QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE_IF_NOT_DEFAULT

Ausführliche Beschreibung

QML verfügt über zahlreiche Listen-Eigenschaften, denen mehr als ein Objektwert zugewiesen werden kann. Die Verwendung einer Listen-Eigenschaft in QML sieht wie folgt aus:

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

Die QQmlListProperty kapselt eine Gruppe von Funktionszeigern, die die Aktionen repräsentieren, die QML an der Liste ausführen kann – Hinzufügen von Elementen, Abrufen von Elementen und Löschen der Liste. In Zukunft werden möglicherweise weitere Operationen unterstützt. Alle Listen-Eigenschaften müssen die Operation „append“ implementieren, die übrigen sind optional.

Um eine Listen-Eigenschaft bereitzustellen, muss eine C++-Klasse die Operations-Callbacks implementieren und anschließend über den Getter der Eigenschaft einen entsprechenden QQmlListProperty-Wert zurückgeben. Listen-Eigenschaften sollten keinen Setter haben. Im obigen Beispiel sieht die Deklaration ` Q_PROPERTY()` wie folgt aus:

Q_PROPERTY(QQmlListProperty<Fruit> fruit READ fruit)

QML-Listen-Eigenschaften sind typsicher. Der Template-Parameter ` T ` gibt den von ` QObject` abgeleiteten Typ an, der in der Liste gespeichert werden kann. In diesem Fall ist ` Fruit ` ein ` QObject `-Typ, von dem ` Apple`, ` Orange ` und ` Banana ` alle abgeleitet sind.

Mit „ QQmlListReference “ können Sie eine `QQmlListProperty` von C++ aus über eine etwas benutzerfreundlichere API bearbeiten, was jedoch mit einem gewissen Mehraufwand verbunden ist.

Siehe auch Kapitel 5: Verwendung von Listen-Eigenschaftstypen und QQmlListReference.

Dokumentation zu Mitgliedstypen

[alias] QQmlListProperty::AppendFunction

Synonym für „ void (*)(QQmlListProperty<T> *property, T *value) “.

Füge den „ value “ zur Liste „ property “ hinzu.

[alias] QQmlListProperty::AtFunction

Synonym für „ T *(*)(QQmlListProperty<T> *property, qsizetype index) “.

Gibt das Element an der Position „ index “ in der Liste „ property “ zurück.

[alias] QQmlListProperty::ClearFunction

Synonym für „ void (*)(QQmlListProperty<T> *property) “.

Liste „ property “ löschen.

[alias] QQmlListProperty::CountFunction

Synonym für „ qsizetype (*)(QQmlListProperty<T> *property) “.

Gibt die Anzahl der Elemente in der Liste „ property “ zurück.

[alias] QQmlListProperty::RemoveLastFunction

Synonym für „ void (*)(QQmlListProperty<T> *property) “.

Entferne das letzte Element aus der Liste „ property “.

[alias] QQmlListProperty::ReplaceFunction

Synonym für void (*)(QQmlListProperty<T> *property, qsizetype index, T *value).

Ersetze das Element an der Position ` index ` in der Liste ` property ` durch ` value`.

Dokumentation der Member-Funktionen

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

Komfortkonstruktor zum Erstellen eines QQmlListProperty-Werts aus einem vorhandenen QList list . Die object, die die Liste verwaltet, und die list selbst müssen bereitgestellt und so lange aufrechterhalten werden, wie Sie eine QQmlListProperty halten, die auf sie verweist.

Dies ist die einfachste und sicherste Methode, um eine QQmlListProperty bereitzustellen, die auf einer ` QList ` basiert, und sollte in den meisten Fällen verwendet werden. Ein typischer Aufruf sieht wie folgt aus:

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

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

Erstellen Sie eine schreibgeschützte `QQmlListProperty` aus einer Reihe von Operationsfunktionen: count und at. Es kann ein undurchsichtiges ` data `-Handle übergeben werden, auf das innerhalb der Operationsfunktionen zugegriffen werden kann. Die Listen-Eigenschaft bleibt gültig, solange das ` object `, dem die Listen-Eigenschaft gehört, existiert.

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

Erstellen Sie eine `QQmlListProperty` aus einer Reihe von Operationsfunktionen: ` append`, ` count`, ` at` und ` clear`. Es kann ein undurchsichtiges ` data `-Handle übergeben werden, auf das innerhalb der Operationsfunktionen zugegriffen werden kann. Die Listen-Eigenschaft bleibt gültig, solange das ` object `, dem die Listen-Eigenschaft gehört, existiert.

Für jede Funktion können Null-Zeiger übergeben werden. Werden Null-Zeiger übergeben, kann die Liste vom Debugger weder dargestellt noch geändert werden. Es wird empfohlen, für alle Funktionen gültige Zeiger anzugeben.

Hinweis: Die resultierende `QQmlListProperty` synthetisiert die Methoden `removeLast()` und `replace()` unter Verwendung von ` count`, ` at`, ` clear` und ` append `, sofern alle diese Methoden angegeben sind. Dies ist langsam. Wenn Sie beabsichtigen, die Liste über das Löschen hinaus zu bearbeiten, sollten Sie diese Methoden explizit bereitstellen.

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)

Erstellen Sie eine `QQmlListProperty` aus einer Reihe von Operationsfunktionen: ` append`, ` count`, ` at`, ` clear`, ` replace` und ` removeLast`. Es kann ein undurchsichtiges ` data `-Handle übergeben werden, auf das innerhalb der Operationsfunktionen zugegriffen werden kann. Die Listen-Eigenschaft bleibt gültig, solange die ` object `, die die Listen-Eigenschaft besitzt, existiert.

Für jede Funktion können Null-Zeiger übergeben werden, was dazu führt, dass die jeweilige Funktion, sofern möglich, mithilfe der anderen Funktionen synthetisiert wird. QQmlListProperty kann

  • clear unter Verwendung von count und removeLast
  • replace count, , sowie at clear append
  • replace count, , sowie at removeLast append
  • removeLast unter Verwendung von count, at, clear und append

sofern diese angegeben sind. Dies ist langsam, aber wenn Ihre Liste keine nativen, schnelleren Optionen für diese Primitive bietet, sollten Sie möglicherweise die synthetisierten verwenden.

Wenn darüber hinaus entweder count, at, append oder clear weder explizit angegeben noch synthetisiert sind, ist die Liste weder entwerfbar noch durch den Debugger veränderbar. Es wird empfohlen, genügend gültige Zeiger bereitzustellen, um diese Situation zu vermeiden.

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

Gibt „true“ zurück, wenn diese „ QQmlListProperty “ mit „ other “ übereinstimmt, andernfalls „false“.

Dokumentation zu Member-Variablen

void *QQmlListProperty::data

Dieses Feld kann einen beliebigen Datenzeiger enthalten

Wenn Sie die Zugriffsmethoden manuell implementieren und benutzerdefinierte Daten speichern müssen, können Sie einen beliebigen Zeiger an den Konstruktor von ` QQmlListProperty ` übergeben und diesen später beim Zugriff auf denselben ` QQmlListProperty ` aus dem Datenfeld abrufen.

Ein ` QQmlListProperty constructed from a QList pointer ` verwendet dieses Feld, um den Zeiger auf die Liste selbst zu speichern, da er nicht direkt auf den Inhalt der Liste über den Eigentümer zugreifen kann.

QObject *QQmlListProperty::object

Dieses Feld enthält den Eigentümer der QQmlListProperty

Bei der manuellen Implementierung der Zugriffsmethoden müssen Sie dieses Feld möglicherweise verwenden, um den Inhalt der bearbeiteten Liste abzurufen.

Makro-Dokumentation

QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_APPEND

Dieses Makro legt fest, dass die Listen-Eigenschaften dieser Klasse auf „Append“ gesetzt werden. Bei der Zuweisung der Eigenschaft in einem abgeleiteten Typ werden die Werte an die der Basisklasse angehängt. Dies ist das Standardverhalten.

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

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

Siehe auch „ QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE_IF_NOT_DEFAULT“ , „ QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE “ und „Defining Object Types through QML Documents“.

QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE

Dieses Makro legt das Verhalten der Listeneigenschaften dieser Klasse auf „Ersetzen“ fest. Bei der Zuweisung der Eigenschaft in einem abgeleiteten Typ ersetzen die Werte diejenigen der Basisklasse.

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

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

Siehe auch „ QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_APPEND“ , „ QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE_IF_NOT_DEFAULT “ und „Defining Object Types through QML Documents“.

QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE_IF_NOT_DEFAULT

Dieses Makro legt das Verhalten der Listeneigenschaften dieser Klasse auf „ReplaceIfNotDefault“ fest. Beim Zuweisen der Eigenschaft in einem abgeleiteten Typ ersetzen die Werte diejenigen der Basisklasse, es sei denn, es handelt sich um die Standardeigenschaft. Im Falle der Standardeigenschaft werden die Werte an diejenigen der Basisklasse angehängt.

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();
    // ...
};

Siehe auch „ QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_APPEND“ , „ QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE “ und „Defining Object Types through QML Documents“.

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