Éric
Bischoff
Andrea
Celli

    andrea.celli@libero.it

Traduzione della documentazione tecnica
2016-05-11
1.0.0 (Applications 16.04)
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 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 del file CMakeLists.txt nella cartella pics/

- Se vuoi installarlo per te stesso, copia i file .svg, .theme e .desktop in `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 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 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 Codice2LettereXTuaLingua.soundtheme file in `ktuberling/sounds` in ``qtpaths` `--paths GenericDataLocation``

  - Copia i tuoi file audio in `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