BaseSettingsManager

To simplify and reduce required coding, LeechCraft provides a BaseSettingsManager class in xmlsettingsdialog/basesettingsmanager.h, whose subclasses should reimplement only two functions:

virtual QSettings* BeginSettings () const;
virtual void EndSettings (QSettings *settings) const;

First one allocates and returns QSettings object and is used to customize the creation process (such as desired company/program name, grouping etc.), second one is used to correctly close that settings object. It should not delete the passed object, BaseSettingsManager's code would do that instead.

Typical example would be:

class XmlSettingsManager : public BaseSettingsManager
{
// Any additional code you want
protected:
    virtual QSettings* BeginSettings () const;
    virtual void BeginSettings (QSettings*) const;
};
 
virtual QSettings* XmlSettingsManager::BeginSettings () const
{
    QSettings *settings = new QSettings ("Deviant", "LeechCraft");
    settings->beginGroup ("Very universal plugin");
    settings->beginGroup ("XML Settings");
    return settings;
}
 
virtual void XmlSettingsManager::EndSettings (QSettings *settings) const
{
    settings->endGroup ();
    settings->endGroup ();
}

XmlSettingsDialog. Initialization.

I'll explain the way I do it, but if you get it, you'll be able to write as you want. I usually write those settings managers as singletons as that's common sense — there is usually only one settings manager in every plugin.

To add the settings dialog with bundled parser to your plugin:

#include <xmlsettingsdialog/xmlsettingsdialog.h>
class MyUniversalPlugin : // any classes you inherit from 
{
    // Lots of your code
    XmlSettingsDialog *XmlSettingsDialog_;
    // Even more here
};
 
// As you now, this function is called when main LeechCraft app loads your plugin.
void MyUniversalPlugin::Init ()
{
    // Initialization code, settings aren't used yet
    XmlSettingsDialog_ = new XmlSettingsDialog (this);
    XmlSettingsDialog_->RegisterObject (XmlSettingsManager::Instance (), "pathtofilewithsettings.xml");
    // Other initialization code where settings should be ready
}

XmlSettingsDialog currently supports only one settings manager object per instance, that limitation would be taken away in near future. There is no correct check now if the registered class is actually a settings manager, so it's entirely your fault when you'll register wrong class. The program wouldn't fail, but you will possibly loose some data.

Using settings

Dynamic properties for settings in XML file are automatically created upon registering settings manager object. So imagine you have a setting ServerAddress (a QString), and ServerPort (integer). To query them somewhere in your code, do the following:

QString address = XmlSettingsManager::Instance ()->property ("ServerAddress").toString ();
int port = XmlSettingsManager::Instance ()->property ("ServerPort").toInt ();

Setting properties from program is of course also possible:

XmlSettingsManager::Instance ()->setProperty ("ServerAddress", address);
XmlSettingsManager::Instance ()->setProperty ("ServerPort", 80);

As both property () and setProperty () use QVariant, make sure your property types work well with it. See the QVariant's docs about it.

Remember that setting the property from code would result in immediate flushing to QSettings, so setting it frequently would result in performance degradation. Future versions would have some kind of delay to accumulate changes.

Retrieving and storing your own settings

You may want to store your own settings not defined in XML file. LeechCraft's settings framework is suitable for that as well.

Imagine you want to get "size" property on startup to resize your plugin's window to previous size. As this is property is not described in XML Settings file, it is not known to XmlSettingsManager, and XmlSettingsManager::Instance ()->property ("size") would return just an invalid QVariant.

A common practice is to check if the returned value is valid, and if it not, use some predefined. So BaseSettingsManager defines a special
Property (const QString& propName, const QVariant& def) member function. If propName already exists, it just returns it's value, otherwise it creates this property, sets it to def and returns def back.

So, our geometry-managing code would look like this:

QSize size = XmlSettingsManager::Instance ()->Property ("size", QSize (800, 600)).toSize ();
resize (size);

Storing your own settings isn't different at all. Remember again that setting the property from code would result in immediate flushing to QSettings, so setting it frequently would result in performance degradation. Future versions would have some kind of delay to accumulate changes.

Subscribing to changes

Program often wants to know when a property changes either by user or by some other code. Imagine user changes port range for the BitTorrent client, and you should somehow rebind to one of those new ports. There are three solutions of this problem.

• You could say everytime:
  

  Restart the program for the changes to take effect.

  Reminds something, doesn't it?

• You could start a timer and query XmlSettingsManager for settings for example once a second. That's quite bad, because there is a slight delay after changes are made and before they are taken into account, sometimes it's critical, especially for good GUI applications. You also should waste resources to query all the properties, sometimes it's also critical. That's not also straight-forward and is even maybe error-prone;
• You could use the "subscribing" feature of XmlSettingsManager.

Let us consider the third approach.

XmlSettingsManager has a member function
RegisterObject (const QByteArray& propName, QObject* object, const QByteArray& funcName)
Where:

• propName — name of property you subscribe to;
• funcName — name of the function that should be called when the property changes;
• object — object on which -+XmlSettingsManager+- would operate.

funcName should be known to Qt's metaobjects, so it should be a slot. It is always called without any parameters, and it's entirely underlying's code job to retrieve needed settings.

So, following code would do the trick:

class SettingsWatcher : public QObject
{
    Q_OBJECT
public slots:
// ...
    void onPortRangeChanged ();
// ...
};
// ...
void SettingsWatcher::onPortRangeChanged ()
{
    // Get new port range and rebind.
}
// ...
// Or somewhere else, but recommended here
void YourVeryCoolPlugin::Init ()
{
    // ...
    // SettingsWatcher is a singleton, but it's not usually required
    // to create a separate holder for slots
    XmlSettingsManager::Instance ()->RegisterObject ("PortRange", SettingsWatcher::Instance (), "onPortRangeChanged");
    // ...
}