<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> 
</authorgroup>
<date>2006-05-05</date> <releaseinfo>0.05.01</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 extiende o añade algo al juego, por favor considere enviar sus mejoras al desarrollador <ulink url="mailto:ebischoff@nerim.net">Éric Bischoff</ulink> para su inclusión en versiones futuras. </para>

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

<para>Es posible cambiar el tamaño y la forma de la zona de juego, así como el número de objetos. Se pueden añadir nuevas zonas de juego. Únicamente son necesarios dos archivos gráficos para cada zona de juego: la zona propiamente dicha y un archivo de máscara. Se permite un máximo de 8 zonas de juegos, de las cuales, en la actualidad, se utilizan 3. </para>

<para>En &ktuberling; se utilizan seis imágenes: <filename>potato-game.png</filename>, <filename>potato-mask.png</filename>, <filename>penguin-game.png</filename>, <filename>penguin-mask.png</filename>, <filename>aquarium-game.png</filename> y <filename>aquarium-mask.png</filename>. La ubicación normal de estos archivos es la carpeta <filename class="directory">$TDEDIR/share/apps/ktuberling/pics/</filename>. </para>

<para>El primer tipo de imágenes, <filename>*-game.png</filename> contiene la zona de juego y los objetos que puede seleccionar el usuario. Este es el gráfico que se ve durante el desarrollo del juego. </para>

<para>El segundo tipo de imágenes, <filename>*-mask.png</filename>, contiene únicamente las máscaras de los objetos. Las máscaras se utilizan para delimitar los bordes de los objetos y, en algunos casos, para darle al objeto algo de transparencia (por ejemplo, los anteojos). Es obligatorio que los objetos estén en la misma posición en ambos archivos gráficos. </para>

<para>En la misma carpeta, un archivo llamado <filename>layout.xml</filename>. (<filename>$TDEDIR/share/apps/ktuberling/pics/layout.xml</filename>) indica qué imágenes hay que utilizar y las enlaza a las entradas de menú. También contiene los parámetros de posición de la zona de juego y de los objetos y las máscaras. Asigna los sonidos a grupos de objetos y posiciones. Finalmente declara los idiomas para los que están traducidos los sonidos. Sigue la sintáxis estándar de XML (vea más detalles <link linkend="layout-details">a continuación</link>). </para>

<para>También en la misma carpeta, un archivo llamado <filename>layout.i18n</filename> (<filename>$TDEDIR/share/apps/ktuberling/pics/layout.xml</filename>) reune las cadenas de <filename>layout.xml</filename> que pueden ser traducidas: <itemizedlist>
<listitem><para>Las entradas de menú que permiten elegir la zona de juego y el idioma</para></listitem>
<listitem><para>Los nombres de las categorías de objetos</para></listitem>
</itemizedlist>
</para>

<para>En la carpeta inmediatamente superior, un archivo llamado <filename>ktuberlingui.rc</filename> (<filename>$TDEDIR/share/apps/ktuberling/ktuberlingui.rc</filename>) es un segundo archivo &XML; que describe los menús de &ktuberling;. Debería contener una etiqueta <markup>&lt;action&gt;</markup> por cada zona de juego y por cada idioma. El nombre simbólico de la acción en este archivo debería ser idéntico al nombre de la acción en <filename>layout.xml</filename>. </para>

</sect1>

<sect1 id="for-translators">
<title>Traducción</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 es posible traducir los sonidos. </para>

<para>Si los distintos traductores puede grabar su voz en un archivo <literal role="extension">.wav</literal>, pueden almacenar ese archivo en la carpeta de cada idioma dependiente de la carpeta de sonidos. El nombre de los sonidos se asigna en el archivo <filename>layout.xml</filename>. Por ejemplo, si el idioma de destino es el español, los traductores pueden grabar su voz en archivos <literal role="extension">.wav</literal> que se ubican en <filename>$TDEDIR/share/apps/ktuberling/sounds/es</filename>. Después pueden asignar el sonido llamado «hat» al archivo <filename>es/sombrero.wav</filename>. </para>

