TDEConfig Module HOWTO - Revision history

Blu256: - Applicable to TDE

2023-01-08T10:12:37Z

- Applicable to TDE

Blu256: Blu256 moved page KConfig Module HOWTO to TDEConfig Module HOWTO

2021-12-24T08:27:02Z

Blu256 moved page KConfig Module HOWTO to TDEConfig Module HOWTO

Blu256: /* What else do I need? */ Adjusted spacing

2021-12-21T10:29:41Z

What else do I need?: Adjusted spacing

Blu256: Added categories, template "Applicable to TDE", cosmetic changes

2021-12-21T10:28:03Z

Added categories, template "Applicable to TDE", cosmetic changes

Blu256: Added KConfig Module HOWTO from old KDE Developer docs

2021-12-21T10:24:35Z

Added KConfig Module HOWTO from old KDE Developer docs

New page

A '''TDEConfig Module''' is a small library with a TDECModule subclass containing code which builds and support a interface for configuration tasks. The module is then encapsulated in a parent application, for example <tt>tdecmshell</tt>, <tt>KControl</tt> or a <tt>KCMultiDialog</tt>.

This HOWTO describes how to write TDEConfig Modules. This technology was originally designed for KControl. Although KControl is the application where the TDECModule tehnology is the most used, it is used in several other places as well, such as Kopete and Kontact. This HOWTO describes how to write config modules, regardless of where it will be used. TDEConfig Modules were originally called "KControl Modules".

If the <tt>TDECModule</tt> in question is intended for KControl the KControl Module Guidelines must be consulted. Much of it applies to KConfig Modules in general, it is probably a good read regardless of what application the KCM targets.

== How to write a KConfig Module ==

Now to the practical side of the matter. Modules have to inherit from the class <tt>TDECModule</tt>, defined in <tt>kcmodule.h</tt>, which is part of the <tt>tdeui</tt> library. This class defines some important functions that are used in the communication between the framework and the module:

<syntaxhighlight lang="c++">
virtual void load();
</syntaxhighlight>

This method is invoked whenever the module should read its configuration (most of the times from a config file) and update the user interface. This happens when the user clicks the "Reset" button in the control center, to undo all of his changes and restore the currently valid settings. NOTE that this is not called after the modules is loaded, so you probably want to call this method in the constructor.

<syntaxhighlight lang="c++">
virtual void save();
</syntaxhighlight>

You might have guessed it: this function gets called when the user wants to save the settings in the user interface, updating the config files or wherever the configuration is stored. The method is called when the user clicks "Apply" or "Ok".

<syntaxhighlight lang="c++">
virtual void defaults();
</syntaxhighlight>

This function is called to set the settings in the module to sensible default values. It gets called when hitting the "Defaults" button. The default values should probably be the same as the ones the application uses when started without a config file.

<syntaxhighlight lang="c++">
int buttons();
</syntaxhighlight>

The module loader calls this function to decide which buttons should be displayed. For example, it does not make sense to display an "Apply" button for one of the information modules. The value returned can be set by modules using setButtons. E.g:

<syntaxhighlight lang="c++">
setButtons( KCModule::Ok | KCModule::Help );
</syntaxhighlight>

will make sure that only the "Ok" and the "Help" button is enabled.

There is also two signals used by the modules:

<syntaxhighlight lang="c++">
void changed(bool state);
</syntaxhighlight>

This signal should be emitted whenever the state of the modules changes. "state" is true, if the contents of the modules differ from the ones in the current configuration, "false" otherwise. For example, if the user changes a value, you emit <tt>changed(true)</tt>. When the user reloads the systems settings, emit <tt>changed(false)</tt>. The module loader uses this signal to keep track about unsaved changes in certain modules.

<syntaxhighlight lang="c++">
void quickHelpChanged();
</syntaxhighlight>

Emit this signal whenever the module's quickhelp changes. Modules implemented as tabbed dialogs might want to implement per-tab quickhelp for example.

There is also a slot for convenience:

<syntaxhighlight lang="c++">
void changed();
</syntaxhighlight>

