The Property Browser Framework

Материал из Wiki.crossplatform.ru

Текущая версия на 10:25, 28 сентября 2020

Qt Quarterly | Выпуск 18 | Документация

Последний выпуск Qt Solutions включал решение Property Browser, конструкцию, предоставляющую набор графических редакторов для свойств Qt, похожих на те, что используются в Qt Designer.

Содержание 1 The Big Picture 2 Заполнение браузера свойств (Populating the Property Browser) 3 Вариантный подход (The Variant Approach) 4 Расширение фреймворка (Extending the Framework) 5 Расширение с помощью Вариантов (Extending with Variants) 6 Summary 7 Текст заголовка

В этой статье мы подробно рассмотрим динамику классов Property Browser, представим два способа их использования в ваших приложениях, а также посмотрим, как фреймворк можно расширять с помощью типов и редакторов.

[source code]

[править] The Big Picture

Фреймворк Property Browser включает в себя виджеты браузера, менеджеры свойств, фабрики свойств и сами свойства.

Виджеты браузера - это пользовательские интерфейсы, позволяющие пользователю редактировать заданный набор иерархически структурированных свойств: QtTreePropertyBrowser представляет свойства с использованием древовидных структур и QtGroupBoxPropertyBrowser отображает свойства в group box.

Кроме того, можно расширить фреймворк, написав собственные виджеты браузера, производные от класса QtAbstractPropertyBrowser.

Настраиваемые виджеты редактора свойств, создаваемые фабриками, производными от класса QAbstractEditorFactory.

Свойства должны быть инкапсулированы только в экземплярах QtProperty, прежде чем они могут быть использованы в виджетах браузера. Эти экземпляры создаются и управляются менеджерами свойств, производными от класса QtAbstractPropertyManager.

[править] Заполнение браузера свойств (Populating the Property Browser)

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

Этот фреймворк предоставляет менеджерам наиболее часто встречающиеся типы. Например, для создания целочисленного свойства мы сначала создаём экземпляр класса QtIntPropertyManager, а затем используем его функцию addProperty() для создания свойства:

QtIntPropertyManager *intManager;
QtProperty *priority:
 
intManager = new QtIntPropertyManager;
priority = intManager->addProperty("Priority");
 
priority->setToolTip("Task Priority");
intManager->setRange(priority, 1, 5);
intManager->setValue(priority, 3);

Класс QtProperty предоставляет функции для установки имени свойства, всплывающей подсказки, подсказки состояния и сообщения "What's This?". Для установки и изменения значения свойства и диапазона, каждый менеджер имеет свой API, специфичный для определённого типа. Например, вот как устанавливается свойство enum и ему присваивается значение по умолчанию:

QtEnumPropertyManager *enumManager;
QtProperty *reportType;
QStringList types;   
...
types << "Bug" << "Suggestion" << "To Do";
enumManager->setEnumNames(reportType, types);
enumManager->setValue(reportType, 1); // "Suggestion"

Свойства можно разбить на группы, используя класс QtGroupPropertyManager. Например:

QtGroupPropertyManager *groupManager;
QtProperty *task1;
 
groupManager = new QtGroupPropertyManager;
task1 = groupManager->addProperty("Task 1");
 
task1->addSubProperty(priority);
task1->addSubProperty(reportType);

Кроме того, каждое свойство может иметь ноль и более под-свойств. Это обычные свойства, которые добавляются к свойству с помощью функции addSubProperty().

Свойства, созданные менеджером свойств группы (GroupPropertyManager), не имеют никакого значения, они просто предоставляются в качестве элементов группировки в иерархиях свойств и могут быть добавлены в браузер так же, как и любое другое свойство.

Получив свойства, мы связываем каждого менеджера свойств фабрикой для предпочтительного редактора данного типа. Как и в случае с менеджерами, фреймворк предоставляет фабрики для таких распространенных виджетов, как QSpinBox and QComboBox.

