解釋Q_PROPERTY的參數及功用

 Q_PROPERTY 是 Qt 中的一個宏，用於聲明一個屬性（property）。這個宏使得屬性能夠在 QML 和 C++ 之間進行綁定和交互，並且支持內部信號和自動屬性變更通知。它的作用類似於 C++ 中的 getter 和 setter 函數，但同時可以讓屬性參與到 Qt 的元對象系統（Meta-Object System）中，並且能夠與 QML 配合使用。

Q_PROPERTY 的語法

Q_PROPERTY(type name READ getter WRITE setter NOTIFY signal)

各個參數的解釋

1. type:

   • 屬性的類型。這是你希望這個屬性擁有的數據類型，這個類型必須是 Qt 支持的（例如 int、QString、bool 等），或者是繼承自 QObject 的自定義類型。
   • 例如：int、QString、QList<QString>、MyCustomClass 等。

2. name:

   • 屬性的名稱，這是你在 QML 或 C++ 代碼中使用的名稱。
   • 這個名稱會與 QML 中的屬性名稱相對應，並且可以在 C++ 中通過 getter 和 setter 方法進行訪問。
   • 例如：value、text 等。

3. READ getter:

   • getter 函數，用來返回屬性值。這個函數會被自動呼叫，當你在 QML 中讀取屬性值時，這個函數會被調用。
   • 例如，int value() const { return m_value; }。
   • 如果你沒有設置 READ，則屬性只能設置值，不能讀取值。

4. WRITE setter:

   • setter 函數，用來設置屬性值。這個函數會在 QML 中對該屬性進行賦值時被調用。
   • 例如，void setValue(int value) { m_value = value; }。
   • 如果你沒有設置 WRITE，則屬性將無法在 QML 中設置值，只能讀取。

5. NOTIFY signal:

   • 信號，用於通知屬性值的變更。當屬性值變更時，這個信號會被發射。
   • 在 QML 中，當屬性值發生改變時，QML 會自動監聽這個信號，並且在值改變時更新綁定的視圖（例如 UI 元素）。
   • 這個信號必須是與屬性值相關的信號，並且應該在 setter 中發射。
   • 例如，void valueChanged();。當 setValue 被調用，並且屬性值改變時，就會發射這個信號。

完整的例子

class MyData : public QObject
{
    Q_OBJECT
    Q_PROPERTY(int value READ value WRITE setValue NOTIFY valueChanged)
    Q_PROPERTY(QString text READ text WRITE setText NOTIFY textChanged)

public:
    MyData() : m_value(0), m_text("Hello") {}

    int value() const { return m_value; }
    void setValue(int value) {
        if (m_value != value) {
            m_value = value;
            emit valueChanged();  // 發射信號通知屬性已變更
        }
    }

    QString text() const { return m_text; }
    void setText(const QString &text) {
        if (m_text != text) {
            m_text = text;
            emit textChanged();  // 發射信號通知屬性已變更
        }
    }

signals:
    void valueChanged();
    void textChanged();

private:
    int m_value;
    QString m_text;
};

Q_PROPERTY 中常見的其他參數

除了上述的基本參數外，Q_PROPERTY 還支持以下一些進階選項：

6. RESET resetter：

   • 用來設置屬性重置的函數。在 QML 中，使用 reset() 可以調用這個函數來重置屬性值。
   • 這通常用於提供一些默認的屬性值。

7. FINAL：

   • 標註這個屬性不可再派生或覆寫。通常在你的類型不希望被子類覆寫時使用。

8. REVISION：

   • 用於指定屬性在版本控制系統中的版本。這對於 QML 的兼容性和向後兼容性非常有用。

範例：帶有 RESET 的 Q_PROPERTY

class MyData : public QObject
{
    Q_OBJECT
    Q_PROPERTY(int value READ value WRITE setValue RESET resetValue NOTIFY valueChanged)

public:
    MyData() : m_value(0) {}

    int value() const { return m_value; }
    void setValue(int value) {
        if (m_value != value) {
            m_value = value;
            emit valueChanged();
        }
    }
    
    void resetValue() {
        m_value = 0;  // 重置屬性值
        emit valueChanged();
    }

signals:
    void valueChanged();

private:
    int m_value;
};

在這個例子中，resetValue 是重置 value 屬性的方法，並且 QML 可以使用 reset() 方法來重置屬性。

小結

Q_PROPERTY 是 Qt 提供的一個非常有用的宏，通過它，你可以將 C++ 中的屬性公開給 QML，並且支持數據綁定、變更通知以及屬性操作。它的參數包括：

• type：屬性的類型。
• name：屬性名稱。
• READ、WRITE：getter 和 setter 函數。
• NOTIFY：當屬性改變時發射的信號。