Il modo più facile di installare nuove definizioni di strutture è usare il supporto per le Novità incorporato in Okteta. Per installare una struttura esistente apri la finestra delle impostazioni dello strumento per le strutture. Lì, seleziona la scheda Gestione strutture e premi il pulsante Prendi nuove strutture. La finestra che apparirà permette di installare e disinstallare strutture.

Lo strumento per le strutture cerca descrizioni di strutture nella sotto-cartella okteta/structures/ della cartella dei dati dei programmi dell'utente (si trova con qtpaths --paths GenericDataLocation). Potresti dover creare questa cartella se non ci sono ancora definizioni di strutture installate.

Ci sono due file per ogni definizione di struttura: un file per la definizione vera e propria, e un file .desktop per i metadati (autore, versione, eccetera).

In quella cartella c'è una sottocartella per ogni definizione di struttura, contenente sia il file .desktop che il file .osd o main.js della definizione.

Per esempio, con la cartella di dati dei programmi qtpaths --paths GenericDataLocation e una definizione di struttura chiamata Esempio, c'è la cartella okteta/structures/Esempio, contenente un file Esempio.desktop e un file Esempio.osd.

Se hai installato una nuova definizione di struttura creando una tale sottocartella con i due file o li hai modificati, devi riavviare Okteta e aprire la finestra di configurazione dello strumento per le strutture. Lì, seleziona la scheda Gestione strutture e assicurati che la definizione di struttura desiderata sia segnata. Usa quindi il pulsante Applica, passa alla scheda Strutture e assicurati che l'elemento desiderato sia elencato sul lato destro.

Il nostro file di metadati ha questo aspetto:

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

          Name=Semplice struttura di prova
          Comment=Struttura di prova molto semplice con due soli elementi

          X-KDE-PluginInfo-Author=Pinco Pallino
          X-KDE-PluginInfo-Email=pinco@pallino.it
          X-KDE-PluginInfo-Name=semplice
          X-KDE-PluginInfo-Version=1.0
          X-KDE-PluginInfo-Website=https://it.wiktionary.org/wiki/semplice
          X-KDE-PluginInfo-Category=structure
          X-KDE-PluginInfo-License=LGPL
          X-KDE-PluginInfo-EnabledByDefault=false
          

Questi campi dovrebbero essere tutti abbastanza facili da capire, tranne X-KDE-PluginInfo-Name: questo deve avere il nome della cartella contenente il file così come il nome del file .desktop. Quando si creano definizioni di strutture con XML, anche il nome del file .osd deve corrispondere.

In questo esempio avremmo una cartella di nome semplice contenente il file semplice.desktop. Quando si definiscono strutture in XML, la cartella conterrebbe anche un file di nome semplice.osd. Usando JavaScript, avremmo invece un file di nome main.js.

Per cominciare creiamo una definizione per una struttura di prova molto semplice, contenente solo tipo di dati integrali (un carattere, un intero a 32 bit, e un campo di bit). In C e C++ verrebbero espressi come:

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

Il primo passo è scrivere il file .osd secondo il formato di file definito nella sezione precedente. Lo chiameremo semplice.osd:

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

il che è abbastanza simile alla definizione in C o C++.

Adesso crea una cartella semplice sotto la cartella di installazione delle strutture (rivedi come si installano manualmente le strutture), e copiaci i due file. Adesso puoi riavviare Okteta e usare la nuova struttura.

Per implementare la struttura sopra in JavaScript, crea un file di nome main.js invece che semplicestruttura.osd e cambia X-KDE-PluginInfo-Category=structure in X-KDE-PluginInfo-Category=structure/js. I contenuti di questo file dovrebbero essere:

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

La struttura visualizzata da Okteta è sempre il valore restituito dalla funzione init.

Le funzioni seguenti possono essere chiamate per creare un tipo primitivo:

La funzione bitfield prende due argomenti, di cui il primo è una stringa che può essere bool, signed o unsigned. Il secondo è un intero che imposta l'ampiezza in bit.

Adesso creiamo la definizione di una struttura più complessa, che chiameremo «complessa» e salveremo in un file di nome complessa.osd. Questa struttura conterrà due array (uno di lunghezza fissa e uno di lunghezza determinata durante l'esecuzione), oltre a una struttura annidata e un'unione.

          <?xml version="1.0" encoding="UTF-8"?>
          <data>
            <struct name="complessa">
              <primitive name="dimensione" type="UInt8" />
              <union name="unione">
                <array name="quattroByte" length="4">
                  <primitive type="Int8" />
                </array>
              </union>
              <struct name="annidata">
                <array name="stringa" length="dimensione"> <!-- fa riferimento alla dimensione di cui sopra -->
                  <primitive type="Char" />
                </array>
              </struct>
            </struct>
          </data>
          

Ciò corrisponderebbe a quanto segue in pseudo C o C++:

struct complessa {
            uint8_t dimensione;
            union unione {
              int8_t quattroByte[4];
            };
            struct annidata {
              char stringa[dimensione] // non è C++ valido, fa riferimento al valore della dimensione uint8
            };
          };
          

Adesso creiamo il file complessa.desktop come nell'esempio precedente (assicurati di impostare X-KDE-PluginInfo-Name correttamente) e facciamo lo stesso per installare i file.

Alcune definizioni di strutture esemplificative sono reperibili nel deposito Git, incluse per esempio le intestazioni dei file PNG e per i file ELF. Uno schema XML che descrive la struttura del file .osd è disponibile qui. Se servono maggiori informazioni, non esitare a contattare (arichardson.kde gmail.com).