<chapter id="technical-reference">
<chapterinfo>

<authorgroup>
<author
><firstname
>Éric</firstname
> <surname
>Bischoff</surname
> </author>
<othercredit role="translator"
> <firstname
>Rafael</firstname
> <surname
>Osuna</surname
> <affiliation
><address
><email
>rosuna@wol.es</email
></address
></affiliation
> <contrib
>Traductor</contrib
> </othercredit
> <othercredit role="translator"
> <firstname
>Miguel</firstname
> <surname
>Revilla Rodríguez</surname
> <affiliation
><address
><email
>yo@miguelrevilla.com</email
></address
></affiliation
> <contrib
>Traductor</contrib
> </othercredit
> <othercredit role="translator"
> <firstname
>Kira</firstname
> <surname
>J. Fernández</surname
> <affiliation
><address
><email
>kirajfdez@gmail.com</email
></address
></affiliation
> <contrib
>Traductora</contrib
> </othercredit
> 
</authorgroup>

<date
>2021-10-04</date>
<releaseinfo
>KDE Gear 21.08</releaseinfo>

<keywordset>
<keyword
>KDE</keyword>
<keyword
>KTuberling</keyword>
<keyword
>referencia técnica</keyword>
</keywordset>
</chapterinfo>

<title
>Referencia técnica</title>

<para
>&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! </para>

<para
>Si extiendes o añades algo al juego, piensa en enviar las mejoras al desarrollador <ulink url="mailto:alex@eyeos.org"
>Alex Fiestas</ulink
> para que las incluya en futuras versiones. </para>

<sect1 id="for-artists">
<title
>Para los artistas</title>

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

<itemizedlist>
  <listitem>
    <para
>Dibujar una zona de juego y guardarla en un archivo &SVG;, donde tienes que: <itemizedlist>
        <listitem
><para
>Llamar «background» a los lugares en los que los elementos se pueden arrastrar.</para
></listitem>
        <listitem
><para
>Dar un nombre único a cada uno de los elementos que se puedan arrastrar.</para
></listitem>
      </itemizedlist>
    </para>
  </listitem>

  <listitem>
    <para
>Crear un archivo <literal role="extension"
>.theme</literal
> siguiendo este esquema:</para>
<programlisting
>&lt;playground gameboard="<replaceable
>tuArchivoSVG</replaceable
>" name="<replaceable
>elArchivoDeEscritorio</replaceable
>"&gt;
    &lt;object name="<replaceable
>nombreDelElemento</replaceable
>" sound="<replaceable
>nombreDelSonido</replaceable
>" scale="<replaceable
>unValor</replaceable
>" /&gt;
    …
    …
    …
    &lt;/playground&gt;
</programlisting>
    <itemizedlist>
      <listitem
><para
><replaceable
>tuArchivoSVG</replaceable
> es el nombre del archivo &SVG; que contiene el dibujo.</para
></listitem>
      <listitem
><para
><replaceable
>elArchivoDeEscritorio</replaceable
> es el nombre del archivo de escritorio que contiene el nombre del tema.</para
></listitem>
      <listitem
><para
>Necesitarás una entrada <literal
>&lt;object&gt;</literal
> para cada objeto. El <replaceable
>nombreDelElemento</replaceable
> es el nombre único que se usa en el archivo &SVG;; <replaceable
>nombreDelSonido</replaceable
> es el nombre del sonido que se reproducirá cuando se arrastre. Consulta el archivo <filename
>sounds/soundthemes.HOWTO</filename
> del código fuente para obtener más información.</para
></listitem>
      <listitem
><para
><literal
>scale</literal
> es opcional y <replaceable
>unValor</replaceable
> es el factor de escala que se usará cuando se dibuje este objeto fuera del almacén; si no se indica, es 1.</para
></listitem>
    </itemizedlist>
  </listitem>

  <listitem>
    <para
>Crear un archivo <literal role="extension"
>.desktop</literal
> siguiendo este esquema:</para>
<programlisting
>[KTuberlingTheme]
Name=<replaceable
>nombreDelTema</replaceable
>
</programlisting>
    <itemizedlist>
      <listitem
><para
>El <replaceable
>nombreDelTema</replaceable
> es el nombre que identifica al tema. Se mostrará en el menú «Zona de juego».</para
></listitem>
    </itemizedlist>
  </listitem>

  <listitem>
    <para
>Si estás añadiendo el tema al repositorio de &ktuberling;, añade los archivos <literal role="extension"
>.svg</literal
>, <literal role="extension"
>.theme</literal
> y <literal role="extension"
>.desktop</literal
> a la sección <literal
>FILES</literal
> de <filename
>CMakeLists.txt</filename
> en la carpeta <filename class="directory"
>pics/</filename
>. </para>
  </listitem>

  <listitem>
    <para
>Si deseas instalarlo para ti, sitúa los archivos <literal role="extension"
>.svg</literal
>, <literal role="extension"
>.theme</literal
> y <literal role="extension"
>.desktop</literal
> en la carpeta <filename class="directory"
>ktuberling/pics</filename
> de <userinput
><command
>qtpaths</command
> <option
>--paths GenericDataLocation</option
></userinput
> </para>
  </listitem>
</itemizedlist>

</sect1>

<sect1 id="for-translators">
<title
>Para los traductores</title>

<para
>Además del mecanismo habitual de archivos <literal role="extension"
>.po</literal
> para la traducción de los mensajes escritos del programa, también se pueden traducir los sonidos. </para>

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

