Qt属性系统详细使用教程

此文较长，例子较多，可以结合右侧目录进行查看。

何为属性？人有名字，年龄，性别，这就是人的属性。

同样，面向对象编程的世界里，一切皆对象，对象也该有自己特定的属性。

在Qt中，QObject实现了对于属性的支持，那么派生于QObject的对象，都可以很容易的拥有自己的属性。

注：

使用Qt属性，则必须继承于QObject

一、属性的声明

让我们看看帮助文档中关于属性声明的定义：

Q_PROPERTY(type name
         (READ getFunction [WRITE setFunction] |
          MEMBER memberName [(READ getFunction | WRITE setFunction)])
         [RESET resetFunction]
         [NOTIFY notifySignal]
         [REVISION int]
         [DESIGNABLE bool]
         [SCRIPTABLE bool]
         [STORED bool]
         [USER bool]
         [CONSTANT]
         [FINAL])

简单捋一下，声明属性的必备条件：

• 继承于QObject
• 使用Q_OBJECT宏
• 使用Q_PROPERTY宏

Q_PROPERTY属性宏，参数分为必须部分和可选部分，接下来讲解，具体各部分含义。

二、属性声明之必须部分

其声明形式如下：

type name 
(READ getFunction [WRITE setFunction] |
MEMBER memberName [(READ getFunction | WRITE setFunction)])

翻译过来，就是有2种形式，带MEMBER和不带MEMBER字段；

1. 不带MEMBER字段

形式为：类型+属性名+READ+get函数+WRITE+set函数，其中WRITE+set函数为可选。

我们定义MyObject类，声明age属性，可以像如下书写：

class MyObject : public QObject
{
    Q_OBJECT
    Q_PROPERTY(int age READ getAge WRITE setAge)
    
public:
    int getAge() const
    {
        return _age;
    }
    void setAge(int value)
    {
        _age = value;
    }
private:
    int _age;
};

访问age属性，当调用setProperty设置属性时，setAge()函数会被调用，以将18保存到_age变量；调用property获取属性时，getAge()函数会被调用，以获取_age变量值。可以说属性实际承载者是我们定义的成员变量。

QObject *obj = new MyObject();
obj->setProperty("age", 18);  // _age == 18
int value = obj->property("age").toInt(); // value == 18

若不写WRITE字段，如下：

Q_PROPERTY(int age READ getAge)

则调用setProperty()设置属性时，不会调用setAge()，此时_age值不变，新属性值被丢弃。
而调用property()时与原来一致。

注：

READ字段为必填项。

2. 带MEMBER字段

形式为：类型+属性名+MEMBER+成员变量名+READ+get函数+WRITE+set函数，其中READ+get函数+WRITE+set函数为可选。

我们仍以MyObject类为例进行说明，声明score属性，可以像如下书写：

class MyObject : public QObject
{
    Q_OBJECT
    Q_PROPERTY(int score MEMBER _score)
    
private:
    int _score;
};

后续设置属性就是指setProperty()，获取属性是指property()，下面不再赘述。

这样写，我们设置和获取属性都是成功的。小伙伴可能会觉得奇怪，此处并没有指定get、set函数，值是如何设置到_score变量，并还能正常获取的呢？

这是因为我们使用MEMBER关键字，Qt会自动生成一对getter/setter函数用于访问_score。

下面，如果加上READ、WRITE字段，如下：

Q_PROPERTY(int score MEMBER _score READ getScore WRITE setScore)

那么我们设置属性时就会调用setScore()，获取属性时就会调用getScore()。

如果只加READ，如下：

Q_PROPERTY(int score MEMBER _score READ getScore)

则设置属性时不调setScore()，调用默认生成的setter()；获取属性时调getScore()。

如果只加WRITE，如下：

Q_PROPERTY(int score MEMBER _score WRITE setScore)

则设置属性时调setScore()，获取属性时不调getScore()，调用默认生成的getter()。

这个Qt属性声明还是相当灵活的。

基本属性使用，我们已经get到了，接下来，我们来锦上添花。

三、属性声明之可选部分

可选字段如下：

