<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [

  <!ENTITY kappname "&rocs;">
  <!ENTITY package "kdeedu">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE">
]>
<book lang="&language;">

<bookinfo>
<title>The &rocs; Handbook</title>
<authorgroup>
<author>
<personname>
<firstname>Tomaz</firstname>
<surname>Canabrava</surname>
</personname>
<email>tomaz.canabrava@gmail.com</email>
</author>
<author>
<personname>
<firstname>Andreas</firstname>
<surname>Cord-Landwehr</surname>
</personname>
<email>cordlandwehr@googlemail.com</email>
</author>

<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>

<copyright><year>2009</year><holder>Tomaz Canabrava</holder></copyright>
<copyright><year>2011</year><holder>Andreas Cord-Landwehr</holder></copyright>

<date>2011-12-04</date>
<releaseinfo>1.1 &kde; 4.8</releaseinfo>

<legalnotice>&FDLNotice;</legalnotice>

<abstract>
<para>
&rocs; is a graph theory tool for KDE.
</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>kdeedu</keyword>
<keyword>mathematics</keyword>
<keyword>math</keyword>
<keyword>graphs</keyword>
<keyword>node</keyword>
<keyword>edge</keyword>
</keywordset>

</bookinfo>

<chapter id="introduction">
<title>Introduction</title>
<para>&rocs; is a Graph Theory IDE for everybody interested in designing and analyzing graph algorithms. This explicitly includes</para>
<itemizedlist>
	<listitem><para>lecturers who eventually want to demonstrate algorithms to their students,</para></listitem>
	<listitem><para>students who want to understand and see how an algorithm works,</para></listitem>
	<listitem><para>and everybody who has to design graph algorithms and needs at tool for prototype testing.</para></listitem>
</itemizedlist>
<para>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.</para>

<screenshot>
<screeninfo>A Screenshot of &rocs;.</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="rocs-screenshot.png" format="PNG" />
</imageobject>
<textobject>
<phrase>A Screenshot of &rocs;.</phrase>
</textobject>
</mediaobject>
</screenshot>
</chapter>

<chapter id="user-interface">
<title>The &rocs; User Interface</title>

<sect1 id="user-interface-all">
<title>General Elements of the User Interface</title>
<para>
The user interface is divided into several logical parts as presented at the screenshot below.
</para>
<screenshot>
	<screeninfo>GUI elements of the &rocs; interface.</screeninfo>
	<mediaobject>
	<imageobject>
	<imagedata fileref="rocs-interfaces.png" format="PNG" />
	</imageobject>
	<textobject>
	<phrase>GUI elements of the &rocs; interface.</phrase>
	</textobject>
	</mediaobject>
</screenshot>
<variablelist>
<varlistentry>
	<term>Visual Graph Editor Toolbar</term>
	<listitem><para>to be able to draw or modify graphs at the Visual Graph Editor whiteboard, you first need to select a tool here</para></listitem>
</varlistentry>
<varlistentry>
	<term>Visual Graph Editor</term>
	<listitem><para>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.</para></listitem>
</varlistentry>
<varlistentry>
	<term>Graph Properties</term>
	<listitem><para>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.</para></listitem>
</varlistentry>
<varlistentry>
	<term>Script Editor</term>
	<listitem><para>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.</para></listitem>
</varlistentry>
<varlistentry>
	<term>Debug &amp; Script Output</term>
	<listitem><para>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.</para></listitem>
</varlistentry>
<varlistentry>
	<term>Script Execution</term>
	<listitem><para>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 <guiicon>Run</guiicon>. While the script is executed, it is possible to stop execution by pressing the <guiicon>Stop</guiicon> button.</para></listitem>
</varlistentry>
</variablelist>
</sect1>

<sect1 id="user-interface-toolbars">
<title>Toolbars</title>
<para>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:</para>
<itemizedlist>
	<listitem><para>Main Toolbar</para></listitem>
	<listitem><para>Alignment Toolbar</para></listitem>
</itemizedlist>

<sect2 id="user-interface-toolbars-main">
<title>Main Toolbar</title>
<para>The <emphasis>Main Toolbar</emphasis> consists of the following actions. Clicking at an action means that your mouse pointer applies this action at the visual graph editor whiteboard:</para>
<itemizedlist>
<listitem><para>
<guilabel>Move</guilabel>: 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.</para></listitem>
<listitem><para>
<guilabel>Add Node</guilabel>: Click at an arbitrary position at the visual graph editor whiteboard to create a new node that belongs to the currently selected graph.</para></listitem>
<listitem><para>
<guilabel>Add Edge</guilabel>: 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).</para></listitem>
<listitem><para>
<guilabel>Delete</guilabel>: Click at an element to delete it. If you delete a node, all adjacent edges are also deleted.</para></listitem>
<listitem><para>
<guilabel>Zoom</guilabel>: 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.</para></listitem>
</itemizedlist>
<screenshot>
<screeninfo>The Main Toolbar.</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="rocs-toolbar-main.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The Main Toolbar.</phrase>
</textobject>
</mediaobject>
</screenshot>
</sect2>

