diff options
Diffstat (limited to 'kutils/ksettings/README.dox')
| -rw-r--r-- | kutils/ksettings/README.dox | 276 |
1 files changed, 0 insertions, 276 deletions
diff --git a/kutils/ksettings/README.dox b/kutils/ksettings/README.dox deleted file mode 100644 index 88268f671..000000000 --- a/kutils/ksettings/README.dox +++ /dev/null @@ -1,276 +0,0 @@ -/** - -\namespace KSettings - -\short A collection of classes to create configuration dialogs that work over -component boundaries - -<h2>How to use KSettings::Dialog in your application.</h2> - -<hr> -<h3>1. Open the dialog from your app</h3> - -All you need to do is instanciate KSettings::Dialog and show() it. I recommend -the following: - -create the 'Configure MyApp' StdAction like this: -\code -KStdAction::preferences( this, SLOT( showConfigDialog() ), actionCollection ); -\endcode - -and the slot looks like this: -\code -if( m_dlg == 0 ) - m_dlg = new KSettings::Dialog( this ); -m_dlg->show(); -\endcode - -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-TDE-ParentApp=<the instance -name of your application>' then you need to use the second ctor of -KSettings::Dialog: -\code -m_dlg = new KSettings::Dialog( QStringList::split( ';', "component1;component2" ) ); -\endcode - -The KSettings::Dialog object will be destructed automatically by the QObject -mechanisms. - - -<hr> -<h3>2. Create pages for your dialog</h3> - -Every page is a KCM. This is what you need for creating a page: - -\code -class MyAppConfig : public TDECModule -{ - Q_OBJECT -public: - MyAppConfig( QWidget *parent, const char *name = 0, const QStringList &args = - QStringList() ); - ~MyAppConfig(); - - void load(); - void save(); - void defaults(); -} -\endcode - -and in the cpp file: - -\code -typedef KGenericFactory<MyAppConfig, QWidget> MyAppConfigFactory; -K_EXPORT_COMPONENT_FACTORY( kcm_myappconfig, MyAppConfigFactory( - "kcm_myappconfig" ) ); - -MyAppConfig::MyAppConfig( QWidget *parent, const char *, const QStringList &args ) - : TDECModule( MyAppConfigFactory::instance(), parent, args ) -{ - // create the pages GUI - load(); -} - -// implementations for the other methods -\endcode - -For the TDEConfig object you can either use -TDEGlobal::config() (I don't recommend it) or KSimpleConfig( "myapprc" ). -I added a method to KSettings::Dispatcher that gives you the TDEConfig -object for every registered instance name: \ref KSettings::Dispatcher::configForInstanceName - - -<hr> -<h3>3. The .desktop file for the page</h3> - -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: -\verbatim -[Desktop Entry] -Encoding=UTF-8 -Icon=myapp -Type=Service -ServiceTypes=TDECModule - -X-TDE-ModuleType=Library -X-TDE-Library=myappconfig -X-TDE-FactoryName=MyAppConfigFactory -X-TDE-ParentApp=myapp -X-TDE-ParentComponents=myapp -X-TDE-Weight=10 - -Name=General -Comment=General configuration of my app -\endverbatim - - -Some explanation for those keys: -- You just keep 'Encoding', 'Type', 'ServiceTypes' and 'X-TDE-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-TDE-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 TDECModule docu. -- X-TDE-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 TDECModule docu. -- X-TDE-ParentApp is the name of the application this config page belongs to. It - is used by the first two \ref KSettings::Dialog constructors. The Dialog will - use all modules that set X-TDE-ParentApp to - TDEGlobal::instance()->instanceName(). It - should be pretty easy to find out what name that is: look at the first - argument to the TDEAboutData ctor. -- X-TDE-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-TDE-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-TDE-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. - - -<hr> -<h3>4. The .setdlg file for hierarchical (TreeList) page layouts</h3> - -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: - -\verbatim -[id] -Name= -Comment= -Icon= -Weight= -Parent= -\endverbatim - -- The group name (id) is the name you use in the .desktop file of the page: - If your page's .desktop file says "X-TDE-CfgDlgHierarchy=id" then it will be - inserted as a child of this entry. -- \p Name: The name of the section. It will appear in the listview. -- \p 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. -- \p Icon: An icon for the item. -- \p Weight: Defines the position in the listview. See X-TDE-Weight above. -- \p Parent: If this group should be a child of another group write the parent's - group id here. - -<hr> -<h3>5. The Pluginselector</h3> - -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: - -\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( ... ); - . - . - . -} -\endcode - -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. - - -<hr> -<h3>6. The .desktop files of plugin config pages</h3> - -this is the entry for the Makefile.am: - -\verbatim -myappconfigpagedir = $(kde_servicesdir)/<appname> -myappconfigpage_DATA = myappconfigpage.desktop -\endverbatim - - -And this is what the .desktop file looks like: - -\verbatim -[Desktop Entry] -Encoding=UTF-8 -Type=Service -Icon=<iconname> -ServiceTypes=KPluginInfo - -Name=MyPlugin -Comment=My plugin is cool and does foo and bar. - -X-TDE-PluginInfo-Name=myplugin - -X-TDE-PluginInfo-Author=<your name> -X-TDE-PluginInfo-Email=<your email> -X-TDE-PluginInfo-Website=http://www.myplugin.org/ -X-TDE-PluginInfo-Category=CoolPlugins -X-TDE-PluginInfo-Version=0.1 -X-TDE-PluginInfo-License=GPL -X-TDE-PluginInfo-EnabledByDefault=true -X-TDE-PluginInfo-Depends=myotherplugin -X-TDE-CfgDlgHierarchy=GroupID -\endverbatim - -Explanation: -mandatory entries: -- leave \p Type and \p Encoding like in the example -- \p Name -- \p Comment -- \p X-TDE-PluginInfo-Name is the "internal name" of the plugin. -- You need to have \p KPluginInfo in \p ServiceTypes but of course you may have more - entries in there. - -optional entries: -- \p Icon is the icon used for your plugin (it's shown in the pluginselector if you - set one). -- \p X-TDE-PluginInfo-Author and \p X-TDE-PluginInfo-Email is some information about the author of the plugin. -- \p X-TDE-PluginInfo-Website is the address for a webpage for this plugin. -- \p X-TDE-PluginInfo-Category is used if your application has different categories of plugins. -- \p X-TDE-PluginInfo-Version is the version of this plugin. -- \p X-TDE-PluginInfo-License is the license of this plugin. -- \p X-TDE-PluginInfo-EnabledByDefault tells the program whether the plugin - should be enabled on first startup or not. -- \p X-TDE-PluginInfo-Depends can be used to tell the application that you need to have - myotherplugin enabled for your plugin to work. -- \p X-TDE-CfgDlgHierarchy is used if you use a \p KSettings::Dialog::ConfigurableInline - KSettings::Dialog to put the plugin checkbox into the group with the GroupID - you set here. - -If you have questions contact Matthias Kretz <kretz@kde.org>. -*/ -// vim: tw=80 |