# The &rocs; Handbook

Tomaz
Canabrava
tomaz.canabrava@gmail.com
Andreas
Cord-Landwehr
cordlandwehr@googlemail.com
2009
Tomaz Canabrava
2011
Andreas Cord-Landwehr
2011-12-04
1.1 &kde; 4.8
&FDLNotice;

&rocs; is a graph theory tool for KDE.

KDE
kdeedu
mathematics
math
graphs
node
edge

## Introduction

&rocs; is a Graph Theory IDE for everybody interested in designing and analyzing graph algorithms. This explicitly includes

- lecturers who eventually want to demonstrate algorithms to their students,

- students who want to understand and see how an algorithm works,

- and everybody who has to design graph algorithms and needs at tool for prototype testing.

For all these users, &rocs; provides an easy to use graph editor to set up graphs, a powerful Qt Script scripting engine to execute algorithms, and several helper tools to set up your graphs and data structures for your experiments. So the usual workflow is to write an algorithm, create a graph, and see in real-time how the algorithm works at the the graph.

A Screenshot of &rocs;.
A Screenshot of &rocs;.

## The &rocs; User Interface

### General Elements of the User Interface

The user interface is divided into several logical parts as presented at the screenshot below.

GUI elements of the &rocs; interface.
GUI elements of the &rocs; interface.

Visual Graph Editor Toolbar

  to be able to draw or modify graphs at the Visual Graph Editor whiteboard, you first need to select a tool here

Visual Graph Editor

  This is the area where you can draw your graphs. Right click at the whiteboard, graph elements, or selected graph elements opens a context menu depending on what you click.

Graph Properties

  This gives a complete list of all different graphs currently at the Visual Graph Editor whiteboard. Here you can make modifications to, &eg;, the graph name, visible properties like node names or values, or define default colors for the graph elements.

Script Editor

  In this text editor you can write algorithms in a Qt Script (for our purposes this is essentially the same as JavaScript). You can work on several algorithms at the same time by opening or creating new script tabs at the main menu. The small disk symbol at a tab appears if current changes are unsaved.

Debug & Script Output

  This text area either writes debug information or the script output of your algorithm, depending on selection of the output setting. If the script throws an error automatically the debug output is selected. Further, the debug output presents all program output messages, too.

Script Execution

  This area controls execution of the algorithms. You can execute the script that is currently open at the script editor at the graph at the Visual Graph Editor whiteboard by pressing Run. While the script is executed, it is possible to stop execution by pressing the Stop button.

### Toolbars

There are different possible toolbars for the visual graph editor that allow you to access features by only one click. At the default setting, the following toolbars are shown:

- Main Toolbar

- Alignment Toolbar

#### Main Toolbar

The Main Toolbar consists of the following actions. Clicking at an action means that your mouse pointer applies this action at the visual graph editor whiteboard:

- Move: To select elements, either click at unused space at the whiteboard, keep the mouse pressed and draw a rectangle that contains some nodes and/or edges to select these elements or otherwise directly click at an unselected element to select this element. If you click at a selected element or a set of selected elements, respectively, by keeping the mouse pressed and moving around you can move these elements. Moving selected elements is also possible with the arrow keys.

- Add Node: Click at an arbitrary position at the visual graph editor whiteboard to create a new node that belongs to the currently selected graph.

- Add Edge: Click at one node, keep the mouse pressed and draw a line to another node to which the pointer/edge shall point. This action is only successful if the current graph allows to add this edge (&eg;, in an undirected graph you are not allowed to add multiple edges between two nodes).

- Delete: Click at an element to delete it. If you delete a node, all adjacent edges are also deleted.

- Zoom: Click at the whiteboard, keep the &LMB; pressed, and by this draw a rectangle. The whiteboard will be zoomed to the selected area. Using the mousewheel to zoom in or out as well. A double click with the &LMB; restores the original zoom.

The Main Toolbar.
The Main Toolbar.

#### Alignment Toolbar

You can add the optional Alignment Toolbar. Pressing an action at this toolbar has direct effect to the currently selected nodes:

- Top: Align the nodes at the vertical position of the top-most node. This only affects the vertical positions.

