The Property Browser Framework

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

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.

The ID of an enum property is not built into QVariant, and must beobtained using the static QtVariantPropertyManager::enumTypeId()function.

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

Then we can call setAttribute() for the property,passing "enumNames" as the attribute name, to set the possible enumvalues that the property can have.

Group properties are created in the same way as enum properties, but withan ID retrieved using the QtVariantPropertyManager::groupTypeId()function.

In the end we create an instance of the QtVariantEditorFactory class,and use it with our variant manager in our chosen property browser:

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

Extending the Framework

So far we have used the existing properties, managers and factories providedby the Property Browser framework. But the framework also allows thedeveloper to create and support custom property types.

Let's say we want to extend our previous example, and support a customfile path property. The value of our custom property can be a QString, and the property can in addition possess afiltering attribute. We can also create a custom editor for our type,FileEdit, a simple composition of QLineEdit and QToolButton. We want to let the line edit show the current file path,and show a file browser dialog when the tool button is pressed (allowing theuser to choose a file from the files that match our filtering attribute).

The editor class provides getter and setter functions for its fields, aswell as a signal that can be emitted whenever the file path changes.

We have described two approaches for populating a browser widget:One uses type specific property managers and editor factories; the otheruses the framework's variant base classes. Both approaches support customtypes.

If we choose the type specific approach, we must provide a managerthat is able to produce properties of our custom type, and that canstore the state of the properties it creates; i.e., their values andattributes. Such a manager looks like this:

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

Our custom FilePathManager is derived from theQtAbstractPropertyManager, enriching the interface with its attributes,and providing the required getter and setter functions for our custom property.The valueChanged() andfilterChanged() signals are used to communicate with custom editorfactories (shown later), and can also be generally used to monitor properties.We define a simple data structure to store the state ofthe value and filter for each file path property, and record each file pathproperty in a 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.

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