# Das Handbuch zu &rocs;

## Einführung

In diesem Kapitel finden Sie einen Überblick über die Funktionen und den Arbeitsablauf in &rocs;. Leser, die sofort mit &rocs; beginnen möchten, sollten auf jeden Fall introduction-nutshell lesen und scripting beim Schreiben von Algorithmen als Referenz benutzen.

### Ziel, Zielgruppe und Arbeitsablauf

&rocs; ist eine Entwicklungsumgebung für Graphen-Theorie für Alle, die an der Entwicklung und Analyse von Graphen-Algorithmen arbeiten, unter anderem:

- Lehrer, die Ihren Studenten Algorithmen demonstrieren möchten,

- Studenten, die verstehen und sehen möchten, wie ein Algorithmus funktioniert,

- Und alle, die an Datenstrukturen und Algorithmen interessiert sind

Für alle diese Benutzer stellt &rocs; einen einfach zu bedienenden Editor für die Erstellung von Datenstrukturen, ein leistungsfähiges Skriptmodul zur Ausführung von Algorithmen und mehrere Hilfswerkzeuge für Ihre Simulationen und Experimente bereit.

Beim typischen Arbeitsablauf erstellen Sie als erstes einen Graphen mit dem visuellen Editor. Den Graphen können Sie von Hand erstellen, indem Sie Datenelemente hinzufügen und sie verbinden. Wenn es einen Generator für die ausgewählte Backend der aktuellen Datenstruktur gibt, können Sie alternativ auch aus dem Menü Graphendokument Extras Graphen erstellen verwenden. Mit Graphendokument Extras Werte zuweisen ist es auch möglich, den Datenstrukturelementen eines Graphen Werte zuzuweisen. Zum Schluß müssen Sie den Algorithmus in der Sprache JavaScript schreiben und mit der gerade erstellten Datenstruktur ausführen. Alle Änderungen an der Datenstruktur durch den Algorithmus sind sofort auf der Zeichenfläche des visuellen Graphen-Editors sichtbar.

Bildschirmphoto von &rocs; Bildschirmphoto von &rocs;

### &rocs; kurz zusammengefasst

Dieser Abschnitt enthält eine knappe Übersicht über die wichtigsten Elemente von &rocs;. Die wichtigen Begriffe Datenstrukturen, Backends für Datenstrukturen und Elementarten werden erläutert. Kenntnis dieser Elemente hilft beim Verständnis, wie Datenstrukturen in &rocs; erstellt und geändert werden können.

Im allgemeinen arbeitet &rocs; mit Projekten: wenn Sie &rocs; starten, wird ein leeres Projekt erstellt. Dieses Projekt können Sie durch Laden oder Importieren eines anderen Projekts ersetzen. Ein Projekt besteht aus Graphendokumenten und Skripten.

#### Backends für Graphendokumente und Datenstrukturen

Ein Graphendokument repräsentiert den Inhalt der Zeichenfläche im visuellen Graphen-Editor.Daher kann ein Graphendokument gleichzeitig mehrere Datenstrukturen, aber nur ein Backend für Datenstrukturen enthalten. Es gibt Backends für Datenstrukturen für mehrere Graphentypen (Allgemeine Graphen, verkettete Listen, Wurzelbäume), die zusätzliche Funktionen beinhalten wie zum Beispiel automatische Anordnung der Elemente, besondere Symbole oder erweiterte Skriptfunktionen, die in Algorithmen benutzt werden können. Es ist möglich, das Backend der Datenstruktur eines Graphendokuments zu ändern, dabei gehen aber unter Umständen Informationen verloren. Es werden zum Beispiel die Kanten eines Kreises in einem allgemeinen Graphen nicht zu einer Baumstruktur hinzugefügt, wenn Sie zum Backend Wurzelbaum wechseln.

Graphendokumente bilden auch die Basis für die Definition von Zeiger- und Datentypen.

#### Datenstrukturen

Datenstrukturen sind die Grundlage aller Arbeit mit &rocs;. Sie können eine oder mehrere Datenstrukturen zu einem Graphendokument hinzufügen, Datenelemente (Knoten, Daten) und Zeiger auf Knoten einfügen und sie mit Skripten bearbeiten. Dazu hat jede Datenstruktur einen eindeutigen Namen oder Bezeichner, über den im Skript auf die Struktur zugegriffen werden kann. Für ein aktuell ausgewähltes Backend der Datenstruktur können die Datenstrukturen nicht willkürlich geändert werden, ⪚ darf eine Baumstruktur keine Kreisstruktur haben. Die Datenstruktur wird durch das verwendete Struktur-Backend aus dem Graphendokument, das dieses Backend enthält, vorgegeben

#### Zeigertypen

