# El manual de &rocs;

## Introducció

En aquest capítol oferim una visió general de les principals característiques i el flux de treball de &rocs;. Per al lector impacient, que vol començar a utilitzar immediatament &rocs;, li suggerim que almenys llegeixi introduction-nutshell i que utilitzi scripting com a referència a l'hora d'escriure algorismes.

### Objectius, destinataris i flux de treball

&rocs; és un IDE per a la teoria de grafs per a tothom interessat en el disseny i anàlisi d'algorismes de graf. Això inclou explícitament

- professors, que volen demostrar algorismes als seus estudiants,

- estudiants, que volen entendre i veure com es realitza el seu algorisme,

- i tothom, que està interessat en les estructures de dades i algorismes.

Per a tots aquests usuaris, &rocs; ofereix una manera fàcil d'utilitzar l'editor d'estructura de dades per a crear estructures de dades, un motor per crear scripts de gran abast per executar algorismes i diverses eines d'ajuda per a les vostres simulacions i experiments.

El flux de treball típic quan s'utilitza &rocs; és començar creant un graf amb l'editor visual de grafs. Ho podeu fer ja sigui a mà, afegint elements de dades i la seva connexió, o utilitzant un dels generadors d'estructura de dades (si estan disponibles per al dorsal d'estructura de dades actualment seleccionat). Els generadors d'estructura de dades es poden trobar a Document de graf Eines Genera el graf. A més, podeu assignar valors als elements de l'estructura de dades, ja sigui a mà o utilitzant Document de graf Eines Assigna valors. Finalment, podeu escriure el vostre algorisme en JavaScript i executar-lo amb l'estructura de dades que acabeu de crear. Tots els canvis que realitzi el vostre l'algorisme a l'estructura de dades seran directament visibles en l'editor visual de grafs.

Una captura de pantalla de &rocs;. Una captura de pantalla de &rocs;

### &rocs; en poques paraules

En aquesta secció proporcionem una visió general compacta dels elements centrals de &rocs;. Expliquem els conceptes importants de les estructures de dades, dorsals de les estructures de dades i tipus d'elements. La comprensió d'aquests conceptes és útil per entendre com es creen i es modifiquen les estructures de dades en &rocs;.

En general &rocs; treballa amb projectes: En obrir &rocs; es crea un projecte buit i el podeu substituir carregant o important un altre projecte. En sí, un projecte consisteix en documents de graf i scripts.

#### Documents de graf i dorsals d'estructura de dades

Un document de graf representa el contingut d'una pissarra en blanc a l'editor visual de grafs. En sí, un document de graf pot contenir diverses estructures de dades alhora, però només un dorsal d'estructura de dades. Els dorsals d'estructura de dades estan presents en diversos tipus de graf (grafs en general, llistes enllaçades, arbres arrelats) i proporcionen característiques addicionals als seus tipus de graf específic. Això pot posicionar automàticament els elements, jocs d'icones especials o un conjunt ampliat de funcions d'script per utilitzar en els vostres algorismes. (Per a més detalls veure la secció corresponent del manual). És possible canviar el dorsal de l'estructura de dades d'un document de graf, tot i que es pot perdre la informació (&pex;, les arestes d'un cercle en un graf general no seran afegides a un d'arbre, si canvieu al dorsal d'arbre arrelat).

Els documents de graf també formen la base per a definir el tipus d'apuntador i els tipus de dades.

#### Estructures de dades

Les estructures de dades són la base de tot el treball en &rocs;. Podeu afegir una o diverses a un document de graf, afegir elements de dades (nodes, dades) i apuntadors a elles i modificar-los mitjançant scripts. Per això, cada estructura de dades té el seu nom únic pel qual es pot accedir des dels scripts. Segons el dorsal de l'estructura de dades triat, pot passar que no es puguin modificar arbitràriament les estructures de dades (&pex;, un arbre mai podrà contenir un cicle). El dorsal de l'estructura de dades està determinat pel dorsal d'estructura de dades associat amb el document de graf corresponent que conté l'estructura de dades.

#### Tipus d'apuntadors

Amb els tipus d'apuntador podeu definir els diferents tipus d'apuntadors que s'utilitzaran en les vostres estructures de dades. És a dir, un tipus d'apuntador pot obtenir un disseny individual (essencialment un color), de manera que serà fàcil accedir des dels vostres scripts als apuntadors només d'un tipus específic. Els casos típics d'ús d'apuntadors poden ser la implementació dels meta-arestes a les vostres estructures de dades que visualitzen les relacions entre els elements de dades (&pex;, visualitzar els interessos de comunicació). Però, a més, si els vostres scripts han d'identificar tipus específics d'arestes (&pex;, les arestes dels arbres i la creu en l'algorisme de cerca de primera profunditat), els tipus d'apuntador poden ser una manera elegant d'implementar-ho.

