This entry can be used to set the name of the factory function in the library.

+

This entry can be used to set the name of the factory function in the library. If you only have one KCModule in a library this key is not needed. If you have several KCMs in one library you will need a desktop file for each KCM.

−

If you only have one KCModule in a library this key is not needed. If

+

−

you have several KCMs in one library you will need a desktop file for each

+

−

KCM.

+

−

For example, if you have a library named: kcm_frog.so with two modules, named

+

For example, if you have a library named: kcm_frog.so with two modules, named "kermit" and "quak", kcm_kermit.desktop would contain:

−

"kermit" and "quak", kcm_kermit.desktop would contain:

+

<syntaxhighlight lang="ini">

<syntaxhighlight lang="ini">

Line 148:

Line 144:

The module loader would then call the "create_kermit" and "create_quak" functions respectively.

The module loader would then call the "create_kermit" and "create_quak" functions respectively.

−

−

;X-KDE-RootOnly

−

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 kdesu and QXEmbed.

;X-KDE-Init-Symbol

;X-KDE-Init-Symbol

−

If the module has to perform some action at system startup, use this entry to

+

If the module has to perform some action at system startup, use this entry to build the name of a function to call. if X-KDE-Init-Symbol is "bell", for example, the function "kcminit_bell" is called in the library indicated by X-KDE-Library.

−

build the name of a function to call. if X-KDE-Init-Symbol is "bell", for example,

+

−

the function "kcminit_bell" is called in the library indicated by X-KDE-Library.

+

−

+

−

;X-KDE-Test-Module

+

−

If the module has to perform some action at system startup, use this entry to

+

−

build the name of a function to call. if X-KDE-Init is "bell", for example,

+

−

the function "init_bell" is called in the library indicated by X-KDE-Library.

+

;NoDisplay

;NoDisplay

−

If this is set to true the module will not show up in System Settings or when viewed

+

If this is set to true the module will not show up in System Settings or when viewed with kcmshell4. This is useful when you need to do something at startup using X-KDE-Init but don't want the module to show up in System Settings.

−

with kcmshell4. This is useful when you need to do something at startup using X-KDE-Init

+

−

but don't want the module to show up in System Settings.

+

You can also make the value of this key depend on the output of a program, using the "[$e]" key suffix. For example:

If you get errors, make sure the constructor signature of your derived class matches
with the signature of KCModule constructor (the QVariantList argument matters).

If the name of your module is "foo", the name of the library should be
"kcm_foo.so". It should be installed into $KDEDIR/lib/kde4.

Exporting more than one module

If you need to export more than one module per library, you have to declare them another way: you must create C functions named "create_${kcm_name}". For
example if your module exposes two KCMs named Foo1 and Foo2, the
"create_" functions would look like this:

This is the name of the library, without the "kcm_" prefix. In our example,
it should be "foo".

Optional keys

Additionally the KCM desktop file may contains the following keys:

X-KDE-FactoryName

This entry can be used to set the name of the factory function in the library. If you only have one KCModule in a library this key is not needed. If you have several KCMs in one library you will need a desktop file for each KCM.

For example, if you have a library named: kcm_frog.so with two modules, named "kermit" and "quak", kcm_kermit.desktop would contain:

X-KDE-Library=frogX-KDE-FactoryName=kermit

and "kcm_quak.desktop" would contain:

X-KDE-Library=frogX-KDE-FactoryName=quak

The module loader would then call the "create_kermit" and "create_quak" functions respectively.

X-KDE-Init-Symbol

If the module has to perform some action at system startup, use this entry to build the name of a function to call. if X-KDE-Init-Symbol is "bell", for example, the function "kcminit_bell" is called in the library indicated by X-KDE-Library.

NoDisplay

If this is set to true the module will not show up in System Settings or when viewed with kcmshell4. This is useful when you need to do something at startup using X-KDE-Init but don't want the module to show up in System Settings.

You can also make the value of this key depend on the output of a program, using the "[$e]" key suffix. For example:

What else do I need?

kcmshell4

You can run one or several modules independently with "kcmshell4 [module_name]". For example, to get the font and the desktop color settings, use "kcmshell4 fonts colors".

To get a list of the available modules, use "kcmshell4 --list".

KCMultiDialog

Sometimes, you may want to reuse your KCModule inside an application. There
are two ways to accomplish this:

The first option is to simply fork and call "kcmshell4 foo".

The second option is to use KCMultiDialog. This is a simple dialog
which can show an arbitrary number of modules in a normal KDialog.
This approach gives you finer control than starting kcmshell4 in a separate process.

Since your module is a simple library, you can just link to it anyway.

KCModuleContainer

The class KCModuleContainer allows great flexibility to handle modules.
The API docs explains its usage the best.

Debugging your module

You can attach gdb, valgrind or whatever to "kcmshell4 [yourmodule]" to track
down leaks or crashes. If you need to trace it down inside System Settings, make sure
you pass --nofork to System Settings on startup.

You really want to use kcmshell4 for debugging as long as your debugging does
not involve debugging bad interaction with the System Settings framework itself.

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".