Es lassen sich verschiedene Zeigertypen definieren, die in Datenstrukturen verwendet werden können. Ein Zeigertyp kann ein individuelles Layout - im wesentlichen eine Farbe - erhalten. Es ist dann leicht möglich, Zugriff nur auf Zeiger eines bestimmten Typs in den Skripten zu erhalten. Ein typischer Anwendungsfall für Zeiger ist die Implementierung von Metakanten einer Datenstruktur, um Beziehungen zwischen Datenelementen zu visualisieren. Aber auch wenn das Skript bestimmte Arten von Kanten wie zum Beispiel Baum- und Kreuzkanten bei einer Tiefensuche (englisch depth-first search) identifizieren soll, sind Zeigertypen ein elegante Implementation dafür.

#### Datentypen

Bei vielen Problemen, die mit Datenstrukturen bearbeitet werden, sollte eine Gruppe von Datenelementen in eigene Strukturtypen aufgeteilt werden, ⪚ bei Cluster- und Überdeckungsproblemen. Für die Ausführung eines Algorithmus ist es nützlich, einen Datenelementtyp für einen bestimmten Typ wie zum Beispiel Breitensuche (english breadth-first search) anzugeben. Für solche Anwendungsfälle können eigene Datentypen definiert werden. Jeder Datentyp hat ein eigenes Symbol. Für eigene definierte Datentypen ist der Zugriff vom Skript leicht möglich.

#### Dynamische Eigenschaften

Jedes Datenelement und jeder Zeiger kann viele Eigenschaften haben. Einige dieser Eigenschaften werden als Standard vom Backend der Datenstruktur vorgegeben. Weitere Informationen dazu finden Sie in der Dokumentation zu den Backends der Datenstrukturen. Um die Eigenschaften von Datenelementen und Zeigern zu erweitern, können dynamische Eigenschaften hinzugefügt werden. Jede dynamische Eigenschaft wird über ihren Namen identifiziert und darf einen beliebigen zugeordneten Wert haben. Der Name muss mit einem Buchstaben (a-z oder A-Z) beginnen und darf nur Buchstaben, Zahlen und den Unterstrich „_“ enthalten. Wenn Sie ungültige Zeichen im Namen der Eigenschaft verwenden, wird die Eigenschaft nicht geändert.

Um dynamische Eigenschaften hinzuzufügen, können Sie die Dialoge Dateneigenschaften und Zeigereigenschaften aus dem Kontextmenü der entsprechenden Elemente oder die Skriptfunktionen benutzen, die im Abschnitt scripting-data-structure erläutert werden.

Sie können auch Skripte dafür verwenden. Sie müssen nur `add_property` mit dem Namen und Wert Ihrer Eigenschaft verwenden. Danach können Sie mit `node.propertyName` oder `pointer.propertyName` die Werte lesen oder setzen.

Hier ein Beispiel, wie dynamische Eigenschaften mit dem Backend für die Datenstruktur „Graph“ benutzt werden können.

    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

### Anleitung

In diesem Abschnitt wird ein Beispielprojekt erzeugt, um die wichtigsten Funktionen von &rocs; zu zeigen. Als Ziel soll ein Graph und ein Skript erstellt werden, um damit einen einfachen Approximationsalgorithmus für das Minimum-Knotenüberdeckungproblem zu zeigen, der eine Knotenüberdeckung mit Güte 2 berechnet. Mit dem Minimum-Knotenüberdeckungsproblem wird eine Untermenge von Graphenknoten C mit minimaler Größe gesucht, so dass jede Graphenkante mit mindestens einem Knoten in C verbunden ist. Dies Problem ist NP-vollständig. Es soll gezeigt werden, wie eine Approximation mit dem Faktor 2 durch Suchen nach Matching in den angegebenen Graphen gefunden wird. Im Folgenden werden die üblichen Begriffe für Graphenalgorithmen verwendet: Graph für die Datenstruktur, Knoten für die Datenelemente und Kanten für die Zeiger.

Ziel ist die Visualisierung der Übereinstimmung von Matching-Knotenüberdeckungen und Minimum-Knotenüberdeckungen. Dazu werden zwei Zeigertypen definiert, einer für die Matching-Kanten und einer zur Darstellung normaler Kanten, außerdem noch zwei Datentypen, die zur Unterscheidung von in C enthaltenen bzw. nicht enthaltenen Knoten verwendet werden.

#### Einen Graphen erstellen

Für das Backend der Datenstruktur „Graph“ können mit &rocs; Graphen erzeugt werden. Wählen Sie dazu Graphendokument Extras Graph erstellen. Erstellen Sie einen „Zufälligen Graphen“ mit 30 Knoten, 90 Kanten und mit Seed = 1. Seed ist der Startwert für den Generator des zufälligen Graphen. Wird der gleiche Seed verwendet, ergibt das auch reproduzierbar den gleichen Graphen. Dann ändern Sie den Namen des Graphen im Datenstrukturbereich in `testgraph`.

#### Typen erstellen

Klicken Sie auf ein Datenelement oder eine Verbindung im Datenstrukturbereich, um den Einstellungsdialog für Daten- und Zeigertypen des aktuellen Dokuments zu öffnen. Als Datentyp wird ein neuer Typ namens „C“ hinzugefügt. Dieser erhält automatisch die Kennung `1`. Als Symbol wird das Serverbild ausgewählt. Dann wird der Dialog Eigenschaften des Zeigertyps geöffnet und ein neuer Zeigertyp mit dem Namen „matching“ erstellt. Er erhält automatisch die Kennung `1`. Als Farbe wird Blau eingestellt.

