<?xml version='1.0' encoding='UTF-8'?>

<chapter id="tools">
  <title
>Strumenti</title>

<!-- The tool Versions is not part of released versions,
just used for development, so no need to document it. -->

<sect1 id="tools-overview">

  <title
>Panoramica</title>
  <para
>&okteta; include alcuni strumenti, alcuni per analizzare e manipolare i vettori di dati e altri con scopi più generali. Questi strumenti si possono attivare o disattivare dal menu <guimenu
>Strumenti</guimenu
>. Ogni strumento ha una piccola vista, che si aggancia in una delle barre laterali o si presenta come finestra a sé. Puoi agganciare, sganciare, ridisporre e anche impilare le viste degli strumenti col mouse, premendo il &LMB; sulla barra del titolo di una vista, spostandola dove vuoi e rilasciando il &LMB; per completare l'azione, altrimenti annullala premendo il tasto &Esc;.</para>

<sect2>
  <title
>Analisi e manipolazione</title>
<variablelist>
  <varlistentry>
    <term
>Tabella dei byte</term>
    <listitem
><para
>La tabella elenca tutti i valori possibili dei byte, sia come caratteri che come valori numerici.</para>
    <para
>Il valore selezionato può essere inserito alla posizione del cursore per un certo numero di byte. Questo si può fare usando il pulsante <guibutton
>Ins</guibutton
> o facendo doppio clic sulla riga nella tabella.</para
></listitem>
  </varlistentry>

  <varlistentry>
    <term
>Filtro binario</term>
    <listitem
><para
>Il filtro effettua operazioni binarie sui byte selezionati. Dopo aver scelto l'operazione (ET, VEL, RUOTA...), gli eventuali parametri possono essere impostati nella casella sotto. Il filtro viene eseguito all'attivazione del pulsante <guibutton
>Filtra</guibutton
>.</para
></listitem>
  </varlistentry>

  <varlistentry>
    <term
>Stringhe</term>
    <listitem
><para
>Questo strumento localizza le stringhe nei byte selezionati. Dopo aver scelto la lunghezza minima delle stringhe, queste vengono ricercate dopo aver usato il pulsante <guibutton
>Estrai</guibutton
>. L'elenco di stringhe visualizzate può venire ristretto inserendo un termine di filtro.</para
></listitem>
  </varlistentry>

  <varlistentry>
    <term
>Statistiche</term>
    <listitem
><para
>Questo strumento genera un dato statistico dei byte selezionati: la frequenza di ogni byte nella selezione. Può essere calcolata con il pulsante <guibutton
>Genera</guibutton
>.</para
></listitem>
  </varlistentry>

  <varlistentry>
    <term
>Codice di controllo</term>
    <listitem
><para
>Questo strumento calcola vari codici di controllo per i byte selezionati. Dopo aver scelto l'algoritmo e impostato il parametro, se ce n'è uno, la somma viene calcolata alla pressione del pulsante <guibutton
>Calcola</guibutton
>.</para
></listitem>
  </varlistentry>

  <varlistentry>
    <term
>Tabella di decodifica</term>
    <listitem
><para
>La tabella visualizza i valori dei byte a partire dal cursore per alcuni tipi di dati comuni come numeri interi o a virgola mobile, ma anche UTF-8. Fare doppio clic in una riga della tabella apre un editor per modificare il valore.</para
></listitem>
  </varlistentry>

  <varlistentry>
    <term
>Strutture</term>
    <listitem
><para
>Questo strumento permette di investigare e modificare vettori di dati basati su definizioni di strutture dell'utente. Per istruzioni dettagliate vedi <xref linkend="tools-structures"/>.</para
></listitem>
  </varlistentry>
</variablelist>
</sect2>

<sect2>
  <title
>Strumenti generali</title>
<variablelist>
  <varlistentry>
    <term
>Filesystem</term>
    <listitem
><para
>Questo strumento offre un selettore di file incorporato.</para
></listitem>
  </varlistentry>

  <varlistentry>
    <term
>Documenti</term>
    <listitem
><para
>Questo strumento mostra tutti i file attualmente creati o caricati. I simboli indicano il file la cui vista è attiva e anche quali file hanno modifiche non salvate o la cui copia salvata è stata modificata da un altro programma.</para
></listitem>
  </varlistentry>

  <varlistentry>
    <term
>Segnalibri</term>
    <listitem
><para
>Questo strumento può essere usato per gestire i segnalibri, in alternativa al menu <link linkend="bookmarks-menu"
><guimenu
>Segnalibri</guimenu
></link
>. <note
><para
>I segnalibri sono al momento temporanei e non vengono salvati se chiudi un vettore di byte o tutto il programma.</para
></note
></para
></listitem>
  </varlistentry>

  <varlistentry>
    <term