QtSpinBoxFactory *spinBoxFactory;
QtEnumEditorFactory *enumFactory;
 
spinBoxFactory = new QtSpinBoxFactory;
enumFactory = new QtEnumEditorFactory;
 
QtTreePropertyBrowser *browser;
browser = new QtTreePropertyBrowser;
browser->setFactoryForManager(intManager, spinBoxFactory);
browser->setFactoryForManager(enumManager, enumFactory);

Привязывая фабрику к менеджеру, мы гарантируем, что всякий раз, когда в браузере появляется свойство, созданное этим менеджером, указанная фабрика будет использована для создания редактора для него.

browser->addProperty(task1);
browser->show();

Наконец, остается только добавить наши свойства в браузер и убедиться, что виджет браузера отображается.

Обратите внимание, что для предоставления различных виджетов редактирования для одного и того же типа свойств, нам нужно только вызвать setFactoryForManager() с другой фабрикой, специфичной для данного типа.

После заполнения виджета браузера пользователь может взаимодействовать с ним и редактировать его свойства. Мы можем отслеживать значения свойств, подключаясь к сигналам каждого менеджера свойств, таких как QtIntPropertyManager::valueChanged() и QtEnumPropertyManager::enumChanged().

[править] Вариантный подход (The Variant Approach)

В предыдущем разделе мы заполнили браузер свойств, используя специализированные классы для каждого типа свойств. Но фреймворк также предоставляет также и второй удобный подход, использующий QVariant для хранения всех значений и атрибутов свойств.

При таком подходе разработчику нужен только один класс менеджера свойств и один класс фабричного редактора. Они выбираются из следующих трех классов:

• QtVariantProperty наследует QtProperty, используя расширенный API, позволяя напрямую запрашивать и изменять значения свойств и атрибутов.
• QtVariantPropertyManager будет использоваться для всех типов свойств, а его вспомогательный API позволит запрашивать поддерживаемые варианты типов и их перечни атрибутов.
• QtVariantEditorFactory предоставляет возможность создавать различные виджеты редактора для типов, поддерживаемых QtVariantPropertyManager.

При таком подходе код из предыдущего раздела для управления целочисленным свойством теперь выглядит следующим образом:

QtVariantPropertyManager *variantManager;
variantManager = new QtVariantPropertyManager;
 
QtVariantProperty *priority = variantManager->addProperty(QVariant::Int, "Priority");
priority->setAttribute("minimum", 1);
priority->setAttribute("maximum", 5);
priority->setValue(3);

Обратите внимание на дополнительный аргумент в функции QtVariantManager::addProperty(). Это тип свойства, которое мы хотим создать. Это может быть любое из значений, определенных в перечислении QVariant::Type enum плюс дополнительные пользовательские значения, полученные с помощью функции qMetaTypeId().

Впоследствии, вместо вызова setRange() на QtIntPropertyManager, мы используем функцию setAttribute() класса QtVariantProperty дважды, передавая минимальное и максимальное значения для свойства. Наконец, мы вызываем функцию setValue() непосредственно на экземпляре QtVariantProperty.

Идентификатор свойства enum не встроен в QVariant, и должен быть получен с помощью статической функции QtVariantPropertyManager::enumTypeId().

QtVariantProperty *reportType = variantManager->addProperty(
    QtVariantPropertyManager::enumTypeId(), "Report Type");
QStringList types;
types << "Bug" << "Suggestion" << "To Do";
reportType->setAttribute("enumNames", types);
reportType->setValue(1); // "Suggestion"

После чего для свойства можно вызвать функцию setAttribute(), передав в качестве имени атрибута "enumNames", чтобы установить возможные значения enum, которые может иметь это свойство.

Групповые свойства создаются таким же образом, как и свойства enum, но с идентификатором, полученным с помощью функции QtVariantPropertyManager::groupTypeId().

