m (self) |
(→.kcfg DTD Structure) |
||
Line 81: | Line 81: | ||
* The remaining entries in the XML file are grouped by the tag <group> which describes the corresponding groups in the configuration file. | * The remaining entries in the XML file are grouped by the tag <group> which describes the corresponding groups in the configuration file. | ||
*#The individual entries must have at least a name or a key. The key is used as the key in the config file. The name is used to create accessor and modifier functions. If <key> is not given, the name is used as the config file key. If <key> is given, but not <name>, the name is constructed by removing all spaces from the <key> contents. | *#The individual entries must have at least a name or a key. The key is used as the key in the config file. The name is used to create accessor and modifier functions. If <key> is not given, the name is used as the config file key. If <key> is given, but not <name>, the name is constructed by removing all spaces from the <key> contents. | ||
− | *# Always add label, tooltip and whatsthis tags to your application in which you describe the configuration options. The label tag is used for short descriptions of the entry, while tooltip and whatsthis contains more verbose documentation. ''It's important for tools like KConfigEditor which can be used by systems administrators to setup machines over on the network.'' | + | *# Always add <label>, <tooltip> and <whatsthis> tags to your application in which you describe the configuration options. The <label> tag is used for short descriptions of the entry, while <tooltip> and <whatsthis> contains more verbose documentation. ''It's important for tools like KConfigEditor which can be used by systems administrators to setup machines over on the network. Note that this tags will be ignored unless you provide SetUserText=true option in your .kcfgc file (see section below)'' |
*# An entry must also have a type. The allowed types are: String, Url, StringList, Font, Rect, Size, Color, Point, Int, UInt, Bool, Double, DateTime, Int64, UInt64 and Password. '' Besides those basic type the following special types are supported and include:'' | *# An entry must also have a type. The allowed types are: String, Url, StringList, Font, Rect, Size, Color, Point, Int, UInt, Bool, Double, DateTime, Int64, UInt64 and Password. '' Besides those basic type the following special types are supported and include:'' | ||
*#* Path - This is a string that is specially treated as a file-path. In particular paths in the home directory are prefixed with $HOME when being stored in the configuration file. | *#* Path - This is a string that is specially treated as a file-path. In particular paths in the home directory are prefixed with $HOME when being stored in the configuration file. |
Languages: عربي | Asturianu | Català | Česky | Kaszëbsczi | Dansk | Deutsch | English | Esperanto | Español | Eesti | فارسی | Suomi | Français | Galego | Italiano | 日本語 | 한국어 | Norwegian | Polski | Português Brasileiro | Română | Русский | Svenska | Slovenčina | Slovenščina | српски | Türkçe | Tiếng Việt | Українська | 简体中文 | 繁體中文
Tutorial Series | KConfig |
Previous | Introduction to KConfig |
What's Next | None |
Further Reading | The KDE Configuration Compiler (KDE 4) The KDE Configuration Compiler (KDE 3) |
Original Author: Zack Rusin <zack@kde.org>
This tutorial introduces the main concepts of the KconfigXT configuration framework and shows how to efficiently use it in applications. It assumes that the reader has already developed a KDE application and is familiar with KConfig. A basic understanding of XML and concepts behind DTDs is also required.
The main idea behind KConfig XT is to make the life of application developers easier while making the administration of large KDE installations more manageable. The four basic parts of the new framework are:
Note |
---|
In this tutorial more advanced and optional features of KConfig XT and their descriptions are marked by italic text. If you decide to skip them during the first reading, be sure to come back to them at some point. |
The structure of the .kcfg file is described by its DTD (kcfg.xsd - available from here (please note that browsers do not display DTDs in a visual form, download the DTD directly and view it like a text file) or the kdecore library). Please go through it before you go any further.
Lets create a simple .kcfg file. Please reference the code below as we go through each step.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE kcfg SYSTEM
"http://www.kde.org/standards/kcfg/1.0/kcfg.xsd">
<kcfg>
<kcfgfile name="kjotsrc"/> <include>kglobalsettings.h</include> <group name="kjots"> <entry name="SplitterSizes" type="IntList"> <label>How the main window is divided.</label> </entry> <entry name="Width" type="Int"> <label>Width of the main window.</label> <default>600</default> </entry> <entry name="Height" type="Int"> <label>Height of the main window.</label> <default>400</default> </entry> <entry name="OpenBooks" type="StringList"> <label>All books that are opened.</label> </entry> <entry name="CurrentBook" type="String"> <label>The book currently opened.</label> </entry> <entry name="Font" type="Font"> <label>The font used to display the contents of books.</label> <default code="true">KGlobalSettings::generalFont()</default> </entry> </group>
</kcfg>
After creating a .kcfg file create a .kcfgc file which describes the C++ file generation options. The .kcfgc file is a simple ini file with the typical "entry=value" format. To create a simple .kcfgc file follow these steps:
For details see the description of kconfig_compiler: [1]
After creating the .kcfg and .kcfgc files the next step is to adjust the build to let kconfig_compiler generate the required class at compile time. Fortunately doing this is trivial and requires only one step, adding this line to the CMakeLists.txt file example:
kde4_add_kcfg_files(<project name>_SRCS settings.kcfgc)
Alternatively, if a .moc file needs to be generated before compiling the generated source code, use
kde4_add_kcfg_files(<project name>_SRCS GENERATE_MOC settings.kcfgc)
This assures that the configuration class is properly generated and that the .kcfg is installed so it can be used by tools like the KConfigEditor.
After making all of the above changes you're ready to use KConfig XT. The kconfig_compiler generated header file will have the name equal to the name of the .kcfg file but with a ".h" extension. Simply include that file wherever you want to access your configuration options.
The use will depend on whether you have added the Singleton=true entry to your .kcfgc file.
One the nicest features of the KConfig XT is its seamless integration with the Qt Designer generated dialogs. You can do that by using KConfigDialog. The steps to do that are as follows:
KConfigDialog* dialog = new KConfigDialog(
this, "settings", YourAppSettings::self() );
assuming that YourAppSettings is the value of the ClassName variable from the kcfgc file and the settings class is a singelton.
Here's an example usage of KConfig XT for the application named Example. With the following example.kcfg file:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE kcfg SYSTEM
"http://www.kde.org/standards/kcfg/1.0/kcfg.dtd">
<kcfg> <kcfgfile name="examplerc"/>
<group name="network"> <entry name="ServerName" type="String"> <label>Defines the sample server.</label> </entry> <entry name="Port" type="Int"> <label>Defines the server port</label> <default>21</default> <min>20</min> <max>990</max> </entry> </group>
</kcfg>
And here's how to actually use the generated class. for the given kcfgc file.
File=example.kcfg
ClassName=ExampleSettings
Singleton=true
Mutators=true
The header files wouldn't change, but the cpp files must now contain the following code to access and store the configuration data :
...
... void ExampleClass::readConfig() {
m_server = ExampleSettings::serverName(); m_port = ExampleSettings::port();
} void ExampleClass:saveSettings() {
ExampleSettings::setServerName( m_server ); ExampleSettings::setPort( m_port ); ExampleSettings::self()->writeConfig();
}
self() returns the current instance of the object. You need to call writeConfig() this way, since it's a virtual method.
To add a dialog you need to create a Qt Designer widget with the widget names corresponding to the names of the options they should edit and prefixed with "kcfg_". It could be something along the lines of:
And you can use the dialog with the following code:
//An instance of your dialog could be already created and could be
// cached, in which case you want to display the cached dialog
// instead of creating another one
if ( KConfigDialog::showDialog( "settings" ) )
return;
// KConfigDialog didn't find an instance of this dialog, so lets // create it : KConfigDialog* dialog = new KConfigDialog(this, "settings",
ExampleSettings::self());
ExampleDesignerWidget* confWdg =
new ExampleDesignerWidget( 0, "Example" );
dialog->addPage( confWdg, i18n("Example"), "example" );
//User edited the configuration - update your local copies of the //configuration data connect( dialog, SIGNAL(settingsChanged()),
this, SLOT(updateConfiguration()) );
dialog->show();
And that's all it takes. You can have a look at KReversi and KTron code in the kdegames module to see a live example of KConfig XT!