#### Tipus de dades

En diversos problemes d'estructura de dades, un conjunt d'elements de dades s'han de separar en grups de diferents tipus (&pex;, problemes d'agrupament o de cobertura). O és útil per a l'execució d'un algorisme per especificar un tipus d'element de dades per expressar un tipus específic (&pex;, per a la cerca primer en amplada). Per als casos d'ús d'aquest tipus podeu definir tipus de dades. Cada tipus de dades té la seva pròpia icona i podeu accedir als tipus de dades d'algun tipus fàcilment des dels vostres scripts.

#### Propietats dinàmiques

Cada element de dades i l'apuntador poden tenir moltes propietats. Algunes d'aquestes propietats són per omissió del dorsal d'estructura de dades. Per a més detalls consulteu la documentació del dorsal d'estructura de dades. Per afegir propietats addicionals als elements de dades i apuntadors, hi podeu afegir propietats dinàmiques. Cada propietat dinàmica s'identifica pel seu nom i pot contenir qualsevol valor associat amb ella. El nom ha de començar amb una lletra (a-z o A-Z) i només pot contenir lletres, nombres i «_». Si intenteu utilitzar qualsevol caràcter no vàlid en el nom de la propietat, la propietat no serà canviada.

Per afegir propietats dinàmiques, utilitzeu els diàlegs Propietats de l'element de dades i Propietats de l'apuntador des dels menús contextuals dels respectius elements o les funcions de l'script, com s'explica a scripting-data-structure.

També podeu utilitzar els scripts. Només necessitareu utilitzar la `add_property` amb el nom i el valor de la vostra propietat. Després d'això, podreu utilitzar el node/pointer.propertyName per establir/obtenir els valors.

Heus aquí un exemple de com utilitzar les propietats dinàmiques amb el dorsal d'estructura de dades «Graf».

    nodes = myGraph.list_nodes()
    for (var i = 0; i < nodes.length; ++i ){
        nodes[i].add_property("MyProperty", 0)
    }
    nodes[0].MyProperty = 2
    nodes[1].MyProperty = nodes[0].MyProperty + 2

### Guia d'aprenentatge

