tde-i18n/tde-i18n-pt/docs/tdegames/ktuberling/technical-reference.docbook

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

<authorgroup>
<author><firstname>Éric</firstname> <surname>Bischoff</surname> </author>
<othercredit role="translator"><firstname>José</firstname><surname>Pires</surname><affiliation><address><email>jncp@netcabo.pt</email></address></affiliation><contrib>Tradução</contrib></othercredit> 
</authorgroup>
<date>2002-04-10</date> <releaseinfo>0.03.02</releaseinfo> <keywordset>
<keyword>KDE</keyword>
<keyword>Homem Batata</keyword>
<keyword>referência técnica</keyword>
</keywordset>
</chapterinfo>

<title>Referência técnica</title>

<para>O &ktuberling; oferece uma forma gentil e compensadora de introduzir à personalização e programação do &kde;. A aplicação pode ser extendida. Por exemplo, sem qualquer codificação, poderão ser adicionados novos recreios, alterando os ficheiros gráficos. Ao adicionar os ficheiros de som apropriados, os tradutores poderão alterar os sons para a sua língua-mãe! </para>

<para>Se extender ou adicionar ao jogo, por favor pense na hipótese de enviar as suas adições ao programador <ulink url="mailto:ebischoff@nerim.net">Éric Bischoff</ulink> de modo a inclui-las nas próximas versões. </para>

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

<para>O tamanho e a forma do recreio, assim como o número de objectos, poderão ser alterados. Poderão ser adicionados novos recreios. Só é preciso criar dois ficheiros de imagens para cada recreio: um tabuleiro de jogo e uma máscara. É permitido um máximo de 8 recreios, dos quais estão usados 3 neste momento. </para>

<para>São usadas seis imagens no &ktuberling;: <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> e <filename>aquarium-mask.png</filename>. A localização normal destes ficheiros é a pasta <filename class="directory">$TDEDIR/share/apps/ktuberling/pics/</filename>. </para>

<para>O primeiro tipo de imagens, os <filename>*-game.png</filename> contém o tabuleiro e os objectos que o utilizador selecciona. Este é o gráfico que o utilizador vê enquanto joga. </para>

<para>O segundo tipo de imagens, os <filename>*-mask.png</filename>, contêm apenas as máscaras dos objectos. Estas máscaras são usadas para delimitar os contornos dos objectos e, em alguns casos, dão ao objecto alguma transferência (por exemplo, os espectáculo). É obrigatório pôr os objectos na mesma posição, tanto no ficheiro do tabuleiro como no da máscara. </para>

<para>Na mesma pasta, um ficheiro chamado <filename>layout.xml</filename>. (<filename>$TDEDIR/share/apps/ktuberling/pics/layout.xml</filename>) indica quais as imagens a usar e associa-os aos itens do menu. Contém também os parâmetros de posição do recreio e dos objectos no tabuleiro e nas máscaras. Ele atribui também os sons aos objectos e coloca os objectos em grupos. Finalmente, declara as línguas como sendo conjuntos de sons traduzidos. Este ficheiro segue a sintaxe-padrão do &XML; (ver os detalhes <link linkend="layout-details">em baixo</link>). </para>

<para>Ainda na mesma pasta, existe um ficheiro chamado <filename>layout.i18n</filename> (<filename>$TDEDIR/share/apps/ktuberling/pics/layout.i18n</filename>) que recapitula os textos no <filename>layout.xml</filename> que podem ser traduzidos: <itemizedlist>
<listitem><para>As entradas de menu que lhe permitem escolher o recreio e a língua</para></listitem>
<listitem><para>Os nomes das categorias de objectos</para></listitem>
</itemizedlist>
</para>

<para>Uma pasta mais acima, existe um ficheiro chamado <filename>ktuberlingui.rc</filename> (<filename>$TDEDIR/share/apps/ktuberling/ktuberlingui.rc</filename>), o qual é um segundo ficheiro &XML; que descreve os menus do &ktuberling;. Ele deverá conter uma marca <markup>&lt;action&gt;</markup> por cada recreio e língua. O nome simbólico da acção neste ficheiro deverá ser idêntico ao nome simbólico da acção no <filename>layout.xml</filename>. </para>

</sect1>

<sect1 id="for-translators">
<title>Tradução</title>

<para>Para além do mecanismo normal dos ficheiros <literal role="extension">.po</literal> para traduzir os textos do programa e as mensagens, os sons também poderão ser localizados. </para>

<para>Se os vários tradutores puderem gravar a sua voz para um ficheiro <literal role="extension">.wav</literal>, eles poderão gravar esse ficheiro para a subpasta específica da língua da pasta de sons. O nome do som é então atribuído a um ficheiro no ficheiro <filename>layout.xml</filename>. Por exemplo, se a língua de destino é o Português, os tradutores poderão gravar a sua voz para os ficheiros <literal role="extension">.wav</literal> localizados na pasta <filename>$TDEDIR/share/apps/ktuberling/sounds/pt</filename>. Aí, eles poderão então atribuir o som chamado <quote>hat</quote> ao nome do ficheiro <filename>pt/chapeu.wav</filename>. </para>

