From e16866e072f94410321d70daedbcb855ea878cac Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Sun, 6 Nov 2011 15:56:40 -0600 Subject: Actually move the kde files that were renamed in the last commit --- tdecore/kconfig_compiler/README.dox | 255 ++++++++++++++++++++++++++++++++++++ 1 file changed, 255 insertions(+) create mode 100644 tdecore/kconfig_compiler/README.dox (limited to 'tdecore/kconfig_compiler/README.dox') diff --git a/tdecore/kconfig_compiler/README.dox b/tdecore/kconfig_compiler/README.dox new file mode 100644 index 000000000..36d9f988b --- /dev/null +++ b/tdecore/kconfig_compiler/README.dox @@ -0,0 +1,255 @@ +/** +\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. + +

XML description of the configuration options

+ +The structure of the .kcfg file is described by its DTD kcfg.dtd. + +The \ tag contains the name of the configuration file described. +Omitting the name will make the generated class use the default configuration +file ("rc"). + +The \ 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 \ +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 \ is given, but not \, the name is constructed by removing +all spaces from \. + +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 \ 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. 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 \ tag +should contain the code="true" attribute. The contents of the \ +tag is then considered to be a C++ expression. Note that in this case you +might have to add an \ 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 \ tag. The contents of the \ 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. + +

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 +SOURCES line in the Makefile.am. + +The following options are read from the kcfgc file: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDefaultDescription
Filestringprogramname.kcfgName of kcfg file containing the options the class is generated for
NameSpacestring-Optional namespace for generated class
ClassNamestring-Name of generated class (required)
InheritsstringKConfigSkeletonClass the generated class inherits from. This class must inherit + KConfigSkeleton.
Visibilitystring-Inserts visibility directive (for example KDE_EXPORT) between "class" keyword and class + name in header file
SingletonboolfalseGenerated class is a singleton.
CustomAdditionsbool-
MemberVariablesstring: public|protected|privateprivateC++ access modifier used for memeber variables holding the configuration + valuse
IncludeFilescomma separated list of strings-Names of files to be included in the header of the generated class
Mutatorstrue, false or a comma seperated list of options-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.
ItemAccessorsboolfalseGenerate accessor functions for the KConfigSkeletonItem objects + corresponding to the configuration options. If SetUserTexts is set, + ItemAccessors also has to be set.
SetUserTextsboolfalseSet the label and whatthis texts of the items from the kcfg file.If + SetUserTexts is set, ItemAccessors also has to be set.
GlobalEnumsboolfalseIf 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.
+ + +

Advanced options

+ +There are several possibilities to parameterize entries. + +- Parameterized entries + +An entry can be parameterized using a fixed range parameter specified with +the \ tag. Such parameter can either be an Enum or an int. An Enum +parameter should specify the possible enumeration values with the \ +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 \. When a +param attribute is specified the default value only applies to that +particular parameter value. + +Example 1: +\verbatim + + + #ff0000 + #00ff00 + #0000ff + #ffff00 + +\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 + + + + Explosion + Crash + Missile + + + boom.wav + crash.wav + missile.wav + +\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 + or Waldo Bastian +*/ -- cgit v1.2.1