#### Der Algorithmus

Dann muss der Algorithmus der Approximation wie im folgenden implementiert werden:

    var E = testgraph.list_edges(); // Menge der nicht bearbeiteten Kanten
    var C = new Array();            // Matching-Kanten
    while (E.length
    > 0) {
        var e = E[0];        // die erste Kante e={u,v}
        var u = e.start();
        var v = e.end();
        e.set_type(1);        // als Matching-Kanten setzen
        E.shift();            // e (i.e., E[0]) aus der Liste der Kanten entfernen
        C.push(u);            // u zu C hinzufügen
        C.push(v);            // v zu C hinzufügen

        // u,v als Knoten von C markieren C
        u.set_type(1);
        v.set_type(1);

        // von E alle Kanten entfernen, die inzident zu u oder v sind
        var adjacent = u.adj_edges();
        for (var i=0; i < adjacent.length; i++) {
            var index = E.indexOf(adjacent[i]); // Index suchen
            if (index!=-1) {
                E.splice(index, 1); // Löschen, wenn gefunden
            }
        }
        var adjacent = v.adj_edges();
        for (var i=0; i < adjacent.length; i++) {
            var index = E.indexOf(adjacent[i]); // Index suchen
            if (index!=-1) {
                E.splice(index, 1); // Löschen, wenn gefunden
            }
        }
    }
    output("Knotenüberdeckung enthält " + C.length + " Knoten.");

#### Ausführung des Algorithmus

Schließlich soll der Algorithmus ausgeführt werden. Die Ausführung wird mit dem Knopf Ausführen der Bedienelemente für Skripte gestartet.

## Die Benutzerschnittstelle von &rocs;

### Standardelemente der Benutzeroberfläche

Die Benutzerschnittstelle besteht aus mehreren logischen Teilen, die im folgenden Bildschirmfoto gezeigt werden.

Bedienungselemente der &rocs;-Benutzeroberfläche Bedienungselemente der &rocs;-Benutzeroberfläche

Dokumentenauswahl

- In dieser Werkzeugleiste wird das aktuelle Dokument und die Datenstruktur ausgewählt. Erstellen und Löschen von Datenstrukturen wie auch das Ändern der Eigenschaften von Datenstrukturen ist hier möglich.

Visueller Graphen-Editor

- Dies ist die Zeichenfläche, auf der Datenstrukturen erstellt und bearbeitet werden. Klicken Sie mit der &RMBn; auf die Zeichenfläche, auf Datenelemente oder Zeiger, um die zugehörigen Kontextmenüs zu öffnen. Sie können auch die Aktionen aus der Werkzeugleiste benutzen, um die Elemente auf der Zeichenfläche zu bearbeiten.

Werkzeugleiste für den visuellen Graphen-Editor

- In dieser Werkzeugleiste finden Sie Aktionen für den visuellen Graphen-Editor. Mit Daten hinzufügen oder Verbindungen hinzufügen können neue Datenelemente erstellt und Verbingungen hinzugefügt werden. Neue Datenelemente werden zu der aktuellen Datenstruktur in der Dokumenten-Auswahl hinzugefügt. Beachten Sie dass Daten hinzufügen und auch Verbindungen hinzufügen Untermenüs enthalten können, um den Typ der neuen Elemente auszuwählen. Weitere Informationen dazu im Abschnitt user-interface-toolbars.

Seitenleiste

- Rechts finden Sie die Seitenleiste mit mehreren Werkzeugen zur Unterstützung Ihres Arbeitsablaufs.

  - Elementtypen: Hier haben Sie direkten Zugriff auf alle vorhandenen Zeiger- und Datentypen.

  - Journal: Für jedes Projekt gibt es ein Journal, um ⪚ Aufgaben, Ergebnisse oder Beobachtungen festzuhalten.

  - Dokumentation: Benutzen Sie dieses Fenster zu Zugriff auf das Handbuch und dadurch auch zur Skriptdokumentation.

Skripteditor

- In diesem Texteditor können Sie Algorithmen schreiben, das wird im scripting erläutert. Sie können gleichzeitig an mehreren Skriptdokumenten arbeiten, indem Sie Unterfenster verwenden. Enthält ein Unterfenster noch nicht gespeicherte Änderungen, dann wird ein kleines Diskettensymbol auf dem Karteireiter angezeigt.

Skriptausgabe

- In diesem Textfeld werden Fehlermeldungen oder Skriptausgaben Ihres Algorithmus angezeigt, abhängig von der gewählten Einstellung der Ausgabe oben. Tritt ein Fehler in Ihrem Skript auf, wird automatisch die Fehlerausgabe angezeigt.

Bedienelemente

