Редактирование: The Property Browser Framework

{{Панель навигации по Qt Quarterly|Выпуск 18}}
{| border="0" cellspacing="0" cellpadding="10" width="100%"
|-
|'''by Jarek Kobus'''
|}<blockquote>'''Последний выпуск Qt Solutions включал решение Property Browser, конструкцию, предоставляющую набор графических редакторов для свойств Qt, похожих на те, что используются в Qt Designer.'''
__TOC__
</blockquote>
В этой статье мы подробно рассмотрим динамику классов Property Browser, представим два способа их использования в ваших приложениях, а также посмотрим, как фреймворк можно расширять с помощью типов и редакторов.

['''[http://www.crossplatform.ru/uploads/articles/sources/qq18-propertybrowser-code.zipDownload source code]''']

<div id="thebigpicture"></div>
== The Big Picture ==
Фреймворк Property Browser включает в себя виджеты браузера, менеджеры свойств, фабрики свойств и сами свойства. 

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

[[Image:qq18-propertybrowser-widgets.png|center]]

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

Custom editor widgets for propertiesare created by factories derived from the [[Qt:Документация_4.3.2/qabstracteditorfactory  | QAbstractEditorFactory]] class.

Properties only need to be encapsulated in <tt>QtProperty</tt> instances beforethey can be used in browser widgets. These instances are created andmanaged by property managers derived from the <tt>QtAbstractPropertyManager</tt>class.

<div id="populatingthepropertybrowser"></div>
== Populating the Property Browser ==

When using a property browser widget, managers must be created foreach of the required property types if we want the user to be able to editthe properties.

The framework provides managers for the most commontypes. For example, to create an integer property we first instantiatethe <tt>QtIntPropertyManager</tt> class, then we use its <tt>addProperty()</tt>function to create the property:
<source lang="cpp-qt">
QtIntPropertyManager *intManager;
QtProperty *priority:

intManager = new QtIntPropertyManager;
priority = intManager->addProperty("Priority");

priority->setToolTip("Task Priority");
intManager->setRange(priority, 1, 5);
intManager->setValue(priority, 3);
</source> 
The <tt>QtProperty</tt> class provides functions for setting a property's name,tooltip, status tip and "What's This?" text. To set and alter theproperty's value and range, each manager has its own type specificAPI. For example, here's how an enum property is set up and given adefault value:
<source lang="cpp-qt">
QtEnumPropertyManager *enumManager;
QtProperty *reportType;
QStringList types;   
...
types << "Bug" << "Suggestion" << "To Do";
enumManager->setEnumNames(reportType, types);
enumManager->setValue(reportType, 1); // "Suggestion"
</source> 
Properties can be categorized into groups using the <tt>QtGroupPropertyManager</tt>class. For example:
<source lang="cpp-qt">
QtGroupPropertyManager *groupManager;
QtProperty *task1;

groupManager = new QtGroupPropertyManager;
task1 = groupManager->addProperty("Task 1");

task1->addSubProperty(priority);
task1->addSubProperty(reportType);
</source> 
In addition, each property can have zero or more subproperties. These are justnormal properties that are added to a property using its <tt>addSubProperty()</tt>function.

The properties created by a group property manager don't have anyvalue, they are just provided as grouping elements in the propertyhierarchies and can be added to the browser in the same way as anyother property.

Once we have the properties, we associate each property manager with afactory for the preferred editor for that type. As with managers, the framework provides factoriesfor common widgets like [[Qt:Документация_4.3.2/qspinbox  | QSpinBox]] and [[Qt:Документация_4.3.2/qcombobox  | QComboBox]].
<source lang="cpp-qt">
QtSpinBoxFactory *spinBoxFactory;
QtEnumEditorFactory *enumFactory;

spinBoxFactory = new QtSpinBoxFactory;
enumFactory = new QtEnumEditorFactory;

QtTreePropertyBrowser *browser;
browser = new QtTreePropertyBrowser;
browser->setFactoryForManager(intManager, spinBoxFactory);
browser->setFactoryForManager(enumManager, enumFactory);
</source> 
By relating a factory to a manager, we ensure that whenever a propertycreated by that manager appears in the browser, the specified factorywill be used to create an editor for it.
<source lang="cpp-qt">
browser->addProperty(task1);
browser->show();
</source> 
Finally, it only remains to add our properties to the browserand ensure that the browser widget is shown.

[[Image:qq18-propertybrowser-example.png|center]]

Note that to provide different editor widgets for the same propertytype, we only need to call <tt>setFactoryForManager()</tt> with another instanceof the type-specific factory.

Once the browser widget is populated, the user can interact with itand edit the properties. We can monitor the values of properties byconnecting to each property manager's signals, such as<tt>QtIntPropertyManager::valueChanged()</tt> and<tt>QtEnumPropertyManager::enumChanged()</tt>.