<sect2 id="user-interface-toolbars-alignment">
<title>Alignment Toolbar</title>
<para>You can add the optional <emphasis>Alignment Toolbar</emphasis>. Pressing an action at this toolbar has direct effect to the currently selected nodes:</para>
<itemizedlist>
<listitem><para>
<inlinemediaobject><imageobject>
<imagedata fileref="hi22-action-rocsaligntop.png" format="PNG"/></imageobject>
</inlinemediaobject>
<guilabel>Top</guilabel>: Align the nodes at the vertical position of the top-most node. This only affects the vertical positions.</para></listitem>
<listitem><para>
<inlinemediaobject><imageobject>
<imagedata fileref="hi22-action-rocsalignvmiddle.png" format="PNG"/></imageobject>
</inlinemediaobject>
<guilabel>Center</guilabel>: Align the nodes at the vertical position given by the center of all selected nodes vertical positions. This only affects the vertical positions.</para></listitem>
<listitem><para>
<inlinemediaobject><imageobject>
<imagedata fileref="hi22-action-rocsalignbottom.png" format="PNG"/></imageobject>
</inlinemediaobject>
<guilabel>Base</guilabel>: Align the nodes at the vertical position of the bottom-most node. This only affects the vertical positions.</para></listitem>
<listitem><para>
<inlinemediaobject><imageobject>
<imagedata fileref="hi22-action-rocsalignleft.png" format="PNG"/></imageobject>
</inlinemediaobject>
<guilabel>Left</guilabel>: Align the nodes at the horizontal position of the left-most node. This only affects the horizontal positions.</para></listitem>
<listitem><para>
<inlinemediaobject><imageobject>
<imagedata fileref="hi22-action-rocsalignhmiddle.png" format="PNG"/></imageobject>
</inlinemediaobject>
<guilabel>Center</guilabel>: Align the nodes at the horizontal position of the top-most node. This only affects the horizontal
positions.</para></listitem>
<listitem><para>
<inlinemediaobject><imageobject>
<imagedata fileref="hi22-action-rocsalignright.png" format="PNG"/></imageobject>
</inlinemediaobject>
<guilabel>Right</guilabel>: Align the nodes at the horizontal position of the right-most node. This only affects the horizontal positions.</para></listitem>
<listitem><para>
<inlinemediaobject><imageobject>
<imagedata fileref="hi22-action-rocsaligncircle.png" format="PNG"/></imageobject>
</inlinemediaobject>
<guilabel>Circle</guilabel>: 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.</para></listitem>
<listitem><para>
<inlinemediaobject><imageobject>
<imagedata fileref="hi22-action-rocsaligntree.png" format="PNG"/></imageobject>
</inlinemediaobject>
<guilabel>Minimize Crossing Edges</guilabel>: Applies the Fruchterman-Reingold algorithm to minimize (approximatively) the number of crossing edges.</para></listitem>
</itemizedlist>
<screenshot>
<screeninfo>The Alignment Toolbar.</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="rocs-toolbar-alignment.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The Alignment Toolbar.</phrase>
</textobject>
</mediaobject>
</screenshot>
</sect2>
</sect1>

<sect1 id="user-interface-graph-properties">
	<title>Graph Properties</title>
	<para>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.</para>

	<itemizedlist>
	<listitem><para>
	<guilabel>Name</guilabel>: This is the name that your algorithm must use to access the graph.
	</para></listitem>
	<listitem><para>
	<guilabel>Data Color</guilabel> for new created nodes, you can change the node color for all current nodes
	by clicking the <guilabel>All</guilabel> button
	</para></listitem>
	<listitem><para>
	  <guilabel>Pointer Color</guilabel> <!--FIXME color of edges?-->
	</para></listitem>
	</itemizedlist>
	<para>The last row of options consists of toggled buttons:</para>
	<itemizedlist>
	<listitem><para>
	<guilabel>Show names in:</guilabel> <guilabel>Data</guilabel> or <guilabel>Pointers</guilabel>.
	</para></listitem>
	<listitem><para>
	<guilabel>Show values in:</guilabel> <guilabel>Nodes</guilabel> or <guilabel>Edges</guilabel>.
	</para></listitem>
	<!-- FIXME missing Graph Type Undirected Graph, Directed Graph, Multigraph -->
	</itemizedlist>
</sect1>
</chapter>