- In diesem Bereich finden Sie die Bedienelelemente, um die Ausführung von Skripten zu steuern. Mit dem Knopf Ausführen starten Sie das aktuell im Editor geöffnete Skript. Wird ein Skript ausgeführt, können Sie es mit Anhalten stoppen. Beachten Sie, dass die Ausführung von Ein Schritt nur bei bestimmten Schlüsselwörtern anhält, siehe scripting.

### Werkzeugleisten

Es gibt mehrere verschiedene Werkzeugleisten für den visuellen Graphen-Editor, die den Zugriff auf alle Aktion mit einem Mausklick ermöglichen. In der Voreinstellung werden folgende Werkzeugleisten angezeigt:

- Haupt-Werkzeugleiste

- Layout-Werkzeugleiste

#### Haupt-Werkzeugleiste

Die Haupt-Werkzeugleiste enthält die im Folgenden genannten Aktionen. Klicken Sie auf den Knopf für eine Aktion, dann können Sie diese Aktion anschließend mit dem Mauszeiger auf die Elemente auf der Zeichenfläche anwenden.

- Verschieben: Um Elemente auszuwählen, klicken Sie entweder mit der &LMBn; auf eine freie Stelle auf der Zeichenfläche, halten die Maustaste gedrückt und ziehen ein Rechteck um Datenelemente und/oder Zeiger, um sie auszuwählen oder klicken Sie sonst zur Auswahl auf ein nicht ausgewähltes Element. Klicken Sie dann auf ein oder mehrere ausgewählte Elemente und verschieben sie mit gedrückter Maustaste. Ausgewählte Elemente können auch mit den Pfeiltasten verschoben werden.

- Daten hinzufügen: Klicken Sie mit der &LMBn; auf eine beliebige Position auf der Zeichenfläche, um ein neues Datenelement für die gerade ausgewählte Datenstruktur zu erstellen. Halten Sie die Maustaste gedrückt, dann erscheint ein Menü, aus dem der Datentyp des neu erstellten Datenelements ausgewählt werden kann, wenn es mehrere Datentypen gibt.

- Verbindung hinzufügen: Klicken Sie mit der &LMBn; auf ein Datenelement, halten Sie die Maustaste gedrückt und ziehen Sie eine Linie zu einem anderen Datenelement. Diese Aktion kann nur dann ausgeführt werden, wenn beim aktuellen Graphen diese Kante hinzugefügt werden kann. In einem ungerichteten Graphen dürfen Sie ⪚ nicht mehrere Kanten zwischen zwei Datenelementen einfügen. Halten Sie die Maustaste gedrückt, dann erscheint ein Menü, aus dem der Datentyp des neu erstellten Zeigers ausgewählt werden kann, wenn es mehrere Zeigertypen gibt.

- Löschen: Klicken Sie auf ein Element, um es zu löschen. Löschen Sie einen Knoten, dann werden alle anliegenden Kanten ebenfalls gelöscht.

- Vergrößerung: Klicken Sie auf die Zeichenfläche, halten Sie die &LMB; gedrückt und zeichnen Sie ein Rechteck. Die Zeichenfläche wird auf diesen gewählten Bereich vergrößert. Mit dem Mausrad können Sie die Ansicht ebenfalls vergrößern bzw. verkleinern. Doppelklicken mit der &LMBn; stellt die ursprüngliche Vergrößerung wieder her.

#### Layout-Werkzeugleiste

Weiterhin gibt es noch die zusätzliche Layout-Werkzeugleiste. Drücken Sie einen Knopf in dieser Werkzeugleiste, dann wird die Aktion direkt an aktuell ausgewählten Knoten ausgeführt:

- Oben: Richtet die Datenelemente an der senkrechten Position des obersten Datenelements aus. Die waagerechte Position bleibt unverändert.

- Mittig: Richtet die Datenelemente an der senkrechten Position aus, die durch die Mitte der senkrechten Positionen aller ausgewählten Datenelemente bestimmt wird. Die waagerechte Position bleibt unverändert.

- Unten: Richtet die Datenelemente an der senkrechten Position des untersten Datenelements aus. Die waagerechte Position bleibt unverändert.

- Mittig: Richtet die Datenelemente an der waagerechten Position des obersten Datenelements aus. Die senkrechte Position bleibt unverändert.

- Mittig: Richtet die Datenelemente an der waagerechten Position des obersten Datenelements aus. Die senkrechte Position bleibt unverändert.

- Rechts: Richtet die Datenelemente an der waagerechten Position des rechten Datenelements aus. Die senkrechte Position bleibt unverändert.

- Kreis: Richtet die Datenelemente auf einem Kreis mit dem größten Abstand der Datenelemente als Durchmesser aus. Die Datenelemente werden in der Reihenfolge angeordnet, die sich aus der Sicht des Schwerpunkts der durch die Datenelemente gebildeten Fläche ergibt.

- Kreuzende Kanten minimieren: Verwendet den Fruchterman-Reingold-Algorithmus, um durch eine geänderte Anordnung der Datenelemente die Anzahl der kreuzenden Verbindungen zu minimieren.

### Arbeiten mit Graphendokumenten

