Qt's Property System

Requirements for Declaring Properties

To declare a property, use the Q_PROPERTY() macro in a class that inherits QObject.

 Q_PROPERTY(type name
            READ getFunction
            [WRITE setFunction]
            [RESET resetFunction]
            [NOTIFY notifySignal]
            [DESIGNABLE bool]
            [SCRIPTABLE bool]
            [STORED bool]
            [USER bool])

Here are some typical examples of property declarations taken from class QWidget.

 Q_PROPERTY(bool focus READ hasFocus)
 Q_PROPERTY(bool enabled READ isEnabled WRITE setEnabled)
 Q_PROPERTY(QCursor cursor READ cursor WRITE setCursor RESET unsetCursor)

A property behaves like a class data member, but it has additional features accessible through the Meta-Object System.

• A READ accessor function is required. It is for reading the property value. It must be const and must return either the property's type or a pointer or reference to that type. e.g., QWidget::focus is a read-only property with READ function QWidget::hasFocus().
• A WRITE accessor function is optional. It is for setting the property value. It must return void and must take exactly one argument, either of the property's type or a pointer or reference to that type. e.g., QWidget::enabled has the WRITE function QWidget::setEnabled(). Read-only properties do not need WRITE functions. e.g., QWidget::focus has no WRITE function.
• A RESET function is optional. It is for setting the property back to its context specific default value. e.g., QWidget::cursor has the typical READ and WRITE functions, QWidget::cursor() and QWidget::setCursor(), and it also has a RESET function, QWidget::unsetCursor(), since no call to QWidget::setCursor() can mean reset to the context specific cursor. The RESET function must return void and take no parameters.
• A NOTIFY signal is optional. If defined, the signal will be emitted whenever the value of the property changes. The signal must take one parameter, which must be of the same type as the property; the parameter will take the new value of the property.
• The DESIGNABLE attribute indicates whether the property should be visible in the property editor of GUI design tool (e.g., Qt Designer). Most properties are DESIGNABLE (default true). Instead of true or false, you can specify a boolean member function.
• The SCRIPTABLE attribute indicates whether this property should be accessible by a scripting engine (default true). Instead of true or false, you can specify a boolean member function.
• The STORED attribute indicates whether the property should be thought of as existing on its own or as depending on other values. It also indicates whether the property value must be saved when storing the object's state. Most properties are STORED (default true), but e.g., QWidget::minimumWidth() has STORED false, because its value is just taken from the width component of property QWidget::minimumSize(), which is a QSize.
• The USER attribute indicates whether the property is designated as the user-facing or user-editable property for the class. Normally, there is only one USER property per class (default false). e.g., QAbstractButton::checked is the user editable property for (checkable) buttons. Note that QItemDelegate gets and sets a widget's USER property.

The READ, WRITE, and RESET functions can be inherited. They can also be virtual. When they are inherited in classes where multiple inheritance is used, they must come from the first inherited class.

The property type can be any type supported by QVariant, or it can be a user-defined type. In this example, class QDate is considered to be a user-defined type.

 Q_PROPERTY(QDate date READ getDate WRITE setDate)

Because QDate is user-defined, you must include the <QDate> header file with the property declaration.

For QMap, QList, and QValueList properties, the property value is a QVariant whose value is the entire list or map. Note that the Q_PROPERTY string cannot contain commas, because commas separate macro arguments. Therefore, you must use QMap as the property type instead of QMap<QString,QVariant>. For consistency, also use QList and QValueList instead of QList<QVariant> and QValueList<QVariant>.

 QPushButton *button = new QPushButton;
 QObject *object = button;

 button->setDown(true);
 object->setProperty("down", true);

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

 class MyClass : public QObject
 {
     Q_OBJECT
     Q_PROPERTY(Priority priority READ priority WRITE setPriority)
     Q_ENUMS(Priority)

 public:
     MyClass(QObject *parent = 0);
     ~MyClass();

     enum Priority { High, Low, VeryHigh, VeryLow };

     void setPriority(Priority priority);
     Priority priority() const;
 };

 MyClass *myinstance = new MyClass;
 QObject *object = myinstance;

 myinstance->setPriority(MyClass::VeryHigh);
 object->setProperty("priority", "VeryHigh");

 Q_CLASSINFO("Version", "3.0.0")