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

<authorgroup>
<author
><firstname
>Eric</firstname
> <surname
>Bischoff</surname
> </author>
<othercredit role="translator"
><firstname
>Marcus</firstname
><surname
>Gama</surname
><affiliation
><address
><email
>marcus_gama@uol.com.br</email
></address
></affiliation
><contrib
>Tradução</contrib
></othercredit
> 
</authorgroup>
<date
>10-04-2002</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;. O aplicativo pode ser extendido. Por exemplo, sem qualquer codificação, poderão ser adicionados novas áreas de jogo, alterando os arquivos gráficos. Ao adicionar os arquivos de som apropriados, os tradutores poderão alterar os sons para o seu idioma nativo! </para>

<para
>Se você extender ou adicionar ao jogo, por favor considere a possibilidade de enviar as suas adições ao programador <ulink url="mailto:e.bischoff@noos.fr"
>Eric Bischoff</ulink
> de modo a incluí-las nas próximas versões. </para>

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

<para
>O tamanho e a forma da área de jogo, assim como o número de objetos, poderão ser alterados. Poderão ser adicionadas novas áreas de jogos. Só é preciso criar dois arquivos de imagens para cada área de jogo: um tabuleiro de jogo e uma máscara. É permitido um máximo de 8 áreas de jogos, das quais 3 estão sendo usadas atualmente. </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 padrão destes arquivos é a pasta <filename class="directory"
>$KDEDIR/share/apps/ktuberling/pics/</filename
>. </para>

<para
>O primeiro tipo de imagem, os <filename
>*-game.png</filename
> contém o tabuleiro e os objetos que o usuário seleciona. Este é o gráfico que o usuário vê enquanto joga. </para>

<para
>O segundo tipo de imagens, os <filename
>*-mask.png</filename
>, contém apenas as máscaras dos objetos. Estas máscaras são usadas para delimitar os contornos dos objetos e, em alguns casos, dão ao objeto alguma transparência (por exemplo, os espetáculos). É obrigatório colocar os objetos na mesma posição, tanto no arquivo do tabuleiro como no da máscara. </para>

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

<para
>Ainda na mesma pasta existe um arquivo chamado <filename
>layout.i18n</filename
> (<filename
>$KDEDIR/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 a área de jogo e o idioma</para
></listitem>
<listitem
><para
>Os nomes das categorias de objetos</para
></listitem>
</itemizedlist>
</para>

<para
>Uma pasta mais acima, existe um arquivo chamado <filename
>ktuberlingui.rc</filename
> (<filename
>$KDEDIR/share/apps/ktuberling/ktuberlingui.rc</filename
>), que é um segundo arquivo XML que descreve os menus do &ktuberling;. Ele deverá conter uma marca <markup
>&lt;action&gt;</markup
> para cada área de jogo e idioma. O nome simbólico da ação neste arquivo deverá ser idêntico ao nome simbólico da ação no <filename
>layout.xml</filename
>. </para>

</sect1>

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

<para
>Além do mecanismo normal dos arquivos <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 arquivo <literal role="extension"
>.wav</literal
>, eles poderão gravar esse arquivo para a sub-pasta específica do idioma da pasta de sons. O nome do som é então atribuído a um arquivo no arquivo <filename
>layout.xml</filename
>. Por exemplo, se a idioma de destino é o Português do Brasil, os tradutores poderão gravar a sua voz para os arquivos <literal role="extension"
>.wav</literal
> localizados na pasta <filename
>$KDEDIR/share/apps/ktuberling/sounds/pt_BR</filename
>. Então, eles poderão então atribuir o som chamado <quote
>hat</quote
> ao nome do arquivo <filename
>pt_BR/chapeu.wav</filename
>. </para>

<para
>Numa versão futura, o &ktuberling; irá usar o formato de arquivos OGG Vorbis rc3 para os sons. Atualmente, será possível converter os arquivos WAV para o OGG Vorbis rc3 através da seguinte linha de comando: <screen
><prompt
>$</prompt
> <userinput
>oggenc_rc3 -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 gerenciamento básico 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
>objetos</quote
> gráficos a serem desenhados</para
> </listitem>
</varlistentry>

<varlistentry>
<term
><classname
>SoundFactory</classname
></term>
<listitem>
<para
>Descrição de um dos idiomas e dos seus sons</para
> </listitem>
</varlistentry>

<varlistentry>
<term
><classname
>Action</classname
></term>
<listitem>
<para
>Uma das ações do usuário na pilha de desfazer/refazer.</para
> </listitem>
</varlistentry>
</variablelist>

</sect2>

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

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

<para
>A primeira linha contém o número do área de jogo.</para>

<para
>Em todas as outras linhas, existe um objeto gráfico por linha, na ordem que é usada para desenhá-los. Cada linha contém 5 números: o identificador do objeto e o retâ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 arquivo 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 para cada área de jogo, bem como várias marcas <markup
>&lt;language&gt;</markup
>, uma para cada idioma. </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 arquivos 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 ação do item do menu que permite selecionar a posição da área onde poderá soltar os objetos, assim como a legenda deste item do menu. Este identificador de açã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á soltar os objetos, 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 objetos. 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 objeto, 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 esse idioma. 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, uma vez que o seu significado é bastante intuitivo. Se você modificar o arquivo <filename
>layout.xml</filename
>, não se esqueça de modificar o <filename
>layout.i18n</filename
> e o <filename
>ktuberlingui.rc</filename
> de acordo. </para>

</sect1>
</chapter>