En aquesta secció volem crear un projecte d'exemple per explorar algunes de les característiques més importants de &rocs;. L'objectiu és crear un graf i un script que il·lustri un algorisme d'aproximació a 2 simple per al problema cobertura de vèrtexs mínima. En aquest problema s'han de trobar un subconjunt de nodes del graf C de mida mínima, de manera que cada aresta del graf estarà connectada a almenys un node de C. Se sap que aquest problema és NP-complex i volem il·lustrar com trobar una aproximació de factor 2 cercant una coincidència en el graf donat (en el que segueix utilitzarem la terminologia comuna per als algorismes de graf: un graf és l'estructura de dades, els nodes són els elements de dades i les arestes són els apuntadors).

El nostre objectiu és visualitzar la correspondència de les coincidències i la cobertura de vèrtexs mínima. Per això, volem especificar dos tipus d'apuntadors, un per mostrar les arestes coincidents i un per mostrar arestes comunes, així com dos tipus de dades que utilitzarem per distingir els nodes continguts en C i els que no estan continguts en C.

#### Generar un graf

Per al dorsal d'estructura de dades Graf, &rocs; ofereix una eina d'ajuda que pot generar grafs. Anem a Document de graf Eines Genera el graf. Cal que generem un Graf aleatori amb 30 nodes, 90 arestes i amb 1 llavor (la llavor és la llavor inicial per al generador de grafs aleatoris; si s'utilitza la mateixa llavor diverses vegades es tornaran a reproduir els mateixos grafs). Finalment, modificarem el nom del graf en el plafó de l'estructura de dades i cridarem al graf `testgraph`.

#### Crear els tipus

Utilitzarem el botó Propietats a la barra del selector de documents per obrir el diàleg de propietats per als tipus de dades i d'apuntador del document de graf actual. Per al tipus de dades afegirem un nou tipus anomenat «C», el qual obtindrà automàticament l'ID `1`. Per aquest tipus seleccionarem la imatge del servidor com a icona. A més, canviarem a la pàgina tipus d'apuntador i afegirem un nou tipus d'apuntador anomenat «coincident». Això ens durà automàticament a l'ID `1` i establirem el color a blau.

#### L'algorisme

Per acabar, hem d'implementar l'algorisme d'aproximació. Per això utilitzarem la següent implementació:

    var E = testgraph.list_edges(); // conjunt d'arestes sense processar
    var C = new Array();            // arestes coincidents
    while (E.length
    > 0) {
        var e = E[0];        // prenem la primera aresta e={u,v}
        var u = e.start();
        var v = e.end();
        e.set_type(1);       // establim l'aresta com a coincident
        E.shift();           // eliminem «e» (és a dir, E[0]) des de la llista d'arestes
        C.push(u);           // afegim «u» a «C»
        C.push(v);           // afegim «v» a «C»

        // marquem «u,v» com a nodes en «C»
        u.set_type(1);
        v.set_type(1);

        // eliminem de «E» totes les arestes adjacents a «u» o «v»
        var adjacent = u.adj_edges();
        for (var i=0; i < adjacent.length; i++) {
            var index = E.indexOf(adjacent[i]); // troba l'índex
            if (index!=-1) {
                E.splice(index, 1); // l'elimina si ja s'ha trobat
            }
        }
        var adjacent = v.adj_edges();
        for (var i=0; i < adjacent.length; i++) {
            var index = E.indexOf(adjacent[i]); // troba l'índex
            if (index!=-1) {
                E.splice(index, 1); // l'elimina si ja s'ha trobat
            }
        }
    }
    Console.log("Vertex Cover conté " + C.length + " nodes.");

#### Executar l'algorisme

Finalment volem executar l'algorisme. Per això podem iniciar l'execució amb el botó Executa al plafó de control de l'script.

## La interfície d'usuari de &rocs;

### Elements generals de la interfície d'usuari

La interfície d'usuari es divideix en diverses parts lògiques que es presenten en la següent captura de pantalla.

Elements de la &IGU; de la interfície de &rocs;. Elements de la &IGU; de la interfície de &rocs;.

Selector de documents

- En aquesta barra de menú superior haureu de seleccionar el document actual i l'estructura de dades. Des d'on també és possible crear i eliminar estructures de dades així com accedir a les propietats de l'estructura de dades.

Editor visual de grafs

- Aquesta és la pissarra en blanc on es poden crear i modificar les estructures de dades. Feu clic dret a la pissarra, en els elements de dades, o en els apuntadors per obrir els menús contextuals. Podeu utilitzar les eines de la barra d'eines Editor visual de grafs per modificar els elements a la pissarra de l'editor visual de grafs.

La barra d'eines Editor visual de grafs

- Aquesta barra d'eines proporciona totes les eines per a l'editor visual de grafs. Utilitzeu els botons Afegeix element o Afegeix connexió per crear nous elements o per connectar elements, respectivament. S'afegeixen nous elements de dades a l'estructura de dades que es troba seleccionada a la barra Selector de documents. Recordeu que tant els botons Afegeix element com Afegeix connexió tenen menús per a seleccionar el tipus dels elements que seran creats. Per a més detalls, veure user-interface-toolbars.

Barra lateral

- A la dreta, trobareu la barra lateral que proporciona diverses eines per al vostre flux de treball:

  - Tipus d'element: Aquest estri us permet accedir directament a l'apuntador i als tipus de dades disponibles.

  - Diari: Cada projecte disposa del seu propi diari que es pot utilitzar per, &pex;, anotar tasques, resultats o observacions.

  - Manual: Podeu obrir aquest estri per obtenir accés directe al manual i a través seu a la documentació dels scripts.

  - API per a crear scripts: Per obtenir accés directe a la documentació dels scripts, podeu obrir aquest estri.

Editor d'scripts

- En aquest editor de text podeu escriure algorismes com s'explica en detall en scripting. Podeu treballar sobre diversos documents d'script simultàniament utilitzant diverses pestanyes. Si l'script conté canvis sense desar a la pestanya apareixerà el símbol d'un disc.

Sortida de l'script

- Aquesta àrea de text bé mostra informació de depuració o la sortida de l'script del vostre algorisme, depenent de la preferència indicada a la part superior d'aquest estri. Si l'script retorna un error, automàticament es presentarà la sortida de depuració.

Controls

- Aquí trobareu els controls per a l'execució d'scripts. Podeu executar l'script que està obert a l'editor d'scripts prement Executa. Mentre s'executa l'script, és possible aturar l'execució prement el botó Atura. Tingueu en compte que l'execució amb Un pas sols s'aturarà a les paraules clau específiques (veure scripting).

### Barres d'eines

Hi ha diferents barres d'eines per a l'editor visual de grafs que us permeten accedir a les funcions amb un sol clic. Per omissió, es mostren les següents barres d'eines:

- Barra d'eines principal

- Barra d'eines d'alineació

#### Barra d'eines principal

La barra d'eines principal es compon de les següents accions. El fer clic sobre una acció significa que el punter del ratolí aplica aquesta acció a la pissarra de l'editor visual de grafs:

- Moure: Per a seleccionar elements, o bé feu clic sobre l'espai sense utilitzar a la pissarra, manteniu premut el ratolí i dibuixeu un rectangle que contingui alguns elements de dades i/o apuntadors per a seleccionar aquests elements o en cas contrari feu clic directament sobre un element sense seleccionar per seleccionar-lo. Si feu clic sobre un element o conjunt d'elements seleccionats, respectivament, els podreu moure mantenint premut el ratolí i movent-lo. També és possible moure els elements seleccionats amb les tecles del cursor.

- Afegeix element: Feu clic sobre una posició arbitrària a la pissarra de l'editor visual de grafs per crear un nou element de dades que pertanyi a l'estructura de dades actualment seleccionada. Si manteniu premut el punter del ratolí sobre el botó, es mostrarà un menú des d'on es podran seleccionar (només si hi ha diferents tipus de dades) els tipus de dades dels nous elements de dades creats.

- Afegeix connexió: Feu clic sobre un element de dades, manteniu premut el ratolí i dibuixeu una línia cap a un altre element de dades al qual assenyali l'apuntador/aresta. Aquesta acció només té èxit si el graf actual permet afegir aquesta aresta (&pex;, en un graf no dirigit no podreu afegir múltiples arestes entre dos elements de dades). Si manteniu premut el punter del ratolí sobre el botó, es mostrarà un menú des d'on es podran seleccionar (només si hi ha diferents tipus d'apuntador) els tipus d'apuntador dels nous elements de dades creats.

- Elimina: Feu clic sobre un element per eliminar-lo. Si elimineu un node, totes les arestes adjacents també s'eliminaran.

- Zoom: Feu clic sobre la pissarra, manteniu premut el &BER; i dibuixeu un rectangle. La pissarra s'ampliarà a la zona seleccionada. Utilitzant també la roda del ratolí per apropar o allunyar. Un doble clic amb el &BER; restaura el zoom original.

#### Barra d'eines d'alineació

Podeu afegir l'opcional barra d'eines d'alineació. En prémer sobre una acció en aquesta barra d'eines tindrà un efecte directe en els nodes seleccionats:

- Dalt: Alinea els elements de dades a la posició vertical de l'element de dades més superior. Això només afecta a les posicions verticals.

- Centre: Alinea els elements de dades a la posició vertical donada pel centre de totes les posicions verticals dels elements de dades seleccionats. Això només afecta a les posicions verticals.

- Base: Alinea els elements de dades a la posició vertical de l'element de dades més inferior. Això només afecta a les posicions verticals.

- Esquerre: Alinea els elements de dades a la posició horitzontal de l'element de dades més a l'esquerra. Això només afecta a les posicions horitzontals.

- Centre: Alinea els elements de dades a la posició horitzontal de l'element de dades més superior. Això només afecta a les posicions horitzontals.

- Dreta: Alinea els elements de dades a la posició horitzontal de l'element de dades més a la dreta. Això només afecta a les posicions horitzontals.

- Cercle: Alinea els elements de dades en un cercle de diàmetre igual que la distància màxima entre els elements de dades. Els elements de dades estan col·locats en la mateixa seqüència que la proposta per vista des del centre de gravetat d'aquests elements de dades.

- Minimitza els creuaments d'arestes: Torna a organitzar els elements de dades seleccionats per a minimitzar el nombre de connexions creuades (aplicació de l'algorisme Fruchterman-Reingold).

### Treballar amb documents de graf

Un projecte de &rocs; conté un o múltiples documents de graf que es poden editar amb l'editor visual de grafs. A més, cada document pot contenir un nombre arbitrari d'estructures de dades. En aquest cas, totes les estructures de dades d'un document utilitzen el mateix dorsal per a l'estructura de dades. En aquesta secció explicarem com canviar entre els documents i la manera de crear-ne de nous.

#### La barra selector de documents

La barra selector de documents s'utilitza per seleccionar el document de graf i també l'estructura de dades. Quan utilitzeu les eines de l'editor visual de grafs per crear elements d'estructures de dades, els nous elements creats s'afegiran automàticament a l'estructura de dades actual. A més, aquesta barra ofereix accés directe a eliminar els ja existents o crear noves estructures de dades dins del document actual.

- Nou: Aquesta acció crea una nova estructura de dades utilitzant un patró de nomenclatura automàtica proposta pel dorsal de l'estructura de dades. L'estructura de dades creada s'afegirà al document de graf seleccionat.

- Elimina: Aquesta acció elimina l'estructura de dades que es troba seleccionada en el selector d'estructura de dades per al document actual.

- Propietats per al Document de graf: Obre un diàleg que permet accedir a les propietats del document, així com als tipus de dades i d'apuntador del document.

- Propietats per a Estructura de dades: Obre un diàleg que permet accedir a les propietats de l'estructura de dades.

La barra d'eines principal La barra selector de documents.

#### Crear i importar documents de graf

Per crear un nou document de graf o afegir un d'existent al projecte, utilitzeu Fitxer Projecte nou o Document de graf Importa un graf. També podreu importar documents de graf des d'aplicacions de tercers (per a això, veure import-export).

## Escriure i executar algorismes en &rocs;

&rocs; utilitza internament el motor per a la creació d'scripts QtScript, el qual és un motor específic de JavaScript. Això significa que tots els algorismes que implementeu hauran d'utilitzar JavaScript. Com funciona JavaScript i com escriure codi no està cobert per aquest manual, encara que s'explica com accedir a les estructures de dades, elements de dades i apuntadors de les estructures de dades del motor per crear scripts. Atès que mai utilitzareu l'objecte d'estructura de dades bàsica, sinó el proporcionat pel dorsal d'estructura de dades utilitzat actualment, la funcionalitat de l'estructura de dades s'estén pel dorsal corresponent i haureu de fer una ullada a la funcionalitat especialitzada. Sobretot, els dorsals d'estructura de dades utilitzant la terminologia comuna del vostre domini (nodes i arestes en els grafs, les fulles i les arrels en els arbres, &etc;)

És important saber que els canvis fets pel motor per a la creació d'scripts es reflecteixen directament en les propietats a la pissarra de l'editor visual de grafs. Per tant, els scripts en realitat modifiquen les estructures de dades.

### Controlar l'execució de l'script

#### Incloure fitxers

Els vostres documents d'script poden incloure altres scripts. Això pot ser útil per reduir la mida dels documents d'script i millorar la llegibilitat. Utilitzant Document d'script Inclusions possibles obtindreu una llista de fitxers d'script que ja vénen amb &rocs; i que podeu incloure. Podeu incloure un fitxer d'script amb la següent ordre:

    include_script(string path);            // camí relatiu o absolut a un fitxer d'script

#### Sortida de l'script

Durant l'execució d'un algorisme, la sortida de depuració i del programa es mostren a la depuració i sortida de l'script. Si el motor per a la creació d'scripts detecta un error de sintaxi, l'error també es mostrarà com a missatge de depuració. Tingueu en compte que tots els missatges del programa també es mostraran a la sortida de depuració (com a text en negreta).

Podeu controlar el text que es mostrarà a la sortida de l'script mitjançant les següents funcions:

    Console.log(string message);            // mostra el missatge com a sortida de l'script
        Console.debug(string message);      // mostra el missatge com a sortida de depuració

#### Controlar l'execució de l'script

Hi ha diferents modes d'execució per als vostres scripts.

Podeu controlar el text que es mostrarà a la sortida de l'script mitjançant les següents funcions:

- Executa: Executa l'script fins finalitzar.

- Un pas: Executa l'script fins que finalitza un pas. Un pas finalitza quan l'script crida la funció `interrupt()`:

      interrupt();    // finalitza un pas

- Depura: Executa l'script en mode de depuració. Això obre el diàleg de depuració de QtScript.

- Atura: Atura l'execució de l'script (sols disponible si s'executa un script).

## L'API per a la creació d'scripts

Cada dorsal proporciona un conjunt especial de funcions i propietats de les seves estructures de dades i els seus elements. Però cada dorsal també proporciona les propietats i funcions definides per l'estructura de dades base.

&apiDatastructure; &apiGraphstructure; &apiLinkedListstructure; &apiRootedTreestructure; &apiConsole;
&chapterImportExport;

## Crèdits i llicència

&rocs;

Copyright del programa:

- Copyright 2008 Ugo Sangiori (ugorox AT gmail.com)

- Copyright 2008-2012 Tomaz Canabrava (tcanabrava AT kde.org)

- Copyright 2008-2012 Wagner Reck (wagner.reck AT gmail.com)

- Copyright 2011-2013 Andreas Cord-Landwehr (cordlandwehr AT kde.org)

Copyright de la documentació:

- Copyright de la documentació 2009 &Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail;

- Copyright de la documentació 2009 Tomaz Canabrava (tcanabrava AT kde.org)

- Copyright de la documentació 2011-2013 Andreas Cord-Landwehr (cordlandwehr AT kde.org)

Traductor de la documentació: &credits.Antoni.Bella;

&underFDL; &underGPL;

## Instal·lació

### Com obtenir el &rocs;

&install.intro.documentation;

### Compilació i instal·lació

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