1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
|
/**
\page rbkconfig_compiler The KDE Configuration Compiler for Ruby
rbkconfig_compiler generates Ruby 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
KDE::ConfigSkeleton 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 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 TQt::Variant 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 an Array of Integers. Useful for storing TQt::Splitter
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 ruby expression.
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 Ruby 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 (retquired)</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:
color_0=#ff0000
color_1=#00ff00
color_2=#0000ff
color_3=#ffff00
The configuration options will be accessible to the application via
a color(colorIndex) and a
setColor(colorIndex, v) method.
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 sound(soundEvent) and a
setSound(soundEvent, v) method.
- Parameterized groups
...STILL TODO...
If you have questions or comments please contact Cornelius Schumacher
<schumacher@kde.org> or Waldo Bastian <bastian@kde.org>
For Ruby specific questions please contact Richard Dale
<Richard_Dale@tipitina.demon.co.uk>
*/
|
