kutils Library API Documentation

KSettings Namespace Reference

A collection of classes to create configuration dialogs that work over component boundaries. More...


Classes

class  ComponentsDialog
 Dialog for selecting which plugins should be active for an application. More...
class  Dialog
 Generic configuration dialog that even works over component boundaries. More...
class  Dispatcher
 Dispatch change notifications from the KCMs to the program. More...
class  PluginPage
 Convenience KCModule for creating a plugins config page. More...

Variables

static KStaticDeleter< Dispatcherksd_kpd


Detailed Description

A collection of classes to create configuration dialogs that work over component boundaries.

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 'KSettingsDialog * 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:

typedef 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

For the KConfig object you can either use KGlobal::config() (I don't recommend it) or KSimpleConfig( "myapprc" ). I added a method to KSettings::Dispatcher that gives you the KConfig object for every registered instance name: KSettings::Dispatcher::configForInstanceName


3. The .desktop file for the page

The .desktop file holds all the information for the dialog 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
X-KDE-Weight=10

Name=General
Comment=General configuration of my app

Some explanation for those keys:


4. The .setdlg file for hierarchical (TreeList) page layouts

If your config dialog should show a tree of pages in the config dialog you need to define that hierarchy with a .setdlg file.

The file should be installed in apps/<appname>/<appname>.setdlg. If third party plugins need to merge in they will install their file to apps/<appname>/ksettingsdialog/<pluginname>.setdlg.

A .setdlg file contains one or more blocks like the following:

[id]
Name=
Comment=
Icon=
Weight=
Parent=


5. The Pluginselector

There are two ways to use the KPluginSelector widget. One is to use the class directly and the second to use KSettings::PluginPage as baseclass for a config page that shows the KPluginSelector widget.

I'll cover the second usage here and the calls to addPlugins are just the same for the first.

To create a plugin page you need the following code:

typedef KGenericFactory<MyAppPluginConfig, QWidget> MyAppPluginConfigFactory;
K_EXPORT_COMPONENT_FACTORY( kcm_myapppluginconfig, MyAppPluginConfigFactory( "kcm_myapppluginconfig" ) );

MyAppPluginConfig( QWidget * parent, const char *, const QStringList & args )
    : PluginPage( MyAppPluginConfigFactory::instance(), parent, args )
{
    pluginSelector()->addPlugins( ... );
    pluginSelector()->addPlugins( ... );
    .
    .
    .
}

pluginSelector() returns a pointer to the KPluginSelector widget of the page. There are three addPlugins methods available, two for adding KParts plugins and one for the rest.


6. The .desktop files of plugin config pages

this is the entry for the Makefile.am:

myappconfigpagedir = $(kde_servicesdir)/<appname>
myappconfigpage_DATA = myappconfigpage.desktop

And this is what the .desktop file looks like:

[Desktop Entry]
Encoding=UTF-8
Type=Service
Icon=<iconname>
ServiceTypes=KPluginInfo

Name=MyPlugin
Comment=My plugin is cool and does foo and bar.

X-KDE-PluginInfo-Name=myplugin

X-KDE-PluginInfo-Author=<your name>
X-KDE-PluginInfo-Email=<your email>
X-KDE-PluginInfo-Website=http://www.myplugin.org/
X-KDE-PluginInfo-Category=CoolPlugins
X-KDE-PluginInfo-Version=0.1
X-KDE-PluginInfo-License=GPL
X-KDE-PluginInfo-EnabledByDefault=true
X-KDE-PluginInfo-Depends=myotherplugin
X-KDE-CfgDlgHierarchy=GroupID

Explanation: mandatory entries:

optional entries:

If you have questions contact Matthias Kretz <kretz@kde.org>.

KDE Logo
This file is part of the documentation for kutils Library Version 3.4.2.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Thu Jul 20 12:45:16 2006 by doxygen 1.4.4 written by Dimitri van Heesch, © 1997-2003