# Manuale di &rocs;

## Introduzione

&rocs; è un ambiente di sviluppo integrato per la teoria dei grafi, pensato per chiunque sia interessato a tracciare e analizzare algoritmi a grafo. Ciò include esplicitamente:

- docenti che vogliano dimostrare gli algoritmi ai loro studenti,

- studenti che vogliono capire e vedere come funziona un algoritmo,

- e chiunque debba tracciare algoritmi a grafi e ha bisogno di uno strumento per provare i prototipi.

Per tutti questi utenti, &rocs; dà un editor di grafi facile da usare per configurare i grafi, un potente motore di scripting basato su Qt Script per eseguire gli algoritmi, e diversi strumenti di supporto per configurare grafi e strutture di dati per i tuoi esperimenti. Il processo di lavoro è di solito scrivere un algoritmo, creare un grafo, e vedere in tempo reale come l'algoritmo funziona nel grafo.

Una schermata di &rocs;. Una schermata di &rocs;.

## L'interfaccia di &rocs;

### Elementi generali dell'interfaccia

L'interfaccia si divide in diverse parti logiche, come presentato nella schermata sotto.

Elementi grafici dell'interfaccia di &rocs;. Elementi grafici dell'interfaccia di &rocs;.

Barra dell'editor visuale di grafi

- Per poter disegnare o modificare i grafi nella lavagna dell'editor visuale dei grafi, devi prima selezionare uno strumento qui.

Editor visuale di grafi

- Questa è l'area dove puoi tracciare i grafi. Un clic destro sulla lavagna, sugli elementi del grafo, o su elementi selezinati del grafo apre un menu contestuale diverso a seconda di su cosa hai fatto clic.

Proprietà del grafo

- Questo dà un elenco completo di tutti i vari grafi attualmente sulla lavagna dell'editor visuale di grafi. Qui puoi fare modifiche, per esempio, al nome del grafo, a proprietà visibili come i nomi o i valori dei nodi, o definire i colori predefiniti per gli elementi del grafo.

Editor di script

- In questo editor di testo puoi scrivere algoritmi in Qt Script (per quel che ci riguarda è essenzialmente la stessa cosa che JavaScript). Puoi lavorare su diversi algoritmi allo stesso tempo aprendo o creando nuove schede di script nel menu principale. Se le modifiche attuali non sono salvate, appare un simbolo a forma di dischetto sulla linguetta.

Output di debug e script

- Quest'area di testo scrive o informazioni di debug o l'output dello script dell'algoritmo, a seconda della selezione dell'impostazione di output. Se lo script produce un errore, viene automaticamente selezionato l'output di debug. Inoltre, l'output di debug presenta anche tutti i messaggi di output del programma.

Esecuzione degli script

- Quest'area controlla l'esecuzione degli algoritmi. Puoi eseguire lo script attualmente aperto nell'editor degli script del grafo nella lavagna dell'editor visuale di grafi premendo Esegui. Mentre lo script è in esecuzione, è possibile interromperlo premendo il pulsante Interrompi.

### Barre degli strumenti

Ci sono diverse barre possibili per l'editor visuale di grafi che permettono di accedere a varie funzionalità con un solo clic. Come impostazione predefinita, sono visualizzate le seguenti barre:

- Barra principale

- Barra di allineamento

#### Barra principale

La barra principale consiste delle seguenti azioni. Fare clic su un'azione implica che il puntatore del mouse l'applica alla lavagna dell'editor visuale di grafi:

- Sposta: per selezionare gli elementi, fai clic su un'area vuota della lavagna, tieni il mouse premuto e disegna un rettangolo che contenga nodi o archi per selezionarli, oppure fai direttamente clic su un elemento non selezionato per selezionarlo. Se fai clic su uno o più elementi selezionati, li puoi spostare tenendo il mouse premuto e spostando il mouse. È possibile spostare gli elementi selezionati anche con i tasti freccia.

