QQmlListProperty Class

template <typename T> class QQmlListProperty

QQmlListProperty 클래스를 사용하면 응용 프로그램에서 QObject 파생 클래스의 목록과 같은 속성을 QML에 노출할 수 있습니다. 더 보기...

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

공용 타입

공용 함수

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

공용 변수

void *data
QObject *object

매크로

상세 설명

QML에는 둘 이상의 객체 값을 할당할 수 있는 목록 프로퍼티가 많이 있습니다. QML에서 목록 프로퍼티를 사용하는 방법은 다음과 같습니다:

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

QQmlListProperty는 QML이 목록에서 수행할 수 있는 일련의 작업(항목 추가, 항목 검색, 목록 지우기 등)을 나타내는 함수 포인터 그룹을 캡슐화합니다. 향후에는 추가 작업이 지원될 수 있습니다. 모든 목록 속성은 추가 연산을 구현해야 하지만 나머지는 선택 사항입니다.

목록 프로퍼티를 제공하려면 C++ 클래스가 연산 콜백을 구현한 다음 프로퍼티 게터에서 적절한 QQmlListProperty 값을 반환해야 합니다. 목록 프로퍼티에는 설정자가 없어야 합니다. 위의 예에서 Q_PROPERTY() 선언문은 다음과 같습니다:

Q_PROPERTY(QQmlListProperty<Fruit> fruit READ fruit)

이 경우 FruitQObject 유형이며 Apple, OrangeBanana 모두 이 유형에서 파생됩니다.

QQmlListReference 을 사용하면 약간의 오버헤드가 발생하지만 조금 더 인체공학적인 API를 사용하여 C++에서 QQmlListProperty를 조작할 수 있습니다.

5장: 리스트 프로퍼티 유형 사용하기QQmlListReference참조하세요 .

멤버 유형 문서

[alias] QQmlListProperty::AppendFunction

void (*)(QQmlListProperty<T> *property, T *value) 의 동의어 .

목록에 value 를 추가합니다 property.

[alias] QQmlListProperty::AtFunction

동의어 T *(*)(QQmlListProperty<T> *property, qsizetype index).

목록의 index 위치에 있는 요소를 반환합니다 property.

[alias] QQmlListProperty::ClearFunction

동의어 void (*)(QQmlListProperty<T> *property).

목록 지우기 property.

[alias] QQmlListProperty::CountFunction

qsizetype (*)(QQmlListProperty<T> *property) 의 동의어.

목록에 있는 요소의 개수를 반환합니다 property.

[alias] QQmlListProperty::RemoveLastFunction

동의어 void (*)(QQmlListProperty<T> *property).

목록에서 마지막 요소를 제거합니다 property.

[alias] QQmlListProperty::ReplaceFunction

void (*)(QQmlListProperty<T> *property, qsizetype index, T *value) 의 동의어.

목록 property 에서 index 위치의 요소를 value 로 바꿉니다.

멤버 함수 문서

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

기존 QList list 에서 QQmlListProperty 값을 만들기 위한 편의 생성자. 목록을 소유하는 objectlist 자체는 반드시 제공되어야 하며, 이를 참조하는 QQmlListProperty를 보유하고 있는 한 유지되어야 합니다.

이는 QList 으로 뒷받침되는 QQmlListProperty를 제공하는 가장 쉽고 안전한 방법이며 대부분의 경우에 사용해야 합니다. 일반적인 호출은 다음과 같습니다:

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

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

countat 연산 함수 집합에서 읽기 전용 QQmlListProperty를 구성합니다. 연산 함수 내에서 액세스할 수 있는 불투명한 data 핸들을 전달할 수 있습니다. 목록 속성을 소유하는 object 이 존재하는 동안 목록 속성은 유효하게 유지됩니다.

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

일련의 연산 함수 append, count, at, clear 로부터 QQmlListProperty를 구성합니다. 연산 함수 내에서 액세스할 수 있는 불투명한 data 핸들을 전달할 수 있습니다. 목록 속성을 소유하는 object 이 존재하는 동안 목록 속성은 유효합니다.

