You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
256 lines
8.5 KiB
256 lines
8.5 KiB
/**
|
|
\page kconfig_compiler The KDE Configuration Compiler
|
|
|
|
kconfig_compiler generates C++ source code from an XML file containing
|
|
information about configuration options (.kcfg) and a file that provides
|
|
the code generation options (.kcfgc) The generated class is based on
|
|
KConfigSkeleton and provides an API for the application to access its
|
|
configuration data.
|
|
|
|
<h2>XML description of the configuration options</h2>
|
|
|
|
The structure of the .kcfg file is described by its DTD kcfg.dtd.
|
|
|
|
The \<kcfgfile\> tag contains the name of the configuration file described.
|
|
Omitting the name will make the generated class use the default configuration
|
|
file ("<appname>rc").
|
|
|
|
The \<include\> tags are optional and may contain C++ header files that
|
|
are needed to compile the code needed to compute default values.
|
|
|
|
The remaining entries in the XML file are grouped by the tag \<group\>
|
|
which describes the corresponding group in the configuration file.
|
|
|
|
The individual entries must have at least a name or a key. The name is used to
|
|
create accessor and modifier functions. It's also used as the key in the config
|
|
file. If \<key\> is given, but not \<name\>, the name is constructed by removing
|
|
all spaces from \<key\>.
|
|
|
|
An entry must also have a type. The list of allowable types is
|
|
specified in the DTD and loosely follows the list of types supported
|
|
by the QVariant with exception of the clearly binary types
|
|
(e.g. Pixmap, Image...) which are not supported. Besides those basic
|
|
type the following special types are supported:
|
|
|
|
- Path This is a string that is specially treated as a file-path.
|
|
In particular paths in the home directory are prefixed with $HOME in
|
|
when being stored in the configuration file.
|
|
|
|
- Enum This indicates an enumeration. The possible enum values should
|
|
be provided via the \<choices\> tag. Enum values are accessed as integers
|
|
by the application but stored as string in the configuration file. This
|
|
makes it possible to add more values at a later date without breaking
|
|
compatibility.
|
|
|
|
- IntList This indicates a list of integers. This information is provided
|
|
to the application as QValueList<int>. Useful for storing QSplitter
|
|
geometries.
|
|
|
|
An entry can optionally have a default value which is used as default when
|
|
the value isn't specified in any config file. Default values are interpreted
|
|
as literal constant values. If a default value needs to be computed
|
|
or if it needs to be obtained from a function call, the \<default\> tag
|
|
should contain the code="true" attribute. The contents of the \<default\>
|
|
tag is then considered to be a C++ expression. Note that in this case you
|
|
might have to add an \<include\> tag as described above so that the code
|
|
which computes the default value can be compiled.
|
|
|
|
Additional code for computing default values can be provided via
|
|
the \<code\> tag. The contents of the \<code\> tag is inserted as-is. A
|
|
typical use for this is to compute a common default value which can
|
|
then be referenced by multiple entries that follow.
|
|
|
|
<h2>Code generation options</h2>
|
|
|
|
The options for generating the C++ sources are read from the file with the
|
|
extension .kcfgc. To generate a class add the corresponding kcfgc file to the
|
|
SOURCES line in the Makefile.am.
|
|
|
|
The following options are read from the kcfgc file:
|
|
|
|
<table>
|
|
<tr>
|
|
<td><b><i>Name</i></b></td>
|
|
<td><b><i>Type</i></b></td>
|
|
<td><b><i>Default</i></b></td>
|
|
<td><b><i>Description</i></b></td>
|
|
</tr>
|
|
<tr>
|
|
<td><b>File</b></td>
|
|
<td>string</td>
|
|
<td>programname.kcfg</td>
|
|
<td>Name of kcfg file containing the options the class is generated for</td>
|
|
</tr>
|
|
<tr>
|
|
<td><b>NameSpace</b></td>
|
|
<td>string</td>
|
|
<td>-</td>
|
|
<td>Optional namespace for generated class</td>
|
|
</tr>
|
|
<tr>
|
|
<td><b>ClassName</b></td>
|
|
<td>string</td>
|
|
<td>-</td>
|
|
<td>Name of generated class (required)</td>
|
|
</tr>
|
|
<tr>
|
|
<td><b>Inherits</b></td>
|
|
<td>string</td>
|
|
<td>KConfigSkeleton</td>
|
|
<td>Class the generated class inherits from. This class must inherit
|
|
KConfigSkeleton.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><b>Visibility</b></td>
|
|
<td>string</td>
|
|
<td>-</td>
|
|
<td>Inserts visibility directive (for example KDE_EXPORT) between "class" keyword and class
|
|
name in header file</td>
|
|
</tr>
|
|
<tr>
|
|
<td><b>Singleton</b></td>
|
|
<td>bool</td>
|
|
<td>false</td>
|
|
<td>Generated class is a singleton.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><b>CustomAdditions</b></td>
|
|
<td>bool</td>
|
|
<td>-</td>
|
|
<td></td>
|
|
</tr>
|
|
<tr>
|
|
<td><b>MemberVariables</b></td>
|
|
<td>string: public|protected|private</td>
|
|
<td>private</td>
|
|
<td>C++ access modifier used for memeber variables holding the configuration
|
|
valuse</td>
|
|
</tr>
|
|
<tr>
|
|
<td><b>IncludeFiles</b></td>
|
|
<td>comma separated list of strings</td>
|
|
<td>-</td>
|
|
<td>Names of files to be included in the header of the generated class</td>
|
|
</tr>
|
|
<tr>
|
|
<td><b>Mutators</b></td>
|
|
<td>true, false or a comma seperated list of options</td>
|
|
<td>-</td>
|
|
<td>If true, mutator functions for all configuration options are generated.
|
|
If false, no mutator functions are generated. If a list is provided,
|
|
mutator functions are generated for the options that are listed.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><b>ItemAccessors</b></td>
|
|
<td>bool</td>
|
|
<td>false</td>
|
|
<td>Generate accessor functions for the KConfigSkeletonItem objects
|
|
corresponding to the configuration options. If <b>SetUserTexts</b> is set,
|
|
<b>ItemAccessors</b> also has to be set.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><b>SetUserTexts</b></td>
|
|
<td>bool</td>
|
|
<td>false</td>
|
|
<td>Set the label and whatthis texts of the items from the kcfg file.If
|
|
<b>SetUserTexts</b> is set, <b>ItemAccessors</b> also has to be set.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><b>GlobalEnums</b></td>
|
|
<td>bool</td>
|
|
<td>false</td>
|
|
<td>If set to true all choices of Enum items will be created in the global
|
|
scope of the generated class. If set to false, each Enum item will get an own
|
|
namespace for its choices.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
|
|
<h2>Advanced options</h2>
|
|
|
|
There are several possibilities to parameterize entries.
|
|
|
|
- Parameterized entries
|
|
|
|
An entry can be parameterized using a fixed range parameter specified with
|
|
the \<parameter\> tag. Such parameter can either be an Enum or an int. An Enum
|
|
parameter should specify the possible enumeration values with the \<choices\>
|
|
tag. An int parameter should specify its maximum value. Its minimum value
|
|
is always 0.
|
|
|
|
A parameterized entry is expanded to a number of entries, one for each
|
|
value in the parameter range. The name and key should contain a reference
|
|
to the parameter in the form of $(parameter-name). When expanding the entries
|
|
the $(parameter-name) part is replaced with the value of the parameter.
|
|
In the case of an Enum parameter it is replaced with the name of the
|
|
enumuration value. In the case of an int parameter it is replaced with
|
|
the numeric value of the parameter.
|
|
|
|
Parameterized entries all share the same default value unless different
|
|
default values have been specified for specific parameter values.
|
|
This can be done with the param= attribute of the \<default\>. When a
|
|
param attribute is specified the default value only applies to that
|
|
particular parameter value.
|
|
|
|
Example 1:
|
|
\verbatim
|
|
<entry name="Color$(ColorIndex)" type="Color" key="color_$(ColorIndex)">
|
|
<parameter name="ColorIndex" type="Int" max="3"/>
|
|
<default param="0">#ff0000</default>
|
|
<default param="1">#00ff00</default>
|
|
<default param="2">#0000ff</default>
|
|
<default param="3">#ffff00</default>
|
|
</entry>
|
|
\endverbatim
|
|
|
|
The above describes 4 color configuration entries with the following defaults:
|
|
|
|
\verbatim
|
|
color_0=#ff0000
|
|
color_1=#00ff00
|
|
color_2=#0000ff
|
|
color_3=#ffff00
|
|
\endverbatim
|
|
|
|
The configuration options will be accessible to the application via
|
|
a QColor color(int ColorIndex) and a
|
|
void setColor(int ColorIndex, const QColor &v) function.
|
|
|
|
Example 2:
|
|
\verbatim
|
|
<entry name="Sound$(SoundEvent)" type="String" key="sound_$(SoundEvent)">
|
|
<parameter name="SoundEvent" type="Enum">
|
|
<values>
|
|
<value>Explosion</value>
|
|
<value>Crash</value>
|
|
<value>Missile</value>
|
|
</values>
|
|
</parameter>
|
|
<default param="Explosion">boom.wav</default>
|
|
<default param="Crash">crash.wav</default>
|
|
<default param="Missile">missile.wav</default>
|
|
</entry>
|
|
\endverbatim
|
|
|
|
The above describes 3 string configuration entries with the following defaults:
|
|
|
|
sound_Explosion=boom.wav
|
|
sound_Crash=crash.wav
|
|
sound_Missile=missile.wav
|
|
|
|
The configuration options will be accessible to the application via
|
|
a QString sound(int SoundEvent) and a
|
|
void setSound(int SoundEvent, const QString &v) function.
|
|
|
|
- Parameterized groups
|
|
|
|
...STILL TODO...
|
|
|
|
|
|
|
|
|
|
|
|
If you have questions or comments please contact Cornelius Schumacher
|
|
<schumacher@kde.org> or Waldo Bastian <bastian@kde.org>
|
|
*/
|