# Technická príručka

&ktuberling; umožňuje príjemnú cestu, ako sa naučiť upravovať &kde; a ako v ňom programovať. Aplikáciu je možné rozšíriť. Napríklad, bez programovania je možné pridať nové ihriská zmenou grafických súborov. Pridaním vhodných zvukových súborov je možné pridať ďalší jazyk.

Ak rozšírite alebo upravíte niektorú časť, prosím, pošlite vaše zmeny autorovi, Ericovi Bischoffovi, aby ich pridal do budúcich verzií.

## Pre umelcov

Veľkosť a tvar ihriska a počet objektov je možné zmeniť. Môžete aj pridať nové ihriská. Stačia na to dva grafické súbory: hracia plocha a maska. Povolených je maximálne 8 ihrísk, pričom 3 už sú definované.

&ktuberling; používa 6 obrázkov: `potato-game.png`, `potato-mask.png`, `penguin-game.png`, `penguin-mask.png`, `aquarium-game.png` a `aquarium-mask.png`. Ich štandardné umiestnenie je v priečinku `$KDEDIR/share/apps/ktuberling/pics/`.

Prvý typ obrázkov, `*-game.png` obsahuje ihrisko a objekty, ktoré je možné umiestniť. Toto je grafika, ktorú používateľ vidí počas hry.

Druhý typ obrázkov, `*-mask.png`, obsahuje iba masky objektov. Používajú sa pre určenie okrajov objektov a v niektorých prípadoch definujú aj priehľadnosť objektov (napríklad pre okuliare). Je nutné, aby objekty boli v súbore masky umiestnené na rovnakom mieste ako v súbore s obrázkami pre hru.

V tom istom priečinku sa nachádza aj súbor `layout.xml`. (`$KDEDIR/share/apps/ktuberling/pics/layout.xml`) Obsahuje definíciu, ktoré obrázky sa majú použiť a určuje pre ne položky menu. Obsahuje aj parametre pozície ihriska a objektov na ploche a v maske. Priraďuje objektom zvuky a vytvára z objektov skupiny. No a nakoniec dekladuje jazyky ako množiny preložených zvukov. Je v štandardnom formáte XML (detaily nájdete nižšie).

V priečinku je ešte súbor `layout.i18n` (`$KDEDIR/share/apps/ktuberling/pics/layout.xml`), ktorý obsahuje texty z `layout.xml`, ktoré je možné preložiť:

- Položky menu, ktoré umožňujú vybrať ihrisko a jazyk

- Mená kategórií objektov

O jednu úroveň vyššie je súbor `ktuberlingui.rc` (`$KDEDIR/share/apps/ktuberling/ktuberlingui.rc`). Popisuje menu &ktuberling;. Mal by obsahovať jednu značku `<action>` pre každé ihrisko a jazyk. Symbolické meno akcie v tomto súbore by malo byť rovnaké ako symbolické meno akcie v súbore `layout.xml`.

## Preklad

Okrem obvyklého spôsobu prekladu pomocou súborov `.po`, je možné preložiť aj zvuky.

Prekladatelia môžu nahrať zvuky a uložiť ich do súborov `.wav`, tie potom uložiť do podpriečinku pre ich jazyk. Meno zvuku sa potom priradí súboru v `layout.xml`. Napríklad, ak sa prekladá so slovenčiny, súbory `.wav` by mali byť v `$KDEDIR/share/apps/ktuberling/sounds/sk`. Potom je možné zvuk hat priradiť menu súboru `sk/klobuk.wav`.

V budúcej verzii bude &ktuberling; používať formát OGG Vorbis rc3. Momentálne je možné previesť súbory WAV na OGG Vorbis rc3 týmto príkazom:

    $ oggenc_rc3 -o zvuk.ogg zvuk.wav

Informácie o mechanizme prekladu &kde; nájdete v The KDE Translation HOWTO.

## Pre programátorov

Pre programátorov nie je zložité &ktuberling; rozšíriť.

### Triedy C++

`TopLevel`

- Okno najvyššej úrovne a základná správa programu

`PlayGround`

- Popis jednej z úrovní hry

`ToDraw`

- Popis jedného z grafických objektov, ktoré sa majú vykresliť

`SoundFactory`

- Popis jedného z jazykov a jeho zvukov

`Akcia`

- Jedna zmena v zásobníku akcií pre vrátenie späť/opakovanie vrátených

### Štruktúra súborov `.tuberling`

Súbor `.tuberling` obsahuje všetky dáta nutné pre prekreslenie obrázku. Dá sa upraviť normálnym textovým editorom.

Prvý riadok obsahuje číslo ihriska.

Každý ďalší riadok obsahuje jeden grafický objekt v poradí, ako sa majú kresliť. Každý riadok obsahuje 5 čísel: identifikátor objektu a obdĺžnik, kde sa má vykresliť (ľavá, horná, pravá, dolná súradnica). Čísla sú oddelené medzerami.

## Štruktúra súboru rozloženia (`layout.xml`)

Značka na najvyššej úrovni môže byť iba jedna a musí to byť `<ktuberling>`. Obsahuje niekoľko častí `<playground>`, pre každé ihrisko jednu a niekoľko častí `<language>`, jednu pre každý jazyk.

Značka `<playground>` má dva atribúty: `gameboard` a `masks`. Obsahujú mená súborov, ktoré obsahujú obrázky. Značka `<playground>` obsahuje aj jednu značku `<menuitem>`, jednu `<editablearea>`, niekoľko `<category>` a niekoľko `<object>`.

Značka `<menuitem>` popisuje idfentifikátor akcie položky menu, ktorá umožňuje vybrať pouíciu, kde sa majú objekty pustiť a text tejto položky menu. Tento identifikátor by mal byť v súbore `ktuberlingui.rc`.

Značka `<editablearea>` popisuje pozíciu, kam sa majú púšťať objekty a meno zvuku s ňou asociovaného.

Značka `<category>` obsahuje pozíciu a text pre skupinu objektov. Napríklad môže popisovať pozíciu a text skupiny vylepšení.

Značka `<object>` popisuje pozíciu (v súbore plánu a masky) objektu, jeho meno a jeho zvuk.

Značka `<language>` má jeden atribút: `code` Obsahuje kód jazyka. Značka `<language>` obsahuje jednu značku `<menuitem>` tag a niekoľko značiek `<sound>`.

Značky na ďalších úrovniach tu už nie sú popísané, pretože ich použitie je zrejmé. Ak zmeníte súbor `layout.xml`, nezabudnite upraviť aj `layout.i18n` a `ktuberlingui.rc`.