The Property Browser Framework

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

Версия 20:57, 27 сентября 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, расширяя интерфейс своими атрибутами и предоставляя необходимые функции getter и setter для нашего пользовательского свойства. Сигналы valueChanged() и filterChanged() используются для связи с фабриками пользовательских редакторов ( будут показаны позже), а также могут быть в общем использованы для мониторинга свойств. Мы определяем простую структуру данных для хранения состояния значения и фильтра для каждого свойства пути к файлу, а также записываем каждое свойство пути к файлу на private map.

The FilePathManager must also reimplement several protectedfunctions provided by its base class that are needed by theframework: valueText() returns a string representation of the property'svalue, initializeProperty() initializes a new property, anduninitializeProperty() is used to clean up when a property is deleted.

We return empty data from getter functions if an unknown property issupplied; otherwise we return the data from the property map:

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

In the setter functions, we ignore attempts to set the values of unknownproperties, and only commit new data to the property map. We emit thebase class's propertyChanged() signal to notify other components of anychanges. However, note that the setFilter() does not need to do thisbecause it does not change the property's value.

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

Before we can add instances of our custom property to the browserwidget, we must also provide a factory which is able to produceFileEdit editors for our property manager:

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

The FileEditFactory is derived from the QtAbstractEditorFactorytemplate class, using our FilePathManager class as the templateargument. This means that our factory is only able to create editorsfor our custom manager while allowing it to access the manager's enrichedinterface.

As with the manager, the custom factory must reimplement some protectedfunctions. For example, the connectPropertyManager() function iscalled when the factory is set up for use with a FilePathManager,and connects the manager's valueChanged() and filterChanged()signals to the corresponding slotPropertyChanged() andslotFilterChanged() slots. These connections keep the state of theeditors up to date. Similarly, disconnectPropertyManager() is used toremove these connections.

The createEditor() function creates and initializes a FileEditwidget, adds the editor to the internal maps:

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;

Before returning the new editor widget, we connect its filePathChanged()signal to the factory's slotSetValue() slot. We also connect itsdestroyed() signal to the factory's slotEditorDestroyed() slot toensure that we are notified if it is destroyed.

Internally, the task of each factory is to synchronize the state of theeditors with the state of the properties. Whenever an editor changesits value we need to tell the framework about it, and vice versa.In our editor factory's editorToProperty map, we relate every editorcreated by the factory to the property it was created to edit.

The opposite relation is kept in the createdEditors map, whereproperties are related to editors. Since it is possible that two or moreproperty browsers are displaying the same instance of a property, we mayneed to create many editors for the same property instance, so we keep alist of editors for each property.

Combined with the private slots, these data structures allow us toinform the framework that an editor value has been changed, and let usupdate all relevant editors whenever the framework changes any of theproperties.

When the factory is destroyed, the state of the properties is no longersynchronized, and the data shown by the editors is no longer valid. For thatreason, all the editors created by the factory are deleted in the factory'sdestructor. Therefore, when an editor is destroyed, we must ensure that itis removed from the internal maps.

The process of adding a custom property is equivalent to adding any otherproperty:

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

The variant-based approach can also be used for custom types. Using thisapproach, we derive our manager from QtVariantPropertyManager and ourfactory from 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.

Текст заголовка