diff options
Diffstat (limited to 'kdecore/kconfig_compiler/README.dox')
| -rw-r--r-- | kdecore/kconfig_compiler/README.dox | 255 |
1 files changed, 0 insertions, 255 deletions
diff --git a/kdecore/kconfig_compiler/README.dox b/kdecore/kconfig_compiler/README.dox deleted file mode 100644 index 36d9f988b..000000000 --- a/kdecore/kconfig_compiler/README.dox +++ /dev/null @@ -1,255 +0,0 @@ -/** -\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> -*/ |