Ein &rocs;-Dokument enthält ein oder mehrere Graphendokumente, die mit dem visuellen Grapheneditor bearbeitet werden können. Jedes Dokument kann eine beliebige Anzahl von Datenstrukturen enthalten. Die Datenstrukturen eines Dokuments verwenden alle das gleiche Backend für Datenstrukturen. In diesem Abschnitt wird erläutert, wie Sie zwischen Dokumenten wechseln und neue Dokumente erzeugen.

#### Die Dokumentenauswahl-Leiste

In der Dokumentenauswahl-Leiste kann das aktuelle Graphendokument und auch die verwendete Datenstruktur ausgewählt werden. Die mit dem visuellen Grapheneditor erzeugten Elemente werden automatisch zur aktuellen Datenstruktur hinzugefügt. In dieser Leiste gibt es außerdem auch Aktionen, um vorhandene Datenstrukturen zu löschen und neue Datenstrukturen im aktuellen Dokument hinzuzufügen.

- Neu: Diese Aktion erzeugt neue Datenstrukturen mit einem automatisch generierten Namensmuster, das vom an der Backend der Datenstruktur vorgegeben wird. Die erzeugte Datenstruktur wird zum aktuell ausgewählten Graphendokument hinzugefügt.

- Löschen: Mit dieser Aktion wird die aktuell ausgewählte Datenstruktur aus dem aktuellen geöffneten Dokument entfernt.

- Eigenschaften der Datenstruktur: Öffnet einen Dialog zum Zugriff auf die Eigenschaften von Datenstrukturen.

- Dokument-Eigenschaften: Öffnet einen Dialog mit Zugriff auf die Eigenschaften eines Dokuments und auch die Daten- und Zeigertypen des Dokuments.

Die Haupt-Werkzeugleiste. Die Dokumentenauswahl-Leiste.

#### Erstellen und Importieren von Graphendokumenten

Um ein neues Graphendokument zu erstellen oder ein vorhandenes zum Projekt hinzuzufügen, benutzen Sie Projekt Neues Graphendokument oder Projekt &rocs;-Graphen importieren. Sie können auch Graphendokumente aus anderen Programmen importieren, siehe import-export.

## Schreiben und Ausführen von Algorithmen in &rocs;

&rocs; verwendet intern QtScript als Skriptmodul, das von JavaScript abgeleitet ist. Daher müssen Ihre implementierten Algorithmen in JavaScript geschrieben werden. Diese Skriptsprache wird hier nicht erklärt, nur der Zugriff auf Datenstrukturen, Datenelemente und Zeiger Ihrer Datenstrukturen mit dem Skriptmodul. Sie verwenden nie ein Basisstrukturobjekt, sondern immer das Objekt, das vom gerade verwendeten Backend der Datenstruktur bereitgestellt wird. Die Funktionalität der Datenstruktur wird also durch das zugehörige Backend erweitert. Daher sollten Sie die speziellen Funktionen der Backends benutzen. Insbesondere verwenden Datenstrukturmodule die üblichen Begriffe Ihrer Domäne wie zum Beispiel Knoten und Kanten für Graphen und Wurzel und Blätter für Baumstrukturen &etc;

Beachten Sie, dass Änderungen durch das Skriptmodul direkt die Eigenschaften im visuellen Graphen-Editor auf der Zeichenfläche verändern. Daher ändern Skripte tatsächlich die Datenstruktur.

### Die Basiselemente von Datenstrukturen

Jedes Backend stellt einen speziellen Satz von Funktionen und Eigenschaften für seine Datenstrukturen und deren Elemente bereit. Außerdem gibt es noch die Eigenschaften und Funktionen für die Basisdatenstruktur. Daher treffen die Erläuterungen in diesem Abschnitt für alle Backends für Datenstrukturen zu.

#### Basiseigenschaften von Datenstrukturen

Datenstrukturen werden über den Namen identifiziert. Angenommen Sie haben eine Datenstruktur mit dem Namen `testgraph`, dann erhalten Sie über diese Kennung Zugriff auf die Datenstruktur. Um zum Beispiel ein Feld aller Datenelemente einer bestimmten Datenstruktur zu erhalten, verwenden Sie `testgraph.list_nodes();` im Skript.

##### Basiseigenschaften von Datenstrukturen und Funktionen

Jede Datenstruktur `testgraph` hat folgende Eigenschaften, die mit `testgraph.property` geschrieben oder gelesen werden können:

    string name  // Kennung der Datenstruktur

#### Basiseigenschaften von Datenelementen und Funktionen

Jedes Datenelement hat die folgenden Eigenschaften, die geschrieben und gelesen werden können:

    double x      // x-Koordinate der aktuellen Position
        double y      // y-Koordinate der aktuellen Position
        double width  // Größe
        string value  // Wert
        int id        // eindeutige Kennung des Datenelements
        string name   // Name
        string color  // Farbe in HEXA

Außerdem ist der Zugriff auf jede dynamische Eigenschaft eines Datenelements über seinen Namen möglich.