В конце мы создаем экземпляр класса QtVariantEditorFactory и используем его с нашим менеджером вариантов в выбранном нами браузере свойств:

 
QtTreePropertyBrowser *browser;
QtVariantEditorFactory *factory;
...
browser->setFactoryForManager(variantManager, factory);

[править] Расширение фреймворка (Extending the Framework)

До сих пор мы использовали существующие свойства, менеджеры и фабрики, предоставленные в рамках Property Browser. Но фреймворк также позволяет разработчику создавать и поддерживать пользовательские типы свойств.

Допустим, мы хотим расширить наш предыдущий пример и добавить поддержку свойств пользовательского пути к файлу. Значением нашего пользовательского свойства может быть QString, и в добавок это свойство может обладать атрибутом фильтрации. Мы также можем создать пользовательский редактор для нашего типа, FileEdit, несложную комбинацию QLineEdit и QToolButton. Мы хотим, чтобы lineEdit показывал текущий путь к файлу и показывал окно браузера файлов при нажатии кнопки toolButton (позволяя пользователю выбрать файл из файлов, соответствующих нашему атрибуту фильтрации).

Класс редактора предоставляет функции геттера и сеттера для своих полей, а также сигнал, который может быть выдан всякий раз, когда меняется путь к файлу.

Мы описали два подхода к заполнению виджета браузера: В одном используются менеджеры свойств и фабрики редакторов, в другом - базовые классы вариантов фреймворка. Оба подхода поддерживают пользовательские типы.

Если мы выбираем подход, ориентированный на конкретный тип, мы должны предоставить такой менеджер, который способен создавать свойства нашего пользовательского типа, и который может хранить состояние создаваемых им свойств, т.е. их значения и атрибуты. Такой менеджер выглядит следующим образом:

class FilePathManager : public QtAbstractPropertyManager
{
    ...
    QString value(const QtProperty *property) const;
    QString filter(const QtProperty *property) const;
public slots:
    void setValue(QtProperty *, const QString &);
    void setFilter(QtProperty *, const QString &);
signals:
    void valueChanged(QtProperty *, const QString &);
    void filterChanged(QtProperty *, const QString &);
protected:
    QString valueText(const QtProperty *property) const
        { return value(property); }
    void initializeProperty(QtProperty *property)
        { theValues[property] = Data(); }
    void uninitializeProperty(QtProperty *property)
        { theValues.remove(property); }
private:
    struct Data {
        QString value;
        QString filter;
    };
    QMap<const QtProperty *, Data> theValues;
};

Наш пользовательский FilePathManager является производным от QtAbstractPropertyManager, расширяя интерфейс своими атрибутами и предоставляя в наше пользовательское свойство необходимые функции геттера и сеттера. Сигналы valueChanged() и filterChanged() используются для связи с фабриками пользовательских редакторов ( будут показаны позже), а также могут быть в общем использованы для мониторинга свойств. Мы определяем простую структуру данных для хранения текущего значения и фильтра для каждого свойства пути к файлу, а также записываем каждое свойство пути в private map.

FilePathManager также должен переопределить несколько protected функций, предоставляемых его базовым классом, которые необходимы фреймворку: функция valueText() возвращает строковое представление значения свойства, функция initializeProperty() инициализирует новое свойство, а функция uninitializeProperty() используется для очистки при удалении свойства.

Мы возвращаем пустые данные из функций геттера, когда указано неизвестное свойство, в противном случае мы возвращаем данные из property map:

QString FilePathManager::value(const QtProperty *property)
        const
{
    if (!theValues.contains(property)) return "";
    return theValues[property].value;
}

В функциях сеттера мы игнорируем попытки установить значения неизвестных свойств и фиксируем только новые данные в property map. Мы посылаем сигнал propertyChanged() базового класса, чтобы уведомить другие компоненты о любых изменениях. Однако, обратите внимание, что функция setFilter() не обязана этого делать, так как не изменяет значение свойства.

