[QT,QML] Q_PROPERTY 매크로

Q_PROPERTY는 Qt의 메타 객체 시스템에서 제공하는 매크로로, 클래스의 프로퍼티(property)를 선언하는 데 사용됩니다. 이 매크로를 사용하여 클래스 멤버를 QML이나 Qt의 시그널-슬롯 시스템에서 접근할 수 있게 하며, 바인딩을 가능하게 합니다. Q_PROPERTY는 일반적인 C++ 멤버 변수와 달리 QML과 같은 고수준 언어에서 데이터를 노출하고, 변화 감지 기능을 제공하여 UI를 자동으로 갱신하는 등 강력한 기능을 제공합니다.

 

 

 

 기본 문법

Q_PROPERTY(type name
           READ getter
           [WRITE setter]
           [RESET resetFunction]
           [NOTIFY notifySignal]
           [REVISION int]
           [DESIGNABLE bool]
           [SCRIPTABLE bool]
           [STORED bool]
           [USER bool])

• type: 프로퍼티의 자료형 (예: int, QString, 사용자 정의 클래스 등)
• name: 프로퍼티의 이름
• READ getter: 프로퍼티의 값을 반환하는 함수 (필수)
• WRITE setter: 프로퍼티의 값을 설정하는 함수 (선택적)
• RESET resetFunction: 프로퍼티를 초기화하는 함수 (선택적)
• NOTIFY notifySignal: 프로퍼티 값이 변경되었음을 알리는 신호 (선택적)
• REVISION int: 프로퍼티를 특정 QML 버전에서만 사용할 수 있도록 제한 (선택적)
• DESIGNABLE bool: Qt 디자이너에서 이 프로퍼티를 설정할 수 있는지 여부 (선택적)
• SCRIPTABLE bool: Qt 스크립트 엔진에서 접근 가능한지 여부 (선택적)
• STORED bool: 객체 상태 저장 시 이 프로퍼티를 포함할지 여부 (선택적)
• USER bool: 사용자 인터페이스에서 기본으로 표시되는지 여부 (선택적)

 

 

 

 사용 예제

아래 예제에서는 Q_PROPERTY를 사용하여 클래스 멤버 변수를 QML에서 접근할 수 있도록 선언하는 방법을 보여줍니다.

#include <QObject>
#include <QString>

class Person : public QObject {
    Q_OBJECT
    Q_PROPERTY(QString name READ name WRITE setName NOTIFY nameChanged)

public:
    explicit Person(QObject *parent = nullptr) : QObject(parent), m_name("") {}

    // Getter 함수
    QString name() const {
        return m_name;
    }

    // Setter 함수
    void setName(const QString &name) {
        if (m_name != name) {
            m_name = name;
            emit nameChanged(); // 프로퍼티 값이 변경되면 시그널을 발생시킴
        }
    }

signals:
    void nameChanged(); // 값이 변경되었음을 알리는 시그널

private:
    QString m_name; // 실제 데이터 멤버
};

 

 

 

 설명

1. Q_PROPERTY 매크로
   • Q_PROPERTY(QString name READ name WRITE setName NOTIFY nameChanged)에서
     • QString: 프로퍼티의 타입.
     • name: 프로퍼티의 이름으로 QML에서 person.name처럼 접근할 수 있게 됩니다.
     • READ name: 프로퍼티의 값을 읽기 위해 호출되는 함수 (name()).
     • WRITE setName: 값을 설정하기 위해 호출되는 함수 (setName()).
     • NOTIFY nameChanged: 프로퍼티 값이 변경될 때 발생하는 시그널 (nameChanged()).
2. Getter와 Setter
   • name(): 프로퍼티의 현재 값을 반환하는 getter 함수.
   • setName(): 값을 설정하는 setter 함수. 새로운 값이 이전 값과 다를 때만 변경하고, 변경 시 시그널(nameChanged())을 발생시킵니다.
3. 시그널
   • nameChanged() 시그널은 프로퍼티가 변경될 때마다 발생하며, 이를 통해 QML UI에서 해당 값을 사용하는 바인딩이 자동으로 갱신될 수 있도록 합니다.

 

 

 

 QML에서 사용하기

위와 같이 선언된 클래스는 QML에서 쉽게 접근할 수 있습니다. 예를 들어 Person 객체를 QML 컨텍스트에 등록하고 사용하면 다음과 같이 값에 접근하고 UI에서 자동으로 업데이트되도록 할 수 있습니다.

 

C++에서 QML에 등록:

#include <QGuiApplication>
#include <QQmlApplicationEngine>
#include <QQmlContext>
#include "Person.h"

int main(int argc, char *argv[]) {
    QGuiApplication app(argc, argv);
    QQmlApplicationEngine engine;

    Person person;
    person.setName("Alice");

    engine.rootContext()->setContextProperty("person", &person);

    engine.load(QUrl(QStringLiteral("qrc:/main.qml")));

    if (engine.rootObjects().isEmpty())
        return -1;

    return app.exec();
}

 

main.qml:

import QtQuick 2.15
import QtQuick.Controls 2.15

ApplicationWindow {
    visible: true
    width: 640
    height: 480

    Text {
        text: person.name // person 객체의 name 프로퍼티 사용
        anchors.centerIn: parent
    }

    Button {
        text: "Change Name"
        onClicked: person.name = "Bob" // 프로퍼티 변경, 자동으로 UI 업데이트
    }
}

 

 

 

 Q_PROPERTY의 장점

• 바인딩 지원: QML에서 객체 프로퍼티가 변경될 때 UI가 자동으로 갱신됩니다. 이를 통해 동적이고 직관적인 UI를 쉽게 구현할 수 있습니다.
• 신호-슬롯 시스템과의 통합: 변경 알림 시그널을 통해 프로퍼티 값 변경 시 필요한 로직을 쉽게 연결할 수 있습니다.
• QML 노출: C++ 객체의 데이터를 QML에 노출하여 UI와 백엔드의 데이터를 손쉽게 결합할 수 있습니다.

 

 

 

 주의사항

• NOTIFY 시그널을 잘 활용해야 QML에서 프로퍼티 변경에 따른 UI 자동 갱신이 이루어집니다. 만약 NOTIFY를 설정하지 않으면 값은 변경되더라도 UI에 즉시 반영되지 않을 수 있습니다.
• Setter 함수에서 조건문을 사용하여 값이 변경될 때만 시그널을 발생시키는 것이 좋습니다. 불필요하게 시그널이 발생하면 성능에 악영향을 줄 수 있습니다.

Q_PROPERTY는 QML에서 동적 UI를 구현할 때 핵심적인 역할을 하며, C++과 QML 간의 데이터 연동을 원활하게 해주는 중요한 도구입니다. 이를 잘 이해하고 활용하면 Qt 애플리케이션의 유연성을 크게 높일 수 있습니다.

 

 

 

---

 

 

개인적으로 학습하면서 정리한 내용입니다.
잘못된 내용이 있을 경우 알려주시면 확인 후 수정 및 반영하도록 하겠습니다.

오늘도 감사합니다.(__)>

 

 

야 너두 할 수 있어!!!

https://www.tistory.com/event/write-challenge-2024

작심삼주 오블완 챌린지