Calling this slot is equal to emitting <code>changed(true)</code>.

== Making a module available ==

Ok, now that you have implemented your class with the module, you must make sure it can be accessed.

To achieve this, the preferred way is to simply use <tt>KGenericFactory</tt>. Don't forget to <code>#include <kgenericfactory.h></code>.

<syntaxhighlight lang="c++">
typedef KGenericFactory<body TQWidget> KDEDFactory;
K_EXPORT_COMPONENT_FACTORY( kcm_xyz, KDEDFactory( "kcm_xyz" ) );
</syntaxhighlight>

If you get errors, make sure that the constructor of your derived class equals the one of the <tt>TDECModule</tt> baseclass (the TQStringList argument matters).

If you need to export more than one module per library, you have to use the old loader. That is, you need to create a function like this:

<syntaxhighlight lang="c++">
extern "C"
{
TDEModule *create_xyz(TQWidget *parent, const char *name)
{
return new XYZ(parent, name); // XYZ inherits from TDECModule
};
}
</syntaxhighlight>

This function and the implementation of the module is then compiled as a shared library. If the name of your modules is 'xyz', the name of the library should be <code>kcm_xyz(.la|.so)</code> and should be installed into <code>$TDEDIR/lib/trinity</code>.



== Initializing on startup ==

If your module needs to initialize on TDE session startup, you must have a construct like:

<syntaxhighlight lang="c++">
extern "C"
{
TDECModule *init_xyz(TQWidget *parent, const char *name)
{
// Do initialization here
};
}
</syntaxhighlight>

Don't forget to add <code>X-TDE-Init</code> to your desktop file. (see below)

== Making a KCModule dynamically available ==

Sometimes it is of interest to hide a <tt>TDECModule</tt> when it does not have any use for the current situation, for example certain hardware or software is lacking. This is achieved by adding to the library:

<syntaxhighlight lang="c++">
extern "C"
{
TDECModule *test_xyz(TQWidget *parent, const char *name)
{
// Probing for hardware/software precense
return true; // If the TDECModule should show up, otherwise it should return false.
};
}
</syntaxhighlight>

The desktop file must also contain "<tt>X-TDE-Test-Module=true</tt>" in order for this to work.

The <tt>TDECModule</tt> will now be "conditionally" loaded, for example when requested via <tt>KCMultiDialog</tt>, <tt>tdecmshell</tt> or <tt>KControl</tt> (as of 2004-03-21 not implemented in KControl).

== The desktop file ==

To declare a <tt>TDECModule's</tt> existence a desktop file must be installed. Call it "<tt>kcm_modulename.desktop</tt>". 

It could be a good idea to have a look at the desktop file standard.

A module's .desktop file supports the following .desktop directives:

{| class="wikitable"
! Directive
! Description
|-
| '''<tt>X-TDE-Library</tt>'''
| This is the name of the library, without the <tt>kcm_</tt> prefix. So in the example, the library name would be "xyz".
|-
| '''<tt>X-TDE-FactoryName</tt>'''
| This entry can be used to set the name of the factory function in the library. If you only have one <tt>TDECModule</tt> in a library this directive is not needed. If you have several modules in one library you will need a .desktop file for each <tt>TDECModule</tt>.

For example, if you have a library named <tt>kcm_frog.la</tt> with two modules, named "<tt>kermit</tt>" and "<tt>quak</tt>", you would have:

<syntaxhighlight lang="ini">
X-KDE-Library=frog
X-KDE-FactoryName=kermit
</syntaxhighlight>

in one of the .desktop files, and in the other:

<syntaxhighlight lang="ini">
X-KDE-Library=frog
X-KDE-FactoryName=quak
</syntaxhighlight>

The module loader would then call the "<tt>create_kermit</tt>" and "<tt>create_quak</tt>" functions respectively.

|-
| '''<tt>X-TDE-RootOnly</tt>'''
| If this is set to "true", the module must be executed with root permissions. The module loader will then show the module in greyed-out (disabled) state with a warning until the "modify" button is pressed which allows running the module in an root environment using <tt>tdesu</tt> and <tt>QXEmbed</tt>.

|-
| '''<tt>X-TDE-ParentApp</tt>'''
| The application you put in this entry determines in what situations it will show. For example, if the line says <code>X-TDE-ParentApp=kcontrol</code> the module will show up in KControl. It is very crucial the selected <tt>ParentApp</tt> is correct, otherwise the module show up in unnecessary places.

|-
| '''<tt>X-TDE-Init</tt>'''
| If the module has to perform some action at system startup, use this entry to build the name of a function to call. if <tt>X-TDE-Init</tt> is "bell", for example, the function "<tt>init_bell</tt>" is called in the library indicated by <tt>X-TDE-Library</tt>.

|-
| '''<tt>X-TDE-Test-Module</tt>'''
| If the module has to perform some action at system startup, use this entry to build the name of a function to call. if <tt>X-TDE-Init</tt> is "bell", for example, the function "init_bell" is called in the library indicated by <tt>X-TDE-Library</tt>.

|-
| '''<tt>NoDisplay</tt>'''
| If this is set to true the module will not show up in <tt>kcontrol</tt> or when viewed with <tt>tdecmshell</tt>. This is usable when you need to do something at startup (<code>X-TDE-Init</code> etc.) but don't want the module to show up in kcontrol, e.g. the module has no GUI.

|-
| '''<tt>Name</tt>'''
| This is 'labels' for the modules and fill the nodes in the three view. Please see the module guidelines on how to pick a good Name.

|-
| '''<tt>Comment</tt>'''
| This directive shows up in the main area in KControl if you select a top node in the three view. See the same section as for Name in the module guidelines for how to pick a good phrase.

|-
| '''<tt>Categories</tt>'''
| This describes where the module should be put in KControl's navigation. It should look like "Categories=QT;TDE;X;" where X is the category. A list of available categories, as well as which one to choose is found in the module guidelines.

|-
| '''<tt>Icon</tt>'''
| Specifies the icon for the module.

|-
| '''<tt>Exec/Type</tt>'''
| These two should say <code>Exec=kcmshell modulename</code> and <code>Type=Application</code>. Used for internal purposes

|-
| '''<tt>Keywords</tt>'''
| A semi colon separated list containing words/phrases search functionality should trigger on.

|}

To summarize, a valid .desktop file must contain these entries:

* <tt>Name</tt>
* <tt>Icon</tt>
* <tt>Type=Application</tt>
* <tt>Exec=tdecmshell modulename</tt>
* <tt>Categories=QT;KDE;X;</tt> (replace X with your category)
* <tt>Keywords</tt>
* <tt>X-TDE-Library</tt>
* <tt>X-TDE-ParentApp</tt>
* <tt>Comment</tt>

And these are optional:

* <tt>X-TDE-Init</tt>
* <tt>X-TDE-Test-Module</tt>
* <tt>NoDisplay</tt>
* <tt>X-TDE-Root-Only</tt>
* <tt>X-TDE-Factory-Name</tt>
* <tt>DocPath</tt>

Any other directives(except the translators) can safely be removed, since they most likely are abundant or are leftovers from old KDE versions. For example, <tt>X-ModuleType</tt> was relevant for KDE 2.0 but not in any new versions.

== What else do I need? ==

There are a number of additional things for convenience.

=== tdecmshell ===

Consider you want to run a module standalone. Call <code>tdecmshell [module]</code>. For example, to get the font and the desktop color settings, use:

<syntaxhighlight lang="shell-session">
$ tdecmshell fonts colors
</syntaxhighlight>

=== KCMultiDialog ===

Sometimes, you may want to reuse your <tt>TDECModule</tt> inside an application. There are two ways to accomplish this:

* Use <tt>KCMultiDialog</tt> (in <tt>tdelibs/tdeutils</tt>) This is a simple dialog that can show an abitrary number of modules in a normal <tt>KDialogBase</tt>. The advantage is that you can control the behaviour and the results much easier that with a separate process. And as your module is a simple library, you can just link to it anyway. 

