summaryrefslogtreecommitdiffstats
path: root/tde-i18n-de/docs/kdegames/ktuberling/technical-reference.docbook
blob: 0f4193eb9c3ac2b42d560d0c0434c46588947fd7 (plain)
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
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
<chapter id="technical-reference">
<chapterinfo>

<authorgroup>
<author
><firstname
>Éric</firstname
> <surname
>Bischoff</surname
> </author>
<othercredit role="translator"
><firstname
>Maren</firstname
><surname
>Pakura</surname
><affiliation
><address
><email
>maren@kde.org</email
></address
></affiliation
><contrib
>Deutsche Übersetzung</contrib
></othercredit
> 
</authorgroup>
<date
>05.05.2006</date
> <releaseinfo
>0.05.01</releaseinfo
> <keywordset>
<keyword
>KDE</keyword>
<keyword
>KTuberling</keyword>
<keyword
>Technische Referenz (in englisch)</keyword>
</keywordset>
</chapterinfo>

<title
>Technische Referenz (in englisch)</title>

<para
>&ktuberling; offers a gentle and rewarding introduction to &kde; customization and programming. The application can be extended. For example, without any coding, new playgrounds can be added by changing the graphics files. By adding appropriate sound files, translators can change the sounds to their native tongue! </para>

<para
>Falls Sie das Spiel erweitern, schicken Sie bitte Ihre Erweiterung an den Entwickler <ulink url="mailto:ebischoff@nerim.net"
>Éric Bischoff</ulink
>, um sie in die nächsten Versionen aufzunehmen. </para>

<sect1 id="for-artists">
<title
>For artists</title>

<para
>The size and shape of the playground and the number of objects can be changed. New playgrounds can be added. Only two image files need to be created for each playground: a gameboard and a mask. A maximum of 8 playgrounds is allowed, out of which only 3 are currently used. </para>

<para
>Six images are used in &ktuberling;: <filename
>potato-game.png</filename
>, <filename
>potato-mask.png</filename
>, <filename
>penguin-game.png</filename
>, <filename
>penguin-mask.png</filename
>, <filename
>aquarium-game.png</filename
> and <filename
>aquarium-mask.png</filename
>. The standard location for these files is the folder <filename class="directory"
>$KDEDIR/share/apps/ktuberling/pics/</filename
>. </para>

<para
>The first type of images, <filename
>*-game.png</filename
> holds the playground and the objects that the user selects. This is the graphic that the user sees when playing the game. </para>

<para
>The second type of images, <filename
>*-mask.png</filename
>, contains only masks of the objects. The masks are used to delimit the borders of the objects and, in some cases, give the object some transparency (for example, the spectacles). It is mandatory to put the objects at the same position in the gameboard file as in the mask file. </para>

<para
>In the same folder, a file named <filename
>layout.xml</filename
>. (<filename
>$KDEDIR/share/apps/ktuberling/pics/layout.xml</filename
>) tells which images to use and links them to menu entries. It also contains the position parameters of the playground and the objects in the gameboard and in the masks. It assigns the sounds to objects and places the objects in groups. It finally declares languages as sets of translated sounds. It follows standard &XML; syntax (see details <link linkend="layout-details"
>below</link
>). </para>

<para
>Still in the same folder, a file named <filename
>layout.i18n</filename
> (<filename
>$KDEDIR/share/apps/ktuberling/pics/layout.xml</filename
>) recapitulates the strings in <filename
>layout.xml</filename
> that can be translated: <itemizedlist>
<listitem
><para
>The menu entries that allow to choose the playground and the language</para
></listitem>
<listitem
><para
>The names of the categories of objects</para
></listitem>
</itemizedlist>
</para>

<para
>One folder above, a file named <filename
>ktuberlingui.rc</filename
> (<filename
>$KDEDIR/share/apps/ktuberling/ktuberlingui.rc</filename
>) is a second &XML; file describing the menus of &ktuberling;. It should contain one <markup
>&lt;action&gt;</markup
> tag per playground and language. The symbolic name of the action in this file should be identical to the symbolic name of the action in <filename
>layout.xml</filename
>. </para>

</sect1>

<sect1 id="for-translators">
<title
>Translation</title>

<para
>Besides the usual <literal role="extension"
>.po</literal
> files mechanism for translating program labels and prompts, the sounds can be localized too. </para>

<para
>If the various translators can record their voice to a <literal role="extension"
>.wav</literal
> file, they can store that file to the language-specific subfolder of the sounds folder. The name of the sound is then assigned to a file in the <filename
>layout.xml</filename
> file. For example, if destination language is Italian, translators can record their voice in <literal role="extension"
>.wav</literal
> files located in <filename
>$KDEDIR/share/apps/ktuberling/sounds/it</filename
>. Then they can assign the sound named <quote
>hat</quote
> to the filename <filename
>it/cappello.wav</filename
>. </para>