- Aggiungi nodo: fai clic su un punto a scelta della lavagna dell'editor visuale di grafi per creare un nuovo nodo appartenente al grafo attualmente selezionato.

- Aggiungi arco: fai clic su un nodo, tieni il mouse premuto, e traccia una linea a un altro nodo a cui il puntatore o arco punterà. Questa azione ha successo solo se il grafo attuale permette l'aggiunta di questo arco (per esempio, in un grafo non direzionale non è possibile aggiungere archi multipli tra due nodi).

- Elimina: fai clic su un elemento per eliminarlo. Se elimini un nodo, verranno eliminati anche tutti gli archi adiacenti.

- Ingrandisci: fai clic sulla lavagna, tieni premuto il &LMB;, e traccia un rettangolo. La lavagna verrà ingrandita all'area selezionata. Puoi usare anche la rotellina del mouse per ingrandire e rimpicciolire. Un doppio clic del &LMB; ripristina la scala originale.

La barra principale. La barra principale.

#### Barra di allineamento

Puoi aggiungere la barra di allineamento facoltativa. Premere un'azione di questa barra ha un effetto immediato sui nodi attualmente selezionati:

- In alto: allinea i nodi alla posizione verticale del nodo più in alto. Questo ha effetto solo sulle posizioni verticali.

- Al centro: allinea i nodi alla posizione verticale data dal centro delle posizioni verticali di tutti i nodi selezionati. Questo ha effetto solo sulle posizioni verticali.

- Base: allinea i nodi alla posizione verticale del nodo più in basso. Questo ha effetto solo sulle posizioni verticali.

- A sinistra: allinea i nodi alla posizione orizzontale del nodo più a sinistra. Questo ha effetto solo sulle posizioni orizzontali.

- Al centro: allinea i nodi alla posizione orizzontale del nodo più in alto. Questo ha effetto solo sulle posizioni orizzontali.

- A destra: allinea i nodi alla posizione orizzontale del nodo più a destra. Questo ha effetto solo sulle posizioni orizzontali.

- In cerchio: allinea i nodi in un cerchio del diametro pari alla massima distanza tra i nodi. I nodi sono posizionati nella stessa sequenza vista dal baricentro dei nodi.

- Minimizza gli incroci degli archi: applica l'algoritmo Fruchterman-Reingold per minimizzare (approssimativamente) il numero di archi che si incrociano.

La barra di allineamento. La barra di allineamento.

### Proprietà del grafo

La barra laterale sinistra contiene delle opzioni di ogni grafo aperto. Tutte queste opzioni sono globali per il grafo e possono essere cambiate per ogni nodo o arco con la finestra Proprietà del nodo e Proprietà dell'arco.

- Nome: questo è il nome che l'algoritmo deve usare per accedere al grafo.

- Il Colore dei dati si applica ai nuovi nodi creati; puoi cambiare il colore di tutti nodi presenti facendo clic sul pulsante Tutti.

- Colore dei puntatori

In fondo ci sono delle caselle:

- Mostra i nomi in: Dati o Puntatori.

- Mostra i valori in: Nodi o Archi.

## Uso di &rocs;

Di solito il primo passo è creare un grafo con l'editor visuale di grafi. Puoi farlo a mano, cioè creando nodi e collegandoli, o usando uno degli algoritmi di assistenza reperibili sotto Strumenti Genera grafo. Potresti anche usare gli strumenti sotto Strumenti Assegna valori per assegnare i valori iniziali ai nodi e agli archi del grafo. Infine devi dare un nome al grafo. Questo nome diverrà l'identificativo da usare per il motore di scripting.

### Script

&rocs; usa un linguaggio di scripting simile a JavaScript; vale a dire che le definizioni delle variabili e delle funzioni, e come vengono usate, viene fatto esattamente come un JavaScript. Inoltre, &rocs; ha una serie di funzioni che permettono di accedere ai grafi sulla lavagna dell'editor visuale di grafi e ai loro elementi.