[RESET resetFunction]
[NOTIFY notifySignal]
[REVISION int]
[DESIGNABLE bool]
[SCRIPTABLE bool]
[STORED bool]
[USER bool]
[CONSTANT]
[FINAL]

1. NOTIFY字段

当属性值发生改变后，会发射一个NOTIFY字段声明的信号。

我们可以像如下书写：

class MyObject : public QObject
{
    Q_OBJECT
    Q_PROPERTY(int age READ getAge WRITE setAge NOTIFY ageChanged)
    
public:
    int getAge() const
    {
        return _age;
    }
    void setAge(int value)
    {
        _age = value;
        emit ageChanged(value);
    }
signals:
    void ageChanged(int value);
private:
    int _age;
};

当age属性值发生改变后，发射ageChanged信号。由于信号是我们手动发射，所以对信号的参数没有限制。

另外我们还可以让信号由Qt系统自动发射，即使用MEMBER字段。如下：

class MyObject : public QObject
{
    Q_OBJECT
    Q_PROPERTY(int score MEMBER _score NOTIFY scoreChanged)
signals:
    void scoreChanged(int value);
private:
    int _score;
};

当score属性值发生改变后，自动发射scoreChanged信号。但是对信号定义有限制，即信号参数个数只能为0个或者1个，且参数类型必须与属性类型相同，参数保存的是属性改变后的新值。

其他的可选字段，不是很常用，大家就自行研究吧。

四、支持的属性类型

Qt属性类型可以是QVariant支持的任何类型，或者是用户自定义的类型。

1. 内置类型属性

如下为QVariant支持的内置类型。

enum Type {
    Invalid = QMetaType::UnknownType,
    Bool = QMetaType::Bool,
    Int = QMetaType::Int,
    UInt = QMetaType::UInt,
    LongLong = QMetaType::LongLong,
    ULongLong = QMetaType::ULongLong,
    Double = QMetaType::Double,
    Char = QMetaType::QChar,
    Map = QMetaType::QVariantMap,
    List = QMetaType::QVariantList,
    String = QMetaType::QString,
    StringList = QMetaType::QStringList,
    ByteArray = QMetaType::QByteArray,
    BitArray = QMetaType::QBitArray,
    Date = QMetaType::QDate,
    Time = QMetaType::QTime,
    DateTime = QMetaType::QDateTime,
    Url = QMetaType::QUrl,
    Locale = QMetaType::QLocale,
    Rect = QMetaType::QRect,
    RectF = QMetaType::QRectF,
    Size = QMetaType::QSize,
    SizeF = QMetaType::QSizeF,
    Line = QMetaType::QLine,
    LineF = QMetaType::QLineF,
    Point = QMetaType::QPoint,
    PointF = QMetaType::QPointF,
    RegExp = QMetaType::QRegExp,
    RegularExpression = QMetaType::QRegularExpression,
    Hash = QMetaType::QVariantHash,
    EasingCurve = QMetaType::QEasingCurve,
    Uuid = QMetaType::QUuid,
#if QT_CONFIG(itemmodel)
    ModelIndex = QMetaType::QModelIndex,
    PersistentModelIndex = QMetaType::QPersistentModelIndex,
#endif
    LastCoreType = QMetaType::LastCoreType,

    Font = QMetaType::QFont,
    Pixmap = QMetaType::QPixmap,
    Brush = QMetaType::QBrush,
    Color = QMetaType::QColor,
    Palette = QMetaType::QPalette,
    Image = QMetaType::QImage,
    Polygon = QMetaType::QPolygon,
    Region = QMetaType::QRegion,
    Bitmap = QMetaType::QBitmap,
    Cursor = QMetaType::QCursor,
    KeySequence = QMetaType::QKeySequence,
    Pen = QMetaType::QPen,
    TextLength = QMetaType::QTextLength,
    TextFormat = QMetaType::QTextFormat,
    Matrix = QMetaType::QMatrix,
    Transform = QMetaType::QTransform,
    Matrix4x4 = QMetaType::QMatrix4x4,
    Vector2D = QMetaType::QVector2D,
    Vector3D = QMetaType::QVector3D,
    Vector4D = QMetaType::QVector4D,
    Quaternion = QMetaType::QQuaternion,
    PolygonF = QMetaType::QPolygonF,
    Icon = QMetaType::QIcon,
    LastGuiType = QMetaType::LastGuiType,

