Warning, /frameworks/kcmutils/src/ksettings/README.dox is written in an unsupported language. File is not indexed.
0001 /** 0002 0003 \namespace KSettings 0004 0005 \short A collection of classes to create configuration dialogs that work over 0006 component boundaries 0007 0008 <h2>How to use KSettings::Dialog in your application.</h2> 0009 0010 <hr> 0011 <h3>1. Open the dialog from your app</h3> 0012 0013 All you need to do is instantiate KSettings::Dialog and show() it. I recommend 0014 the following: 0015 0016 create the 'Configure MyApp' StdAction like this: 0017 \code 0018 KStandardAction::preferences( this, SLOT( showConfigDialog() ), actionCollection ); 0019 \endcode 0020 0021 and the slot looks like this: 0022 \code 0023 if( m_dlg == 0 ) 0024 m_dlg = new KSettings::Dialog( this ); 0025 m_dlg->show(); 0026 \endcode 0027 0028 Of course you need to have the 'KSettings::Dialog * m_dlg' member var and 0029 initialize it to 0 in the ctor. 0030 0031 If your application uses KParts that don't set 'X-KDE-ParentApp=<the instance 0032 name of your application>' then you need to use the second ctor of 0033 KSettings::Dialog: 0034 \code 0035 m_dlg = new KSettings::Dialog( QStringList::split( ';', "component1;component2" ) ); 0036 \endcode 0037 0038 The KSettings::Dialog object will be destructed automatically by the QObject 0039 mechanisms. 0040 0041 0042 <hr> 0043 <h3>2. Create pages for your dialog</h3> 0044 0045 Every page is a KCM. This is what you need for creating a page: 0046 0047 \code 0048 class MyAppConfig : public KCModule 0049 { 0050 Q_OBJECT 0051 public: 0052 MyAppConfig( QWidget *parent, const char *name = 0, const QStringList &args = 0053 QStringList() ); 0054 ~MyAppConfig(); 0055 0056 void load(); 0057 void save(); 0058 void defaults(); 0059 } 0060 \endcode 0061 0062 and in the cpp file: 0063 0064 \code 0065 K_PLUGIN_FACTORY(MyAppConfigFactory, 0066 registerPlugin<MyAppConfig>(); 0067 ) 0068 0069 MyAppConfig::MyAppConfig(QWidget *parent, const char *, const QVariantList &args) 0070 : KCModule(MyAppConfigFactory::instance(), parent, args) 0071 { 0072 // create the pages GUI 0073 load(); 0074 } 0075 0076 // implementations for the other methods 0077 \endcode 0078 0079 For the KConfig object you can either use 0080 KSharedConfig::openConfig() (I don't recommend it) or KSimpleConfig( "myapprc" ). 0081 I added a method to KSettings::Dispatcher that gives you the KConfig 0082 object for every registered instance name: \ref KSettings::Dispatcher::configForInstanceName 0083 0084 0085 <hr> 0086 <h3>3. The .desktop file for the page</h3> 0087 0088 The .desktop file holds all the information for the dialog to find the page and 0089 insert it at the right place (with the right icon, name and comment). 0090 0091 An example file: 0092 \verbatim 0093 [Desktop Entry] 0094 Icon=myapp 0095 Type=Service 0096 X-KDE-ServiceTypes=KCModule 0097 0098 X-KDE-Library=myappconfig 0099 X-KDE-ParentApp=myapp 0100 X-KDE-ParentComponents=myapp 0101 X-KDE-Weight=10 0102 0103 Name=General 0104 Comment=General configuration of my app 0105 \endverbatim 0106 0107 0108 Some explanation for those keys: 0109 - You just keep 'Encoding', 'Type' and 'X-KDE-ServiceTypes' like 0110 in the example. For very special needs you might add another ServiceType to 0111 the list... 0112 - Icon is the icon that will be used in the listview/iconview for your page. 0113 - X-KDE-Library is the name of the library where the page is in. The library 0114 always needs to be prefixed with kcm_ but you don't write the prefix in the 0115 desktop file. For more docu on this look for the KCModule docu. 0116 - X-KDE-ParentApp is the name of the application this config page belongs to. It 0117 is used by the first two \ref KSettings::Dialog constructors. The Dialog will 0118 use all modules that set X-KDE-ParentApp to QCoreApplication::applicationName(). 0119 It should be pretty easy to find out what name that is: look for setApplicationName() 0120 in main(), otherwise the name of the executable is used. 0121 - X-KDE-ParentComponents is a list of the components (plugin/KPart/whatever) 0122 this config page belongs to. Normally there is only one component. 0123 It is used for two things: 0124 -# If you use KSettings::Dispatcher the dispatcher will notify all components 0125 in this list after the save() method of your KCM has been called. The 0126 components then can reload the configuration and apply the changes the user 0127 did to the config. 0128 -# If your component is used by another application (that is not = 0129 X-KDE-ParentApp) then it may add the name of the component to the ctor of 0130 KSettings::Dialog and the dialog will automatically include all config 0131 pages that have the components name in their ParentComponents list. 0132 - X-KDE-Weight sets the order for the modules to be inserted into the dialog. 0133 The higher the number (heavier) the lower the module will appear in the list. 0134 (the default value is 100) 0135 - Name is the string that is shown in the listview/iconview right below the 0136 icon. 0137 - Comment is the string that is shown on top of the config page for a short 0138 description what you can do on this page. 0139 0140 0141 <hr> 0142 <h3>4. The .setdlg file for hierarchical (TreeList) page layouts</h3> 0143 0144 If your config dialog should show a tree of pages in the config dialog you need 0145 to define that hierarchy with a .setdlg file. 0146 0147 The file should be installed in apps/<appname>/<appname>.setdlg. If third party 0148 plugins need to merge in they will install their file to 0149 apps/<appname>/ksettingsdialog/<pluginname>.setdlg. 0150 0151 A .setdlg file contains one or more blocks like the following: 0152 0153 \verbatim 0154 [id] 0155 Name= 0156 Comment= 0157 Icon= 0158 Weight= 0159 Parent= 0160 \endverbatim 0161 0162 - The group name (id) is the name you use in the .desktop file of the page: 0163 If your page's .desktop file says "X-KDE-CfgDlgHierarchy=id" then it will be 0164 inserted as a child of this entry. 0165 - \p Name: The name of the section. It will appear in the listview. 0166 - \p Comment: A description of what the modules in this section are. It will 0167 appear in the place where the KCMs are placed when the user clicks on the item 0168 in the listview. 0169 - \p Icon: An icon for the item. 0170 - \p Weight: Defines the position in the listview. See X-KDE-Weight above. 0171 - \p Parent: If this group should be a child of another group write the parent's 0172 group id here. 0173 0174 <hr> 0175 <h3>5. The Pluginselector</h3> 0176 0177 There are two ways to use the KPluginSelector widget. One is to use the class 0178 directly and the second to use KSettings::PluginPage as baseclass for a config 0179 page that shows the KPluginSelector widget. 0180 0181 I'll cover the second usage here and the calls to addPlugins are just the same 0182 for the first. 0183 0184 To create a plugin page you need the following code: 0185 0186 \code 0187 K_PLUGIN_FACTORY(MyAppPluginConfigFactory, 0188 registerPlugin<MyAppPluginConfig>(); 0189 ) 0190 0191 MyAppPluginConfig(QWidget * parent, const char *, const QVariantList & args) 0192 : PluginPage(MyAppPluginConfigFactory::instance(), parent, args) 0193 { 0194 pluginSelector()->addPlugins( ... ); 0195 pluginSelector()->addPlugins( ... ); 0196 . 0197 . 0198 . 0199 } 0200 \endcode 0201 0202 pluginSelector() returns a pointer to the KPluginSelector widget of the page. 0203 There are three addPlugins methods available, two for adding KParts plugins and 0204 one for the rest. 0205 0206 0207 <hr> 0208 <h3>6. The .desktop files of plugin config pages</h3> 0209 0210 this is the entry for the Makefile.am: 0211 0212 \verbatim 0213 myappconfigpagedir = $(kde_servicesdir)/<appname> 0214 myappconfigpage_DATA = myappconfigpage.desktop 0215 \endverbatim 0216 0217 0218 And this is what the .desktop file looks like: 0219 0220 \verbatim 0221 [Desktop Entry] 0222 Type=Service 0223 Icon=<iconname> 0224 X-KDE-ServiceTypes=KPluginInfo 0225 0226 Name=MyPlugin 0227 Comment=My plugin is cool and does foo and bar. 0228 0229 X-KDE-PluginInfo-Name=myplugin 0230 0231 X-KDE-PluginInfo-Author=<your name> 0232 X-KDE-PluginInfo-Email=<your email> 0233 X-KDE-PluginInfo-Website=http://www.myplugin.org/ 0234 X-KDE-PluginInfo-Category=CoolPlugins 0235 X-KDE-PluginInfo-Version=0.1 0236 X-KDE-PluginInfo-License=GPL 0237 X-KDE-PluginInfo-EnabledByDefault=true 0238 X-KDE-PluginInfo-Depends=myotherplugin 0239 X-KDE-CfgDlgHierarchy=GroupID 0240 \endverbatim 0241 0242 Explanation: 0243 mandatory entries: 0244 - leave \p Type and \p Encoding like in the example 0245 - \p Name 0246 - \p Comment 0247 - \p X-KDE-PluginInfo-Name is the "internal name" of the plugin. 0248 - You need to have \p KPluginInfo in \p X-KDE-ServiceTypes but of course you may have more 0249 entries in there. 0250 0251 optional entries: 0252 - \p Icon is the icon used for your plugin (it's shown in the pluginselector if you 0253 set one). 0254 - \p X-KDE-PluginInfo-Author and \p X-KDE-PluginInfo-Email is some information about the author of the plugin. 0255 - \p X-KDE-PluginInfo-Website is the address for a webpage for this plugin. 0256 - \p X-KDE-PluginInfo-Category is used if your application has different categories of plugins. 0257 - \p X-KDE-PluginInfo-Version is the version of this plugin. 0258 - \p X-KDE-PluginInfo-License is the license of this plugin. 0259 - \p X-KDE-PluginInfo-EnabledByDefault tells the program whether the plugin 0260 should be enabled on first startup or not. 0261 - \p X-KDE-PluginInfo-Depends can be used to tell the application that you need to have 0262 myotherplugin enabled for your plugin to work. 0263 - \p X-KDE-CfgDlgHierarchy is used if you use a \p KSettings::Dialog::ConfigurableInline 0264 KSettings::Dialog to put the plugin checkbox into the group with the GroupID 0265 you set here. 0266 0267 If you have questions contact Matthias Kretz <kretz@kde.org>. 0268 */ 0269 // vim: tw=80