* Call <code>tdecmshell [modules...]</code>.

=== KCModuleContainer ===

The class <tt>KCModuleContainer</tt> allows great flexibility with handling modules. The API docs explain it usage the best.

== Debugging your module ==

You can attach <tt>gdb</tt>, <tt>valgrind</tt> or whatever to <code>tdecmshell [yourmodule]</code> to track down leaks or crashes. If you need to trace it down inside <tt>kcontrol</tt>, make sure you pass it <code>--nofork</code> on startup. You really want to use <tt>tdecmshell</tt> for debugging as long as your debugging does not involve debugging bad interaction with the <tt>kcontrol</tt> framework itself.


'''Copyright notice'''

Imported from [https://websvn.kde.org/*checkout*/trunk/www/sites/developer/documentation/other/kcm_howto.html?revision=471709 KDE Developer Documentation SVN].

Copyright (C) 2003 Daniel Molkentin <molketin@kde.org>
Copyright (C) 2004 Frans Englich <frans.englich@telia.com>
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

← Older revision		Revision as of 10:12, 8 January 2023
Line 1:		Line 1:
	{{Applicable to TDE}}

	A '''TDEConfig Module''' is a small library with a TDECModule subclass containing code which builds and support a interface for configuration tasks. The module is then encapsulated in a parent application, for example <tt>tdecmshell</tt>, <tt>KControl</tt> or a <tt>KCMultiDialog</tt>.		A '''TDEConfig Module''' is a small library with a TDECModule subclass containing code which builds and support a interface for configuration tasks. The module is then encapsulated in a parent application, for example <tt>tdecmshell</tt>, <tt>KControl</tt> or a <tt>KCMultiDialog</tt>.

@@ Line 1: / Line 1: @@
+{{Applicable to TDE}}
 A '''TDEConfig Module''' is a small library with a TDECModule subclass containing code which builds and support a interface for configuration tasks. The module is then encapsulated in a parent application, for example <tt>tdecmshell</tt>, <tt>KControl</tt> or a <tt>KCMultiDialog</tt>.
@@ Line 4: / Line 6: @@
 If the <tt>TDECModule</tt> in question is intended for KControl the KControl Module Guidelines must be consulted. Much of it applies to KConfig Modules in general, it is probably a good read regardless of what application the KCM targets.
+__TOC__
 == How to write a KConfig Module ==
@@ Line 267: / Line 272: @@
+----
 <small>
 '''Copyright notice'''
@@ Line 276: / Line 282: @@
  Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".
 </small>
+[[Category:Developers]]
+[[Category:Tutorials]]

← Older revision	Revision as of 08:27, 24 December 2021
(No difference)

@@ Line 242: / Line 242: @@
 There are a number of additional things for convenience.
 === tdecmshell ===
@@ Line 251: / Line 250: @@
 $ tdecmshell fonts colors
 </syntaxhighlight>
 === KCMultiDialog ===
@@ Line 257: / Line 255: @@
 Sometimes, you may want to reuse your <tt>TDECModule</tt> inside an application. There are two ways to accomplish this:
-* Use <tt>KCMultiDialog</tt> (in <tt>tdelibs/tdeutils</tt>)<br><br>This is a simple dialog that can show an abitrary number of modules in a normal <tt>KDialogBase</tt>. The advantage is that you can control the behaviour and the results much easier that with a separate process. And as your module is a simple library, you can just link to it anyway.<br>
+* Use <tt>KCMultiDialog</tt> (in <tt>tdelibs/tdeutils</tt>)<br>This is a simple dialog that can show an abitrary number of modules in a normal <tt>KDialogBase</tt>. The advantage is that you can control the behaviour and the results much easier that with a separate process. And as your module is a simple library, you can just link to it anyway.<br>
 * Call <code>tdecmshell [modules...]</code>.
 === KCModuleContainer ===
 The class <tt>KCModuleContainer</tt> allows great flexibility with handling modules. The API docs explain it usage the best.
 == Debugging your module ==