Jedes Datenelementobjekt stellt die folgenden Methoden bereit:

    int type();                         // Datentyp des Datenelements
        int set_type(int);                  // setzt den Datentyp des Elements
        void add_property(string name,      // fügt eine dynamische Eigenschaft mit dem angegebenen Namen und Wert hinzu
                          string value);
        array adj_data();                   // Liste der anliegenden Daten
        array adj_pointers();               // Liste der anliegenden Zeiger
    array input_pointers();             // Liste der Eingabezeiger
        array output_pointers();            // Liste der Ausgabezeiger
        array loop_pointers();              // Liste der Zeiger, die eine Schleife bilden
        array connected_pointers(target);   // Liste der Zeiger zu „target“
        void remove();                 // entfernt dieses Datenelement

#### Basiseigenschaften von Zeigern und Funktionen

Jeder Zeiger hat die folgenden Eigenschaften, die geschrieben und gelesen werden können:

    string color  // Farbe in HEXA
        string value  // Wert
        string name   // Name
        double width  // Breite
        string style  // Erlaubte Werte dot, dash, dash dot, solid

Außerdem ist der Zugriff auf jede dynamische Eigenschaft eines Zeigers über seinen Namen möglich.

Jedes Zeigerobjekt stellt die folgenden Methoden bereit:

    int type();                         // Zeigertyp des Zeigers
        int set_type(int);                  // setzt den Zeigertyp des Zeigers
        void add_property(string name,      // fügt dynamische Eigenschaften zum Datenelement mit dem Namen und Wert hinzu
                          string value);
        node start();                       // Startknoten des Zeigers
        node end();                         // Zielknoten des Zeigers
        void remove();                 // entfernt diesen Zeiger

### Das Backend „Graph“

#### Grapheneigenschaften und Funktionen

##### Besondere Eigenschaften der Backends für Graphen

Im Dialog Eigenschaften der Datenstruktur finden Sie die Einstellungen für ein bestimmtes Graphen-Backend. Mit Graphentyp können Sie den Typ eines Graphen auswählen. Die Typen haben folgende Bedeutung:

- Graph: Ein Graph, bei dem dieselben Kanten unter Berücksichtigung von Start- und Endpunkt nur einmal vorkommen dürfen.

- Multigraph: Ein Graph, bei dem dieselben Kanten unter Berücksichtigung von Start- und Endpunkt auch mehrfach vorkommen dürfen.

##### Die Graphenstruktur

Mit einem Datenstrukturobjekt vom Typ „Graph“ können Sie folgende Member-Funktionen aufrufen:

    array list_nodes();                   // Liste aller Knoten des Graphen
        array list_nodes(int type);           // Liste aller Knoten des angegebenen Typs
        array list_edges();                   // Liste aller Kanten des Graphen
        array list_edges(int type);           // Liste aller Kanten des angegebenen Typs
        node add_node(name);                  // fügt einen neuen Knoten hinzu und gibt ihn zurück
        edge add_edge(node from, node to);    // fügt eine neue Kante von „from“ nach „to“ hinzu und gibt sie zurück
        array overlay_edges(int overlayID);   // Liste aller Kanten in der angegebenen Überlagerung
        edge add_overlay_edge(node from,
                              node to,
                              int overlayID); // fügt eine Kante vom angegebenen Zeigertyp/in der angegebenen Überlagerung hinzu

##### Graphenknoten

Mit einem Datenstrukturobjekt vom Typ „Graph“ können Sie folgende Member-Funktionen für die Graphenknoten zusätzlich zu den Eigenschaften des Datenelements aufrufen:

    array adj_nodes();                    // Liste aller anliegenden Knoten
        array adj_edges();                    // Liste der anliegenden Kanten
        array input_edges();                  // Liste der Eingabe-Kanten
        array output_edges();                 // Liste der Ausgabe-Kanten
        array loop_edges();                   // Liste aller Kanten, die mit dem Knoten in einer Schleife liegen
        array connected_edges(node target);   // Alle Kanten, die mit dem Knoten „target“ verbunden sind

##### Graphenkanten

Für Kanten einer Datenstruktur vom Typ „Graph“ sind nur die Eigenschaften der Basis-Datenstruktur verfügbar.

#### Graphenstruktur-Algorithmen

Das Backend „Graph“ stellt einige besondere Funktionen bereit, die mit dem Skriptmodul verwendet werden können.

Berechnung des kürzesten Wegs

- Berechnet den kürzesten Weg zwischen dem Start- und Endknoten. Beide Knoten müssen auf demselben Graphen liegen. Bei dieser Berechnung wird berücksichtigt, ob der Graph gerichtet oder ungerichtet ist.

          array dijkstra_shortest_path node start node end

Entfernungen des kürzesten Wegs

- Berechnet die Entfernungen der kürzesten Wege vom Knoten Start zu allen anderen Knoten des Graphen. Bei dieser Berechnung wird berücksichtigt, ob der Graph gerichtet oder ungerichtet ist.

          array distances node start

### Das Backend „Verkettete Liste“

