# 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 crei estensioni o aggiunte al gioco, considera l'idea di inviare i tuoi contributi allo sviluppatore Alex Fiestas affinché possa includerli nelle prossime versioni.

## Per i disegnatori

Per creare una nuova scena di &ktuberling; devi:

- Disegnare lo sfondo in formato &SVG;, per farlo dovrai:

  - Dare un nome al punto dove gli oggetti possono essere trascinati sullo sfondo.

  - Dare un nome univoco a tutti gli oggetti trascinabili.

- Creare un file `.theme`. Che deve rispettare questo schema:

      <playground gameboard="TuoFileSVG" name="IlFileDesktop">
          <object name="NomeOggetto" sound="NomeSuono" scale="ValoreOpportuno" />
          ...
          ...
          ...
          </playground>

  - `TuoFileSVG` è il nome del file &SVG; che contiene il disegno.

  - `IlFileDesktop` è il nome del file del desktop che ha il nome del tema.

  - Per ogni oggetto ti serve una voce `<object>`. `NomeOggetto` è il nome univoco che hai usato nel file &SVG;, `NomeSuono` è la voce che si sente quando trascini l'oggetto. Vedi il file `sounds/soundthemes.HOWTO` presente nel codice sorgente per maggiori informazioni.

  - `scale` è opzionale e `ValoreOpportuno` è il fattore di scala che viene applicato all'oggetto quando viene trascinato fuori dal deposito. Se non è specificato, sarà 1.

- Per creare un file `.desktop` bisogna seguire questo schema:

      [KTuberlingTheme]
      Name=NomeTema

  - `NomeTema` è il nome che identifica il tema. Verrà mostrato nel menu Scena.

- Se vuoi aggiungere il tuo tema nel deposito di &ktuberling;, devi aggiungere i file `.svg`, `.theme` e `.desktop` alla sezione `FILES` del file `CMakeLists.txt` nella cartella `pics/`.

- Se vuoi installarlo per te stesso, copia i file `.svg`, `.theme` e `.desktop` all'interno della cartella `ktuberling/pics` in ``qtpaths` `--paths GenericDataLocation``

## Per i traduttori

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

Per creare un nuovo tema sonoro per &ktuberling; devi:

- Registrare i suoni su file con formato OGG Vorbis rc3.

- Creare un file ``Codice2LettereXTuaLingua``. soundtheme file, che deve avere questo schema:

      <language code="Codice2LettereXTuaLingua">
      <sound name="NomeSuono" file="PercorsoRelativo" />
      ...
      ...
      ...
      </language>

  - `Codice2LettereXTuaLingua` è il codice in due lettere che individua la tua lingua, ad esempio "it" per italiano.

  - Per ogni suono serve una riga `<sound>`. `NomeSuono` deve corrispondere al NomeSuono specificato nel tema della scena (vedi `pics/themes.HOWTO` dal codice sorgente). `PercorsoRelativo` deve essere il percorso relativo da seguire per trovare dove è installato il file con questo suono. Tipicamente sarà ``QualcosaDiUnivoco`/`NomeSuono`.`formato`` (ad esempio, `QualcosaDiUnivoco` potrebbe essere il codice di due lettere della tua lingua).

- Se vuoi aggiungere il tuo tema sonoro a &ktuberling;:

  - Aggiungi i file audio e i file `.soundtheme` nella cartella `data/kdegames/ktuberling` delle traduzioni della tua lingua.

  - Proprio in questa cartella dovrai creare un file `CMakeLists.txt` che indica come installare i file. La sua forma tipica è:

        FILE( GLOB oggfiles *.ogg )
        INSTALL( FILES ${oggfiles} DESTINATION ${KDE_INSTALL_DATADIR}/ktuberling/sounds/Codice2LettereXTuaLingua )
        INSTALL( FILES Codice2LettereXTuaLingua.soundtheme DESTINATION ${KDE_INSTALL_DATADIR}/ktuberling/sounds/ )

- Se vuoi installarlo per te stesso:

  - Copia il file ``Codice2LettereXTuaLingua`.soundtheme` nella cartella `ktuberling/sounds` in ``qtpaths` `--paths GenericDataLocation``

  - Copia i tuoi file audio nella cartella `ktuberling/sounds/`unPercorsoUnivoco`` in ``qtpaths` `--paths GenericDataLocation``

Le informazioni su come utilizzare i meccanismi di traduzione per &kde; sono disponibili su The &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.