#### Accedere a un grafo

Nell'interfaccia di scripting puoi accedere a un grafo semplicemente scrivendone il nome e usandolo come oggetto con una delle seguenti funzioni. Per accedere a un nodo o a un arco devi ottenere un identificativo dell'oggetto del grafo.

Oggetti del grafo

-     // funzioni
           array list_nodes();
           array list_edges();
           node add_node(name);
           edge add_edge(from, to);
           node node_byname(QString& name);
           node begin_node();
           array end_nodes();

      // variabili
           bool directed
           bool automate
           string name
           string nodeDefaultColor // in ESA
           string edgeDefaultColor  // in ESA

Oggetti dei nodi

-     // funzioni
           array adj_nodes();
           array adj_edges();
           array input_edges();
           array output_edges();
           array loop_edges();
           array connected_edges(Node *n);
           void self_remove();

      // variabili
          double x
          double y
          double width
          string value
          string name
          string color  // in ESA
          bool begin
          bool end

Oggetti degli archi

-     string color ( em hexa )
          string value
          string name
          double width
          string style ( dot, dash, dash dot, solid )

          node start();
          node  end();

          void self_remove();

#### Algoritmi dei grafi

A volte è utile usare le funzioni per compiti comuni, come calcolare la distanza più breve tra due nodi. Attualmente supportiamo i seguenti algoritmi, che sono richiamabili dal motore di scripting con i nodi dello stesso grafo.

Calcolo del percorso più breve

- Calcola il percorso più breve tra i nodi `inizio` e `fine`. Devono essere dello stesso grafo. Questo calcolo rispetta l'eventuale direzionalità del grafo.

      	array dijkstra_shortest_path Node* inizio Node* fine

### Esempio

Qui di seguito un semplice script di esempio che imposta il colore dei primi quattro nodi del primo grafo:

    /* Un semplice esempio che imposta il colore dei primi 4 nodi del primo
    grafo: */

    var colors = new Array("red", "green", "blue", "yellow");

    /* graphs è un array di grafi; puoi accedere ad un grafo con l'indice
    dell'array o il suo nome. Se il grafo si chiama SenzaNome0, le istruzioni
    seguenti sono corrette */
    var list1= graphs[0].list_nodes(); //  prima forma.
    var list2=SenzaNome0.list_nodes();              // seconda forma

     for ( var i = 0; i < colors.length; i++){
            if (i
    > list2.length) break;
            list2[i].color = colors[i]
     }

### Importazione ed esportazione

&rocs; attualmente supporta l'importazione e l'esportazione dei seguenti formati di file:

- File Dot, altrimenti noti come GraphViz.

- File GML

- File di testo semplice.

Attualmente, per la maggior parte di questi file vengono importati solo alcuni valori. I valori importati includono i nodi e i loro collegamenti, i nomi di tutti gli elementi, i valori, e se presenti anche le coordinate.

## Riconoscimenti e licenza

&rocs;

Copyright del programma:

- Copyright 2008 di Ugo Sangiori (ugorox@gmail.com)

- Copyright 2008-2011 di Tomaz Canabrava (tcanabrava@kde.org)

- Copyright 2008-2011 di Wagner Reck (wagner.reck@gmail.com)

- Copyright 2011 di Andreas Cord-Landwehr (cordlandwehr@googlemail.com)

Copyright della documentazione:

- Copyright della documentazione 2009 di &Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail;

- Copyright della documentazione 2009 di Tomaz Canabrava (tcanabrava@kde.org)

- Copyright della documentazione 2011 di Andreas Cord-Landwehr (cordlandwehr@googlemail.com)

Traduzione di Francesco Nigro e Federico Zenithfederico.zenith@member.fsf.org

&underFDL; &underGPL;

## Installazione

### Come ottenere &rocs;

&install.intro.documentation;

### Compilazione e installazione

&install.compile.documentation;
&documentation.index;