#### Eigenschaften von verketteten Listen und Funktionen

##### Die Struktur „Verkettete Liste“

Mit einem Datenstrukturobjekt vom Typ „Verkettete Liste“ können Sie folgende Member-Funktionen aufrufen:

    node begin();                           // gibt den ersten Knoten der verketteten Liste zurück
        setBegin(node begin):                   // setzt den Knoten „begin“ als ersten Knoten der Liste und ordnet die Liste um
        createNode();                           // erstellt einen neuen Knoten in der Liste

##### Knoten verketteter Liste

Mit einem Datenstrukturobjekt vom Typ „Verkettete Liste“ können Sie folgende Member-Funktionen für die Graphenknoten zusätzlich zu den Eigenschaften des Datenelements aufrufen:

    node front();                           // gibt den Vorgänger des Knotens zurück

##### Kanten verketteter Listen

Für Kanten einer Datenstruktur vom Typ „Verkettete Liste“ sind nur die Eigenschaften der Basis-Datenstruktur verfügbar.

### Das Backend „Wurzelbaum“

#### Eigenschaften von Wurzelbäumen und Funktionen

##### Das Backend „Wurzelbaum“

Im Dialog Eigenschaften der Datenstruktur finden Sie die die Einstellungen für ein bestimmtes Graphen-Backend. Kreuzen Sie in diesem Dialog Alle Zeiger anzeigen an, dann werden alle Zeiger zwischen den Baumknoten angezeigt. Ist diese Einstellung nicht aktiv, werden mehrere Zeiger zwischen denselben Knoten zusammengefasst.

##### Die Struktur „Wurzelbaum“

Für jedes Datenstrukturobjekt vom Typ „Wurzelbaum“ können folgende Eigenschaften geschrieben oder gelesen werden:

    ShowAllPointers     // wenn wahr, werden alle Kanten angezeigt. Setzen Sie dies auf falsch, wenn mehrfache Kanten zusammengefasst werden sollen

Mit einem Datenstrukturobjekt vom Typ „Wurzelbaum“ können Sie folgende Member-Funktionen aufrufen:

    node add_data(string name);         // fügt einen Knoten mit dem angegebenen Namen zum Baum hinzu
        void set_root_node(node root);      // setzt root als Wurzel des Baums
        node root_node();                   // gibt den Wurzelknoten des Baums zurück

##### Knoten von Wurzelbäumen

Für ein Knotenobjekt vom Typ „Wurzelbaum“ können folgende Eigenschaften geschrieben oder gelesen werden:

    int numberOfChilds                  // setzt die Anzahl der zulässigen Unterknoten für diesen Knoten
        node left_child                     // nur lesbar: gibt den linken Unterknoten zurück
        node right_child                    // nur lesbar: gibt den rechten Unterknoten zurück
        node node_parent                    // nur lesbar: gibt den übergeordneten Knoten zurück

Mit einem Knotenobjekt vom Typ „Wurzelbaum“ können Sie folgende Member-Funktionen aufrufen:

    node add_left_child(node child);    // linken Unterknoten hinzufügen
        node add_right_child(node child);   // rechten Unterknoten hinzufügen
        node add_child(node child, int i);  // Unterknoten als n-ten Unterknoten zum Knoten hinzufügen
        node add_node_parent(node child);   // Übergeordneten Knoten hinzufügen (nur möglich, wenn noch nicht vorhanden)
        node left_child();                  // rechten Unterknoten zurückgeben
        node right_child();                 // linken Unterknoten zurückgeben
        node child_at(int i);               // n-ten Unterknoten des Knotens zurückgeben
        node node_parent();                 // Übergeordneten Knoten zurückgeben

##### Kanten von Wurzelbäumen

Für Kanten einer Datenstruktur vom Typ „Wurzelbaum“ sind nur die Eigenschaften der Basis-Datenstruktur verfügbar.

### Kontrolle der Skriptausführung

#### Dateien einbeziehen

Ihr Skriptdokument kann andere Skripte einschließen. Das ist nützlich, um die Größe des Skriptdokuments zu verringern und die Lesbarkeit zu verbessern. Benutzen Sie Skripte Mögliche Includes aus dem Menü, um eine Liste von Skriptdateien anzuzeigen, die mit &rocs; ausgeliefert werden. Eine Skriptdatei schließen Sie mit folgendem Befehl ein:

    include_script(string path);            // relativer oder absoluter Pfad zur Skriptdatei

#### Skriptausgabe

Bei der Ausführung eines Algorithmus werden Meldungen in der Fehler- & Skriptausgabe angezeigt. Erkennt das Skriptmodul einen Syntaxfehler in Ihrem Skript, wird der Fehler als Debug-Nachricht angezeigt. Auch alle Programmausgaben werden in der Fehlerausgabe als fett gedruckter Text angezeigt.

Sie können den angezeigten Text in der Skriptausgabe mit folgenden Funktionen steuern:

    output(string message);            // zeigt message als Skriptausgabe
        debug(string message);             // zeigt message als Fehlerausgabe