void FilePathManager::setValue(QtProperty *property, const QString &val)
{
    if (!theValues.contains(property)) return;
    Data data = theValues[property];
    if (data.value == val) return;
    data.value = val;
    theValues[property] = data;
    emit propertyChanged(property);
    emit valueChanged(property, data.value);
}

Прежде чем мы сможем добавить экземпляры нашего пользовательского свойства в виджет браузера, мы также должны предоставить фабрику, которая сможет создавать редакторы FileEdit для нашего менеджера свойств:

class FileEditFactory
    : public QtAbstractEditorFactory<FilePathManager>
{
    ...
private slots:
    void slotPropertyChanged(QtProperty *property,
                             const QString &amp;value);
    void slotFilterChanged(QtProperty *property,
                           const QString &amp;filter);
    void slotSetValue(const QString &amp;value);
    void slotEditorDestroyed(QObject *object);
private:
    QMap<QtProperty *, QList<FileEdit *> > createdEditors;
    QMap<FileEdit *, QtProperty *> editorToProperty;
};

FileEditFactory является производным от шаблонного класса QtAbstractEditorFactory, используя наш класс FilePathManager в качестве аргумента шаблона. Это означает, что наша фабрика может создавать редакторы только для нашего пользовательского менеджера, в то же время позволяя ему получить доступ к расширенному интерфейсу менеджера.

Как и в случае с менеджером, пользовательская фабрика должна переопределить некоторые закрытые функции. Например, функция connectPropertyManager() вызывается, когда фабрика настраивается на использование с FilePathManager, и соединяет сигналы valueChanged() и filterChanged() менеджера с соответствующими слотами slotPropertyChanged() и slotFilterChanged(). Эти связи позволяют поддерживать состояние редакторов в актуальном состоянии. Аналогично, для удаления этих соединений используется функция disconnectPropertyManager().

Функция createEditor() создает и инициализирует виджет FileEdit, добавляет редактор во внутренние map-ы:

FileEdit *editor = new FileEdit(parent);
editor->setFilePath(manager->value(property));
editor->setFilter(manager->filter(property));
createdEditors[property].append(editor);
editorToProperty[editor] = property;
 
connect(editor, SIGNAL(filePathChanged(const QString &)),
        this, SLOT(slotSetValue(const QString &)));
connect(editor, SIGNAL(destroyed(QObject *)),
        this, SLOT(slotEditorDestroyed(QObject *)));
return editor;

Прежде чем вернуть новый виджет редактора, мы подключаем его сигнал filePathChanged() к фабричному слоту slotSetValue(). Мы также подключаем его сигнал destroyed() к фабричному слоту slotEditorDestroyed(), чтобы быть уверенными в том, что мы получим оповещение, когда он будет уничтожен.

Задача каждой фабрики - синхронизировать состояние редакторов с состоянием свойств. Всякий раз, когда редактор изменяет своё значение, нам необходимо сообщить об этом фреймворку, и наоборот. Каждый редактор, созданный фабрикой, в нашей мапе editorToProperty, мы связываем со свойством, для редактирования которого он был создан.

Противоположная связь сохраняется в map createEditors, где свойства связаны с редакторами. Поскольку возможно, что два или более браузеров свойств отображают один и тот же экземпляр свойства, нам может потребоваться создать множество редакторов для одного и того же экземпляра свойства, поэтому мы ведем список редакторов для каждого свойства.

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

Когда фабрика уничтожается, состояние свойств больше не синхронизируется, и данные, отображаемые редакторами, перестают быть действительными. По этой причине все редакторы, созданные фабрикой, удаляются в деструкторе фабрики. Поэтому при уничтожении редактора необходимо убедиться, что он удален из внутренних maps.

Процесс добавления пользовательского свойства эквивалентен добавлению любого другого свойства:

FilePathManager *filePathManager;
FileEditFactory *fileEditFactory 
QtProperty *example;
 
filePathManager = new FilePathManager;
example = filePathManager->addProperty("Example");
 