<chapter id="using-rocs">
<title>Using &rocs;</title>
<para>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 <menuchoice><guimenu>Tools</guimenu> <guimenuitem>Generate Graph</guimenuitem></menuchoice>. Eventually, you also want to use the <menuchoice><guimenu>Tools</guimenu> <guimenuitem>Assign Values</guimenuitem></menuchoice> 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.</para>

<sect1 id="using-rocs-scripting">
<title>Scripting</title>
<para>&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.
</para>

<sect2><title>Accessing a Graph</title>
<para>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</para>
<variablelist>
<varlistentry>
<term>Graph Objects</term>
<listitem>
<programlisting>
// functions
     array list_nodes();
     array list_edges();
     node add_node(name);
     edge add_edge(from, to);
     node node_byname(QString&amp; name);
     node begin_node();
     array end_nodes();

// variables
     bool directed
     bool automate
     string name
     string nodeDefaultColor // in HEXA
     string edgeDefaultColor  // in HEXA
</programlisting>
</listitem>
</varlistentry>

<varlistentry>
<term>Node Objects</term>
<listitem>
<programlisting>
// 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
</programlisting>
</listitem>
</varlistentry>

<varlistentry>
<term>Edge Objects</term>
<listitem>
<programlisting>
    string color ( em hexa )
    string value
    string name
    double width
    string style ( dot, dash, dash dot, solid )

    node start();
    node  end();

    void self_remove();
</programlisting>
</listitem>
</varlistentry>
</variablelist>
</sect2>

<sect2 id="script-graph-algorithms">
<title>Graph Algorithms</title>
<para>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.</para>
<variablelist>
<varlistentry>
<term>Shortest Path Computation</term>
<listitem>
	<para>Computes the shortest path between the nodes <emphasis>start</emphasis> and <emphasis>end</emphasis>. Both nodes must be of the same graph. This computation respects if the graph is directed or undirected.</para>
	<funcsynopsis>
	<funcprototype>
	<funcdef>array <function>dijkstra_shortest_path</function></funcdef>
	<paramdef>Node* <parameter><replaceable>start</replaceable></parameter></paramdef>
	<paramdef>Node* <parameter><replaceable>end</replaceable></parameter></paramdef>
	</funcprototype>
	</funcsynopsis>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>

<sect1 id="script-example">
<title>Example</title>
<para>Here is a simple script example that sets the color of the 4 first nodes in the first
graph:</para>
<programlisting>
/* 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 &lt; colors.length; i++){
        if (i > list2.length) break;
        list2[i].color = colors[i]
 }
</programlisting>
</sect1>
<sect1>
	<title>Import and Export</title>
	<para>&rocs; currently supports import and export of the following file formats:</para>
	<itemizedlist>
		<listitem><para>DOT files, also known as Graphviz files.</para></listitem>
		<listitem><para>GML files</para></listitem>
		<listitem><para>Plain-Text files.</para></listitem>
	</itemizedlist>
	<para>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.</para>
</sect1>
</chapter>

<chapter id="credits">
<title>Credits and License</title>

<para>
&rocs;
</para>
<para>Program Copyright:</para>
<itemizedlist>
	<listitem><para>Copyright 2008       Ugo Sangiori (ugorox AT gmail.com)</para></listitem>
	<listitem><para>Copyright 2008-2011  Tomaz Canabrava (tcanabrava AT kde.org)</para></listitem>
	<listitem><para>Copyright 2008-2011  Wagner Reck (wagner.reck AT gmail.com)</para></listitem>
	<listitem><para>Copyright 2011 Andreas Cord-Landwehr (cordlandwehr AT googlemail.com)</para></listitem>
</itemizedlist>

<para>Documentation Copyright:</para>
<itemizedlist>
	<listitem><para>Documentation copyright 2009 &Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail;</para></listitem>
	<listitem><para>Documentation copyright 2009 Tomaz Canabrava (tcanabrava AT kde.org)</para></listitem>
	<listitem><para>Documentation copyright 2011 Andreas Cord-Landwehr (cordlandwehr AT googlemail.com)</para></listitem>
</itemizedlist>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
&underFDL;               <!-- FDL: do not remove -->
&underGPL;               <!-- GPL License -->

</chapter>

<appendix id="installation">
<title>Installation</title>

<sect1 id="getting-rocs">
<title>How to obtain &rocs;</title>

&install.intro.documentation;

</sect1>

<sect1 id="compilation">
<title>Compilation and installation</title>

&install.compile.documentation;

</sect1>
</appendix>

&documentation.index;
</book>
<!--
Local Variables:
mode: sgml
sgml-minimize-attributes: nil
sgml-general-insert-case: lower
sgml-indent-step:0
sgml-indent-data:nil
End:
-->
