diff options
| -rw-r--r-- | src/kconfig_compiler/README.dox | 549 |
1 files changed, 285 insertions, 264 deletions
diff --git a/src/kconfig_compiler/README.dox b/src/kconfig_compiler/README.dox index bf72f3eb..90dd4597 100644 --- a/src/kconfig_compiler/README.dox +++ b/src/kconfig_compiler/README.dox @@ -10,7 +10,7 @@ configuration data. The generated C++ source code is output to a .h and a .cpp file, whose base name is the same as that of the .kcfgc file. -<h2>XML description of the configuration options</h2> +\section kcfg_format The .kcfg XML file format: description of the configuration skeleton The structure of the .kcfg file is described by its DTD kcfg.xsd. @@ -41,24 +41,38 @@ by the QVariant with exception of the clearly binary types (e.g. Pixmap, Image...) which are not supported. Besides those basic types 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 and optional - enum name should be provided via the \<choices\> tag. Enum values are - accessed as integers by the application but stored as strings 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 QList<int>. Useful for storing QSplitter - geometries. - -- Color isn't a special type but has special input. It is generated as QColor. - Any valid input to QColor(QString) can be used (hex or SVG keyword notation) - as well as a special format r,g,b,a where the a denotes the alpha channel and - may be omitted. +<dl> + <dt>Path</dt> + <dd> + 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. + </dd> + + <dt>Enum</dt> + <dd> + This indicates an enumeration. The possible enum values and optional + enum name should be provided via the \<choices\> tag. Enum values are + accessed as integers by the application but stored as strings in the + configuration file. This makes it possible to add more values at a later + date without breaking compatibility. + </dd> + + <dt>IntList</dt> + <dd> + This indicates a list of integers. This information is provided + to the application as QList<int>. Useful for storing QSplitter + geometries. + </dd> + + <dt>Color</dt> + <dd> + Isn't a special type but has special input. It is generated as QColor. + Any valid input to QColor(QString) can be used (hex or SVG keyword notation) + as well as a special format r,g,b,a where the a denotes the alpha channel and + may be omitted. + </dd> +</dl> 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 @@ -75,7 +89,7 @@ entry definition 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> +\section kcfgc_format The .kcfgc file format: code generation options 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 @@ -83,185 +97,189 @@ 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>HeaderExtension</b></td> - <td>string</td> - <td>h</td> - <td>Extension to use for the name of the generated C++ header files. Since KF 5.57</td> -</tr> -<tr> - <td><b>SourceExtension</b></td> - <td>string</td> - <td>cpp</td> - <td>Extension to use for the name of the generated C++ source file. Since KF 5.57</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 and must provide a default constructor (kcfgfile not specified), a constructor - taking a QString argument (kcfgfile with "name" attribute) and a constructor taking a - KSharedConfig::Ptr as argument (kcfgfile with "arg" attribute). - Please refer to the documentation of 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|dpointer</td> - <td>private</td> - <td>C++ access modifier used for member variables holding the configuration - values</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. Enclose a - file name in (escaped) double quotes to generate \#include "..." instead of - \#include \<...\>.</td> -</tr> -<tr> - <td><b>SourceIncludeFiles</b></td> - <td>comma separated list of strings</td> - <td>-</td> - <td>Names of files to be included in the source file of the generated class. Enclose - a file name in (escaped) double quotes to generate \#include "..." instead of - \#include \<...\>.</td> -</tr> -<tr> - <td><b>Mutators</b></td> - <td>true, false or a comma separated list of options</td> - <td>false</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>Notifiers</b></td> - <td>true, false or a comma separated list of options</td> - <td>false</td> - <td>If true, entries will be written with the <b>Notify</b> flag enabled, - so changes can be detected using <b>KConfigWatcher</b>. - If a list is provided, the options that are listed are written with - said flag.</td> -</tr> -<tr> - <td><b>DefaultValueGetters</b></td> - <td>true, false or a comma separated list of options</td> - <td>false</td> - <td>If true, functions to return the default value of all configuration options - are generated. If false, no default value functions are generated. If a list - is provided, default value 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 whose enum is not - explicitly named will get its own namespace for its choices.</td> -</tr> -<tr> - <td><b>UseEnumTypes</b></td> - <td>bool</td> - <td>false</td> - <td>If set to true, all Enum items whose enums are named will use enum types for - the return value of accessor functions and for the parameter of mutator - functions. This eliminates the need to cast accessor return values to the enum - type if you want to use the enum type in your own code. If set to false, - accessor return values and mutator parameters will be of type int.</td> -</tr> -<tr> - <td><b>ForceStringFilename</b></td> - <td>bool</td> - <td>false</td> - <td>If set to true, forces the first parameter of the generated class to be a QString when using an argument for the filename. This is useful to specify at runtime the filename of the configuration class.</td> -</tr> -<tr> - <td><b>GenerateProperties</b></td> - <td>bool</td> - <td>false</td> - <td>If set to true, a Q_PROPERTY will be generated for each member variable holding a configuration value - and the Q_OBJECT macro will be added to the generated class. - Note that you will also need to pass the GENERATE_MOC option to the kconfig_add_kcfg_files macro.</td> -</tr> -<tr> - <td><b>ParentInConstructor</b></td> - <td>bool</td> - <td>false</td> - <td>If set to true, the generated constructor will take an additional QObject* parameter that will be used as the object's parent. - This is useful when working with KQuickAddons::ManagedConfigModule to set it as the parent of the generated class to allow automatic settings discovery and handle the deallocation. - Note this parameter is incompatible with <b>Singleton</b> set to true. - </td> -</tr> -</table> - - -<h2>Advanced options</h2> + +<dl> + <dt>File=\<string\></dt> + <dd> + Default: \<programname\>.kcfg \n + Name of kcfg file containing the options the class is generated for + <!-- what? --> + </dd> + + <dt>HeaderExtension=\<string\></dt> + <dd> + Default: h \n + Since KF 5.57 \n + Extension to use for the name of the generated C++ header files. + </dd> + + <dt>SourceExtension=\<string\></dt> + <dd> + Default: cpp \n + Since KF 5.57 \n + Extension to use for the name of the generated C++ source file. + </dd> + + <dt>NameSpace=\<string\></dt> + <dd> + Optional namespace for generated class + </dd> + + <dt>ClassName=\<string\></dt> + <dd> + Name of generated class (required) + </dd> + + <dt>Inherits=\<string\></dt> + <dd> + Default: KConfigSkeleton \n + Class the generated class inherits from. + + This class must inherit KConfigSkeleton and must provide a default + constructor (kcfgfile not specified), a constructor taking a + QString argument (kcfgfile with "name" attribute) and a constructor + taking a KSharedConfig::Ptr as argument (kcfgfile with "arg" attribute). + Please refer to the documentation of KConfigSkeleton. + </dd> + + <dt>Visibility=\<string\></dt> + <dd> + Inserts visibility directive (for example KDE_EXPORT) between + "class" keyword and class name in header file + </dd> + + <dt>Singleton=\<bool\></dt> + <dd> + Default: false \n + Generated class is a singleton. + </dd> + + <dt>CustomAdditions=\<bool\></dt> + <dd> + <!-- what? --> + </dd> + + <dt>MemberVariables=\<string\></dt> + <dd> + Values: public, protected, private, dpointer \n + Default: private \n + C++ access modifier used for member variables holding the configuration + values + </dd> + + <dt>IncludeFiles=\<string\>, \<string\> ...</dt> + <dd> + Names of files to be included in the header of the generated class. + + Enclose a file name in (escaped) double quotes to generate + \#include "..." instead of \#include \<...\>. + </dd> + + <dt>SourceIncludeFiles=\<string\>, \<string\> ...</dt> + <dd> + Names of files to be included in the source file of the generated class. + + Enclose a file name in (escaped) double quotes to generate + \#include "..." instead of \#include \<...\>. + </dd> + + <dt>Mutators=\<value\></dt> + <dd> + Values: true, false or a comma separated list of options \n + Default: false \n + 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. + </dd> + + <dt>Notifiers=\<value\></dt> + <dd> + Values: true, false or a comma separated list of options \n + Default: false \n + If true, entries will be written with the <b>Notify</b> flag enabled, + so changes can be detected using <b>KConfigWatcher</b>. + If a list is provided, the options that are listed are written with + said flag. + </dd> + + <dt>DefaultValueGetters=\<value\></dt> + <dd> + Values: true, false or a comma separated list of options \n + Default: false \n + If true, functions to return the default value of all configuration options + are generated. If false, no default value functions are generated. If a list + is provided, default value functions are generated for the options that are listed. + </dd> + + <dt>ItemAccessors=\<bool\></dt> + <dd> + Default: false \n + 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. + </dd> + + <dt>SetUserTexts=\<bool\></dt> + <dd> + Default: false \n + 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. + </dd> + + <dt>GlobalEnums=\<bool\></dt> + <dd> + Default: false \n + 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 whose enum is not + explicitly named will get its own namespace for its choices. + </dd> + + <dt>UseEnumTypes=\<bool\></dt> + <dd> + Default: false \n + If set to true, all Enum items whose enums are named will use enum types for + the return value of accessor functions and for the parameter of mutator + functions. This eliminates the need to cast accessor return values to the enum + type if you want to use the enum type in your own code. If set to false, + accessor return values and mutator parameters will be of type int. + </dd> + + <dt>ForceStringFilename=\<bool\></dt> + <dd> + Default: false \n + If set to true, forces the first parameter of the generated class + to be a QString when using an argument for the filename. + This is useful to specify at runtime the filename of the configuration class. + </dd> + + <dt>GenerateProperties=\<bool\></dt> + <dd> + Default: false \n + If set to true, a Q_PROPERTY will be generated for each member variable holding a + configuration value and the Q_OBJECT macro will be added to the generated class. + Note that you will also need to pass the GENERATE_MOC option to the + kconfig_add_kcfg_files macro. + </dd> + + + <dt>ParentInConstructor=\<bool\></dt> + <dd> + Default: false \n + If set to true, the generated constructor will take an additional QObject* + parameter that will be used as the object's parent. + This is useful when working with KQuickAddons::ManagedConfigModule + to set it as the parent of the generated class to allow automatic + settings discovery and handle the deallocation. + Note this parameter is incompatible with <b>Singleton</b> set to true. + </dd> +</dl> + + +\section entry_options Advanced entry options There are several possibilities to parameterize entries. -- Parameterized entries +\subsection parametrized_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 @@ -284,15 +302,15 @@ 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 +\code{.xml} +<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> +\endcode The above describes 4 color configuration entries with the following defaults: @@ -308,75 +326,77 @@ 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 +\code{.xml} +<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> +\endcode The above describes 3 string configuration entries with the following defaults: +\verbatim sound_Explosion=boom.wav sound_Crash=crash.wav sound_Missile=missile.wav +\endverbatim 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 +\subsection parametrized_groups Parameterized groups A group name can be parametrized using a parameter given to the KConfigSkeleton instance (which means this feature cannot be used with singleton classes). Example 1: -\verbatim - <kcfgfile name="testrc"> - <parameter name="groupname"/> - </kcfgfile> - <group name="$(groupname)"> - <entry key="Text" type="string"> - </entry> - </group> -\endverbatim +\code{.xml} +<kcfgfile name="testrc"> + <parameter name="groupname"/> +</kcfgfile> +<group name="$(groupname)"> + <entry key="Text" type="string"> + </entry> +</group> +\endcode In this case passing "Group2" as the 'groupname' parameter to the generated class will make it use group "Group2" for the entry "Text". -- Enums +\subsection enums Enums By default, if <b>GlobalEnums</b> is set to false, a separate named enum will be generated for each Enum entry. Since each enum is defined in a little enclosing class of its own, this allows the same Enum value names to be used in different enums. For example, the .kcfg entry -\verbatim +\code{.xml} <entry name="KeepData" type="Enum"> <choices> <choice name="Do"> <choice name="Dont" value="Don't"> </choices> </entry> -\endverbatim +\endcode will generate this public class containing the enum definition, inside the generated class: -\verbatim - class EnumKeepData - { - public: - enum type { Do, Dont, COUNT }; - }; -\endverbatim +\code{.cpp} +class EnumKeepData +{ + public: + enum type { Do, Dont, COUNT }; +}; +\endcode Since 5.68, if present the <b>value</b> attribute will be used as the choice value written to the backend instead of the <b>name</b>, allowing to write text incompatible with enum naming. @@ -388,21 +408,21 @@ in \<choices\> to prevent duplicate enum member names clashing. Using this, the names are prefixed in code with the string you specify. For example, if <b>GlobalEnums</b> is set to true, the .kcfg entry -\verbatim +\code{.xml} <entry name="KeepData" type="Enum"> <choices prefix="Keep_"> <choice name="Do"> <choice name="Dont" value="Don't"> </choices> </entry> -\endverbatim +\endcode will generate config file entries of "KeepData=Do" and "KeepData=Dont", but the enum will be declared -\verbatim - enum { Keep_Do, Keep_Dont }; -\endverbatim +\code{.cpp} +enum { Keep_Do, Keep_Dont }; +\endcode It is possible to specify your own name for a generated enum, by including a 'name' parameter in \<choices\>. Just like unnamed enums, this enum will be defined in @@ -412,20 +432,20 @@ Therefore the names of Enum values must be unique across both unnamed enums (if An example of a specifically named enum: -\verbatim +\code{.xml} <entry name="KeepData" type="Enum"> <choices name="Types"> <choice name="Do"> <choice name="Dont"> </choices> </entry> -\endverbatim +\endcode which results in the following enum declaration, inside the generated class: -\verbatim - enum Types { Do, Dont }; -\endverbatim +\code{.cpp} +enum Types { Do, Dont }; +\endcode It is also possible to specify the use of enums external to the generated class, by including the string "::" in the enum name - just ensure that it is sufficiently @@ -433,31 +453,32 @@ qualified to be unambiguous in use. To specify use of an unnamed enum, append a trailing "::". For example, to use the enum 'myEnum' defined in class ClassA, use either of -\verbatim +\code{.xml} <choices name="ClassA::myEnum"> <choices name="::ClassA::myEnum"> -\endverbatim +\endcode To specify an unnamed enum in namespace ProgSpace, use -\verbatim +\code{.xml} <choices name="ProgSpace::"> -\endverbatim +\endcode To specify a top-level unnamed enum, use -\verbatim +\code{.xml} <choices name="::"> -\endverbatim +\endcode To specify the top-level enum 'anotherEnum', use -\verbatim +\code{.xml} + <choices name="::anotherEnum"> -\endverbatim +\endcode -- Signal support. +\subsection notify_signals Notify signals An entry can emit a signal when it gets changed. First of all, you must define a list of signals for the configuration class. The signal's name may be @@ -468,26 +489,26 @@ of the entries defined in the .kcfg file. A signal definition can also contain a \<label\> tag which will be the documentation line in the generated file. -\verbatim +\code{.xml} <signal name="emoticonSettingsChanged" /> <signal name="styleChanged"> <label>Tell when a complete style change.</label> - <argument type="String">stylePath</argument> - <argument type="String">StyleCSSVariant</argument> + <argument type="String">stylePath</argument> + <argument type="String">StyleCSSVariant</argument> </signal> -\endverbatim +\endcode After defining the signals, you must tell which signal to emit for the entry. A signal can be emitted by multiple entries. Also, you don't need to specify the arguments for a signal, the signal name will suffice. -\verbatim +\code{.xml} <entry key="stylePath" type="String"> <label>Absolute path to a directory containing a Adium/Kopete chat window style.</label> <emit signal="styleChanged" /> </entry> -\endverbatim +\endcode You can also use the generic configChanged() signal from KConfigSkeleton to notify your application about configuration changes. |