모든 함수에 대해 널 포인터를 전달할 수 있습니다. 널 포인터가 전달되면 디버거에서 목록을 디자인하거나 변경할 수 없습니다. 모든 함수에 대해 유효한 포인터를 제공하는 것이 좋습니다.

참고: 결과 QQmlListProperty는 count, at, clear, append 을 사용하여 removeLast() 및 replace() 메서드를 합성합니다(모두 제공된 경우). 이는 느립니다. 목록을 지우는 것 이상으로 조작하려는 경우 이러한 메서드를 명시적으로 제공해야 합니다.

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)

append, count, at, clear, replace, removeLast 연산 함수 집합으로 QQmlListProperty를 구성합니다. 연산 함수 내에서 액세스할 수 있는 불투명한 data 핸들을 전달할 수 있습니다. 목록 속성을 소유한 object 이 존재하는 동안 목록 속성은 유효합니다.

모든 함수에 대해 널 포인터를 전달할 수 있으며, 가능한 경우 해당 함수가 다른 함수를 사용하여 합성되도록 할 수 있습니다. QQmlListProperty는 다음과 같이 합성할 수 있습니다.

  • clear 사용 countremoveLast
  • replace count , at, clear, 그리고 append
  • replace count , at, removeLast, 및 append
  • removeLast count , at, clear, 그리고 append

를 사용할 수 있습니다. 이 방법은 느리지만 목록에서 기본적으로 이러한 프리미티브에 대해 더 빠른 옵션을 제공하지 않는 경우 합성된 옵션을 사용할 수 있습니다.

또한 count, at, append, clear 중 어느 것도 명시적으로 제공되지 않거나 합성되지 않은 경우 디버거에서 목록을 설계하거나 변경할 수 없습니다. 이러한 상황을 피하기 위해 유효한 포인터를 충분히 제공하는 것이 좋습니다.

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

QQmlListPropertyother 과 같으면 참을 반환하고, 그렇지 않으면 거짓을 반환합니다.

멤버 변수 문서

void *QQmlListProperty::data

이 필드에는 임의의 데이터 포인터를 저장할 수 있습니다.

접근자 메서드를 수동으로 구현하고 사용자 정의 데이터를 저장해야 하는 경우 QQmlListProperty 생성자에 임의의 포인터를 전달하고 나중에 동일한 QQmlListProperty 에 액세스할 때 데이터 필드에서 이를 검색할 수 있습니다.

QQmlListProperty constructed from a QList pointer 는 소유자로부터 목록 콘텐츠에 직접 액세스할 수 없으므로 이 필드를 사용하여 목록 자체에 대한 포인터를 저장합니다.

QObject *QQmlListProperty::object

필드에는 QQmlListProperty

접근자 메서드를 수동으로 구현할 때 조작된 목록의 콘텐츠를 검색할 때 이 필드를 사용해야 할 수 있습니다.

매크로 문서

QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_APPEND

이 매크로는 이 클래스의 목록 프로퍼티의 동작을 Append로 정의합니다. 파생된 유형으로 속성을 할당할 때 기본 클래스의 값에 값이 추가됩니다. 이것이 기본 동작입니다.

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

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

QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE_IF_NOT_DEFAULT, QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE, 및 QML 문서를 통해 객체 유형 정의하기를참조하세요 .

QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE

이 매크로는 이 클래스의 목록 속성을 대체하는 동작을 정의합니다. 파생된 유형에서 속성을 할당할 때 기본 클래스의 값을 대체합니다.

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

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

QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_APPEND, QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE_IF_NOT_DEFAULT, 및 QML 문서를 통해 객체 유형 정의하기를참조하세요 .

QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE_IF_NOT_DEFAULT

이 매크로는 이 클래스의 목록 프로퍼티의 동작을 ReplaceIfNotDefault로 정의합니다. 파생 유형으로 프로퍼티를 할당할 때 기본 프로퍼티가 아니라면 기본 클래스의 값을 대체합니다. 기본 속성의 경우 기본 클래스의 값에 값이 추가됩니다.

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

QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_APPEND, QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE, 및 QML 문서를 통한 객체 유형 정의하기를참조하세요 .

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