- Center: Align the nodes at the vertical position given by the center of all selected nodes vertical positions. This only affects the vertical positions.

- Base: Align the nodes at the vertical position of the bottom-most node. This only affects the vertical positions.

- Left: Align the nodes at the horizontal position of the left-most node. This only affects the horizontal positions.

- Center: Align the nodes at the horizontal position of the top-most node. This only affects the horizontal positions.

- Right: Align the nodes at the horizontal position of the right-most node. This only affects the horizontal positions.

- Circle: Aligns the nodes at a circle of diameter equals to the maximal distance of the nodes. The nodes are positioned in the same sequence as given by view from the center of gravity of these nodes.

- Minimize Crossing Edges: Applies the Fruchterman-Reingold algorithm to minimize (approximatively) the number of crossing edges.

The Alignment Toolbar.
The Alignment Toolbar.

### Graph Properties

On the left sidebar you can find the options for each opened graph. All these options are global per graph and can be changed per node and edge with the Node Properties and the Edge Properties dialogs.

- Name: This is the name that your algorithm must use to access the graph.

- Data Color for new created nodes, you can change the node color for all current nodes by clicking the All button

- Pointer Color

The last row of options consists of toggled buttons:

- Show names in: Data or Pointers.

- Show values in: Nodes or Edges.

## Using &rocs;

Usually the first step is to create a graph with the visual graph editor. You can do this either by hand, this is adding nodes and connecting them, or by using one of the helper algorithms that can be found Tools Generate Graph. Eventually, you also want to use the Tools Assign Values helper tools to assign your graph nodes and edges with initial values. Finally you need to give your graph a name. This name then will be the identifier that you must use for the scripting engine.

### Scripting

&rocs; use a JavaScript like scripting language. This is, essentially that definition of variables and functions and their use are done exactly like in JavaScript. Besides, &rocs; provides a set of functions that let you access the graphs at the visual graph editor whiteboard and their elements.

#### Accessing a Graph

In the scripting interface you can access a graph by simply typing its name and using this as an object with one of the following functions. To access a node or an edge you must get an identifier from the graph object

Graph Objects

      // functions
           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();

      // variables
           bool directed
           bool automate
           string name
           string nodeDefaultColor // in HEXA
           string edgeDefaultColor  // in HEXA

Node Objects

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

      // variables
          double x
          double y
          double width
          string value
          string name
          string color  // in HEXA
          bool begin
          bool end

Edge Objects

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

          node start();
          node  end();

          void self_remove();

#### Graph Algorithms

Sometimes it is useful if you can use functions for standard tasks, like computing shortest distances between two nodes. Currently we support the following algorithms that can be called from the scripting engine with nodes from the same graph.

Shortest Path Computation

  Computes the shortest path between the nodes start and end. Both nodes must be of the same graph. This computation respects if the graph is directed or undirected.

      	array dijkstra_shortest_path
      	Node* start
      	Node* end

### Example

Here is a simple script example that sets the color of the 4 first nodes in the first graph:

    /* A simple example that sets the color of the 4 first nodes in the first
    graph: */

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

    /* graphs is an array of graphs, you can access a graph by its index in the
    array or by its name, so if the first graph's name is Untitled0, the following
    sentence are right  */
    var list1= graphs[0].list_nodes(); //  1st form.
    var list2=Untitled0.list_nodes();              // 2nd form

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

### Import and Export

&rocs; currently supports import and export of the following file formats:

- DOT files, also known as Graphviz files.

- GML files

- Plain-Text files.

Currently, for most of these file types only few values are imported. The imported values include nodes and their corresponding connections, names of all elements, values, and if given also coordinates.

## Credits and License

&rocs;

Program Copyright:

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

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

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

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

Documentation Copyright:

- Documentation copyright 2009 &Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail;

- Documentation copyright 2009 Tomaz Canabrava (tcanabrava AT kde.org)

- Documentation copyright 2011 Andreas Cord-Landwehr (cordlandwehr AT googlemail.com)

&underFDL; &underGPL;

## Installation

### How to obtain &rocs;

&install.intro.documentation;

### Compilation and installation

&install.compile.documentation;

&documentation.index;