Eric
Bischoff
Marcus
Gama

    marcus_gama@uol.com.br

Tradução
10-04-2002
0.03.02
KDE
Homem Batata
referência técnica

# Referência técnica

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!

Se você extender ou adicionar ao jogo, por favor considere a possibilidade de enviar as suas adições ao programador Eric Bischoff de modo a incluí-las nas próximas versões.

## Para artistas

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.

São usadas seis imagens no &ktuberling;: `potato-game.png`, `potato-mask.png`, `penguin-game.png`, `penguin-mask.png`, `aquarium-game.png` e `aquarium-mask.png`. A localização padrão destes arquivos é a pasta `$KDEDIR/share/apps/ktuberling/pics/`.

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

O segundo tipo de imagens, os `*-mask.png`, 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.

Na mesma pasta, um arquivo chamado `layout.xml`. (`$KDEDIR/share/apps/ktuberling/pics/layout.xml`) 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 abaixo).

Ainda na mesma pasta existe um arquivo chamado `layout.i18n` (`$KDEDIR/share/apps/ktuberling/pics/layout.i18n`) que recapitula os textos no `layout.xml` que podem ser traduzidos:

- As entradas de menu que lhe permitem escolher a área de jogo e o idioma

- Os nomes das categorias de objetos

Uma pasta mais acima, existe um arquivo chamado `ktuberlingui.rc` (`$KDEDIR/share/apps/ktuberling/ktuberlingui.rc`), que é um segundo arquivo XML que descreve os menus do &ktuberling;. Ele deverá conter uma marca <action> 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 `layout.xml`.

## Tradução

Além do mecanismo normal dos arquivos `.po` para traduzir os textos do programa e as mensagens, os sons também poderão ser localizados.

Se os vários tradutores puderem gravar a sua voz para um arquivo `.wav`, 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 `layout.xml`. Por exemplo, se a idioma de destino é o Português do Brasil, os tradutores poderão gravar a sua voz para os arquivos `.wav` localizados na pasta `$KDEDIR/share/apps/ktuberling/sounds/pt_BR`. Então, eles poderão então atribuir o som chamado hat ao nome do arquivo `pt_BR/chapeu.wav`.

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:

    $ oggenc_rc3 -o som.ogg som.wav

A informação sobre como lidar com os mecanismos de tradução no &kde; está disponível no HOWTO de Traduções do KDE.

## Para programadores

Não é difícil aos programadores extenderem o &ktuberling;.

### Classes C++

`TopLevel`

  Janela de topo e gerenciamento básico do programa

`PlayGround`

  Descrição de um dos níveis de jogo

`ToDraw`

  Uma descrição de um dos objetos gráficos a serem desenhados

`SoundFactory`

  Descrição de um dos idiomas e dos seus sons

`Action`

  Uma das ações do usuário na pilha de desfazer/refazer.

### Estrutura dos arquivos `.tuberling`

Um arquivo `.tuberling` que contém todos os dados necessários para desenhar um boneco. Ele poderá ser editado com um editor de texto normal.

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

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.

## Estrutura do arquivo de disposição (`layout.xml`)

A marca do nível de topo é única e chama-se <ktuberling>. Ela contém várias marcas <playground>, uma para cada área de jogo, bem como várias marcas <language>, uma para cada idioma.

A marca <playground> tem dois atributos: o gameboard e o masks. Estes atributos contém os nomes dos arquivos que contém as imagens. A marca <playground> também contém uma marca <menuitem>, uma <editablearea> e várias marcas <category>, tendo ainda várias marcas <object>.

A marca <menuitem> 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 `ktuberlingui.rc`.

A marca <editablearea> descreve a posição da área onde você poderá soltar os objetos, bem como o nome do som associado a ele.

A marca <category> 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 diversos.

A marca <object> descreve a posição (no tabuleiro e nas máscaras) de um objeto, assim como o nome do som associado a ele.

A marca <language> tem um atributo: o code. Este atributo dá o código da localização para esse idioma. A marca <language> também contém uma marca <menuitem> tag e várias <sound>.

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 `layout.xml`, não se esqueça de modificar o `layout.i18n` e o `ktuberlingui.rc` de acordo.