Back to Qt.io
Contact Us Blog Download Qt
이 페이지에서

QQmlListProperty Class

template <typename T> class QQmlListProperty

QQmlListProperty 클래스를 사용하면 애플리케이션에서 ` QObject`에서 파생된 클래스의 목록형 속성을 QML에 노출할 수 있습니다. 더 보기...

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

공개 타입

AppendFunction
AtFunction
ClearFunction
CountFunction
RemoveLastFunction
ReplaceFunction

공개 함수

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_LIST_PROPERTY_ASSIGN_BEHAVIOR_APPEND
QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE
QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE_IF_NOT_DEFAULT

상세 설명

QML에는 하나 이상의 객체 값을 할당할 수 있는 여러 목록 속성이 있습니다. QML에서 목록 속성을 사용하는 방법은 다음과 같습니다:

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

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

리스트 속성을 제공하려면 C++ 클래스가 연산 콜백을 구현한 다음, 속성 게터에서 적절한 QQmlListProperty 값을 반환해야 합니다. 리스트 속성에는 세터가 없어야 합니다. 위 예제에서 Q_PROPERTY() 선언문은 다음과 같습니다:

Q_PROPERTY(QQmlListProperty<Fruit> fruit READ fruit)

QML 리스트 속성은 타입 안전합니다. 템플릿 매개변수 T 는 리스트에 저장될 수 있는 QObject 에서 파생된 타입을 지정합니다. 이 경우 Fruit 는 QObject 타입이며, Apple, Orange 및 Banana 가 모두 이 타입에서 파생됩니다.

QQmlListReference 를 사용하면 약간의 오버헤드를 감수하는 대신, C++에서 QQmlListProperty를 좀 더 사용하기 편리한 API를 통해 조작할 수 있습니다.

제5장: 리스트 속성 유형 사용 및 QQmlListReference도 참조하십시오 .

멤버 유형 문서

[alias] QQmlListProperty::AppendFunction

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

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

[alias] QQmlListProperty::AtFunction

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

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

[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` 값을 생성하기 위한 편리한 생성자입니다. 해당 목록을 소유하는 ` object `와 ` list ` 자체는 반드시 제공되어야 하며, 이를 참조하는 `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)

count 및 at 와 같은 일련의 연산 함수를 사용하여 읽기 전용 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 가 존재하는 동안 유효합니다.

모든 함수에 대해 null 포인터를 전달할 수 있습니다. null 포인터가 전달된 경우, 디버거를 통해 목록을 디자인하거나 수정할 수 없게 됩니다. 모든 함수에 유효한 포인터를 제공하는 것이 권장됩니다.

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

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 가 존재하는 동안 유효합니다.

모든 함수에 대해 null 포인터를 전달할 수 있으며, 이 경우 가능한 경우 해당 함수가 다른 함수를 사용하여 합성됩니다. QQmlListProperty는

  • clear count 을 사용하여, removeLast
  • 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

이 ` QQmlListProperty `가 ` other`와 같으면 `true`를 반환하고, 그렇지 않으면 `false`를 반환합니다.

멤버 변수 설명

void *QQmlListProperty::data

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

액세서 메서드를 수동으로 구현하고 사용자 정의 데이터를 저장해야 하는 경우, ` QQmlListProperty ` 생성자에 임의의 포인터를 전달한 뒤, 나중에 해당 ` QQmlListProperty `에 액세스할 때 ` data ` 필드에서 해당 포인터를 가져올 수 있습니다.

QQmlListProperty constructed from a QList pointer 는 소유자(owner)로부터 목록의 내용을 직접 액세스할 수 없기 때문에, 이 필드를 사용하여 목록 자체에 대한 포인터를 저장합니다.

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

이 매크로는 이 클래스의 목록 속성 동작을 ‘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 문서를 통한 객체 유형 정의도참조하십시오 .

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