<div id="thevariantapproach"></div>
== The Variant Approach ==
In the previous section we populated the property browser usingspecialized classes for each property type. But the framework alsoprovides a convenient second approach that uses [[Qt:Документация_4.3.2/qvariant  | QVariant]] to holdall the properties' values and attributes.

In this approach, the developer only needs one property manager classand one editor factory class. These are selected from the followingthree classes:
* <tt>QtVariantProperty</tt> inherits <tt>QtProperty</tt> but has anenriched API, allowing properties values and attributes to be directlyqueried and altered. 
* <tt>QtVariantPropertyManager</tt> can be used for all propertytypes, and its additional API can be used to query for supported variant typesand their attribute lists. 
* <tt>QtVariantEditorFactory</tt> is capable of creating variouseditor widgets for the types supported by <tt>QtVariantPropertyManager</tt>. 
Using this approach, the code from the previous section to manage aninteger property now looks like this:
<source lang="cpp-qt">
QtVariantPropertyManager *variantManager;
variantManager = new QtVariantPropertyManager;

QtVariantProperty *priority = variantManager->addProperty(QVariant::Int, "Priority");
priority->setAttribute("minimum", 1);
priority->setAttribute("maximum", 5);
priority->setValue(3);
</source> 
Note the additional argument in the <tt>QtVariantManager::addProperty()</tt>function. It is the type of property we want to create. This can beany of values defined in the [[Qt:Документация_4.3.2/qvariant  | QVariant]]::Type enum plus additional uservalues obtained using the <tt>qMetaTypeId()</tt> function. 

Subsequently, instead of calling <tt>setRange()</tt> on<tt>QtIntPropertyManager</tt>, we use the <tt>setAttribute()</tt> function of<tt>QtVariantProperty</tt> class twice, passing minimum and maximum valuesfor the property. Finally, we call the <tt>setValue()</tt> function directlyon the <tt>QtVariantProperty</tt> instance. 

The ID of an enum property is not built into [[Qt:Документация_4.3.2/qvariant  | QVariant]], and must beobtained using the static <tt>QtVariantPropertyManager::enumTypeId()</tt>function.
<source lang="cpp-qt">
QtVariantProperty *reportType = variantManager->addProperty(
    QtVariantPropertyManager::enumTypeId(), "Report Type");
QStringList types;
types << "Bug" << "Suggestion" << "To Do";
reportType->setAttribute("enumNames", types);
reportType->setValue(1); // "Suggestion"
</source> 
Then we can call <tt>setAttribute()</tt> for the property,passing <tt>"enumNames"</tt> 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 <tt>QtVariantPropertyManager::groupTypeId()</tt>function.

In the end we create an instance of the <tt>QtVariantEditorFactory</tt> class,and use it with our variant manager in our chosen property browser:
<source lang="cpp-qt"> 
QtTreePropertyBrowser *browser;
QtVariantEditorFactory *factory;
...
browser->setFactoryForManager(variantManager, factory);
</source>

<div id="extendingtheframework"></div>
== 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[[Qt:Документация_4.3.2/qstring  | QString]], and the property can in addition possess afiltering attribute. We can also create a custom editor for our type,<tt>FileEdit</tt>, a simple composition of [[Qt:Документация_4.3.2/qlineedit  | QLineEdit]] and[[Qt:Документация_4.3.2/qtoolbutton  | 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.

[[Image:qq18-propertybrowser-example-extension.png|center]]

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:
<source lang="cpp-qt">
class FilePathManager : public QtAbstractPropertyManager
{
    ...
    QString value(const QtProperty *property) const;
    QString filter(const QtProperty *property) const;
public slots:
    void setValue(QtProperty *, const QString &amp;);
    void setFilter(QtProperty *, const QString &amp;);
signals:
    void valueChanged(QtProperty *, const QString &amp;);
    void filterChanged(QtProperty *, const QString &amp;);
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;
};
</source> 
Our custom <tt>FilePathManager</tt> is derived from the<tt>QtAbstractPropertyManager</tt>, enriching the interface with its attributes,and providing the required getter and setter functions for our custom property.The <tt>valueChanged()</tt> and<tt>filterChanged()</tt> 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 <tt>FilePathManager</tt> must also reimplement several protectedfunctions provided by its base class that are needed by theframework: <tt>valueText()</tt> returns a string representation of the property'svalue, <tt>initializeProperty()</tt> initializes a new property, and<tt>uninitializeProperty()</tt> 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:
<source lang="cpp-qt">
QString FilePathManager::value(const QtProperty *property)
        const
{
    if (!theValues.contains(property)) return "";
    return theValues[property].value;
}
</source> 
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 <tt>propertyChanged()</tt> signal to notify other components of anychanges. However, note that the <tt>setFilter()</tt> does not need to do thisbecause it does not change the property's value.
<source lang="cpp-qt">
void FilePathManager::setValue(QtProperty *property, const QString &amp;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);
}
</source> 
Before we can add instances of our custom property to the browserwidget, we must also provide a factory which is able to produce<tt>FileEdit</tt> editors for our property manager:
<source lang="cpp-qt">
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;
};
</source> 
The <tt>FileEditFactory</tt> is derived from the <tt>QtAbstractEditorFactory</tt>template class, using our <tt>FilePathManager</tt> 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 <tt>connectPropertyManager()</tt> function iscalled when the factory is set up for use with a <tt>FilePathManager</tt>,and connects the manager's <tt>valueChanged()</tt> and <tt>filterChanged()</tt>signals to the corresponding <tt>slotPropertyChanged()</tt> and<tt>slotFilterChanged()</tt> slots. These connections keep the state of theeditors up to date. Similarly, <tt>disconnectPropertyManager()</tt> is used toremove these connections.

