Éric
Bischoff
Marcus
Gama

    marcus.gama@gmail.com

Tradução
04/10/2021
KDE Gear 21.08
KDE
KTuberling
referência técnica

# Referências técnicas

O &ktuberling; oferece uma forma gentil e compensadora de introduzir à personalização e programação do &kde;. O aplicativo pode ser estendido. 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ê estender ou adicionar algo ao jogo, por favor considere enviar as suas adições ao mantenedor Alex Fiestas de modo a incluí-las nas próximas versões.

## Para artistas

Para criar uma nova área de jogo para o &ktuberling;, você terá que:

- Desenhar a área de jogo num arquivo &SVG;, onde terá que:

  - Chamar background ao local onde os itens poderão ser colocados.

  - Dar um nome único a todos os itens arrastáveis.

- Criar um arquivo `.theme` que terá que seguir este esquema:

      <playground gameboard="seruArquivoSVG" name="oArquivoDesktop">
      <object name="nomeItem" sound="nomeSom" scale="algumValor" />
      ...
      ...
      ...
      </playground>

  - seuArquivoSVG é o nome do arquivo &SVG; que tem o desenho.

  - oArquivoDesktop é o nome do arquivo 'desktop' que tem o nome do tema.

  - Para cada objeto, irá necessitar de um item `<object>`. O nomeItem é o nome único que usou no arquivo &SVG;, o nomeSom é o nome do som que será tocado ao arrastar o item; veja o `sounds/soundthemes.HOWTO` do código-fonte para mais informações.

  - O `scale` é opcional e o valor é o fator de escala que será usado ao desenhar este objeto fora do armazém; se não for indicado, é igual a 1.

- Crie um arquivo `.desktop` que siga o seguinte esquema:

      [KTuberlingTheme]
      Name=Nomedotema

  - nomeTema é o nome que identifica o tema, o qual aparecerá no menu da Área de Jogo.

- Se você estiver adicionando o tema ao repositório do &ktuberling;, adicione os arquivos `.svg`, `.theme` e `.desktop` à seção `FILES` do arquivo `CMakeLists.txt` da pasta `pics/`.

- Se quiser instalá-lo você mesmo, coloque os arquivos `.svg`, `.theme` e `.desktop` na pasta `ktuberling/pics` no ``qtpaths` `--paths GenericDataLocation``

## Para tradutores

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.

Para criar um novo tema de sons do &ktuberling;, você terá que:

- Gravar os sons no formato de arquivo RC3 do OGG Vorbis.

- Criar um arquivo `códigoDuasLetrasDeSeuIdioma.soundtheme` que terá que seguir este esquema:

      <language code="códigoDuasLetrasDeSeuIdioma">
      <sound name="nomeSom" file="localRelativo" />
      ...
      ...
      ...
      </language>

  - códigoDuasLetrasDeSeuIdioma é o código de duas letras do seu idioma, sendo por exemplo 'pt' para o Português.

  - Para cada som, deverá existir um item `<sound>`. O nomeSom deverá corresponder ao 'nomeSom' indicado no tema do recreio (ver `pics/themes.HOWTO` no código-fonte). O localRelativo deverá ser o local relativo onde irá instalar o arquivo com este som, sendo tipicamente igual a `umLocalUnico/nomeSom.format` (o umLocalUnico pode ser o código de duas letras da sua língua, por exemplo).

- Se você estiver adicionando o tema de som ao &ktuberling; à pasta do seu idioma:

  - Adicione os arquivos de sons e o arquivo `.soundtheme` à pasta `data/kdegames/ktuberling` das traduções do seu idioma.

  - Nessa mesma pasta, será necessário um arquivo `CMakeLists.txt` que descreve como instalar os arquivos, sendo tipicamente.

        FILE( GLOB oggfiles *.ogg )
        INSTALL( FILES ${oggfiles} DESTINATION ${KDE_INSTALL_DATADIR}/ktuberling/sounds/códigoDuasLetrasDeSeuIdioma )
        INSTALL( FILES códigoDuasLetrasDeSeuIdioma.soundtheme DESTINATION ${KDE_INSTALL_DATADIR}/ktuberling/sounds/ )

- Se quiser instalá-lo você mesmo:

  - Coloque o arquivo `códigoDuasLetrasDeSeuIdioma.soundtheme` em `ktuberling/sounds` em ``qtpaths` `--paths GenericDataLocation``

  - Coloque seus arquivos de som na pasta `ktuberling/sounds/algumCaminhoUnico` em``qtpaths` `--paths GenericDataLocation``

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.

`Ação`

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