La manera més fàcil d'instal·lar definicions noves d'estructura és utilitzant el suport integrat del KNewStuff a l'Okteta. Per a instal·lar una estructura existent obriu el diàleg de configuració de l'eina Estructura. Allà seleccioneu la pestanya Gestió d'estructures i premeu el botó Obtén estructures noves.... El diàleg que es mostra ara us permet instal·lar i desinstal·lar estructures.

L'eina Estructura cerca descripcions d'estructura en el subdirectori okteta/structures/ del directori de l'usuari per a les dades del programa (que es troba executant qtpaths --paths GenericDataLocation). És possible que hàgiu de crear aquest directori si encara no hi ha cap definició d'estructura instal·lada.

Hi ha dos fitxers per a cada definició d'estructura: un fitxer per a la definició real i un fitxer .desktop per a les metadades (autor, versió, etc.).

En aquest directori hi ha un subdirectori per a cada definició d'estructura, que conté tant el fitxer .desktop com el fitxer .osd o main.js d'aquesta definició.

Per exemple, amb el directori de dades del programa qtpaths --paths GenericDataLocation i una definició d'estructura anomenada ExampleStructure, hi ha el directori okteta/structures/ExampleStructure que conté un fitxer ExampleStructure.desktop i un fitxer ExampleStructure.osd.

Després d'instal·lar una definició nova d'estructura haureu de reiniciar l'Okteta abans de poder-la utilitzar. Un cop s'ha iniciat l'Okteta, obriu el diàleg de configuració de l'eina Estructura. Allà seleccioneu la pestanya Gestió d'estructures i assegureu-vos que la definició de l'estructura corresponent està marcada. Després canvieu a la pestanya Estructures i assegureu-vos que l'element desitjat està llistat a la dreta.

El nostre fitxer de metadades hauria de ser així:

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

        Name=Estructura simple de prova
        Comment=Una estructura de prova senzilla que conté dos elements

        X-KDE-PluginInfo-Author=Alex Richardson
        X-KDE-PluginInfo-Email=foo.bar@email.org
        X-KDE-PluginInfo-Name=simplestruct
        X-KDE-PluginInfo-Version=1.0
        X-KDE-PluginInfo-Website=https://www.plugin.org/
        X-KDE-PluginInfo-Category=structure
        X-KDE-PluginInfo-License=LGPL
        X-KDE-PluginInfo-EnabledByDefault=false
        

Aquests camps haurien de ser força autoexplicatius, excepte X-KDE-PluginInfo-Name. El valor d'aquest camp ha de coincidir amb el nom del directori que conté el fitxer així com el nom del fitxer .desktop. En crear les definicions d'estructura XML el nom del fitxer .osd també ha de coincidir amb el nom.

En aquest exemple tindríem un directori anomenat simpletruct que conté el fitxer simpletruct.desktop. En definir estructures en XML el directori també conté un fitxer anomenat simpletruct.osd. Utilitzant JavaScript en el seu lloc tindríem un fitxer anomenat main.js.

Per a començar creem una definició per a una estructura de prova molt senzilla que conté només tipus de dades integrals (un caràcter, un enter amb signe de 32 bits i un camp de bits). Això s'expressa en C/C++ com:

          struct simple {
            char aChar;
            int anInt;
            bool bitFlag :1;
            unsigned padding :7;
          };
          

El primer pas és escriure el fitxer .osd d'acord amb el format de fitxer definit a la secció anterior. Invocarem simpletruct.osd:

          <?xml version="1.0" encoding="UTF-8"?>
          <data>
            <struct name="simple">
              <primitive name="aChar" type="Char"/>
              <primitive name="anInt" type="Int32"/>
              <bitfield name="bitFlag" type="bool" width="1"/>
              <bitfield name="padding" type="unsigned" width="7"/>
            </struct>
          </data>
          

que és força similar a la definició en C/C++.

Ara creeu un directori simpletruct dins del directori d'instal·lació de l'estructura (vegeu manualment les definicions d'estructura) i copieu els dos fitxers a aquest directori. Ara podeu reiniciar l'Okteta i utilitzar l'estructura nova.

Per a implementar l'estructura anterior en JavaScript, creeu un fitxer anomenat main.js en lloc de simpletruct.osd i canvieu X-KDE-PluginInfo-Category=structure a X-KDE-PluginInfo-Category=structure/js. El contingut d'aquest fitxer hauria de ser:

        function init() {
          var structure = struct({
            aChar : char(),
            anInt : int32(),
            bitFlag : bitfield("bool", 1),
            padding : bitfield("unsigned", 7),
          })
          return structure;
        }
        

L'estructura mostrada per l'Okteta és sempre el valor de retorn de la funció init.

Les funcions següents es poden anomenar per a crear un tipus primitiu:

La funció camp de bits té dos paràmetres, el primer és una cadena que consta d'un bool, signed o unsigned. El segon paràmetre és un enter que estableix l'amplada en bits.

A continuació creem una definició d'una estructura més complexa que anomenarem «complex» i desarem en un fitxer anomenat complex.osd. Aquesta estructura contindrà dues matrius (una amb longitud fixa i una altra on la longitud es determina en temps d'execució) així com una estructura imbricada i una unió.

          <?xml version="1.0" encoding="UTF-8"?>
          <data>
            <struct name="complex">
              <primitive name="size" type="UInt8" />
              <union name="aUnion">
                <array name="fourBytes" length="4">
                  <primitive type="Int8" />
                </array>
              </union>
              <struct name="nested">
                <array name="string" length="size"> <!-- fa referència a la mida del camp anterior -->
                  <primitive type="Char" />
                </array>
              </struct>
            </struct>
          </data>
          

Això correspondria al següent en pseudocodi C/C++

struct complex {
            uint8_t size;
            union aUnion {
              int8_t fourBytes[4];
            };
            struct nested {
              char string[size] //no és C++ vàlid, fa referència al valor de la mida d'«uint8»
            };
          };
          

A continuació creem el fitxer complex.desktop com en l'exemple anterior (assegureu-vos que heu establert X-KDE-PluginInfo-Name correctament) i també feu el mateix per a instal·lar els dos fitxers.

Es poden trobar algunes definicions d'estructura d'exemple al repositori Git. Això inclou per exemple la capçalera de fitxer per a fitxers PNG i la capçalera de fitxer ELF. Es pot trobar un esquema XML que descriu l'estructura del fitxer .osd aquí. Si es necessita més informació us podeu posar en contacte amb mi a (arichardson.kde gmail.com)