filePathManager->setValue(example, "main.cpp");
filePathManager->setFilter(example, 
                           "Source files (*.cpp *.c)");
 
fileEditFactory = new FileEditFactory;
browser->setFactoryForManager(filePathManager, fileEditFactory);
task1->addSubProperty(example);

[править] Расширение с помощью Вариантов (Extending with Variants)

Вариантный подход также может быть использован на пользовательских типах. Используя этот подход, мы получаем менеджер из QtVariantPropertyManager, а нашу фабрику - из QtVariantPropertyFactory.

In the previous example, the FilePathManager class handled the datainternally for our custom property type. In this case, we define theproperty type as a path value with an associated filter attribute. Both thepath and the filter are stored as strings, and we define a new property typefor the file path as a whole:

class FilePathPropertyType
{
};
Q_DECLARE_METATYPE(FilePathPropertyType)

The custom manager must reimplement several inherited functions andprovide a static function to return the new property type:

int VariantManager::filePathTypeId()
{
    return qMetaTypeId<FilePathPropertyType>();
}

This function returns a unique identifier for our file path property typethat can be passed to QtVariantPropertyManager::addProperty() tocreate new file path properties.

Unlike the FilePathManager class, all the functions inherited fromthe base class already have an implementation; all we have to do is tointercept the process whenever our custom property type occurs. Forexample, when reimplementing the isPropertyTypeSupported()function we should return true for our custom type, and callthe base class implementation for all other types:

bool VariantManager::isPropertyTypeSupported(
     int propertyType) const
{
    if (propertyType == filePathTypeId())
        return true;
    return QtVariantPropertyManager::
        isPropertyTypeSupported(propertyType);
}

The VariantFactory class, like every other editor factory, doesnot have to provide any new members. Basically, the implementationis very similar to FileEditFactory in the previous section. The onlydifference in the connectPropertyManager() function is that we mustconnect the manager's attributeChanged() signal to a generalslotPropertyAttributeChanged() slot instead of connecting a specificsignal for the filter to a specific slot to handle changes.

We also need to check that the property can handle our custom type in thecreateEditor() function:

if (manager->propertyType(property) == VariantManager::filePathTypeId()) {
  ...
  connect(editor, SIGNAL(filePathChanged(const QString&)),
          this, SLOT(slotSetValue(const QString &)));
  connect(editor, SIGNAL(destroyed(QObject *)),
          this, SLOT(slotEditorDestroyed(QObject *)));
  return editor;
}
...

We also monitor the editor via its destroyed() and customfilePathChanged() signals.

Using custom variant managers and factories is no different thanusing those delivered by the framework:

QtVariantPropertyManager *variantManager;
variantManager = new VariantManager;
QtVariantEditorFactory *variantFactory;
variantFactory = new VariantFactory;
 
QtVariantProperty *example;
example = variantManager->addProperty(
          VariantManager::filePathTypeId(), "Example");
example->setValue("main.cpp");
example->setAttribute("filter", "Source files (*.cpp *.c)");
 
QtVariantProperty *task1;
task1 = variantManager->addProperty(
    QtVariantPropertyManager::groupTypeId(), "Task 1");
task1->addSubProperty(example);

All that's left to do is to set up the browser to use the propertymanager and factory in the same way as before.

[править] Summary

The Property Browser Solution provides a framework for creating propertyeditors that can be used and extended with either a type-specificor a variant-based API.

The type-specific approach provides a specialized API for each property thatmakes compile-time checking possible. In this approach, the managers andfactories can easily be subclassed and used in other projects. In addition,the developer can customize the property browser with new editorfactories without subclassing.

The variant-based approach provides immediate convenience for the developer,allowing simple, extensible code to be written. However, it can be difficultto integrate into a more complex code base, and QtVariantEditorFactorymust be subclassed to change the default editors.

The first release of the Property Browser framework contained a comprehensive set of examples and documentation. A new version, incorporatingseveral new improvements is expected in the next Qt Solutions release.

[править] Текст заголовка