A forma mais simples de instalar novas definições de estruturas é usar o suporte incorporado do KNewStuff no Okteta. Para instalar uma estrutura existente, abra a janela de configuração da ferramenta de Estruturas. Aí, seleccione a página de Gestão de Estruturas e carregue no botão Obter Estruturas Novas.... A janela que aparecerá permite-lhe então instalar ou desinstalar estruturas.

A ferramenta de Estruturas procura pelas descrições de estruturas na sub-pasta okteta/structures/ da pasta do utilizador para os dados das aplicações (descubra-a com o comando qtpaths --path GenericDataLocation). Poderá ter de criar esta pasta, caso não existam ainda nenhumas definições de estruturas instaladas.

Existem dois ficheiros para cada definição da estrutura: Um ficheiro para a definição em si e um ficheiro .desktop para os meta-dados (autor, versão, etc.).

Nessa sub-pasta, existe uma sub-pasta própria para cada definição de estruturas, a qual contém tanto o ficheiro .desktop como o .osd ou o main.js para essa definição.

Por exemplo, com a pasta de dados das aplicações qtpaths --paths GenericDataLocation e com uma definição de estrutura chamada EstruturaExemplo, existe a pasta okteta/structures/EstruturaExemplo, que contém um ficheiro EstruturaExemplo.desktop e um ficheiro EstruturaExemplo.osd.

Se tiver instalado uma nova definição de estruturas, poderá ter de reiniciar o Okteta e abrir a janela de configuração da ferramenta de Estruturas. Aí, seleccione a página de Gestão das Estruturas e certifique-se que a definição da estrutura relevante é assinalada. Depois, mude para a página Estruturas e certifique-se que o elemento desejado está listado no lado direito.

Os nossos meta-dados ficarão algo do género:

        [Desktop Entry]
        Encoding=UTF-8
        Icon=arrow-up❶
        Type=Service
        ServiceTypes=KPluginInfo

        Name=Estrutura de testes simples
        Comment=Uma estrutura muito simples de testes que só contém dois itens

        X-KDE-PluginInfo-Author=José Pires
        X-KDE-PluginInfo-Email=jose.pires@email.org
        X-KDE-PluginInfo-Name=estrutura-simples
        X-KDE-PluginInfo-Version=1.0
        X-KDE-PluginInfo-Website=http://www.plugin.org/
        X-KDE-PluginInfo-Category=structure
        X-KDE-PluginInfo-License=LGPL
        X-KDE-PluginInfo-EnabledByDefault=false
        

Estes campos deverão ser relativamente intuitivos, exceptuando o X-KDE-PluginInfo-Name. O valor deste campo deverá corresponder ao nome da pasta que contém o ficheiro, assim como o nome do ficheiro .desktop. Ao criar as definições de estruturas em XML, o nome do ficheiro .osd deverá também corresponder ao nome.

Neste exemplo, teríamos uma pasta chamada estruturasimples que contém os ficheiros estruturasimples.desktop. Ao definir as estruturas em XML, a pasta iria conter também um ficheiro chamado estruturasimples.osd. Se usarmos o JavaScript, iríamos ter um ficheiro chamado main.js em alternativa.

Para começar, iremos criar uma definição de uma estrutura de testes muito simples, contendo apenas tipos de dados integrais (um carácter, um inteiro com sinal de 32 bits e um campo de bits). Isto seria descrito em C/C++ como:

          struct simples {
            char umCaracter;
            int umInteiro;
            bool campoBits :1;
            unsigned preenchimento :7;
          };
          

O primeiro passo é criar o ficheiro .osd de acordo com o formato do ficheiro definido na secção anterior. Iremos chamar ao ficheiro estrutura-simples.osd:

          <?xml version="1.0" encoding="UTF-8"?>
          <data>
            <struct name="simple">
              <primitive name="umCaracter" type="Char"/>
              <primitive name="umInteiro" type="Int32"/>
              <bitfield name="campoBits" type="bool" width="1"/>
              <bitfield name="preenchimento" type="unsigned" width="7"/>
            </struct>
          </data>
          

, o que corresponderá de certa forma à definição em C/C++.

Agora crie uma sub-pasta estrutura-simples como descrito acima, copie os dois ficheiros para esta pasta e reinicie o Okteta, para poder usar a nova estrutura.

Para implementar a estrutura acima em JavaScript, crie um ficheiro chamado main.js em vez de simplestruct.osd e mude o texto 'X-KDE-PluginInfo-Category=structure' para 'X-KDE-PluginInfo-Category=structure'. O conteúdo desse ficheiro seria:

        function init() {
          var estrutura = struct({
            carácter : char(),
            inteiro : int32(),
            opcaoBit : bitfield("bool", 1),
            preenchimento : bitfield("unsigned", 7),
          })
          return estrutura;
        }
        

A estrutura apresentada pelo Okteta é sempre o valor devolvido pela função init.

Poderá invocar as seguintes funções para criar um tipo primitivo:

A função 'bitfield' recebe dois parâmetros, sendo o primeiro um texto que consiste em bool, signed ou unsigned. O segundo parâmetro é um inteiro que define o tamanho em 'bits'.

De seguida, iremos criar uma estrutura mais complexa, que se irá chamar "complexa" e gravá-la num ficheiro complexa.osd. Esta estrutura irá conter duas listas (uma de tamanho fixo e outra com o tamanho determinado durante a execução), assim como uma estrutura encadeada e uma união.

          <?xml version="1.0" encoding="UTF-8"?>
          <data>
            <struct name="complexa">
              <primitive name="tamanho" type="UInt8" />
              <union name="umaUniao">
                <array name="quatroBytes" length="4">
                  <primitive type="Int8" />
                </array>
              </union>
              <struct name="encadeado">
                <array name="texto" length="tamanho"> <!-- referencia o campo 'tamanho' acima -->
                  <primitive type="Char" />
                </array>
              </struct>
            </struct>
          </data>
          

Isto irá corresponder ao seguinte, em pseudo-C/C++

struct complexa {
            uint8_t tamanho;
            union umaUniao {
              int8_t quatroBytes[4];
            };
            struct encadeado {
              char texto[tamanho] //C++ não válido por referenciar o valor de 'tamanho'
            };
          };
          

Depois, será criado o ficheiro complexo.desktop, como foi feito no exemplo anterior (certifique-se que define o X-KDE-PluginInfo-Name correctamente) e faça o mesmo para instalar ambos os ficheiros.

Poderá encontrar alguns exemplos de definições de estruturas aqui. Isto inclui, por exemplo, o cabeçalho dos ficheiros PNG. Poderá encontrar um esquema em XML que descreve a estrutura do ficheiro .osd aqui. Se precisar de mais informações, sinta-se à vontade em contactar-me em (arichardson.kde gmail.com)