Using the dialog template for your conduit

Now that we have the dialog template, we can include it in the configuration dialog box. First, create a subclass of ConduitConfig, where we only have to implement the con- and destructor as well as the methods

• virtual void readSettings()
• virtual void commitChanges()

This class ConduitConfig will do most of the work for us, all that is left to us is to read the config settings from the config file and set the values of the controls in the dialog (in the readSettings() method). Also, when commitChanges() is called, this means that the dialog was existed with the OK button, so we need to read the new values from the controls and store them to the configuration file.

The whole class declaration is:

class MALWidget;

class MALWidgetSetup : public ConduitConfig 
{
Q_OBJECT
public:
    MALWidgetSetup(QWidget *,const char *,const QStringList &);
    virtual ~MALWidgetSetup() {};
    virtual void readSettings();
protected:
    virtual void commitChanges();
private:
    MALWidget *fConfigWidget;
} ;

This class implements the dialog box itself, and our dialog template will be inserted into this dialog by the constructor:

MALWidgetSetup::MALWidgetSetup(QWidget *w, const char *n,
    const QStringList & a) :
    ConduitConfig(w,n,a)
{
    FUNCTIONSETUP;

    fConfigWidget = new MALWidget(widget());
    setTabWidget(fConfigWidget->tabWidget);
    addAboutPage(false,MALConduitFactory::about());

    fConfigWidget->tabWidget->adjustSize();
    fConfigWidget->resize(fConfigWidget->tabWidget->size());
}

The first two lines create an instance of our dialog template and add it as the tab widget to the dialog. Since we will have to set and read the values of the controls in that tab widget, we need to store a pointer to the instance in the variable fConfigWidget which is of the same type (MALWidget) we assigned to our dialog template in QT Designer. The third line of code adds the about page (which is created by the factory, see last section) to the tab widget, while the last two line just adjust the size of the dialog box and are not always needed.

As mentioned above, we only need to implement MALWidgetSetup::readSettings() and MALWidgetSetup::commitChanges(). The ConduitConfig class already stores an instance named fConfig to KPilot's configuration facility. We only have to set the correct configuration group name (I suggest, you store the name of the configuration group for you conduit in a static char* variable of the conduit factory class), and then we can use the methods

• fConfig->readNumEntry("entryname", defaultNumericValue)
• fConfig->readEntry("entryname", defaultstring)
• fConfig->readBoolEntry("entryname", defaultBoolValue)

to retrieve the settings from the configuration file. We then use the methods of the QT and KDE widgets to assign the text or value to the controls:

/* virtual */ void MALWidgetSetup::readSettings()
{
    FUNCTIONSETUP;

    if (!fConfig) return;
    KConfigGroupSaver s(fConfig,MALConduitFactory::group());
    
    fConfigWidget->syncTime->setButton(fConfig->readNumEntry(MALConduitFactory::syncTime(), 0));
    
    // Proxy settings
    fConfigWidget->proxyType->setButton(
        fConfig->readNumEntry(MALConduitFactory::proxyType(), 0));
    fConfigWidget->proxyServerName->setEditText(
        fConfig->readEntry(MALConduitFactory::proxyServer(), ""));
    int proxyPortNr=fConfig->readNumEntry(MALConduitFactory::proxyPort(), 0);
    if (proxyPortNr>0 && proxyPortNr<65536) 
    {
        fConfigWidget->proxyCustomPortCheck->setChecked(true);
        fConfigWidget->proxyCustomPort->setEnabled(true);
        fConfigWidget->proxyCustomPort->setValue(proxyPortNr);
    }
    fConfigWidget->proxyUserName->setText(fConfig->readEntry(
        MALConduitFactory::proxyUser(), ""));
    fConfigWidget->proxyPassword->setText(fConfig->readEntry(
        MALConduitFactory::proxyPassword(), ""));
}

In this example, we don't store to the configuration file if a custom proxy port should be used. Instead, we just store a port number, and if the port number is 0 this means to use the default port. In this case, the custom port CheckBox needs to stay unchecked, and the port NumEntry control will stay disabled as it is in the dialog template. In all other cases, however, the custom port CheckBox should be checked, and the port NumEntry control will be enabled and filled with the correct custom port.

The KPilot user can then change all the settings in the dialogbox without any intervention from KPilot, so we don't need to write any code for that. Only the commitChanges() method remains to be done, which does the opposite of the readSettings() method. It reads the values of the controls and stores them to the configuration file. The KConfig class (the fConfig variable, resp.) has only one method KConfig::writeEntry("entryname", valueOfWhateverType) to write a value to the configuration file. However, this method has several overloaded implementations so that you can write numeric, string, boolean, date and many more variable types with the same syntax. First, we need to set the correct configuration group again, and then we just read each of the settings and write it out immediately using the writeEntry method:

/* virtual */ void MALWidgetSetup::commitChanges()
{
    FUNCTIONSETUP;

    if (!fConfig) return;
    KConfigGroupSaver s(fConfig,MALConduitFactory::group());
    
    fConfig->writeEntry(MALConduitFactory::syncTime(),
        fConfigWidget->syncTime->id(fConfigWidget->syncTime->selected()));
    
    // Proxy settings
    fConfig->writeEntry(MALConduitFactory::proxyType(),
        fConfigWidget->proxyType->id(fConfigWidget->proxyType->selected()));
    fConfig->writeEntry(MALConduitFactory::proxyServer(), 
        fConfigWidget->proxyServerName->currentText() );

    if (fConfigWidget->proxyCustomPortCheck->isChecked() ) 
    {
        fConfig->writeEntry(MALConduitFactory::proxyPort(), 
            fConfigWidget->proxyCustomPort->value());
    }
    else 
    {
        fConfig->writeEntry(MALConduitFactory::proxyPort(), 0);
    }
    fConfig->writeEntry(MALConduitFactory::proxyUser(), 
        fConfigWidget->proxyUserName->text() );
    fConfig->writeEntry(MALConduitFactory::proxyPassword(), 
        fConfigWidget->proxyPassword->text() );
}

This was all that is needed to implement the configuration for your conduit. Simple, isn't it?