<para>En el futuro, &ktuberling; utilizará archivos OGG Vorbis para los sonidos. En ese momento, será posible convertir los archivos WAV en OGG Vorbis por medio de la siguiente línea de órdenes: <screen><prompt>$</prompt> <userinput>oggenc -q 10 -o <replaceable>sonido.ogg</replaceable> <replaceable>sonido.wav</replaceable></userinput>
</screen>
</para>

<para>Si quiere información sobre el funcionamiento de los mecanismos de traducción de &kde;, la encontrará disponible en <ulink url="http://i18n.kde.org/translation-howto/index.html">The Translation HOWTO</ulink> y en <ulink url="http://kurly.org/kde">la traducción de &kde; al español</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 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 deshacer/rehacer.</para> </listitem>
</varlistentry>
</variablelist>

</sect2>

<sect2 id="files-structure">
<title>Estructura de los archivos <literal role="extension">.tuberling</literal></title>

<para>Un archivo <literal role="extension">.tuberling</literal> contiene toda la información necesaria para reproducir el dibujo original. Puede ser editado con un editor de textos estándar.</para>

<para>La primera línea contiene en número de la zona de juego.</para>

<para>En el resto de las líneas hay un objeto gráfico por línea, en el orden en que se dibujaron. Cada línea contiene 5 números: el identificador del objeto, y el rectángulo en el que debe ser dibujado (izquierda, arriba, derecha, abajo). Los números están separados por espacios en blanco.</para>

</sect2>
</sect1>

<sect1 id="layout-details">
<title>Estructura del archivo de disposiciones (<filename>layout.xml</filename>)</title>

<para>La etiqueta de primer nivel es única y se llama <markup>&lt;ktuberling&gt;</markup>. Contiene varias etiquetas <markup>&lt;playground&gt;</markup>, una por cada zona de juego, y varias etiquetas <markup>&lt;language&gt;</markup>, una por idioma. </para>

<para>La etiqueta <markup>&lt;playground&gt;</markup> tiene dos atributos: <markup>gameboard</markup> y <markup>masks</markup>. Estos atributos nombran los archivos que contienen las imágenes. La etiqueta <markup>&lt;playground&gt;</markup> también contiene una etiqueta <markup>&lt;menuitem&gt;</markup>, una etiqueta <markup>&lt;editablearea&gt;</markup>, varias etiquetas <markup>&lt;category&gt;</markup> y varias etiquetas <markup>&lt;object&gt;</markup>. </para>

<para>La etiqueta <markup>&lt;menuitem&gt;</markup> describe el identificador de acción del elemento de menú que permite seleccionar la posición del área en la que se pueden colocar los objetos y la etiqueta de este elemento de menú. El identificar de acción debe ser idéntico al del <filename>ktuberlingui.rc</filename>. </para>

<para>La etiqueta <markup>&lt;editablearea&gt;</markup> describe la posición del área en la que se pueden colocar los objetos y el nombre del sonido asociado con ella. </para>

<para>La etiqueta <markup>&lt;category&gt;</markup> describe la posición y la etiqueta de un texto que describe un grupo de objetos. Por ejemplo, puede describir la posición y el texto del grupo de «orejas». </para>

<para>La etiqueta <markup>&lt;object&gt;</markup> describe la posición (en la zona de juego y en las máscaras) de un objeto, así como el nombre del sonido asociado con él. </para>

<para>La etiqueta <markup>&lt;language&gt;</markup> tiene un atributo: <markup>code</markup>. Este atributo indica el código de identificación del idioma. La etiqueta <markup>&lt;language&gt;</markup> también contiene la etiqueta <markup>&lt;menuitem&gt;</markup> y varias etiquetas <markup>&lt;sound&gt;</markup>. </para>

<para>Las etiquetas de más bajo nivel no están descritas aquí, ya que su significado es fácilmente deducible. Si modifica <filename>layout.xml</filename>, no olvide modificar también <filename>layout.i18n</filename> y <filename>ktuberlingui.rc</filename> de forma coherente. </para>

</sect1>
</chapter>
