How to use KSettings::Dialog in your application.

1. Open the dialog from your app
--------------------------------

All you need to do is instanciate KSettings::Dialog and show() it. I recommend
the following:

create the 'Configure MyApp' StdAction like this:
KStdAction::preferences( this, SLOT( showConfigDialog() ), actionCollection );

and the slot looks like this:
if( m_dlg == 0 )
  m_dlg = new KSettings::Dialog( this );
m_dlg->show();

Of course you need to have the 'KSettings::Dialog * m_dlg' member var and
initialize it to 0 in the ctor.

If your application uses KParts that don't set 'X-KDE-ParentApp=<the instance
name of your application>' then you need to use the second ctor of
KSettings::Dialog:
m_dlg = new KSettings::Dialog( QStringList::split( ';', "component1;component2" ) );

The KSettings::Dialog object will be destructed automatically by the QObject
mechanisms.


2. Create pages for your dialog
-------------------------------

Every page is a KCM. This is what you need for creating a page:

class MyAppConfig : public KCModule
{
  Q_OBJECT
public:
  MyAppConfig( QWidget *parent, const char *name = 0, const QStringList &args =
      QStringList() );
  ~MyAppConfig();

  void load();
  void save();
  void defaults();
}

and in the cpp file:

typdef KGenericFactory<MyAppConfig, QWidget> MyAppConfigFactory;
K_EXPORT_COMPONENT_FACTORY( kcm_myappconfig, MyAppConfigFactory(
    "kcm_myappconfig" ) );

MyAppConfig::MyAppConfig( QWidget *parent, const char *, const QStringList &args )
  : KCModule( MyAppConfigFactory::instance(), parent, args )
{
  // create the pages GUI
  load();
}

// implementations for the other methods - don't forget to call
// setChanged( bool ) else the apply button will be disabled and the config of
// your page won't be saved. For the KConfig object you can either use
// KGlobal::config() (I don't recommend it) or KSimpleConfig( "myapprc" ).
// I just added a new method to KSettings::Dispatcher that gives you the KConfig
// object for every registered instance name: configForInstanceName


3. The .desktop file for the page
---------------------------------

The .desktop file holds all the information for the KCD to find the page and
insert it at the right place (with the right icon, name and comment).

An example file:
[Desktop Entry]
Encoding=UTF-8
Icon=myapp
Type=Service
ServiceTypes=KCModule

X-KDE-ModuleType=Library
X-KDE-Library=myappconfig
X-KDE-FactoryName=MyAppConfigFactory
X-KDE-ParentApp=myapp
X-KDE-ParentComponents=myapp

Name=General
Comment=General configuration of my app


Some explanation for those keys:
- You just keep 'Encoding', 'Type', 'ServiceTypes' and 'X-KDE-ModuleType' like
  in the example. For very special needs you might add another ServiceType to
  the list...
- Icon is the icon that will be used in the listview/iconview for your page.
- X-KDE-Library is the name of the library where the page is in. The library
  always needs to be prefixed with kcm_ but you don't write the prefix in the
  desktop file. For more docu on this look for the KCModule docu.
- X-KDE-FactoryName is either the name of the Factory you used in the
  KGenericFactory call or the suffix of the create_ function that you created.
  Again for more info look for the KCModule docu.
- X-KDE-ParentApp is the name of the application this config page belongs to. It
  should be pretty easy to find out what name that is: look at the first
  argument to the KAboutData ctor.
- X-KDE-ParentComponents is a list of the components (plugin/KPart/whatever)
  this config page belongs to. Normally there is only one component.
  It is used for two things:
  1. If you use KSettings::Dispatcher the dispatcher will notify all components
     in this list after the save() method of your KCM has been called. The
     components then can reload the configuration and apply the changes the user
     did to the config.
  2. If your component is used by another application (that is not =
     X-KDE-ParentApp) then it may add the name of the component to the ctor of
     KSettings::Dialog and the dialog will automatically include all config
     pages that have the components name in their ParentComponents list.
- X-KDE-Weight sets the order for the modules to be inserted into the dialog.
  The higher the number (heavier) the lower the module will appear in the list.
- Name is the string that is shown in the listview/iconview right below the
  icon.
- Comment is the string that is shown on top of the config page for a short
  description what you can do on this page.

4. The Pluginselector
---------------------


5. The .desktop files of plugin config pages
--------------------------------------------

# vim: tw=80
