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 instantiate KSettings::Dialog and show() it. I recommend the following:
create the 'Configure MyApp' StdAction like this:
and the slot looks like this:
Of course you need to have the 'KSettings::Dialog * m_dlg' member var and initialize it to 0 in the ctor.
2. Create pages for your dialog
Every page is a KCM. This is what you need for creating a page:
and in the cpp file:
For the KConfig object you can either use KSharedConfig::openConfig() (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] Icon=myapp Type=Service X-KDE-ServiceTypes=KCModule X-KDE-Library=myappconfig 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:
- You just keep 'Encoding', 'Type' and 'X-KDE-ServiceTypes' 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-ParentApp is the name of the application this config page belongs to. It is used by the first two KSettings::Dialog constructors. The Dialog will use all modules that set X-KDE-ParentApp to QCoreApplication::applicationName(). It should be pretty easy to find out what name that is: look for setApplicationName() in main(), otherwise the name of the executable is used.
- 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:
- 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.
- 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. (the default value is 100)
- 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 .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=
- The group name (id) is the name you use in the .desktop file of the page: If your page's .desktop file says "X-KDE-CfgDlgHierarchy=id" then it will be inserted as a child of this entry.
Name:The name of the section. It will appear in the listview.
Comment:A description of what the modules in this section are. It will appear in the place where the KCMs are placed when the user clicks on the item in the listview.
Icon:An icon for the item.
Weight:Defines the position in the listview. See X-KDE-Weight above.
Parent:If this group should be a child of another group write the parent's group id here.
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:
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] Type=Service Icon=<iconname> X-KDE-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:
Encodinglike in the example
X-KDE-PluginInfo-Nameis the "internal name" of the plugin.
- You need to have
X-KDE-ServiceTypesbut of course you may have more entries in there.
Iconis the icon used for your plugin (it's shown in the pluginselector if you set one).
X-KDE-PluginInfo-Emailis some information about the author of the plugin.
X-KDE-PluginInfo-Websiteis the address for a webpage for this plugin.
X-KDE-PluginInfo-Categoryis used if your application has different categories of plugins.
X-KDE-PluginInfo-Versionis the version of this plugin.
X-KDE-PluginInfo-Licenseis the license of this plugin.
X-KDE-PluginInfo-EnabledByDefaulttells the program whether the plugin should be enabled on first startup or not.
X-KDE-PluginInfo-Dependscan be used to tell the application that you need to have myotherplugin enabled for your plugin to work.
X-KDE-CfgDlgHierarchyis used if you use a
KSettings::Dialog::ConfigurableInlineKSettings::Dialog to put the plugin checkbox into the group with the GroupID you set here.
If you have questions contact Matthias Kretz kretz[email protected]@kde[email protected].org.