>Informazioni sul file</term>
    <listitem
><para
>Questo strumento visualizza alcune informazioni sul file attuale, inclusi il tipo, il luogo di memorizzazione e le dimensioni.</para
></listitem>
  </varlistentry>
</variablelist>
</sect2>

</sect1>


<sect1 id="tools-structures">

    <title
>Strumento per le strutture</title>

    <sect2>
      <title
>Generale</title>

      <para
>Lo strumento per le strutture permette di analizzare e modificare i vettori di byte in base a definizioni di strutture dell'utente, che possono essere costituite da array, unioni, tipi primitivi ed enumerazioni.</para>
     <!-- explain/link what these types are? probably not, since most user will be programmers? -->
      <para
>Ha una propria finestra di configurazione, che si può raggiungere con il pulsante <guibutton
>Impostazioni</guibutton
>. Ci sono diverse opzioni configurabili, come lo stile con cui i valori sono visualizzati (decimale, esadecimale, o binario). Inoltre è possibile scegliere quali definizioni di strutture caricare e quali mostrare nella vista.</para>
      <para
>Le strutture sono definite in file di definizione di strutture di &okteta; (basati su &XML;, con estensione <literal role="extension"
>.osd</literal
>). Inoltre, un file <literal role="extension"
>.desktop</literal
> contiene dati aggiuntivi sul file di descrizione delle strutture, come autore, pagina Web e licenza.</para>
      <para
>Attualmente non c'è un supporto integrato per creare, modificare o installare definizioni di strutture, quindi ciò va fatto manualmente, come descritto nelle sezioni seguenti.</para>
    </sect2>

    <sect2>
      <title
>Installare definizioni di strutture</title>

      <para
>Lo strumento per le strutture cerca descrizioni di strutture nella sottocartella <filename class="directory"
>share/apps/okteta/structures/</filename
> della cartella dei dati dei programmi dell'utente (la trovi con <userinput
><command
>kde4-config</command
> <option
>--localprefix</option
></userinput
>). Potresti dover creare questa cartella se non ci sono ancora definizioni di strutture installate.</para>
      <para
>In quella sottocartella ce n'è un'altra per ogni definizione di struttura, contenente sia il file <literal role="extension"
>.desktop</literal
> che il file <literal role="extension"
>.osd</literal
> della definizione.</para>
      <para
>Per esempio, con la cartella di dati dei programmi <filename class="directory"
>~/.kde</filename
> e una definizione di struttura chiamata Esempio, c'è la cartella <filename class="directory"
>.kde/share/apps/okteta/structures/Esempio</filename
>, contenente un file <filename
>Esempio.desktop</filename
> e un file <filename
>Esempio.osd</filename
>.</para>
      <para
>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 <guilabel
>Gestione strutture</guilabel
> e assicurati che la definizione di struttura desiderata sia segnata. Usa quindi il pulsante <guibutton
>Applica modifiche</guibutton
>, passa alla scheda <guilabel
>Strutture</guilabel
> e assicurati che l'elemento desiderato sia elencato sul lato destro.</para>
    </sect2>

    <sect2>
      <title
>Condividere definizioni di strutture</title>
      <para
>Per le strutture comuni potresti non dover creare una tua definizione, ma riutilizzarne invece una già disponibile per esempio da <ulink url="http://kde-files.org/index.php?xcontentmode=691"
>kde-files.org</ulink
>.</para>
      <para
>Potresti anche voler condividere una tua definizione. Per farlo, crea un file d'archivio (per esempio un archivio tar compresso, <literal role="extension"
>.tgz</literal
>) contenente solo la sottocartella con il file <literal role="extension"
>.osd</literal
> e il file <literal role="extension"
>.desktop</literal
>. L'esempio nella sezione precedente sarebbe nella cartella <filename class="directory"
>Esempio</filename
>. Se aderisci a questo formato, le versioni future dello strumento per le strutture permetteranno lo scaricamento e l'installazione automatici di queste definizioni.</para>
    </sect2>

    <sect2>
      <title
>Creare le tue definizioni di strutture</title>

      <sect3>
        <title
>Una prima definizione di struttura</title>
        <para
>Per cominciare creiamo una definizione per una struttura di prova molto semplice, contenente solo tipo di dati integrali (un carattere e un intero a 32 bit). In C e C++ verrebbero espressi come: <screen>
          struct simple {
            char aChar;
            int anInt;
          };
          </screen
