# The &rocs; Handbook

Tomaz
Canabrava
tomaz.canabrava@gmail.com
2009
Tomaz Canabrava
&FDLNotice;
2009-11-05
1.0

&rocs; is a graph theory viewer tool for KDE.

KDE
kdeedu
mathematics
math
graphs
node
edge

## Introduction

&rocs; aims to be a Graph Theory IDE for helping professors to show the results of a graph algorithm and also helping students to do the algorithms.

&rocs; has a scripting module, done in Qt Script, that interacts with the drawn graph and every change in the graph with the script is reflected on the drawn one.

## Using &rocs;

The user interface is divided in two parts:

- the top right part is where you draw your graphs, and the bottom right one is where you create your algorithms,

- the left sidebar is where all your open graphs stay, you can open multiple graphs per file.

### &rocs; global settings

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.

- Graph Name

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

- Edge Color

The last row of options consists in toggled buttons:

- Oriented Graph

- Automated Graph

- Show nodes names

- Show edges names

- Show nodes values

- Show edges values

### &rocs; toolbars

There are two toolbars, on the top. The main one has the following tools:

- Move Node: moves a node around the drawing area.

- Add Node: creates a new node at the clicked position on the drawing area.

- Add Edge: creates a new edge between two nodes.

- Select: select items by clicking on them.

- Delete: delete items by clicking on them.

A right mouse click on a node or edge brings you the property dialog for that node or edge.

The layout toolbar consists in various aligns icons.

To align nodes, choose the Select tool, click and drag a rectangle, then choose the alignement that you want.

## Scripting &rocs;

After the graph is on screen, you can start creating the script for it. The language uses a Javascript syntax and following are the Graph, Node and Edge objects.

### Graph

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

Graph variables that can be changed:

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

### Nodes

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

Node Variables:

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

### Edges

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

        node start();
        node  end();

        void self_remove();

### 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 colours = 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 < colours.length; i++){
            if (i > list2.length) break;
            list2[i].color = colours[i]
     }

## Command Reference

### Menus and Shortcut Keys

#### The File Menu

&Ctrl;Q File Quit

  Quits &rocs;

#### The Settings Menu

Settings Toolbars Shown

  Toggle the Main, and Layout toolbars.

Settings Show Statusbar

  Toggle the statusbar.

Settings Configure Shortcuts...

  Open standard &kde; setting dialog that allows you to choose different shortcut keys for different actions.

Settings Configure Toolbars...

  Configure the items you want to put in the toolbar.

#### The Help Menu

&help.menu.documentation;

## Credits and License

&rocs;

Program copyright 2009 Tomaz Canabrava tcanabrava at kde dot org

Documentation copyright 2009 &Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail; and Tomaz Canabrava tcanabrava at kde dot org

&underFDL; &underGPL;

## Installation

### How to obtain &rocs;

&install.intro.documentation;

### Compilation and installation

&install.compile.documentation;

&documentation.index;