Rename a number of libraries and executables to avoid conflicts with KDE4

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