Система свойств

Qt предоставляет сложную систему свойств, похожую на системы, предоставляемые некоторыми поставщиками компиляторов. Однако, как независимая от компилятора и платформы библиотека, Qt не полагается на нестандартные возможности компиляторов, такие как __property или [property]. Решение Qt работает с любым стандартным C++ компилятором на каждой платформе, поддерживаемой Qt. Оно основано на системе метаобъектов, которая также обеспечивает межобъектное взаимодействие через сигналы и слоты.

Требования к объявлению свойств

Для объявления свойства используйте макрос Q_PROPERTY() в классе, наследующем от QObject.

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

Вот несколько типичных примеров объявлений свойств, взятых из класса 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)

Вот пример, показывающий, как экспортировать переменные-члены в качестве свойств Qt, используя ключевое слово MEMBER. Обратите внимание, что необходимо указать сигнал NOTIFY, чтобы разрешить привязку свойств QML.

    Q_PROPERTY(QColor color MEMBER m_color NOTIFY colorChanged)
    Q_PROPERTY(qreal spacing MEMBER m_spacing NOTIFY spacingChanged)
    Q_PROPERTY(QString text MEMBER m_text NOTIFY textChanged)
    ...
signals:
    void colorChanged();
    void spacingChanged();
    void textChanged(const QString &newText);

private:
    QColor  m_color;
    qreal   m_spacing;
    QString m_text;

Свойство ведет себя как член данных класса, но имеет дополнительные возможности, доступные через систему метаобъектов.

• Функция-аксессор READ требуется, если не указана переменная MEMBER. Она предназначена для чтения значения свойства. В идеале для этой цели используется константная функция, которая должна возвращать либо тип свойства, либо константную ссылку на этот тип. Например, QWidget::focus — это свойство только для чтения с функцией READ QWidget::hasFocus().
• Функция-аксессор WRITE необязательна. Она предназначена для установки значения свойства. Она должна возвращать void и принимать ровно один аргумент, либо тип свойства, либо указатель или ссылку на этот тип. Например, QWidget::enabled имеет функцию WRITE QWidget::setEnabled(). Свойствам только для чтения не нужны функции WRITE . Например, QWidget::focus не имеет функции WRITE.
• Связывание с переменной MEMBER требуется, если не указана функция-аксессор READ . Это делает заданную переменную-член доступной для чтения и записи без необходимости создания функций-акссессоров READ и WRITE. По-прежнему можно использовать функции-акссессоры READ или WRITE в дополнение к ассоциации с переменной MEMBER (но не оба варианта), если вам нужно управлять доступом к переменной.
• Функция RESET необязательна. Она предназначена для возврата свойства к его контекстно-зависимому значению по умолчанию. Например, QWidget::cursor имеет типичные функции READ и WRITE QWidget::cursor() и QWidget::setCursor(), а также функцию RESET QWidget::unsetCursor(), поскольку любой вызов QWidget::setCursor() может означать восстановление контекстно-зависимого курсора. Функция RESET должна возвращать void и не принимать параметров.
• Сигнал NOTIFY необязателен. Если он определен, он должен указывать существующий сигнал в этом классе, который испускается всякий раз, когда значение свойства изменяется. NOTIFY сигналы для MEMBER переменных должны принимать ноль или один параметр, который должен быть того же типа, что и свойство. Параметр будет принимать новое значение свойства. Сигнал NOTIFY должен испускаться только при реальном изменении свойства, чтобы избежать ненужного переоценивания привязок в QML, например. Qt автоматически испускает этот сигнал при необходимости для свойств MEMBER, у которых нет явного установщика.
• Число REVISION или макрос REVISION() необязательны. Если они включены, они определяют свойство и его уведомляющий сигнал для использования в определённой версии API (обычно для экспонирования в QML). Если они не включены, по умолчанию используется 0.
• Атрибут DESIGNABLE указывает, должно ли свойство отображаться в редакторе свойств инструмента проектирования графического интерфейса (например, Qt Designer). Большинство свойств DESIGNABLE (значение по умолчанию — true). Допустимые значения — true и false.
• Атрибут SCRIPTABLE указывает, должно ли это свойство быть доступным для скриптового движка (значение по умолчанию — true). Допустимые значения — true и false.
• Атрибут STORED указывает, должно ли свойство рассматриваться как существующее само по себе или как зависящее от других значений. Он также указывает, должно ли значение свойства сохраняться при сохранении состояния объекта. Большинство свойств STORED (значение по умолчанию — true), но, например, QWidget::minimumWidth() имеет STORED false, потому что его значение берётся из компонента ширины свойства QWidget::minimumSize(), которое является QSize.
• Атрибут USER указывает, предназначено ли свойство как пользовательское или изменяемое пользователем свойство для класса. Обычно в классе существует только одно USER свойство (значение по умолчанию — false). Например, QAbstractButton::checked является изменяемым пользователем свойством для (флажковых) кнопок. Обратите внимание, что QItemDelegate получает и устанавливает свойство USER виджета.
• Атрибут BINDABLE bindableProperty указывает, что свойство поддерживает привязки, и что привязку к этому свойству можно установить и проверить через систему метаобъектов (QMetaProperty). bindableProperty указывает член класса типа QBindable<T>, где T — тип свойства. Этот атрибут был введён в Qt 6.0.
• Наличие атрибута CONSTANT указывает, что значение свойства является константой. Для данного экземпляра объекта метод READ константного свойства должен возвращать одно и то же значение каждый раз, когда он вызывается. Это константное значение может быть разным для разных экземпляров объекта. Константное свойство не может иметь метод WRITE или сигнал NOTIFY.
• Наличие атрибута FINAL указывает, что свойство не будет переопределено производным классом. Это может использоваться для оптимизации производительности в некоторых случаях, но moc не навязывает этого. Следует быть осторожным, чтобы не переопределять свойство FINAL.
• Наличие атрибута REQUIRED указывает, что свойство должно устанавливаться пользователем класса. Это не навязывается moc и в основном полезно для классов, экспонируемых в QML. В QML классы с REQUIRED свойствами не могут быть созданы, пока все REQUIRED свойства не будут установлены.

