<chapter id="technical-reference">
<chapterinfo>

<authorgroup>
<author
> <firstname
>Eric</firstname
> <surname
>Bischoff</surname
> </author>
<othercredit role="translator"
><firstname
>Andrea</firstname
><surname
> Celli</surname
><affiliation
><address
><email
>a.celli@caltanet.it</email
></address
></affiliation
><contrib
>Traduzione della documentazione tecnica</contrib
></othercredit>
</authorgroup>

<date
>2002-01-14</date>
<releaseinfo
>0.02.08</releaseinfo>

<keywordset>
<keyword
>KDE</keyword>
<keyword
>KTuberling</keyword>
<keyword
>documentazione tecnica</keyword>
</keywordset>
</chapterinfo>

<title
>Documentazione tecnica</title>

<para
> &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. </para>

<para
> Se introduci estensioni o aggiunte al gioco, considera l'idea di inviare i tuoi contributi allo sviluppatore r <ulink url="mailto:e.bischoff@noos.fr"
>Eric Bischoff</ulink
> perché li includa nelle prossime versioni. </para>

<sect1 id="for-artists">
<title
>Per gli artisti</title>

<para
> 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 : un piano di gioco e una maschera. Si possono mettere fino a 8 zone di gioco, delle quali al momento se sono presenti solo due. </para>

<para
> In &ktuberling; ci sono quattro file grafici: <filename
>potato-game.png</filename
>, <filename
>potato-mask.png</filename
>, <filename
>penguin-game.png</filename
> e <filename
>penguin-mask.png</filename
>. La collocazione abituale per questi file è la directory <filename class="directory"
>$KDEDIR/share/apps/ktuberling/pics/</filename
>. </para>

<para
> Il primo tipo di immagini, <filename
>*-game.png</filename
> contiene la zona ricreativa e gli oggetti che il giocatore può selezionare. Questa è la grafica che il giocatore vede quando gioca. </para>

<para
> il secondo tipo di immagini, <filename
>*-mask.png</filename
>, 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. </para>

<para
> Nella stessa directory, un file chiamato <filename
>layout.xml</filename
>. (<filename
>$KDEDIR/share/apps/ktuberling/pics/layout.xml</filename
>) 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 tra le maschere. Esso, infine, assegna i suoni agli oggetti e classifica gli oggetti in gruppi. Esso segue la sintassi XML standard (per i dettagli vedi <link linkend="layout-details"
>più avanti</link
>). </para>

<para
> Sempre nella stessa directory, un file chiamato <filename
>layout.i18n</filename
> (<filename
>$KDEDIR/share/apps/ktuberling/pics/layout.xml</filename
>) riporta le stringhe del file <filename
>layout.xml</filename
> che possono essere tradotte:  <itemizedlist
> <listitem
><para
>Le voci del menu che permettono di scegliere i piani di gioco</para
></listitem
> <listitem
><para
>i nomi delle categorie di oggetti</para
></listitem
> <listitem
><para
>I nomi dei file sonori. C'è un trucco di programmazione che permette ai team di traduttori di registrare la voce di qualcuno che dice i nomi degli oggetti nella loro lingua e di fare riferimento al nome di questi eventuali file sonori.</para
></listitem
> </itemizedlist
> </para>

<para
> In un'altra directory, un file chiamato <filename
>ktuberlingui.rc</filename
> (<filename
>$KDEDIR/share/apps/ktuberling/ktuberlingui.rc</filename
>) è un secondo file XML che descrive i menu di &ktuberling;. Dovrebbe contenere un <markup
>&lt;action&gt;</markup
> tag per ogni piano di gioco. Il nome simbolico dell'azione in questo file dovrà essere identico al nome simbolico dell'azione in <filename
>layout.xml</filename
>. </para>

</sect1>

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

<para
> Oltre all'abituale sistema dei file <literal role="extension"
>.po</literal
> per tradurre messaggi e richieste del programma, occorrerà localizzare anche i file sonori. </para>

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

<para
> 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: <screen>
<prompt
>$</prompt
> <userinput
>oggenc_rc3 -o <replaceable
>sound.ogg</replaceable
> <replaceable
>sound.wav</replaceable
></userinput>
</screen
> </para>

<para
> Le informazioni su come utilizzare i meccanismi di traduzione per &kde; sono disponibili nel <ulink url="http://i18n.kde.org/translation-howto/index.html"
>KDE Translation HOWTO</ulink
>. </para>

</sect1>

<sect1 id="for-programmers">

<title
>Per i programmatori</title>
<para
>Non è molto difficile per un programmatore estendere &ktuberling;.</para>

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

<variablelist
> <varlistentry
> <term
><classname
>TopLevel</classname
></term
> <listitem
> <para
>Gestione a alto livello della finestra e del programma base</para
> </listitem
> </varlistentry
> <varlistentry
> <term
><classname
>ToDraw</classname
></term
> <listitem
> <para
>Descrizione di uno degli <quote
>oggetti</quote
> grafici da disegnare.</para
> </listitem
> </varlistentry
> </variablelist>

</sect2>

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

<para
>Un file <literal role="extension"
>.tuberling</literal
> contiene tutti i dati necessari per ridisegnare un uomo-patata. Esso può essere modificato con un normale editor di testi.</para>

<para
>La prima riga contiene il numero progressivo della zona di ricreazione.</para>

<para
>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.</para>

</sect2>
</sect1>

<sect1 id="layout-details">
<title
>Struttura del file di formattazione (<filename
>layout.xml</filename
>)</title>

<para
> Il tag di livello superiore è unico e si chiama <markup
>&lt;ktuberling&gt;</markup
>. Esso contiene diversi tag <markup
>&lt;playground&gt;</markup
>, uno per ogni zona ricreativa. </para>

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

<para
> Il tag <markup
>&lt;menuitem&gt;</markup
> 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 <filename
>ktuberlingui.rc</filename
>. </para>

<para
> Il tag <markup
>&lt;editablearea&gt;</markup
> descrive la posizione della zona ricreativa dove si possono porre gli oggetti e il suono associato. </para>

<para
> Il tag <markup
>&lt;category&gt;</markup
> 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 <quote
>ornamenti</quote
>. </para>

<para
> Il tag <markup
>&lt;object&gt;</markup
> descrive la posizione (nel piano di gioco e nella maschera) di un oggetto e del suono inglese associato ad esso. </para>

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

</sect1>
</chapter>