From c90c389a8a8d9d8661e9772ec4144c5cf2039f23 Mon Sep 17 00:00:00 2001 From: toma Date: Wed, 25 Nov 2009 17:56:58 +0000 Subject: Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features. BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdegames@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da --- doc/ktuberling/technical-reference.docbook | 262 +++++++++++++++++++++++++++++ 1 file changed, 262 insertions(+) create mode 100644 doc/ktuberling/technical-reference.docbook (limited to 'doc/ktuberling/technical-reference.docbook') diff --git a/doc/ktuberling/technical-reference.docbook b/doc/ktuberling/technical-reference.docbook new file mode 100644 index 00000000..94abf945 --- /dev/null +++ b/doc/ktuberling/technical-reference.docbook @@ -0,0 +1,262 @@ + + + + + +Éric +Bischoff + + + + +2006-05-05 +0.05.01 + + +KDE +KTuberling +technical reference + + + +Technical reference + + +&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! + + + +If you extend or add to the game please consider sending your additions to the +developer Éric Bischoff for +inclusion in future releases. + + + +For artists + + +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. + + + +Six images are used in &ktuberling;: potato-game.png, +potato-mask.png, penguin-game.png, +penguin-mask.png, aquarium-game.png +and aquarium-mask.png. The standard location +for these files is the folder $KDEDIR/share/apps/ktuberling/pics/. + + + +The first type of images, *-game.png holds the playground +and the objects that the user selects. This is the graphic that the user sees +when playing the game. + + + +The second type of images, *-mask.png, 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. + + + +In the same folder, a file named layout.xml. +($KDEDIR/share/apps/ktuberling/pics/layout.xml) 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 +below). + + + +Still in the same folder, a file named layout.i18n +($KDEDIR/share/apps/ktuberling/pics/layout.xml) +recapitulates the strings in layout.xml that can be +translated: + +The menu entries that allow to choose the playground and the language +The names of the categories of objects + + + + +One folder above, a file named ktuberlingui.rc +($KDEDIR/share/apps/ktuberling/ktuberlingui.rc) is a +second &XML; file describing the menus of &ktuberling;. It should contain +one <action> 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 layout.xml. + + + + + +Translation + + +Besides the usual .po files mechanism for +translating program labels and prompts, the sounds can be localized too. + + + +If the various +translators can record their voice to a .wav +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 +layout.xml file. For example, if destination language is +Italian, translators can record their voice in .wav files located in +$KDEDIR/share/apps/ktuberling/sounds/it. Then they can +assign the sound named hat to the filename +it/cappello.wav. + + + +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: + +$ oggenc -q 10 -o sound.ogg sound.wav + + + + +Information on how to work with the translation mechanisms in &kde; is available +in The +&kde; Translation HOWTO. + + + + + + +For programmers +&ktuberling; isn't really difficult to extend for programmers. + + +C++ classes + + + +TopLevel + +Top-level window and basic program management + + + + +PlayGround + +Description of one of the game levels + + + +ToDraw + +Description of one of the graphical objects to be +drawn + + + +SoundFactory + +Description of one of the languages and its sounds + + + +Action + +One of the user's manipulation in the undo/redo stack + + + + + + +<literal role="extension">.tuberling</literal> files structure + +A .tuberling file holds all the +necessary data to redraw a tuberling. It can be edited with an ordinary text +editor. + +The first line holds the number of the playground. + +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. + + + + + +Structure of the layout file (<filename>layout.xml</filename>) + + +The top-level tag is unique and is named <ktuberling>. +It contains several <playground> tags, one per +playground, and several <language> tags, one per language. + + + +The <playground> tag has two attributes: gameboard +and masks. These attributes give the name of the files holding the +pictures. The <playground> tag also contains one +<menuitem> tag, one <editablearea> +tag, several <category> tags, and several +<object> tags. + + + +The <menuitem> 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 +ktuberlingui.rc. + + + +The <editablearea> tag describes the position of the +area where you can drop objects, and the name of the sound associated with it. + + + +The <category> 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 goodies. + + + +The <object> 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. + + + +The <language> tag has one attribute: code +This attribute give the code of the locale for that language. +The <language> tag also contains one +<menuitem> tag and several +<sound> tags. + + + +The lower level tags are not explained here, since their meaning is +quite straightforward. If you modify layout.xml, +don't forget to modify layout.i18n and +ktuberlingui.rc accordingly. + + + + -- cgit v1.2.1