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 zone di ricreazione 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 r Eric Bischoff perché li includa nelle prossime versioni.

## Per gli artisti

La dimensione e l'aspetto della zona di ricreazione e il numero degli oggetti possono essere cambiati. Nuove zone di ricreazione possono essere aggiunte. Servono solo due file grafici per ogni zona ricreativa: un piano di gioco e una maschera. Si possono mettere fino a 8 zone di gioco, delle quali al momento se sono presenti solo tree.

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 directory `$KDEDIR/share/apps/ktuberling/pics/`.

Il primo tipo di immagini, `*-game.png` contiene la zona ricreativa 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 directory, 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 zona ricreativa e degli oggetti nel piano di gioco e nelle maschere. Esso, infine, assegna i suoni agli oggetti e classifica gli oggetti in gruppi. Esso infine dichiara i linguaggi come insiemi di suoni tradotti. Esso segue la sintassi XML standard (per i dettagli vedi più avanti).

Sempre nella stessa directory, 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 i piani di gioco e la lingua

- i nomi delle categorie di oggetti

In un'altra directory, un file chiamato `ktuberlingui.rc` (`$KDEDIR/share/apps/ktuberling/ktuberlingui.rc`) è un secondo file XML che descrive i menu di &ktuberling;. Dovrebbe contenere un <action> tag per ogni piano di gioco 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 un file `.wav`, che poi possono collocare nella sottodirectory riservata alla loro lingua della directory 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

`Zona ricreativa`

  Descrizione di uno dei livelli di gioco

`Disegnare`

  Descrizione di uno degli oggetti grafici da disegnare.

`Laboratorio sonoro`

  Descrizione di una lingua e dei suoi suoni

`Azione`

  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 zona di ricreazione.

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 zona ricreativa, e del tipo <language> tags, 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 zona ricreativa 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 zona ricreativa 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`.