    SizePolicy = QMetaType::QSizePolicy,

    UserType = QMetaType::User,
    LastType = 0xffffffff // need this so that gcc >= 3.4 allocates 32 bits for Type
};

除了容器类型外，其他的类型基本都可以直接定义使用，如下：

Q_PROPERTY(QDate date READ getDate WRITE setDate)

注意：

Q_PROPERTY字符串不能包含逗号，因为逗号会分割宏的参数。

所以，对于QMap、QList和QHash等容器类型属性，必须使用QMap作为属性的类型而不是QMap<QString,QVariant>，同样，也只能使用QList和QHash，而不是QList和QHash<QString,QVariant>。

2. 自定义枚举属性

属性类型为自定义枚举时，可能有以下2种需求：

• 有些枚举是单值，如：

enum Priority { High, Low, VeryHigh, VeryLow };
xxx(High);

• 而有的可以将多个枚举值进行或运算，多值，如：

enum Align
{
    Left = 0x01,
    Right = 0x02,
    HCenter = 0x04,
    Top = 0x08,
    Bottom = 0x10,
    VCenter = 0x20
};
xxx(Left|Top);

接下来，分别举例说明。

（1）使用Q_ENUM注册单值枚举

若属性类型为自定义枚举，则必须使用Q_ENUM()注册到元对象系统中。

使用Q_ENUM()注册枚举类型，如下：

class MyObject : public QObject
{
    Q_OBJECT
    Q_PROPERTY(Priority priority READ priority WRITE setPriority NOTIFY priorityChanged) 

public:
    enum Priority { High, Low, VeryHigh, VeryLow };
    Q_ENUM(Priority)

    void setPriority(Priority priority)
    {
        _priority = priority;
        emit priorityChanged(priority);
    }
    Priority priority() const
    {
        return _priority;
    }

signals:
    void priorityChanged(Priority priority);

private:
    Priority _priority;
};

由于已经注册在元对象系统中，所以在setProperty()时，可以直接用枚举值的字符串形式作为实参，如下：

QObject *object = new MyObject();
object->setProperty("priority", "VeryHigh"); // _priority == MyObject::VeryHigh
QVariant temp = object->property("priority");
MyObject::Priority pri = temp.value<MyObject::Priority>(); // pri == MyObject::VeryHigh

此时，字符串"VeryHigh"会在内部自动转换为枚举值VeryHigh，并通过调用setPriority()，将m_priority设置为枚举值VeryHigh。

如果枚举类型在其它类中声明，那么需要使用枚举的全名（例如：OtherClass::Priority)，而且这个类也必须从QObject派生，并且使用Q_ENUM()宏注册枚举类型。

（2）使用Q_FLAG注册多值枚举

比注册单值枚举要稍微麻烦一点。有以下几个注意事项：

• 使用Q_DECLARE_FLAGS、Q_FLAG、Q_DECLARE_OPERATORS_FOR_FLAGS三个宏。
• 将枚举值定义为2的n次方，保证或操作不会出现交叉，如 0x00, 0x01, 0x02, 0x04, 0x08, 0x10, 0x20。
• 不使用原枚举类型，而是使用Q_FLAG(xx)定义的xx类型。

代码如下：

class MyObject : public QObject
{
    Q_OBJECT
    Q_PROPERTY(Aligns aligns READ aligns WRITE setAligns NOTIFY alignsChanged) // 测试多值枚举

public:
    enum Align
    {
        Left = 0x01,
        Right = 0x02,
        HCenter = 0x04,
        Top = 0x08,
        Bottom = 0x10,
        VCenter = 0x20
    };
    Q_DECLARE_FLAGS(Aligns, Align)
    Q_FLAG(Aligns)

    void setAligns(Aligns aligns)
    {
        _aligns = aligns;
        emit alignsChanged(aligns);
    }
    Aligns aligns() const
    {
        return _aligns;
    }

signals:
    void alignsChanged(Aligns align);

private:
    Aligns _aligns;
};
Q_DECLARE_OPERATORS_FOR_FLAGS(MyObject::Aligns)