The <tt>createEditor()</tt> function creates and initializes a <tt>FileEdit</tt>widget, adds the editor to the internal maps:
<source lang="cpp-qt">
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 &amp;)),
        this, SLOT(slotSetValue(const QString &amp;)));
connect(editor, SIGNAL(destroyed(QObject *)),
        this, SLOT(slotEditorDestroyed(QObject *)));
return editor;
</source> 
Before returning the new editor widget, we connect its <tt>filePathChanged()</tt>signal to the factory's <tt>slotSetValue()</tt> slot. We also connect its<tt>destroyed()</tt> signal to the factory's <tt>slotEditorDestroyed()</tt> 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 <tt>editorToProperty</tt> map, we relate every editorcreated by the factory to the property it was created to edit.

The opposite relation is kept in the <tt>createdEditors</tt> 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:
<source lang="cpp-qt">
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);
</source>

<div id="extendingwithvariants"></div>
== Extending with Variants ==
The variant-based approach can also be used for custom types. Using thisapproach, we derive our manager from <tt>QtVariantPropertyManager</tt> and ourfactory from <tt>QtVariantPropertyFactory</tt>.

In the previous example, the <tt>FilePathManager</tt> 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:
<source lang="cpp-qt">
class FilePathPropertyType
{
};
Q_DECLARE_METATYPE(FilePathPropertyType)
</source> 
The custom manager must reimplement several inherited functions andprovide a static function to return the new property type:
<source lang="cpp-qt">
int VariantManager::filePathTypeId()
{
    return qMetaTypeId<FilePathPropertyType>();
}
</source> 
This function returns a unique identifier for our file path property typethat can be passed to <tt>QtVariantPropertyManager</tt>::<tt>addProperty()</tt> tocreate new file path properties.

Unlike the <tt>FilePathManager</tt> 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 <tt>isPropertyTypeSupported()</tt>function we should return <tt>true</tt> for our custom type, and callthe base class implementation for all other types:
<source lang="cpp-qt">
bool VariantManager::isPropertyTypeSupported(
     int propertyType) const
{
    if (propertyType == filePathTypeId())
        return true;
    return QtVariantPropertyManager::
        isPropertyTypeSupported(propertyType);
}
</source> 
The <tt>VariantFactory</tt> class, like every other editor factory, doesnot have to provide any new members. Basically, the implementationis very similar to <tt>FileEditFactory</tt> in the previous section. The onlydifference in the <tt>connectPropertyManager()</tt> function is that we mustconnect the manager's <tt>attributeChanged()</tt> signal to a general<tt>slotPropertyAttributeChanged()</tt> 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 the<tt>createEditor()</tt> function:
<source lang="cpp-qt">
if (manager->propertyType(property) == VariantManager::filePathTypeId()) {
  ...
  connect(editor, SIGNAL(filePathChanged(const QString&amp;)),
          this, SLOT(slotSetValue(const QString &amp;)));
  connect(editor, SIGNAL(destroyed(QObject *)),
          this, SLOT(slotEditorDestroyed(QObject *)));
  return editor;
}
...
</source> 
We also monitor the editor via its <tt>destroyed()</tt> and custom<tt>filePathChanged()</tt> signals.

Using custom variant managers and factories is no different thanusing those delivered by the framework:
<source lang="cpp-qt">
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);
</source> 
All that's left to do is to set up the browser to use the propertymanager and factory in the same way as before.

<div id="summary"></div>
== 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 <tt>QtVariantEditorFactory</tt>must 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.
<hr />
{| width="100%"
|-
|Copyright &copy; 2006 Trolltech
| align="right" | [http://www.trolltech.com/trademarks.html Trademarks]
|}