<para
>In a future release, &ktuberling; will use OGG Vorbis rc3 file format for sounds. At that moment, it will be possible to convert the WAV files to OGG Vorbis rc3 through the following command line: <screen
><prompt
>$</prompt
> <userinput
>oggenc -q 10 -o <replaceable
>sound.ogg</replaceable
> <replaceable
>sound.wav</replaceable
></userinput
>
</screen>
</para>

<para
>Information on how to work with the translation mechanisms in &kde; is available in <ulink url="http://i18n.kde.org/translation-howto/index.html"
>The &kde; Translation HOWTO</ulink
>. </para>

</sect1>

<sect1 id="for-programmers">

<title
>For programmers</title>
<para
>&ktuberling; isn't really difficult to extend for programmers.</para>

<sect2 id="classes">
<title
>C++ classes</title>

<variablelist>
<varlistentry>
<term
><classname
>TopLevel</classname
></term>
<listitem>
<para
>Top-level window and basic program management</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><classname
>PlayGround</classname
></term>
<listitem>
<para
>Description of one of the game levels</para
> </listitem>
</varlistentry>

<varlistentry>
<term
><classname
>ToDraw</classname
></term>
<listitem>
<para
>Description of one of the graphical <quote
>objects</quote
> to be drawn</para
> </listitem>
</varlistentry>

<varlistentry>
<term
><classname
>SoundFactory</classname
></term>
<listitem>
<para
>Description of one of the languages and its sounds</para
> </listitem>
</varlistentry>

<varlistentry>
<term
><classname
>Action</classname
></term>
<listitem>
<para
>One of the user's manipulation in the undo/redo stack</para
> </listitem>
</varlistentry>
</variablelist>

</sect2>

<sect2 id="files-structure">
<title
><literal role="extension"
>.tuberling</literal
> files structure</title>

<para
>A <literal role="extension"
>.tuberling</literal
> file holds all the necessary data to redraw a tuberling. It can be edited with an ordinary text editor.</para>

<para
>The first line holds the number of the playground.</para>

<para
>On all other lines, there is one graphical object per line, in the order that is used to draw them. Each line contains 5 numbers: the identifier of the object, and the rectangle where it should be drawn (left, top, right, bottom). The numbers are separated by whitespaces.</para>

</sect2>
</sect1>

<sect1 id="layout-details">
<title
>Structure of the layout file (<filename
>layout.xml</filename
>)</title>

<para
>The top-level tag is unique and is named <markup
>&lt;ktuberling&gt;</markup
>. It contains several <markup
>&lt;playground&gt;</markup
> tags, one per playground, and several <markup
>&lt;language&gt;</markup
> tags, one per language. </para>

<para
>The <markup
>&lt;playground&gt;</markup
> tag has two attributes: <markup
>gameboard</markup
> and <markup
>masks</markup
>. These attributes give the name of the files holding the pictures. The <markup
>&lt;playground&gt;</markup
> tag also contains one <markup
>&lt;menuitem&gt;</markup
> tag, one <markup
>&lt;editablearea&gt;</markup
> tag, several <markup
>&lt;category&gt;</markup
> tags, and several <markup
>&lt;object&gt;</markup
> tags. </para>

<para
>The <markup
>&lt;menuitem&gt;</markup
> tag describes the action identifier of the menu item allowing to select position of the area where you can drop objects, and the label of this menu item. This action identifier should be identical to the one in <filename
>ktuberlingui.rc</filename
>. </para>

<para
>The <markup
>&lt;editablearea&gt;</markup
> tag describes the position of the area where you can drop objects, and the name of the sound associated with it. </para>

<para
>The <markup
>&lt;category&gt;</markup
> tag describes the position and the label of a text describing a group of objects. For example, it can describe the position and the text of the group of <quote
>goodies</quote
>. </para>

<para
>The <markup
>&lt;object&gt;</markup
> tag describes the position (in the gameboard and in the masks) of an object, as well as the name of the sound associated with it. </para>

<para
>The <markup
>&lt;language&gt;</markup
> tag has one attribute: <markup
>code</markup
> This attribute give the code of the locale for that language. The <markup
>&lt;language&gt;</markup
> tag also contains one <markup
>&lt;menuitem&gt;</markup
> tag and several <markup
>&lt;sound&gt;</markup
> tags. </para>

<para
>The lower level tags are not explained here, since their meaning is quite straightforward. If you modify <filename
>layout.xml</filename
>, don't forget to modify <filename
>layout.i18n</filename
> and <filename
>ktuberlingui.rc</filename
> accordingly. </para>

</sect1>
</chapter>