# Referencia técnica

&ktuberling; ofrece una interesante y satisfactoria introducción a la personalización y programación de &kde;. Es posible extender la aplicación. Por ejemplo, sin necesidad de programar, se pueden añadir más zonas de juego cambiando los archivos de gráficos. ¡Añadiendo los archivos de sonido adecuados, los traductores pueden poner el audio en su propio idioma!

Si extiendes o añades algo al juego, piensa en enviar las mejoras al desarrollador Alex Fiestas para que las incluya en futuras versiones.

## Para los artistas

Para crear una zona de juego nueva en &ktuberling; debes hacer lo siguiente:

- Dibujar una zona de juego y guardarla en un archivo &SVG;, donde tienes que:

  - Llamar «background» a los lugares en los que los elementos se pueden arrastrar.

  - Dar un nombre único a cada uno de los elementos que se puedan arrastrar.

- Crear un archivo `.theme` siguiendo este esquema:

      <playground gameboard="tuArchivoSVG" name="elArchivoDeEscritorio">
          <object name="nombreDelElemento" sound="nombreDelSonido" scale="unValor" />
          …
          …
          …
          </playground>

  - `tuArchivoSVG` es el nombre del archivo &SVG; que contiene el dibujo.

  - `elArchivoDeEscritorio` es el nombre del archivo de escritorio que contiene el nombre del tema.

  - Necesitarás una entrada `<object>` para cada objeto. El `nombreDelElemento` es el nombre único que se usa en el archivo &SVG;; `nombreDelSonido` es el nombre del sonido que se reproducirá cuando se arrastre. Consulta el archivo `sounds/soundthemes.HOWTO` del código fuente para obtener más información.

  - `scale` es opcional y `unValor` es el factor de escala que se usará cuando se dibuje este objeto fuera del almacén; si no se indica, es 1.

- Crear un archivo `.desktop` siguiendo este esquema:

      [KTuberlingTheme]
      Name=nombreDelTema

  - El `nombreDelTema` es el nombre que identifica al tema. Se mostrará en el menú «Zona de juego».

- Si estás añadiendo el tema al repositorio de &ktuberling;, añade los archivos `.svg`, `.theme` y `.desktop` a la sección `FILES` de `CMakeLists.txt` en la carpeta `pics/`.

- Si deseas instalarlo para ti, sitúa los archivos `.svg`, `.theme` y `.desktop` en la carpeta `ktuberling/pics` de ``qtpaths` `--paths GenericDataLocation``

## Para los traductores

Además del mecanismo habitual de archivos `.po` para la traducción de los mensajes escritos del programa, también se pueden traducir los sonidos.

Para crear un nuevo tema de sonido para &ktuberling; debes hacer lo siguiente:

- Grabar los sonidos en un archivo con formato OGG Vorbis rc3.

- Crear un archivo ``códigoDeDosLetrasDeTuIdioma`.soundtheme`, según el siguiente esquema:

      <language code="códigoDeDosLetrasDeTuIdioma">
      <sound name="nombreDelSonido" file="rutaRelativa" />
      …
      …
      …
      </language>

  - El `códigoDeDosLetrasDeTuIdioma` es el código de dos letras de tu idioma (por ejemplo, gl para el gallego).

  - Para cada sonido necesitarás una entrada `<sound>`. `nombreDelSonido` debería coincidir con el nombreDelSonido indicado en el tema del juego (consulta el archivo `pics/themes.HOWTO` del código fuente). La `rutaRelativa` debe ser la ruta relativa al lugar donde se va a instalar el archivo con este sonido, que suele ser ``unaRutaÚnica`/`nombreDelSonido`.`formato`` (`unaRutaÚnica` puede ser, por ejemplo, el código de dos letras de tu idioma).

- Si estás añadiendo el tema de sonido a &ktuberling;: en la carpeta de tu idioma:

  - Añade los archivos de sonido y los archivos `.soundtheme` a la carpeta `data/kdegames/ktuberling` de las traducciones de tu idioma.

  - En este misma misma carpeta necesitarás un archivo `CMakeLists.txt` que describa cómo instalar los archivos. Suele ser:

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

- Si deseas instalarlo para ti:

  - Sitúa el archivo ``códigoDeDosLetrasDeTuIdioma`.soundtheme` en la carpeta `ktuberling/sounds` de ``qtpaths` `--paths GenericDataLocation``

  - Sitúa los archivos de sonido en la carpeta `ktuberling/sounds/`unaRutaÚnica`` de ``qtpaths` `--paths GenericDataLocation``

Dispones de información sobre el funcionamiento de los mecanismos de traducción de &kde; en El manual de traducción de &kde;.

## Para programadores

&ktuberling; resulta sencillo de extender por programadores.

### Clases C++

`TopLevel`

- Ventana de nivel principal y administración básica del programa.

`PlayGround`

- Descripción de uno de los niveles del juego.

`ToDraw`

- Descripción de uno de los «objetos» gráficos que se va a dibujar.

`SoundFactory`

- Descripción de uno de los idiomas y sus sonidos.

`Action`

- Una de las manipulaciones del usuario en la pila de deshacer/rehacer.