<para>Numa versão futura, o &ktuberling; irá usar o formato de ficheiros OGG Vorbis rc3 para os sons. Nessa altura, será possível converter os ficheiros WAV para o OGG Vorbis rc3 através da seguinte linha de comandos: <screen><prompt>$</prompt> <userinput>oggenc -q 10 -o <replaceable>som.ogg</replaceable> <replaceable>som.wav</replaceable></userinput>
</screen>
</para>

<para>A informação sobre como lidar com os mecanismos de tradução no &kde; está disponível no <ulink url="http://i18n.kde.org/translation-howto/index.html">HOWTO de Traduções do &kde;</ulink>. </para>

</sect1>

<sect1 id="for-programmers">

<title>Para programadores</title>
<para>Não é difícil aos programadores extenderem o &ktuberling;.</para>

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

<variablelist>
<varlistentry>
<term><classname>TopLevel</classname></term>
<listitem>
<para>Janela de topo e gestão básica do programa</para>
</listitem>
</varlistentry>

<varlistentry>
<term><classname>PlayGround</classname></term>
<listitem>
<para>Descrição de um dos níveis de jogo</para> </listitem>
</varlistentry>

<varlistentry>
<term><classname>ToDraw</classname></term>
<listitem>
<para>Uma descrição de um dos <quote>objectos</quote> gráficos a serem desenhados</para> </listitem>
</varlistentry>

<varlistentry>
<term><classname>SoundFactory</classname></term>
<listitem>
<para>Descrição de uma das línguas e dos seus sons</para> </listitem>
</varlistentry>

<varlistentry>
<term><classname>Action</classname></term>
<listitem>
<para>Uma das acções do utilizador na minha de desfazer/refazer.</para> </listitem>
</varlistentry>
</variablelist>

</sect2>

<sect2 id="files-structure">
<title>Estrutura dos ficheiros <literal role="extension">.tuberling</literal></title>

<para>Um ficheiro <literal role="extension">.tuberling</literal> que contém todos os dados necessários para desenhar um boneco. Este poderá ser editado com um editor de texto normal.</para>

<para>A primeira linha contém o número do recreio.</para>

<para>Em todas as outras linhas, existe um objecto gráfico por linha, na ordem que é usada para os desenhar. Cada linha contém 5 números: o identificador do objecto e o rectângulo onde deverá ser desenhado (esquerda, cima, direita, baixo). Os números são separados por espaços.</para>

</sect2>
</sect1>

<sect1 id="layout-details">
<title>Estrutura do ficheiro de disposição (<filename>layout.xml</filename>)</title>

<para>A marca do nível de topo é única e chama-se <markup>&lt;ktuberling&gt;</markup>. Ela contém várias marcas <markup>&lt;playground&gt;</markup>, uma por cada recreio, bem como várias marcas <markup>&lt;language&gt;</markup>, uma para cada língua. </para>

<para>A marca <markup>&lt;playground&gt;</markup> tem dois atributos: o <markup>gameboard</markup> e o <markup>masks</markup>. Estes atributos contêm os nomes dos ficheiros que contêm as imagens. A marca <markup>&lt;playground&gt;</markup> também contém uma marca <markup>&lt;menuitem&gt;</markup>, uma <markup>&lt;editablearea&gt;</markup> e várias marcas <markup>&lt;category&gt;</markup>, tendo ainda várias marcas <markup>&lt;object&gt;</markup>. </para>

<para>A marca <markup>&lt;menuitem&gt;</markup> descreve o identificador da acção do item do menu que permite seleccionar a posição da área onde poderá largar os objectos, assim como a legenda deste item do menu. Este identificador de acção deverá ser idêntico ao do <filename>ktuberlingui.rc</filename>. </para>

<para>A marca <markup>&lt;editablearea&gt;</markup> descreve a posição da área onde você poderá largar os objectos, bem como o nome do som associado a ele. </para>

<para>A marca <markup>&lt;category&gt;</markup> descreve a posição e o texto que descreve um grupo de objectos. Por exemplo, ela pode descrever a posição e o texto do grupo <quote>diversos</quote>. </para>

<para>A marca <markup>&lt;object&gt;</markup> descreve a posição (no tabuleiro e nas máscaras) de um objecto, assim como o nome do som associado a ele. </para>

<para>A marca <markup>&lt;language&gt;</markup> tem um atributo: o <markup>code</markup>. Este atributo dá o código da localização para essa língua. A marca <markup>&lt;language&gt;</markup> também contém uma marca <markup>&lt;menuitem&gt;</markup> tag e várias <markup>&lt;sound&gt;</markup>. </para>

<para>As marcas de nível inferior não são aqui explicadas, dado que o seu significado é bastante intuitivo. Se você modificar o ficheiro <filename>layout.xml</filename>, não se esqueça de modificar o <filename>layout.i18n</filename> e o <filename>ktuberlingui.rc</filename> na mesma medida. </para>

</sect1>
</chapter>