> Il primo passo è scrivere il file <literal role="extension"
>.osd</literal
>, che chiamiamo <filename
>semplice.osd</filename
>: <screen
><markup>
          &lt;?xml version="1.0" encoding="UTF-8"?&gt;
          &lt;data&gt;
            &lt;struct name="semplice"&gt;
              &lt;primitive name="carattere" type="Char"/&gt;
              &lt;primitive name="intero" type="Int32"/&gt;
            &lt;/struct&gt;
          &lt;/data&gt;
          </markup
></screen
> il che è abbastanza simile alla definizione in C o C++. L'attributo di tipo può essere uno tra i seguenti:</para>
          <simplelist>
          <member
>Char</member>
          <member
>Int8</member>
          <member
>UInt8</member>
          <member
>Int16</member>
          <member
>UInt16</member>
          <member
>Int32</member>
          <member
>UInt32</member>
          <member
>Int64</member>
          <member
>UInt64</member>
          <member
>Float</member>
          <member
>Double</member>
          <member
>Bool8</member>
          <member
>Bool16</member>
          <member
>Bool32</member>
          <member
>Bool64</member>
          </simplelist>
          <para
>Il passo successivo è scrivere il file <literal role="extension"
>.desktop</literal
> per i dati aggiuntivi, che è solo una serie di coppie chiave-valore. Dovrebbe avere il nome <filename
>semplice.desktop</filename
>. In questo esempio si può scrivere così: <screen>
          [Desktop Entry]
          Encoding=UTF-8
          Icon=arrow-up
          Type=Service
          ServiceTypes=KPluginInfo

          Name=Semplice struttura di prova
          Comment=Una struttura di prova molto semplice contenente solo due 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=http://it.wiktionary.org/wiki/semplice
          X-KDE-PluginInfo-Category=structure
          X-KDE-PluginInfo-License=LGPL
          X-KDE-PluginInfo-EnabledByDefault=false
          </screen
> Questi campi dovrebbero essere tutti abbastanza facili da capire, tranne <literal
>X-KDE-PluginInfo-Name</literal
>. Questo deve avere il nome del file <literal role="extension"
>.osd</literal
> (senza il suffisso) come valore.</para>
          <para
>Adesso crea una sottocartella <filename class="directory"
>semplice</filename
> come sopra descritto, copiaci i due file, e riavvia &okteta;.</para>
      </sect3>
      <sect3>
        <title
>Strutture più complesse</title>
        <para
>Adesso creiamo la definizione di una struttura più complessa, che chiameremo <quote
>complessa</quote
> e salveremo in un file di nome <filename
>complessa.osd</filename
>. 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. <screen
><markup>
          &lt;?xml version="1.0" encoding="UTF-8"?&gt;
          &lt;data&gt;
            &lt;struct name="complessa"&gt;
              &lt;primitive name="dimensione" type="UInt8" /&gt;
              &lt;union name="unione"&gt;
                &lt;array name="quattroByte" length="4"&gt;
                  &lt;primitive type="Int8" /&gt;
                &lt;/array&gt;
              &lt;/union&gt;
              &lt;struct name="annidata"&gt;
                &lt;array name="stringa" length="dimensione"&gt; &lt;!-- fa riferimento alla dimensione di cui sopra --&gt;
                  &lt;primitive type="Char" /&gt;
                &lt;/array&gt;
              &lt;/struct&gt;
            &lt;/struct&gt;
          &lt;/data&gt;
          </markup
></screen
> Ciò corrisponderebbe a quanto segue in pseudo C o C++: <screen
>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
            };
          };
          </screen>
          </para>
          <note
><para
>Ovviamente puoi far riferire array a lunghezza dinamica solo a campi che vengono prima di questi.</para
></note>
          <para
>Adesso creiamo il file <filename
>complessa.desktop</filename
> come nell'esempio precedente (assicurati di impostare <literal
>X-KDE-PluginInfo-Name</literal
> correttamente) e facciamo lo stesso per installare i file.</para>
      </sect3>
      <sect3>
        <title
>Ulteriori informazioni</title>
        <para
>Alcune definizioni di strutture esemplificative si possono trovare <ulink url="http://websvn.kde.org/branches/KDE/4.4/kdeutils/okteta/kasten/controllers/view/structures/schema/example/"
>qui</ulink
>, incluse per esempio le intestazioni per i file PNG. Uno schema &XML; per descrivere la struttura del file <literal role="extension"
>.osd</literal
> è disponibile <ulink url="http://websvn.kde.org/branches/KDE/4.4/kdeutils/okteta/kasten/controllers/view/structures/schema/"
>qui</ulink
>. Se ti servono maggiori informazioni, non esitare a contattarmi a &Alex.Richardson.email;. </para>
      </sect3>
    </sect2>
</sect1>

</chapter>