测试代码如下：

QObject *object = new MyObject();
object->setAligns(MyObject::Left|MyObject::Bottom); // _aligns == MyObject::Left|MyObject::Bottom
object->setProperty("aligns", "Left|Top"); // _aligns == MyObject::Left|MyObject::Top
QVariant temp = object->property("aligns");
MyObject::Aligns aligns = temp.value<MyObject::Aligns>(); // aligns == MyObject::Left|MyObject::Top

使用方式与Q_ENUM()类似，也是注册枚举类型，但它是把枚举类型作为一个flag集合，也就是，值可以用或操作来合并。

3. 自定义类型属性

若属性类型为自定义类型，则必须使用Q_DECLARE_METATYPE宏注册该类型，使其能够放入QVariant，如下：

class Person
{
public:
    int varA;
    float varB;
    QString varC;
};
Q_DECLARE_METATYPE(Person)

然后，声明此类型属性如下：

class MyObject : public QObject
{
    Q_OBJECT
    Q_PROPERTY(Person person READ getPerson WRITE setPerson NOTIFY personChanged)

public:
    Person getPerson() const
    {
        return _person;
    }
    void setPerson(const Person &person)
    {
        _person = person;
        emit personChanged(person);
    }

signals:
    void personChanged(Person person);

private:
    Person _person;
};

测试代码，如下：

Person person;
person.varA = 10;
person.varB = 5.0;
person.varC = "test";

QObject *object = new MyObject();
object->setProperty("person", QVariant::fromValue(person)); // _person.varA==10,_person.varB==5.0,_person.varC=="test"
QVariant temp = object->property("person");
Person result = temp.value<Person>(); // result.varA==10,result.varB==5.0,result.varC=="test"

注意：

如果需要使用MEMBER字段声明自定义类型属性，则需要为自定义类型重载!=操作符，可能是在设置或者获取属性时，调用Qt自身生成的setter/getter，会间接调用!=进行比较，所以必须要实现，否则编译报错：

添加重载!=操作符后的，代码如下：

class Person
{
public:
    Person() { }

    bool operator!=(const Person& person)
    {
        if (person.varA == varA &&
            person.varB == varB &&
            person.varC == varC)
            return false;
        else
            return true;
    }

    int varA;
    float varB;
    QString varC;
};
Q_DECLARE_METATYPE(Person)

此时，再使用MEMBER关键字声明Person类型属性，则不会再报错，可以正常运行。声明属性代码如下：

class MyObject : public QObject
{
    Q_OBJECT

    Q_PROPERTY(Person person MEMBER _person NOTIFY personChanged)

public:

signals:
    void personChanged(Person person);

private:
    Person _person;
};

测试代码，如下：

Person person;
person.varA = 10;
person.varB = 5.0;
person.varC = "test";

QObject *object = new MyObject();
object->setProperty("person", QVariant::fromValue(person)); // _person.varA==10,_person.varB==5.0,_person.varC=="test"
QVariant temp = object->property("person");
Person result = temp.value<Person>(); // result.varA==10,result.varB==5.0,result.varC=="test"

五、静态属性与动态属性

使用Q_PROPERTY宏定义的属性，就是静态属性。

后期使用setProperty()动态添加的属性，就是动态属性。

无论静态还是动态，都可以按如下方式，获取所有的属性名和属性值。如下：

QObject *object = ...
const QMetaObject *metaobject = object->metaObject();
int count = metaobject->propertyCount();
for (int i=0; i<count; ++i) 
{
    QMetaProperty metaproperty = metaobject->property(i);
    const char *name = metaproperty.name();
    QVariant value = object->property(name);
    ...
}

本文工程代码地址：

https://gitee.com/bailiyang/cdemo/tree/master/Qt/40Property/Property

参考链接：

《Qt 之属性系统》

《枚举与 QFlags》

《Qt中的枚举变量》

《Qt 中的属性系统》

===================================================

===================================================

业余时间不定期更新一些想法、思考文章，欢迎关注，共同探讨，沉淀技术！