<itemizedlist>
  <listitem
><para
>Grabar los sonidos en un archivo con formato OGG Vorbis rc3.</para
></listitem>
  <listitem
><para
>Crear un archivo <filename
><replaceable
>códigoDeDosLetrasDeTuIdioma</replaceable
>.soundtheme</filename
>, según el siguiente esquema:</para>
<programlisting
>&lt;language code="<replaceable
>códigoDeDosLetrasDeTuIdioma</replaceable
>"&gt;
&lt;sound name="<replaceable
>nombreDelSonido</replaceable
>" file="<replaceable
>rutaRelativa</replaceable
>" /&gt;
…
…
…
&lt;/language&gt;
</programlisting>
    <itemizedlist>
      <listitem
><para
>El <replaceable
>códigoDeDosLetrasDeTuIdioma</replaceable
> es el código de dos letras de tu idioma (por ejemplo, gl para el gallego).</para
></listitem>
      <listitem
><para
>Para cada sonido necesitarás una entrada <literal
>&lt;sound&gt;</literal
>. <replaceable
>nombreDelSonido</replaceable
> debería coincidir con el nombreDelSonido indicado en el tema del juego (consulta el archivo <filename
>pics/themes.HOWTO</filename
> del código fuente). La <replaceable
>rutaRelativa</replaceable
> debe ser la ruta relativa al lugar donde se va a instalar el archivo con este sonido, que suele ser <filename
><replaceable
>unaRutaÚnica</replaceable
>/<replaceable
>nombreDelSonido</replaceable
>.<replaceable
>formato</replaceable
></filename
> (<replaceable
>unaRutaÚnica</replaceable
> puede ser, por ejemplo, el código de dos letras de tu idioma).</para
></listitem>
    </itemizedlist>
  </listitem>

  <listitem
><para
>Si estás añadiendo el tema de sonido a &ktuberling;: en la carpeta de tu idioma:</para>
    <itemizedlist>
      <listitem
><para
>Añade los archivos de sonido y los archivos <literal role="extension"
>.soundtheme</literal
> a la carpeta <filename class="directory"
>data/kdegames/ktuberling</filename
> de las traducciones de tu idioma.</para
></listitem>
      <listitem
><para
>En este misma misma carpeta necesitarás un archivo <filename
>CMakeLists.txt</filename
> que describa cómo instalar los archivos. Suele ser:</para>
<!--FIXME l10n-kf5/*/data/kdegames/ktuberling/CMakeLists.txt has DATA_INSTALL_DIR, has this to be changed?-->
<programlisting
>FILE( GLOB oggfiles *.ogg )
INSTALL( FILES ${oggfiles} DESTINATION ${KDE_INSTALL_DATADIR}/ktuberling/sounds/<replaceable
>códigoDeDosLetrasDeTuIdioma</replaceable
> )
INSTALL( FILES <replaceable
>códigoDeDosLetrasDeTuIdioma</replaceable
>.soundtheme DESTINATION ${KDE_INSTALL_DATADIR}/ktuberling/sounds/ )
</programlisting>
      </listitem>
    </itemizedlist>
  </listitem>

  <listitem
><para
>Si deseas instalarlo para ti:</para>
    <itemizedlist>
      <listitem
><para
>Sitúa el archivo <filename
><replaceable
>códigoDeDosLetrasDeTuIdioma</replaceable
>.soundtheme</filename
> en la carpeta <filename class="directory"
>ktuberling/sounds</filename
> de <userinput
><command
>qtpaths</command
> <option
>--paths GenericDataLocation</option
></userinput
></para
></listitem>
      <listitem
><para
>Sitúa los archivos de sonido en la carpeta <filename class="directory"
>ktuberling/sounds/<replaceable
>unaRutaÚnica</replaceable
></filename
> de <userinput
><command
>qtpaths</command
> <option
>--paths GenericDataLocation </option
></userinput
></para
></listitem>
    </itemizedlist>
  </listitem>
</itemizedlist>

<para
>Dispones de información sobre el funcionamiento de los mecanismos de traducción de &kde; en <ulink url="https://i18n.kde.org/translation-howto/index.html"
>El manual de traducción de &kde;</ulink
>. </para>

</sect1>

<sect1 id="for-programmers">

<title
>Para programadores</title>
<para
>&ktuberling; resulta sencillo de extender por programadores.</para>

<sect2 id="classes">
<title
>Clases C++</title>

<variablelist>
  <varlistentry>
    <term
><classname
>TopLevel</classname
></term>
    <listitem
><para
>Ventana de nivel principal y administración básica del programa.</para
></listitem>
  </varlistentry>

  <varlistentry>
    <term
><classname
>PlayGround</classname
></term>
    <listitem
><para
>Descripción de uno de los niveles del juego.</para
></listitem>
  </varlistentry>

  <varlistentry>
    <term
><classname
>ToDraw</classname
></term>
    <listitem
><para
>Descripción de uno de los «objetos» gráficos que se va a dibujar.</para
></listitem>
  </varlistentry>

  <varlistentry>
    <term
><classname
>SoundFactory</classname
></term>
    <listitem
><para
>Descripción de uno de los idiomas y sus sonidos.</para
></listitem>
  </varlistentry>

  <varlistentry>
    <term
><classname
>Action</classname
></term>
    <listitem
><para
>Una de las manipulaciones del usuario en la pila de deshacer/rehacer.</para
></listitem>
  </varlistentry>
</variablelist>

</sect2>

</sect1>
</chapter>