Функции READ, WRITE, и RESET могут быть унаследованы. Они также могут быть виртуальными. Когда они наследуются в классах, использующих множественное наследование, они должны быть унаследованы от первого наследуемого класса.

Тип свойства может быть любым типом, поддерживаемым QVariant, или это может быть пользовательский тип. В этом примере класс QDate рассматривается как пользовательский тип.

Q_PROPERTY(QDate date READ getDate WRITE setDate)

Поскольку QDate является пользовательским типом, вам необходимо включить заголовочный файл <QDate> с объявлением свойства.

По историческим причинам, QMap и QList в качестве типов свойств являются синонимами QVariantMap и QVariantList.

Чтение и запись свойств с помощью системы метаобъектов

Свойство можно читать и записывать с помощью общих функций QObject::property() и QObject::setProperty(), не зная ничего о владеющем классе, кроме имени свойства. В приведенном ниже фрагменте кода вызов QAbstractButton::setDown() и вызов QObject::setProperty() оба устанавливают свойство "down".

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

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

Обращение к свойству через его WRITE аксессор предпочтительнее, так как это быстрее и даёт лучшие диагностические сообщения на этапе компиляции, но установка свойства таким способом требует знания класса на этапе компиляции. Доступ к свойствам по имени позволяет получить доступ к классам, которые неизвестны на этапе компиляции. Вы можете определить свойства класса во время выполнения, запросив его QObject, QMetaObject и QMetaProperties.

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

В приведенном выше фрагменте используется QMetaObject::property() для получения метаданных о каждом свойстве, определённом в некотором неизвестном классе. Имя свойства извлекается из метаданных и передаётся в QObject::property() для получения значения свойства в текущем объекте.

Простой пример

Предположим, у нас есть класс MyClass, который наследуется от QObject и использует макрос Q_OBJECT в своём разделе private. Мы хотим объявить свойство в MyClass для отслеживания значения приоритета. Имя свойства будет priority, а его тип — перечисление с именем Priority, определённое в MyClass.

