summaryrefslogtreecommitdiffstats
path: root/tdeutils/ksettings/README.dox
diff options
context:
space:
mode:
authorTimothy Pearson <kb9vqf@pearsoncomputing.net>2013-01-26 13:17:21 -0600
committerTimothy Pearson <kb9vqf@pearsoncomputing.net>2013-01-26 13:17:21 -0600
commitdfe289850f068f19ba4a83ab4e7e22a7e09c13c9 (patch)
treec297348a55df66c571de4525646e0b9762427353 /tdeutils/ksettings/README.dox
parentb7658a0d5eca24a9d37c6e04f88298ef02389db0 (diff)
downloadtdelibs-dfe289850f068f19ba4a83ab4e7e22a7e09c13c9.tar.gz
tdelibs-dfe289850f068f19ba4a83ab4e7e22a7e09c13c9.zip
Rename a number of libraries and executables to avoid conflicts with KDE4
Diffstat (limited to 'tdeutils/ksettings/README.dox')
-rw-r--r--tdeutils/ksettings/README.dox276
1 files changed, 276 insertions, 0 deletions
diff --git a/tdeutils/ksettings/README.dox b/tdeutils/ksettings/README.dox
new file mode 100644
index 000000000..88268f671
--- /dev/null
+++ b/tdeutils/ksettings/README.dox
@@ -0,0 +1,276 @@
+/**
+
+\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=&lt;the instance
+name of your application&gt;' 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/&lt;appname&gt;/&lt;appname&gt;.setdlg. If third party
+plugins need to merge in they will install their file to
+apps/&lt;appname&gt;/ksettingsdialog/&lt;pluginname&gt;.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