Eric
Bischoff
Andrea
Celli

    a.celli@caltanet.it

Traduzione della documentazione tecnica
2002-04-10
0.03.02
KDE
KTuberling
documentazione tecnica

# Documentazione tecnica

&ktuberling; fornisce un'introduzione agevole e gratificante alla programmazione e personalizzazione in &kde;. Questa applicazione può essere estesa. Per esempio, si possono introdurre nuove scene cambiando i file grafici, senza bisogno di programmare. Aggiungendo gli appropriati file sonori, i traduttori possono mettere i commenti sonori nella propria lingua.

Se introduci estensioni o aggiunte al gioco, considera l'idea di inviare i tuoi contributi allo sviluppatore Eric Bischoff perché li includa nelle prossime versioni.

## Per gli artisti

La dimensione e l'aspetto della scena e il numero degli oggetti possono essere cambiati. Nuove scene possono essere aggiunte. Servono solo due file grafici per ogni scena: un piano di gioco e una maschera. Si possono usare fino a 8 scene, delle quali al momento ne sono presenti solo tre.

In &ktuberling; ci sono sei file grafici: `potato-game.png`, `potato-mask.png`, `penguin-game.png`, `penguin-mask.png`, `aquarium-game.png` e `aquarium-mask.png`. La collocazione abituale per questi file è la cartella `$KDEDIR/share/apps/ktuberling/pics/`.

Il primo tipo di immagini, `*-game.png` contiene la scena e gli oggetti che il giocatore può selezionare. Questa è la grafica che il giocatore vede quando gioca.

Il secondo tipo di immagini, `*-mask.png`, contiene solo maschere degli oggetti. le maschere sono usate per delimitare i bordi degli oggetti e, talora, per dare agli oggetti un po' di trasparenza (ad es. gli occhiali). E` indispensabile mettere nella stessa posizione gli oggetti e le relative maschere nei due tipi di file.

Nella stessa cartella, un file chiamato `layout.xml`. (`$KDEDIR/share/apps/ktuberling/pics/layout.xml`) dice quali immagini usare e le collega alle voci del menu. Esso contiene anche i parametri posizionali della scena e degli oggetti nel piano di gioco e nelle maschere. Assegna i suoni agli oggetti e classifica gli oggetti in gruppi. Esso, infine, dichiara i linguaggi come insiemi di suoni tradotti. é scritto seguendo la sintassi XML standard (per i dettagli vedi più avanti).

Sempre nella stessa cartella, un file chiamato `layout.i18n` (`$KDEDIR/share/apps/ktuberling/pics/layout.xml`) riporta le stringhe del file `layout.xml` che possono essere tradotte:

- Le voci del menu che permettono di scegliere le scene e la lingua

- i nomi delle categorie di oggetti

In un'altra cartella, un file chiamato `ktuberlingui.rc` (`$KDEDIR/share/apps/ktuberling/ktuberlingui.rc`) è un secondo file XML che descrive i menu di &ktuberling;. Dovrebbe contenere un tag <action> per ogni scena e lingua. Il nome simbolico dell'azione in questo file dovrà essere identico al nome simbolico dell'azione in `layout.xml`.

## Traduzione

Oltre all'abituale sistema dei file `.po` per tradurre messaggi e richieste del programma, occorrerà localizzare anche i file sonori.

I vari traduttori possono registrare la loro voce su file `.wav`, che poi possono collocare nella sotto-cartella riservata alla loro lingua della cartella sounds. Il nome del file audio verrà poi tradotto nel file `.po`. Per esempio, se la lingua da usare fosse l'italiano, i traduttori possono registrare la loro voce in file `.wav` da mettere in `$KDEDIR/share/apps/ktuberling/sounds/it`. Poi, tradurranno i nomi di file come `en/hat.wav` in qualcosa tipo `it/cappello.wav`.

In una versione futura, &ktuberling; userà il formato di file OGG Vorbis rc3 per i suoni. In quel momento, sarà possibile convertire i file WAV in file OGG Vorbis rc3 usando la seguente riga di comando:

    $ oggenc_rc3 -o sound.ogg sound.wav

Le informazioni su come utilizzare i meccanismi di traduzione per &kde; sono disponibili nel KDE Translation HOWTO.

## Per i programmatori

Non è molto difficile per un programmatore estendere &ktuberling;.

### Classi C++

`TopLevel`

  Gestione a alto livello della finestra e del programma base

`PlayGround`

  Descrizione di uno dei livelli di gioco

`ToDraw`

  Descrizione di uno degli oggetti grafici da disegnare.

`SoundFactory`

  Descrizione di una lingua e dei suoi suoni

`Action`

  Una delle manipolazioni dell'utente sullo stack annulla/rifai

### struttura dei file `.tuberling`

Un file `.tuberling` contiene tutti i dati necessari per ridisegnare un uomo-patata. Esso può essere modificato con un normale editor di testi.

La prima riga contiene il numero progressivo della scena.

Su tutte le altre righe, viene messo un oggetto per riga, nell'ordine in cui verranno disegnati. Ogni riga contiene 5 numeri: l'identificatore dell'oggetto e il rettangolo all'interno del quale verrà disegnato (sinistra, alto, destra, basso). I numeri sono separati da spazi.

## Struttura del file di formattazione (`layout.xml`)

Il tag di livello superiore è unico e si chiama <ktuberling>. Esso contiene diversi tag del tipo <playground>, uno per ogni scena, e del tipo <language>, uno per ogni lingua.

Il tag <playground> ha due attributi: gameboard e masks. Questi attributi assegnano i nomi dei file che contengono i disegni. Il tag <playground> contiene anche un tag <menuitem>, un tag <editablearea>, diversi tag <category> e diversi tag <object>.

Il tag <menuitem> descrive l'action identifier della voce di menu che permette di selezionare il punto della scena dove vuoi disporre l'oggetto, e l'etichetta di questa voce del menu. Questo action identifier deve essere identico a quello in `ktuberlingui.rc`.

Il tag <editablearea> descrive la posizione della scena dove si possono porre gli oggetti e il nome del suono associato.

Il tag <category> descrive la posizione e l'etichetta di un testo che descrive un gruppo di oggetti. Per esempio, esso può descrivere la posizione e il testo del gruppo degli ornamenti.

Il tag <object> descrive la posizione (nel piano di gioco e nella maschera) di un oggetto e del suono associato ad esso.

Il tag <playground> ha un attributo: code. Questo attributo assegna il codice per la localizzazione di quel linguaggio. Il tag <playground> contiene anche un tag <menuitem> e diversi tag <sound>.

I tag di livello inferiore non saranno spiegati qui, in quanto il loro significato è abbastanza ovvio. Se modifichi `layout.xml`, non dimenticarti di modificare coerentemente `layout.i18n` e `ktuberlingui.rc`.