<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-04-10</date> <releaseinfo >0.03.02</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 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. </para> <para > In &ktuberling; ci sono sei file grafici: <filename >potato-game.png</filename >, <filename >potato-mask.png</filename >, <filename >penguin-game.png</filename >, <filename >penguin-mask.png</filename >, <filename >aquarium-game.png</filename > e <filename >aquarium-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 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 <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 e la lingua</para ></listitem > <listitem ><para >i nomi delle categorie di oggetti</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 ><action></markup > 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 <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 un 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 >Zona ricreativa</classname ></term > <listitem > <para >Descrizione di uno dei livelli di gioco</para > </listitem > </varlistentry > <varlistentry > <term ><classname >Disegnare</classname ></term > <listitem > <para >Descrizione di uno degli <quote >oggetti</quote > grafici da disegnare.</para > </listitem > </varlistentry > <varlistentry > <term ><classname >Laboratorio sonoro</classname ></term > <listitem > <para >Descrizione di una lingua e dei suoi suoni</para > </listitem > </varlistentry > <varlistentry > <term ><classname >Azione</classname ></term > <listitem > <para >Una delle manipolazioni dell'utente sullo stack annulla/rifai</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 ><ktuberling></markup >. Esso contiene diversi tag del tipo<markup ><playground></markup >, uno per ogni zona ricreativa, e del tipo <markup ><language></markup > tags, uno per ogni lingua. </para> <para > Il tag <markup ><playground></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 ><playground></markup > contiene anche un tag <markup ><menuitem></markup >, un tag <markup ><editablearea></markup >, diversi tag <markup ><category></markup > e diversi tag <markup ><object></markup >. </para> <para > Il tag <markup ><menuitem></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 ><editablearea></markup > descrive la posizione della zona ricreativa dove si possono porre gli oggetti e il nome del suono associato. </para> <para > Il tag <markup ><category></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 ><object></markup > descrive la posizione (nel piano di gioco e nella maschera) di un oggetto e del suono associato ad esso. </para> <para > Il tag <markup ><playground></markup > ha un attributo: <markup >code</markup >. Questo attributo assegna il codice per la localizzazione di quel linguaggio. Il tag <markup ><playground></markup > contiene anche un tag <markup ><menuitem></markup > e diversi tag <markup ><sound></markup >. </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>