Мы объявляем свойство с помощью макроса Q_PROPERTY() в разделе private класса. Требуемая функция READ называется priority, и мы включаем функцию WRITE с именем setPriority. Перечисление необходимо зарегистрировать в системе метаобъектов с помощью макроса Q_ENUM(). Регистрация типа перечисления делает имена перечислителей доступными для использования в вызовах QObject::setProperty(). Мы также должны предоставить собственные объявления для функций READ и WRITE . Объявление MyClass может выглядеть следующим образом:

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

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

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

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

signals:
    void priorityChanged(Priority);

private:
    Priority m_priority;
};

Функция READ является константной и возвращает тип свойства. Функция WRITE возвращает void и имеет ровно один параметр типа свойства. Компилятор метаобъектов навязывает эти требования.

Учитывая указатель на экземпляр MyClass или указатель на QObject, который является экземпляром MyClass, у нас есть два способа установить свойство priority:

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

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

В примере тип перечисления, который является типом свойства, объявлен в MyClass и зарегистрирован в Системе метаобъектов с помощью макроса Q_ENUM(). Это делает значения перечисления доступными в виде строк для использования, например, в вызове setProperty(). Если бы тип перечисления был объявлен в другом классе, потребовалось бы его полное имя (т. е. OtherClass::Priority), и этот другой класс также должен был бы унаследовать от QObject и зарегистрировать тип перечисления там с помощью макроса Q_ENUM().

Также доступен похожий макрос Q_FLAG(). Как и Q_ENUM(), он регистрирует тип перечисления, но помечает тип как набор флагов, т. е. значений, которые можно объединять с помощью оператора OR. Класс ввода/вывода может иметь значения перечисления Read и Write, а затем QObject::setProperty() может принимать Read | Write. Для регистрации этого типа перечисления следует использовать Q_FLAG().

Динамические свойства

QObject::setProperty() также может использоваться для добавления новых свойств к экземпляру класса во время выполнения. При вызове с именем и значением, если свойство с заданным именем существует в QObject и если заданное значение совместимо с типом свойства, значение хранится в свойстве, и возвращается true. Если значение не совместимо с типом свойства, свойство не изменяется, и возвращается false. Но если свойство с заданным именем не существует в QObject (т. е. если оно не было объявлено с помощью Q_PROPERTY()), новое свойство с заданным именем и значением автоматически добавляется в QObject, но всё равно возвращается false. Это означает, что возвращение false нельзя использовать для определения того, было ли фактически установлено конкретное свойство, если вы не знаете заранее, что свойство уже существует в QObject.

Обратите внимание, что динамические свойства добавляются на основе каждого экземпляра, т. е. они добавляются в QObject, а не в QMetaObject. Свойство можно удалить из экземпляра, передав имя свойства и недействительное значение QVariant в QObject::setProperty(). Конструктор по умолчанию для QVariant создаёт недействительное значение QVariant.

Динамические свойства можно запросить с помощью QObject::property(), точно так же, как свойства, объявленные во время компиляции с помощью Q_PROPERTY().

Свойства и пользовательские типы

Пользовательские типы, используемые свойствами, необходимо регистрировать с помощью макроса Q_DECLARE_METATYPE(), чтобы их значения можно было хранить в объектах QVariant. Это делает их подходящими для использования как со статическими свойствами, объявленными с помощью макроса Q_PROPERTY() в определениях классов, так и с динамическими свойствами, созданными во время выполнения.

Добавление дополнительной информации в класс

Связанный с системой свойств дополнительный макрос Q_CLASSINFO() может использоваться для добавления дополнительных пар имя--значение в метаобъект класса, например:

Q_CLASSINFO("Version", "3.0.0")

Как и другие метаданные, информация о классе доступна во время выполнения через метаобъект; см. QMetaObject::classInfo() для получения подробностей.

См. также Систему метаобъектов, Сигналы и слоты, Q_DECLARE_METATYPE(), QMetaType и QVariant.