# 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 paragrafo sui temi sonori 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 di pics/CMakeLists.txt.

- Se vuoi installarlo da solo, metti i file .svg .theme .desktop in `kde4-config --prefix`/share/apps/ktuberling/pics

## 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 l'HOWTO dei temi). `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 2 lettere della tua lingua).

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

  - aggiungi i file audio e i file .soundtheme nella directory data/kdegames/ktuberling delle traduzioni della tua lingua.

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

        FILE(GLOB datafiles *.ogg)
        install( FILES ${datafiles} DESTINATION ${DATA_INSTALL_DIR}/ktuberling/sounds/Codice2LettereXTuaLingua )
        install( FILES Codice2LettereXTuaLingua.soundtheme DESTINATION ${DATA_INSTALL_DIR}/ktuberling/sounds/ )

- Se vuoi installarlo per te stesso:

  - Metti il file `Codice2LettereXTuaLingua`.soundtheme in `kde4-config --prefix`/share/apps/ktuberling/sounds

  - Metti TuoiFileSuono in `kde4-config --prefix`/share/apps/ktuberling/sounds/PercorsoUnivoco

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