# Referência Técnica

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!

Se extender ou adicionar ao jogo, por favor pense na hipótese de enviar as suas adições ao programador Alex Fiestas de modo a inclui-las nas próximas versões.

## Para Artistas

Para criar um novo recreio para o &ktuberling;, terá de:

- Desenhar o recreio num ficheiro SVG, onde terá de:

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

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

- Criar um ficheiro '.theme' que terá de seguir este esquema:

      <playground gameboard="oSeuFicheiroSVG" name="oFicheiroDesktop">
          <object name="nomeItem" sound="nomeSom" scale="valor" />
          ...
          ...
          ...
          </playground>

  - `oSeuFicheiroSVG` é o nome do ficheiro SVG que tem o desenho.

  - `oFicheiroDesktop` é o nome do ficheiro 'desktop' que tem o nome do tema.

  - Para cada objecto, irá necessitar de um item <object>. O `nomeItem` é o nome único que usou no ficheiro SVG, o `nomeSom` é o nome do som que será tocado ao arrastar o item; veja o HOWTO de temas de sons para mais informações.

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

- Crie um ficheiro '.desktop' que siga este esquema

      [KTuberlingTheme]
          Name=nomeTema

  - `nomeTema` é o nome que identifica o tema, o qual aparecerá no menu de Recreio.

- Se estiver a adicionar o tema ao repositório do &ktuberling;, adicione os ficheiros '.svg' '.theme' e '.desktop' à secção FILES do ficheiro CMakeLists.txt da pasta 'pics/'

- Se o quiser instalar você mesmo, coloque os ficheiros '.svg', '.theme' e '.desktop' do tema em `ktuberling/pics`, dentro da pasta devolvida por ``qtpaths` `--paths GenericDataLocation``

## Para os Tradutores

Para além do mecanismo normal dos ficheiros `.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;, terá de:

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

- Criar um ficheiro `codigoDuasLetrasDaSuaLingua`.soundtheme que terá de seguir este esquema:

      <language code="oCodigoDuasLetrasLingua">
      <sound name="nomeSom" file="localRelativo" />
      ...
      ...
      ...
      </language>

  - `oSeuCodigoDuasLetras` é o código de duas letras da sua língua, 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 o HOWTO dos temas). O `localRelativo` deverá ser o local relativo onde irá instalar o ficheiro 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 estiver a adicionar o tema de sons ao &ktuberling; na sua pasta 'language':

  - Adicione os ficheiros de sons e o ficheiro '.soundtheme' à pasta 'data/kdegames/ktuberling' das traduções da sua língua.

  - Nessa mesma pasta, será necessário um ficheiro 'CMakeLists.txt' que descreve como instalar os ficheiros, sendo tipicamente.

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

- Se quiser instalá-lo você mesmo:

  - Coloque o ficheiro `codigoDuasLetrasSuaLingua`.soundtheme na pasta `ktuberling/sounds` dentro da pasta devolvida por ``qtpaths` `--paths GenericDataLocation``

  - Coloque os seus ficheiros de som em `ktuberling/sounds/localizacaoUnica`, dentro da pasta devolvida por ``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 os Programadores

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

### Classes C++

`TopLevel`

- Janela de topo e gestão básica do programa

`PlayGround`

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

`ToDraw`

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

`SoundFactory`

- Descrição de uma das línguas e dos seus sons

`Action`

- Uma das acções do utilizador na minha de desfazer/refazer.