#### Kontrolle der Skriptausführung

Es gibt verschiedene Ausführungsmodi für Skripte.

Sie können den angezeigten Text in der Skriptausgabe mit folgenden Funktionen steuern:

- Ausführen: Führt das Skript bis zum Ende aus.

- Anhalten: Hält die Ausführung eines Skripts an und ist nur während der Ausführung aktiviert.

- Ein Schritt: Führt das Skript bis zum Ende eines Schritts aus. Ein Schritt endet, wenn das Skript die Funktion `interrupt()` aufruft:

      interrupt();    // beendet einen Schritt

- Debuggen: Führt das Skript im Debug-Modus aus, damit wird der QtScript-Debugdialog geöffnet.

## Importieren und Exportieren

### &rocs;-Projekte austauschen

&rocs;-Projekte können als Archivdateien im Format `.tar.gz` importiert und exportiert werden. Diese Archive können zum Austausch von Projekten benutzt werden. Der Import und Export erfolgt mit Datei Projekt importieren beziehungsweise Datei Projekt exportieren

### Import und Export von Graphendokumenten

&rocs; unterstützt zurzeit den Import und Export folgender Dateiformate:

- DOT-Dateien, auch als Graphviz-Dateien bekannt.

- GML-Dateien

- „Trivial Graph“-Dateien

#### „Trivial Graph“-Dateiformat

Das „Trivial Graph“-Format (TGF) ist ein einfaches textbasiertes Dateiformat zur Beschreibung von Graphen. Eine TGF-Datei besteht aus einer Liste von Knotendefinitionen mit der Zuordnung von Kennungen zu Beschriftungen, gefolgt von einer Liste von Kanten. In diesem Format kann es nur eine Beschriftung für einen Knoten und einen Wert für eine Kante geben. &rocs; interpretiert importierte Graphen als ungerichtet. Exportierte Graphen enthalten zwei Kanten für jede zweiseitige Verbindung.

##### Beschreibung des Formats

- Die Datei beginnt mit einer Liste der Knoten, jeder Knoten auf einer einzelnen Zeile. Dann folgt eine Zeile nur mit dem Zeichen „#“, gefolgt von einer Liste von Kanten in einer eigenen Zeile.

- Ein Knoten wird durch eine ganze Zahl als Kennung, dann ein Leerzeichen und ein beliebiger Text beschrieben.

- Die Beschreibung einer Kante besteht aus zwei ganzen Zahlen (Kennungen von Knoten), durch Leerzeichen getrennt, dann folgt nach einem Leerzeichen ein beliebiger Text. Es wird angenommen, dass die gerichtete Kante von der ersten zur zweiten Kennung zeigt.

##### Ein Beispiel

    1 Startknoten
    2 Sender
    3 Endknoten
    #
    1 2 blau
    2 1 rot
    2 3 grün

#### DOT-Sprache / Graphviz-Graphendateiformat

„DOT“ ist eine Beschreibungssprache für Graphen, die ein einfaches Textformat verwendet. Damit ist die Darstellung von Graphen für den Benutzer gut lesbar und sie kann effizient durch Anzeigeprogramme für Graphen verarbeitet werden. „DOT“ ist das Standardformat für das Visualisierungsprogramm Graphviz, wird aber auch häufig von anderen Graphenprogrammen verwendet. „DOT“-Dateien haben üblicherweise die Erweiterung .gv und .dot.

##### Nicht unterstützte Fähigkeiten

&rocs; kann jede Graphendatei einlesen und verarbeiten, die in der Sprache „DOT“

http://www.graphviz.org/content/dot-language

spezifizierte Graphen enthält. Die Funktionen der Sprache werden vollständig mit folgenden Ausnahmen unterstützt:

- Untergraph: Wegen des fehlenden Konzepts für Untergraphen in &rocs; werden Untergraphen nur als Menge von Datenelementen und Verbindungen importiert. Besonders Verbindungen zu oder von Untergraphen werden nicht importiert.

- &HTML; und &XML; Attribute: Attribute wie Beschriftungen mit &HTML;- oder &XML;-Syntax werden unverändert eingelesen. Insbesondere werden keine Anpassungen für Schriften und Stile aus diesen Attributen eingelesen.

##### Ein Beispiel

    digraph myGraph {
        a -> b -> c;
        b -> d;
    }

## Danksagungen und Lizenz

&rocs;

Copyright für das Programm:

- 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-2012 Andreas Cord-Landwehr (cordlandwehr AT googlemail.com)

Copyright der Dokumentation:

- Dokumentation Copyright 2009 &Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail;

- Dokumentation Copyright 2009 Tomaz Canabrava (tcanabrava AT kde.org)

- Dokumentation Copyright 2011-2012 Andreas Cord-Landwehr (cordlandwehr AT googlemail.com)

Übersetzung Burkhard Lück lueck@hube-lueck.de

&underFDL; &underGPL;

## Installation

### Wie Sie &rocs; erhalten

&install.intro.documentation;

### Kompilierung und Installation

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