Move kconfig code to the root directory.

1 files changed, 446 insertions, 0 deletions

diff --git a/src/kconfig_compiler/README.dox b/src/kconfig_compiler/README.dox
new file mode 100644
index 00000000..b9606f1d
--- /dev/null
+++ b/src/kconfig_compiler/README.dox
@@ -0,0 +1,446 @@
+/**
+\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.
+
+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>
+
+The structure of the .kcfg file is described by its DTD kcfg.xsd.
+
+The \<kcfgfile\> tag may contain either the "name" attribute, which should be the name
+of the configuration file described, or the "arg" attribute, which, if set to
+"true", will allow you to pass the KSharedConfig::Ptr object to use.
+
+If neither "name" nor "arg" is set, the default configuration file
+("\<appname\>rc") will be used.
+
+The \<include\> tags are optional and may contain C++ header files that
+are needed to compile the code needed to compute default values. To generate
+a \#include "..." statement instead of \#include \<...\>, enclose the header
+file name in double quotes (e.g. \<include\>"header.h"\</include\>).
+
+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 key is used
+as the key in the config file, while the name is used to create accessor and
+modifier functions. If \<key\> is given, but not \<name\>, the name is
+constructed by removing all spaces from \<key\>. If \<name\> is given, but
+not \<key\>, the key is the same as \<name\>.
+
+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
+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 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, or a
+SourceIncludeFiles entry in the .kcfgc file as described below, so that the
+code which computes the default value can be compiled.
+
+Additional code for computing default values can be provided outside any
+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>
+
+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|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>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>
+</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
+
+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
+
+In this case passing "Group2" as the 'groupname' parameter to the generated class
+will make it use group "Group2" for the entry "Text".
+
+- 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
+<entry name="KeepData" type="Enum">
+  <choices>
+    <choice name="Do">
+    <choice name="Dont">
+  </choices>
+</entry>
+\endverbatim
+
+will generate this public class containing the enum definition, inside the generated class:
+
+\verbatim
+    class EnumKeepData
+    {
+      public:
+      enum type { Do, Dont, COUNT };
+    };
+\endverbatim
+
+Alternatively, if <b>GlobalEnums</b> is set to true, all Enum items are defined as
+unnamed enums in the global scope of the generated class. In this case, all Enum values
+must have different names to avoid clashes. However, you can use a 'prefix' argument
+in \<choices\> to prevent duplicate enum member names clashing. Using this, the Enum value
+names are prefixed in code with the string you specify. For example, if <b>GlobalEnums</b>
+is set to true, the .kcfg entry
+
+\verbatim
+<entry name="KeepData" type="Enum">
+  <choices prefix="Keep_">
+    <choice name="Do">
+    <choice name="Dont">
+  </choices>
+</entry>
+\endverbatim
+
+will generate config file entries of "KeepData=Do" and "KeepData=Dont", but the enum
+will be declared
+
+\verbatim
+    enum { Keep_Do, Keep_Dont };
+\endverbatim
+
+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
+the global scope of the generated class (without any enclosing class of its own).
+Therefore the names of Enum values must be unique across both unnamed enums (if
+<b>GlobalEnums</b> is set to true) and all specifically named enums.
+
+An example of a specifically named enum:
+
+\verbatim
+<entry name="KeepData" type="Enum">
+  <choices name="Types">
+    <choice name="Do">
+    <choice name="Dont">
+  </choices>
+</entry>
+\endverbatim
+
+which results in the following enum declaration, inside the generated class:
+
+\verbatim
+    enum Types { Do, Dont };
+\endverbatim
+
+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
+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
+<choices name="ClassA::myEnum">
+<choices name="::ClassA::myEnum">
+\endverbatim
+
+To specify an unnamed enum in namespace ProgSpace, use
+
+\verbatim
+<choices name="ProgSpace::">
+\endverbatim
+
+To specify a top-level unnamed enum, use
+
+\verbatim
+<choices name="::">
+\endverbatim
+
+To specify the top-level enum 'anotherEnum', use
+
+\verbatim
+<choices name="::anotherEnum">
+\endverbatim
+
+
+- Signal support.
+
+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
+any legal identifier you wish. The \<argument\> tag allows you to specify arguments
+for the emitted signal. It supports all types as defined in
+the KConfigXT DTD. The argument value must specify the name, without spaces, of one
+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
+<signal name="emoticonSettingsChanged" />
+
+<signal name="styleChanged">
+  <label>Tell when a complete style change.</label>
+    <argument type="String">stylePath</argument>
+    <argument type="String">StyleCSSVariant</argument>
+</signal>
+\endverbatim
+
+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
+<entry key="stylePath" type="String">
+  <label>Absolute path to a directory containing a Adium/Kopete chat window style.</label>
+  <emit signal="styleChanged" />
+</entry>
+\endverbatim
+
+You can also use the generic configChanged() signal from KConfigSkeleton to notify your application
+about configuration changes.
+
+If you have questions or comments please contact Cornelius Schumacher
+<schumacher@kde.org> or Waldo Bastian <bastian@kde.org>
+*/