<chapter id="tulip-library"><title>Tulip Library</title>
<sect1 id="tulip-library-intro"><title>Introduction</title>
  <para>Efficient visualization of graphs and their usage for data analysis implies
    <itemizedlist>
    <listitem><para>the manipulation of the structure of the graph</para></listitem>
    <listitem><para>the extraction of parts of it</para></listitem>
    <listitem><para>association of values to a graph's elements (nodes and edges)</para></listitem>
    <listitem><para>the computation of intrinsic parameters (parameters derived from a graph's structure,
    e.g. in a filesystem graph (directory tree): number of files in a directory, can be computed by counting 
    outgoing edges)</para></listitem>
    <listitem><para>the computation of extrinsic parameters (parameters derived from external information, 
    e.g. in a filesystem graph: file size)</para></listitem>
    </itemizedlist>
</para>
<para>
This chapter describes the Tulip data structure that takes into account all the requirement
of a graph visualization system. For each part we describe the general principle and
then we give examples explaining how to do it with the Tulip library.
</para>
</sect1>
<sect1 id="graphs"><title>Graphs</title>
    <para>The core of the Tulip library provides an interface for the manipulation of graphs. It enables one 
to access and modify the structure of a graph. The aim of this library is to be as general 
as possible and thus it manipulates a general class of graphs called directed pseudo-graphs. 
In a pseudo graph, there can be more than one edge between two nodes, and loops are permitted. A loop is an
edge that links a node to itself. Furthermore, edges are directed, thus an edge u->v is distinct from an edge v->u.
    </para>
    <para>
    Because we use pseudo-graphs, there can be more than one edge u->v, so it is not possible to
distinguish two edges using only source and target (u,v). To make this possible, all the elements in Tulip
are entities (C++ objects). Thus, even if two edges have the same source and the same target, they are distinct.    
    </para>
    <para>
The elements of a graph are encapsulated in the graph. It is therefore not possible to access 
the graph's structure through elements, all operations must be done by querying the graph.
For example, to know the source of an edge e of graph G, one must ask G, not e, what e's source is.
This makes the use of the library less intuitive, but it minimizes memory usage for entities and allows to
share them between subgraphs. Building a container of elements is cheap, because to handle elements, 
Tulip uses objects which use the same amount of storage as integers.
    </para>
    <para>
The library supports access and modification of the graph structure. The access to the structure are made by using iterators,
one very important point is that the iterator are not persistent. Thus, if one modify the graph structure all the iterators
on the graph structure can be invalid. This property enables to prevent from cloning the data structure and thus enables 
better access to it. For ease of use, Tulip includes mechanism that enables to transform an iterator into stable iterator,
one must keep in mind that it corresponds to clone the data structure and thus, it should be use only if it is necessary.
    </para>
    <para>
If one uses Tulip only for the manipulation of one graph (no graph hierarchy), the list of available operations on the 
graph is given afterward. In the next section we will enhance the set of operations and the actions that they perform 
in order to manage a hierarchy of subgraphs
    <itemizedlist>
    <title>List of available modification operations</title>
    <listitem><para><methodname>node addNode()</methodname> : creates a new node in the graph and returns its identifier.</para></listitem>
    <listitem><para>    
        <methodname>edge addEdge(node,node)</methodname> : create a new edge in the graph, given the source and target. </para></listitem>
    <listitem><para><methodname>void delNode(node)</methodname> : deletes the given node.</para></listitem>
    <listitem><para><methodname>void delEdge(edge)</methodname> : deletes the given edge.</para></listitem>
    <listitem><para><methodname>void reverse(edge)</methodname> : reverses an edge (swaps source and target).</para></listitem>
    </itemizedlist>
    <itemizedlist>
    <title>List of available access operations</title>
    <listitem><para><methodname>unsigned int deg(node)</methodname> : returns the degree of a node (number of edges).</para></listitem>
    <listitem><para><methodname>unsigned int indeg(node)</methodname> : returns the in degree of a node (number of times it is a target).</para></listitem>
    <listitem><para><methodname>unsigned int outdeg(node)</methodname> : returns the out degree of a node (number of times it is a source).</para></listitem>
    <listitem><para><methodname>node source(edge)</methodname> : returns the source of an edge.</para></listitem>
    <listitem><para><methodname>node target(edge)</methodname> : returns the target of an edge.</para></listitem>
    <listitem><para><methodname>node opposite(edge,node)</methodname> : it enables to obtain the opposite of a node of an edge.</para></listitem>
    <listitem><para><methodname>Iterator * getInNodes(node)</methodname> : returns an iterator on the predecessor nodes of a node.</para></listitem>
    <listitem><para><methodname>Iterator * getOutNodes(node)</methodname> : returns an iterator on the successor nodes of a node.</para></listitem>
    <listitem><para><methodname>Iterator * getInOutNodes(node)</methodname> : returns an iterator on the neighbor nodes of a node.</para></listitem>
    <listitem><para><methodname>Iterator * getInEdges(node)</methodname> : returns an iterator on the predecessor edges of a node.</para></listitem>
    <listitem><para><methodname>Iterator * getOutEdges(node)</methodname> : returns an iterator on the successor edges of a node.</para></listitem>
    <listitem><para><methodname>Iterator * getInOutEdges(node)</methodname> : returns an iterator on the neighbor edges of a node.</para></listitem>
    </itemizedlist>
    </para>
</sect1>

<sect1 id="hierarchy-graphs"><title>Hierarchy of graphs</title>
    <para> The Tulip library can also manage subgraphs. By definition a subgraph G' of a graph G is part (subset) 
of the elements of G such that G' is also a graph (all sources and targets of the edges of G' must be in G'). 
As a subgraph is also a graph it can itself contain subgraphs. In such a hierarchy,  
if a graph G" is a descendant of a graph G, G" is also a subgraph of G.
    </para>
    <para> One of the strong point of Tulip is to ensure efficiently that all elements are shared between graphs in a hierarchy
of graphs. Thus, if a node n is an element of a graph G and of a graph G', the entity n is the same in both graphs. Of course,
the parameters of the entity can change between graphs. For instance, the degree of n can be smaller for a subgraph,
as it can have less edges.
    </para>
    <para> The subgraph relation in the hierarchy is preserved when one modifies a graph. This means that
if one adds a node to a graph, this node is automatically added to all its ancestors as well. If one deletes a
node, this node is automatically deleted from all the descendants of the graph. If one reverses an edge, this edge is 
reversed in all the graphs of the hierarchy.
    </para>
    <para> In order to manipulate a hierarchy of graphs, more functions have been added to those introduced above.
They provide navigation and modification for the hierarchy. The access to the hierarchy is provided by iterators, which
are not persistent and thus, if the hierarchy is modified, the iterators are invalid.
    <itemizedlist>
    <title>List of available modification operations</title>
    <listitem><para><methodname>Graph *addSubGraph()</methodname> : returns an empty subgraph of this graph.</para></listitem>
    <listitem><para><methodname>Graph *delSubGraph(Graph *)</methodname> : deletes a subgraph. Its descendants
    continue to be descendants of this graph.</para></listitem>
    <listitem><para><methodname>Graph *delAllSubGraph(Graph *)</methodname> : deletes a subgraph and all its descendants.</para></listitem>
    <listitem><para><methodname>edge addEdge(edge)</methodname> : adds an edge element from another graph in the hierarchy.</para></listitem>
    <listitem><para><methodname>void addNode(node)</methodname> : adds a node element from another graph in the hierarchy.</para></listitem>
    </itemizedlist>
    <itemizedlist>
    <title>List of available access operations</title>
    <listitem><para><methodname>Iterator * getSubGraphs()</methodname> : returns an iterator on the subgraphs.</para></listitem>
    <listitem><para><methodname>Graph * getSuperGraph()</methodname> : returns the parent of the graph. If the graph has
    no parent, it returns the graph itself.</para></listitem>
    </itemizedlist>
    </para>
</sect1>

<sect1 id="attributes"><title>Attributes</title>
	<para>
		An attributes is a kind of property that can be associated to a graph. An attributes has a name (a string) and a value of any type. It can be, for example ,the name of a graph, or a date of creation of the graph.  
	</para>
	<para>
		Attributes can be added and accessed with those three following member functions :
	</para>
	<itemizedlist>
		<listitem><para><code>const DataSet getAttributes()</code> : returns the attributes of a graph.
		</para></listitem>
		<listitem><para><code>template&lt;typename ATTRIBUTETYPE&gt;bool getAttribute(const std::string &amp;name, ATTRIBUTETYPE &amp;value)</code> : get an attribute.
		</para></listitem>
		<listitem><para><code> template&lt;typename ATTRIBUTETYPE&gt;void setAttribute (const std::string &amp;name, const ATTRIBUTETYPE &amp;value) </code> : set a new attribute value.
		</para></listitem>
	</itemizedlist>
</sect1>

<sect1 id="properties"><title>Properties</title>
    <para> In Tulip, a property is an attribute of an element of a graph. It is called a property in 
order to prevent confusion with attributes of a graph: properties are for elements and attributes are for graphs.
In Tulip, a property is always defined for both kinds of elements (nodes and edges), so one can always query
for the value of the property associated with any edge or node.
    </para>
    <para> To access the value of an elements one must query the graph for a property. This makes
the use of the library less intuitive, but it minimizes memory usage for properties. 
    </para>
    <para>
A property can be seen as an associative table where you can set and get the value for every element. 
All property operations have a TYPE argument, so there is no need to cast the result of a property query. The standard
operations of a property are:
    <itemizedlist>
    <title>List of available modification operations</title>
    <listitem><para><methodname>void setNodeValue(node,TYPE)</methodname> : sets the value of a node.</para></listitem>
    <listitem><para><methodname>void setAllNodeValue(TYPE)</methodname> : sets the value of all nodes.</para></listitem>
    <listitem><para><methodname>void setEdgeValue(edge,TYPE)</methodname> : sets the value of an edge.</para></listitem>
    <listitem><para><methodname>void setAllEdgeValue(TYPE)</methodname> : sets the value of all edges.</para></listitem>
    </itemizedlist>
    <itemizedlist>
    <title>List of available access operations</title>
    <listitem><para><methodname>TYPE getNodeValue(node)</methodname> : returns the value of a node.</para></listitem>
    <listitem><para><methodname>TYPE getEdgeValue(edge)</methodname> : returns the value of an edge.</para></listitem>
    </itemizedlist>
    </para>
    <para> For each property type there is a specific implementation (subclass) that allows operations which
    are specific to the property type (see Tulip libraries documentation). For instance, it is possible to obtain 
    the maximum value of a property if the property type is <code>double</code>. 
    </para>
    <para> A graph includes a set of functions that enables to obtain/create/delete a property. Because
the C++ signature of functions does not include the return type, the syntax for this call is not 
very simple. For instance, if one wants to obtain a property containing double (called DoubleProperty in Tulip) one must use
the following syntax : <methodname> DoubleProperty *metric=graph->getProperty&lt;DoubleProperty&gt;("name of the property");</methodname>
In the graph each property is identified by its name which is a std::string, when one asks for a property the type of this 
property is checked using the run time type interrogation mechanism of C++. Warning: This test only happens when one 
compiles its sources in DEBUG mode (default mode). In order to facilitate the navigation/edition of the set of properties, a
set of functions is accessible through the graph interface.
    <itemizedlist>
    <title>List of available operations</title>
    <listitem><para><methodname>Iterator * getLocalProperties()</methodname> : returns an iterator on all properties of this graph.</para></listitem>
    <listitem><para><methodname>void delLocalProperty(const std::string&amp;)</methodname> : deletes a property.</para></listitem>
    <listitem><para><methodname>bool existLocalProperty(const std::string&amp;)</methodname> : returns true if the property exists.</para></listitem>
    <listitem><para><methodname>PropertyType * getLocalProperty (const std::string&amp;)</methodname> : returns the property. 
    If it did not exist, creates it first </para></listitem>
    </itemizedlist>
    </para>
    <para> For the property mechanism described above to work with a hierarchy of graphs, a mechanism have been added 
to share properties between graphs, which works like this: if a property exists in an ancestor of a graph G, it also 
exists in the graph G. Thus, properties of graphs are inherited like members of objects in object-oriented languages. 
In order to facilitate the navigation/edition of properties, a set of function is accessible through the graph interface.
    <itemizedlist>
    <title>List of available operations</title>
    <listitem><para><methodname>Iterators * getInheritedProperties()</methodname> : returns an iterator on all properties (both inherited and local).</para></listitem>
    <listitem><para><methodname>bool existProperty(const std::string&amp;)</methodname> : returns true if the property exists (inherited or local).</para></listitem>
    <listitem><para><methodname>PropertyType * getProperty(const std::string&amp;)</methodname> : returns the property (inherited or local). 
    If it did not exist, creates it first (locally)</para></listitem>
    </itemizedlist>
    </para>
</sect1>

<sect1 id="code-example-intro"><title>TUTORIAL Intro.</title>
<para> Before doing any of the tutorials please read the following warnings :
</para>
<itemizedlist>
	<listitem><para>
		Follow the tutorials, one by one, from the first one to the last one.
	</para></listitem>
	<listitem><para>
		You can find at the end of each tutorial, the integral source code that we used.
	</para></listitem>
	<listitem><para>
		If you want more details on a specific function or class please read the Tulip Graph library <ulink url="../../doxygen/tulip.html">documentation</ulink>. 
	</para></listitem>	
</itemizedlist>
</sect1>
    <sect1 id="code-examples-graphs"><title>TUTORIAL 001 : Graphs creation, adding and deleting nodes or edges.</title>
        <para>
        	In this first tutorial, we will show you how to create a graph, add three nodes and three edges, remove an edge and a node, and finally, print the result on the standard output.
        </para>
        <graphic fileref="images/tuto_001_graphcreated_3.png"/>
        <sect2 id="code-examples-graphs-headfile"><title>1. Header files</title>
        <para>Let's start with the files we need to include :
        <programlisting>
<![CDATA[#include <iostream>
#include <tulip/Graph.h>]]>
		</programlisting>
        </para>
        <itemizedlist>
        	<listitem><para><code>iostream :</code> This "file" contains the C++ standard declarations for in and out streams. We need it in this tutorial to print the final graph on the standard output.
        	</para></listitem>
        	<listitem><para><code>tulip/Graph.h :</code> This file is the core of the tulip graph API. It provides declarations for graphs (edges , nodes) and functions to load one from a file, to save one, and a lot more. You can find a list in the Tulip Graph library <ulink url="../../doxygen/tulip-lib/Graph_8h.html">documentation</ulink>.
        	</para></listitem>
        </itemizedlist>

	
	<para>The namespaces usage declarations, so that we can omit namespace prefix.
	<programlisting>
<![CDATA[using namespace std;
using namespace tlp;]]>
  	</programlisting></para>
  	</sect2>
  	<sect2 id="code-examples-graphs-create"><title>2. Creation of a Graph</title>
	<para>Create an empty graph with the function <code> Graph* tlp::newGraph( )</code>. This function returns a pointer on a empty Graph.</para>
	
	<programlisting>
<![CDATA[int main() {
  //create an empty graph
  Graph *graph = tlp::newGraph();]]>
  	</programlisting>
  	</sect2>
  	<sect2 id="code-examples-graphs-addnodes"><title>3. Add nodes</title>
  	<para>In the following, we are adding three nodes with the member function <code>  node Graph::addNode () </code> that will, create an instance of a 'node', add it to the graph, and return it.<note><para>Using this function, the node is also added in all the graph ancestors to maintain the sub-graph relation between graphs.</para></note>
  	</para>
  	
  	
  	<programlisting>
<![CDATA[  //add three nodes
  node n1 = graph->addNode();
  node n2 = graph->addNode();
  node n3 = graph->addNode();]]>
  	</programlisting>
  	</sect2>
  	<sect2 id="code-examples-graphs-addedges"><title>4. Add edges</title>
  	<para>Now that nodes are created, we can create the edges. To do so, we can use the function <code>  edge Graph::addEdge  ( const node, const node ) </code> that will, add a new edge in the graph and return it.<note><para>The edge is also added in all the super-graph of the graph to maintain the sub-graph relation between graphs.</para></note>
  	 </para>
  	 <para>
  	 	The first parameter is the "source node", and, of course, the second is the "target node" (in tulip, every edge are oriented but you can choose not to consider the orientation). We will see later (TUTORIAL 005) that the edges enumeration order is the one in which they are added. 
  	 </para>
  	
  	<programlisting>
<![CDATA[  //add three edges
  edge e1 = graph->addEdge(n2,n3);
  edge e2 = graph->addEdge(n1,n2);
  edge e3 = graph->addEdge(n3,n1);]]>
  	</programlisting>
  	<para>Following is a picture of the graph that we just have created. It is being displayed with tulip.</para>
  	<graphic fileref="images/tuto_001_graphcreated_1.png"/>
  	</sect2>
  	<sect2 id="code-examples-graphs-delEdgeNode"><title>5. Delete an edge and a node</title>
  	
  	<para> The Graph class provides member functions to delete edges and nodes.
  	<itemizedlist>
  		<listitem><para><code>  void tlp::Graph::delEdge (const edge) </code> :
  			delete an edge of the graph. This edge is also removed in all the sub-graphs hierarchy to maintain the sub-graph relation between graphs. The ordering of edges is preserved. 
  		</para></listitem>
  		<listitem><para><code>  void tlp::Graph::delNode ( const node ) </code> :
  			delete a node of the graph. This node is also removed in all the sub-graph of the graph to maintain the sub-graph relation between graphs. When the node is deleted, all its edges are deleted (in and out edges).
  		</para></listitem>
  	</itemizedlist></para>
  	<note><para>The class Graph implements member functions like <code>void delAllNode (const node)</code>, and, <code>void delAllEdge (const edge)</code>.</para></note> 
  	<programlisting>
<![CDATA[  //delete an edge
  graph->delEdge(e1);

  //delete a node
  graph->delNode(n2);]]>
  	</programlisting>
  	<para>Following is our graph with node n2 deleted.</para>
  	<graphic fileref="images/tuto_001_graphcreated_2.png"/>
  	</sect2>
  	<sect2 id="code-examples-graphs-print"><title>6. Printing the graph</title>
  	<para>The class graph has a friend function which is an overload of the stream operator &lt;&lt;. This function will print the graph (only nodes and edges) in an output stream (here, the standard output, "cout"), in the tulip format.</para>
  	<programlisting>
<![CDATA[  //print the result on the standard output
  cout << graph << flush;]]>
        </programlisting>

	</sect2>
	<sect2 id="code-examples-graphs-save"><title>7. Saving a graph</title>
	<para>Instead of having our graph printed on the standard output, we can save it in a .tlp (tulip format) suffixed file that can be read by tulip :</para>
        <programlisting>
<![CDATA[  //Save  the graph :
  tlp::saveGraph(graph,"tuto1.tlp");]]>
        </programlisting>
        </sect2>
	<sect2 id="code-examples-graphs-del"><title>8. Graph deletion</title>
	<para>Before exiting the main function, do not forget memory leaks, and delete the graph to free memory usages.</para>
	<programlisting>
<![CDATA[  //delete the graph
  delete graph;
  return EXIT_SUCCESS;
}]]>
        </programlisting>
        </sect2>
        <sect2 id="code-examples-graphs-run"><title>9. Compiling and running the program.</title>
        <para>
        Compile this program with this command :</para>
	<para><code>g++ `tulip-config --libs --cxxflags` tutorial.cpp -o tutorial001 </code>
        </para>
        <para>Run it to have a look :</para>
	 <para><code> ./tutorial001 </code> </para>
        <graphic fileref="images/tuto_001_graphcreated_3.png"/>
        </sect2>
        <sect2 id="code-examples-graphs-exit"><title>10. Source Code</title>
        
<programlisting>
<![CDATA[#include <iostream>
#include <tulip/Graph.h>

/**
 *
 * Tutorial 001
 *
 * Create a graph 
 * add three nodes and three edges
 * remove an edge and a node
 * print the result on the standard output
 * 
 */

using namespace std;
using namespace tlp;

int main() {
  //create an empty graph
  Graph *graph = tlp::newGraph();

  //add three nodes
  node n1 = graph->addNode();
  node n2 = graph->addNode();
  node n3 = graph->addNode();

  //add three edges
  edge e1 = graph->addEdge(n2,n3);
  edge e2 = graph->addEdge(n1,n2);
  edge e3 = graph->addEdge(n3,n1);

  //delete an edge
  graph->delEdge(e1);

  //delete a node
  graph->delNode(n2);

  //print the result on the standard output
  cout << graph << flush ;

  tlp::saveGraph(graph,"tuto1.tlp");

  //delete the graph
  delete graph;
  return EXIT_SUCCESS;
}]]>
        </programlisting>
	<para>
	</para>
	<para>
	</para>
	<para>
	</para>
        </sect2>
    </sect1>
    <sect1 id="code-examples-iterator-foreach"><title>TUTORIAL 002 : Iterating over a graph (class Iterator and the macro forEach)</title>
    	<para>
    		In this tutorial, we will, display on the standard output, all the structure using iterators. For each node, we will display its ancestors, successors, neighbors, and, its incoming and outgoing edges.
    	</para>
    	<para> In this tutorial, the graph created is the same that in Tutorial 1 (after the 3 edges were added) see the following picture :
    	</para>
    
    
    	<graphic fileref="images/tuto_001_graphcreated_1.png"/>
    	
    	<sect2 id="code-examples-iterator-headfile"><title>1. Header files (Same as Tutorial 1)</title>
        <para>Let's start with the files we need to include :
        <programlisting>
<![CDATA[#include <iostream>
#include <tulip/Graph.h>]]>
		</programlisting>
        </para>
        <itemizedlist>
        	<listitem><para><code>iostream :</code> This "file" contains the C++ standard declarations for in and out streams. We need it in this tutorial to print the final graph on the standard output.
        	</para></listitem>
        	<listitem><para><code>tulip/Graph.h :</code> This file is the core of the tulip graph API. It provides declarations for graphs (edges , nodes) and functions to load one from a file, to save one, and a lot more. You can find a list in the doxygen <ulink url="../../doxygen/tulip-lib/Graph_8h.html">documentation</ulink>.
        	</para></listitem>
        </itemizedlist>
	<para>As you can see, we just need the "Graph.h" header file to create a graph and iterate over its nodes, even though the declaration of the abstract class "Iterator" is in Iterator.h</para>    	
    	</sect2>
    	
    	<sect2 id="code-examples-iterator-allnode"><title>2. Iterating over all nodes</title>
    		<para> To iterate over all nodes, we need to create an Iterator on the graph nodes with the member function <code>Iterator* Graph::getNodes () const</code>, we will make it point on the graphs nodes.
    		</para>
    		<programlisting>
<![CDATA[  Iterator<node> *itNodes = graph->getNodes();]]>
        	</programlisting>
    		<para>
    		 The documentation of the interface Iterator can be found <ulink url="http://tulip.labri.fr/doxygen/tulip-lib/structtlp_1_1Iterator.html"> here.</ulink>
    		</para>
    		<para>With the functions <code>template &lt;class itType &gt;
 bool tlp::Iterator&lt; itType &gt;::hasNext ( )</code> and <code> node next ( )</code>, we can iterate through our graph nodes with a simple while :
		</para>
		<programlisting role="C">
<![CDATA[   while(itNodes->hasNext()) {
   	node n = itNodes->next();]]>
        	</programlisting>
        	<para>In this <code>while</code> loop, we display some node topological properties :</para>
        	<programlisting role="C">
<![CDATA[    cout << "node: " <<  n.id << endl;
    cout << " degree: " << graph->deg(n) << endl;
    cout << " in-degree: " << graph->indeg(n) << endl;
    cout << " out-degree: " << graph->outdeg(n) << endl;]]>
        	</programlisting>
        	<para>At the end of the loop, we will need to delete the iterator: <code>delete itNodes;</code> </para>
        	<para>Following is the output of this simple while loop :</para>
        	<programlisting>
<![CDATA[[root@atlas tutorial-002]# ./tutorial002
node: 0
 degree: 2
 in-degree: 1
 out-degree: 1
node: 1
 degree: 2
 in-degree: 1
 out-degree: 1
node: 2
 degree: 2
 in-degree: 1
 out-degree: 1]]>
        	</programlisting>
    	</sect2>
    	<sect2 id="code-example-graphit-pred"><title>3. Iterating through a node predecessors</title>
    		<para>To iterate through predecessors of node, we use the same type of Iterator, but, instead of using the function getNodes() of the class Graph, we will use the function <code> Iterator&lt;node&gt;* getInNodes (const node) const</code> that will return an iterator on the predecessors of a node. </para>
    		
    		<programlisting>
<![CDATA[    //===========================
    //iterate all predecessors of a node
    cout << " predecessors: {";
    Iterator<node> *itN=graph->getInNodes(n);
    while(itN->hasNext()) {
      cout << itN->next().id;
      if (itN->hasNext()) cout << ",";
    } delete itN; //!!!Warning : do not forget to delete iterators (memory leak)
    cout << "}" << endl;]]>
        	</programlisting>
    	</sect2>
    	<sect2 id="code-example-graphit_succs"><title>4. Iterating through a node successors</title>
    		<para>To iterate through successors of a node, we just need to use the function <code>Iterator&lt;node&gt;* Graph::getOutNodes (const node) const</code> to have an Iterator on its successors.</para>
    		
    		<programlisting>
<![CDATA[    //===========================
    //iterate all successors of a node
    cout << " successors: {";
    itN = graph->getOutNodes(n);
    while (itN->hasNext()) {
      cout << itN->next().id;
      if (itN->hasNext()) cout << ",";
    } delete itN; //!!!Warning : do not forget to delete iterators (memory leak)
    cout << "}" << endl;]]>
        	</programlisting>
    	</sect2>
    	<sect2 id="code-example-graphit-all"><title>5. Iterating through a node neighbors (predecessors and successors)</title>
    		<para>For neighbors, we will use the function <code> Iterator&lt;node&gt;* Graph::getInOutNodes (const node) const </code> to have an Iterator on its neighbors.</para>
    		
    		<programlisting>
<![CDATA[    //===========================
    //iterate the neighborhood of a node
    cout << " neighborhood: {";
    itN = graph->getInOutNodes(n);
    while(itN->hasNext()) {
      cout << itN->next().id;
      if (itN->hasNext()) cout << ",";
    } delete itN; //!!!Warning : do not forget to delete iterators (memory leak)
    cout << "}" << endl;]]>
        	</programlisting>
    	</sect2>
        <sect2 id="code-example-graphit-inedges"><title>6. Iterating through a node incoming edges</title>
    		<para>For incoming edges, we will use an Iterator on edges with the member function <code>Iterator&lt;edge&gt;* Graph::getInEdges (const node) const</code>.</para>
    		
    		<programlisting>
<![CDATA[   //===========================
    //iterate the incoming edges
    cout << " incoming edges: {";
    Iterator<edge> *itE=graph->getInEdges(n);
    while(itE->hasNext()) {
      cout << itE->next().id;
      if (itE->hasNext()) cout << ",";
    } delete itE; //!!!Warning : do not forget to delete iterators (memory leak)
    cout << "}" << endl;
    cout << " outcoming edges: {";]]>
        	</programlisting>
    	</sect2>
    	<sect2 id="code-example-graphit-outedges"><title>7. Iterating through a node outgoing edges</title>
    		<para>For outgoing edges, we will use the function <code>Iterator&lt;edge&gt;* Graph::getOutEdges (const node) const</code>.</para>
    		
    		<programlisting>
<![CDATA[     //===========================
    //iterate the outcomming edges
    itE = graph->getOutEdges(n);
    while(itE->hasNext()) {
      cout << itE->next().id;
      if (itE->hasNext()) cout << ",";
    } delete itE; //!!!Warning : do not forget to delete iterators (memory leak)
    cout << "}" << endl;]]>
        	</programlisting>
    	</sect2>
    	<sect2 id="code-example-graphit"><title>8. Iterating through a node adjacent edges</title>
    		<para>For adjacent edges, we will use the function <code>Iterator&lt;edge&gt;* Graph::getInOutEdges (const node) const</code>.</para>
    		
    		<programlisting>
<![CDATA[    //===========================
    //iterate the adjacent edges
    cout << " adjacent edges: {";
    itE = graph->getInOutEdges(n);
    while(itE->hasNext()) {
      cout << itE->next().id;
      if (itE->hasNext()) cout << ",";
    } delete itE; //!!!Warning : do not forget to delete iterators (memory leak)
    cout << "}" << endl;]]>
        	</programlisting>
    	</sect2>
    	<sect2 id="code-example-endwhile"><title>Don't forget memory leaks</title>
    		 <para>As we are still in the first while (iterating through all nodes) we need to delete the Iterator on Nodes :</para>
    		 
    		 <programlisting>
<![CDATA[}// end while 
delete itNodes; //!!!Warning : do not forget to delete iterators (memory leak)]]>
        	</programlisting>
    	</sect2>
    	<sect2 id="code-example-graphit-edges"><title>9. Iterating on edges (all edges).</title>
    		 <para>Some times it can be useful to iterate on edges, for example in the algorithm of Kruskal. That is why the graph class owns the function <code>Iterator&lt;edge&gt;* Graph::getEdges (const node) const</code>, that return a pointer on an Iterator of type edge. Following is an exemple of its use. </para>
    		 
    		 <programlisting>
<![CDATA[  //===========================
  //Iterate all edges
  Iterator<edge> *itEdges=graph->getEdges();
  while(itEdges->hasNext()) {
    edge e = itEdges->next();
    cout << "edge: " << e.id;
    cout << " source: " << graph->source(e).id;
    cout << " target: " << graph->target(e).id;
    cout << endl;
  } delete itEdges; //!!!Warning : do not forget to delete iterators (memory leak)]]>
        	</programlisting>
    	</sect2>
    	<sect2 id="code-example-foreach"><title>10. The forEach Macro </title>
    		<para>To simplify the use of Iterators, the API of tulip provides a macro forEach which is quite similar to the foreach of C# or Java. It takes two parameters :</para>
    		<itemizedlist>
    			<listitem><para> A variable :
    			</para></listitem>
    			<listitem><para>
    				An Iterator for the same type as the variable, for example : Variable of type node, Graph::getNodes().
    			</para></listitem>
    		</itemizedlist>
    		<warning><itemizedlist>
    			<listitem><para>
    				Must use breakForEach to break iteration
    			</para></listitem>
    			<listitem><para> Must use returnForEach to return during iteration
    			</para></listitem>
    		</itemizedlist></warning>
    		<para>This macro function is defined in the header file : tulip/ForEach.h</para>
    		<para>Following is a small example of its use.
    		<programlisting>
<![CDATA[#include <tulip/ForEach.h>

  //...
  //main
  //load Graph 
  //... 
  
  node n = graph->getOneNode();	
  cout << "In Edges :" << endl;		
  edge e;
  forEach(e, graph->getInEdges(n))
  {
    cout << e.id << ",";
  }
  
  //...]]>
        	</programlisting></para>
    	</sect2>
    	<sect2 id="code-example-tuto002"><title>Source Code</title>
    		<programlisting>
<![CDATA[#include <iostream>
#include <tulip/Graph.h>

/**
 * Tutorial 002
 *
 * Create a graph 
 * display all the structure using iterators
 *
 */

using namespace std;
using namespace tlp;

void buildGraph(Graph *graph) {
  //add three nodes
  node n0=graph->addNode();
  node n1=graph->addNode();
  node n2=graph->addNode();
  //add three edges
  graph->addEdge(n1,n2);
  graph->addEdge(n0,n1);
  graph->addEdge(n2,n0);
}

int main() {
  //create an empty graph
  Graph *graph=tlp::newGraph();

  //build the graph
  buildGraph(graph);
  
  //===========================
  //Iterate all nodes and display the structure
  Iterator<node> *itNodes = graph->getNodes();
  while(itNodes->hasNext()) {
    node n = itNodes->next();
    cout << "node: " <<  n.id << endl;
    cout << " degree: " << graph->deg(n) << endl;
    cout << " in-degree: " << graph->indeg(n) << endl;
    cout << " out-degree: " << graph->outdeg(n) << endl;

    //===========================
    //iterate all ancestors of a node
    cout << " ancestors: {";
    Iterator<node> *itN=graph->getInNodes(n);
    while(itN->hasNext()) {
      cout << itN->next().id;
      if (itN->hasNext()) cout << ",";
    } delete itN; //!!!Warning : do not forget to delete iterators (memory leak)
    cout << "}" << endl;

    //===========================
    //iterate all successors of a node
    cout << " successors: {";
    itN = graph->getOutNodes(n);
    while (itN->hasNext()) {
      cout << itN->next().id;
      if (itN->hasNext()) cout << ",";
    } delete itN; //!!!Warning : do not forget to delete iterators (memory leak)
    cout << "}" << endl;

    //===========================
    //iterate the neighborhood of a node
    cout << " neighborhood: {";
    itN = graph->getInOutNodes(n);
    while(itN->hasNext()) {
      cout << itN->next().id;
      if (itN->hasNext()) cout << ",";
    } delete itN; //!!!Warning : do not forget to delete iterators (memory leak)
    cout << "}" << endl;

    //===========================
    //iterate the incoming edges
    cout << " incoming edges: {";
    Iterator<edge> *itE=graph->getInEdges(n);
    while(itE->hasNext()) {
      cout << itE->next().id;
      if (itE->hasNext()) cout << ",";
    } delete itE; //!!!Warning : do not forget to delete iterators (memory leak)
    cout << "}" << endl;
    cout << " outcoming edges: {";

    //===========================
    //iterate the outcomming edges
    itE = graph->getOutEdges(n);
    while(itE->hasNext()) {
      cout << itE->next().id;
      if (itE->hasNext()) cout << ",";
    } delete itE; //!!!Warning : do not forget to delete iterators (memory leak)
    cout << "}" << endl;

    //===========================
    //iterate the adjacent edges
    cout << " adjacent edges: {";
    itE = graph->getInOutEdges(n);
    while(itE->hasNext()) {
      cout << itE->next().id;
      if (itE->hasNext()) cout << ",";
    } delete itE; //!!!Warning : do not forget to delete iterators (memory leak)
    cout << "}" << endl;

  } delete itNodes; //!!!Warning : do not forget to delete iterators (memory leak)

  //===========================
  //Iterate all edges
  Iterator<edge> *itEdges=graph->getEdges();
  while(itEdges->hasNext()) {
    edge e = itEdges->next(); 
    cout << "edge: " << e.id;
    cout << " source: " << graph->source(e).id;
    cout << " target: " << graph->target(e).id;
    cout << endl;
  } delete itEdges; //!!!Warning : do not forget to delete iterators (memory leak)

  delete graph; //delete the entire graph
  return EXIT_SUCCESS;
}]]>
        	</programlisting>
    	</sect2>

    </sect1>
    

    <sect1 id="code-examples-properties"><title>TUTORIAL 003 : Properties</title>
        <para> This tutorial will show you how to add / create properties to a Graph. For local or inherited properties, see tututorial 005. An instance of a property is owned by a graph and is an association table between the elements of graph (nodes and edges) and values of a predefined type.
        </para>
        <sect2 id="code-example-headfiles"><title>1. Header files and predefined properties</title>
        	<para> In tulip API, every type of property is declared in its own header file. Following is a list of those header files and the type of value which can be associated to an element of the graph:
        	</para>
        	<itemizedlist>
        		<listitem><para>DoubleProperty : tulip/DoubleProperty.h /
        			value type for edge = double, node = double
        		</para></listitem>
        		<listitem><para>BooleanProperty : tulip/BooleanProperty.h /
        			value type for edge = bool, node = bool
        		</para></listitem>
        		<listitem><para>IntegerProperty: tulip/IntegerProperty.h /
        			value type for edge = int, node = int
        		</para></listitem>
        		<listitem><para>LayoutProperty : tulip/LayoutProperty.h /
        			value type for edge = Coord(), node = vector&lt;Coord&gt;()
        		</para></listitem>
        		<listitem><para>ColorProperty : tulip/ColorProperty.h /
        			value type for edge = Color(), node = Color()
        		</para></listitem>
        		<listitem><para>SizeProperty : tulip/SizeProperty.h /
        			value type for edge = Size(), node = Size()
        		</para></listitem>
        		<listitem><para>StringProperty : tulip/StringProperty.h /
        			value type for edge = string, node = string
        		</para></listitem> 
        		<listitem><para>GraphProperty : tulip/GraphProperty.h /
        			value type for edge = graph, node = graph
        		</para></listitem>
        	</itemizedlist>
        </sect2>
        <sect2 id="code-example-create-prop"><title>2. Creation of a property.</title>
        	<para>
        		The creation of a property is accomplished by the function <code> Graph::getLocalProperty&lt;TypeProperty&gt;("name of the property")</code>. This function returns a pointer to a property. The real type of the property is given with the template parameter. If the property of the given name does not yet exists, a new one is created and returned. 
        	</para>
        	<warning><para>Using of delete on that property will cause a segmentation violation (use delLocalProperty instead).
        	</para></warning>
        	<para> Following is a sample of code that creates 8 properties :
        	</para>
        	<programlisting>
<![CDATA[  //Get and create several properties
  DoubleProperty *metric = graph->getLocalProperty<DoubleProperty>("firstMetric");
  BooleanProperty *select = graph->getLocalProperty<BooleanProperty>("firstSelection");
  LayoutProperty *layout = graph->getLocalProperty<LayoutProperty>("firstLayout");
  IntegerProperty *integer = graph->getLocalProperty<IntegerProperty>("firstInteger");
  ColorProperty *colors = graph->getLocalProperty<ColorProperty>("firstColors");
  SizeProperty *sizes = graph->getLocalProperty<SizeProperty>("firstSizes");
  GraphProperty *meta = graph->getLocalProperty<GraphProperty>("firstMeta");
  StringProperty *strings = graph->getLocalProperty<StringProperty>("firstString");]]>
        	</programlisting>
        </sect2>
        <sect2 id="code-example-init-props"><title>3. Initialize all properties.</title>
        	<para>
        		One property has to be initialized for both edges and nodes. It is done with the functions <code>setAllNodeValue(value)</code> and <code>setAllEdgeValue(value)</code> which are both member functions of the property.</para>
		<para>Following is an example :</para>
        	<programlisting>
<![CDATA[  //initialize all the properties
  metric->setAllNodeValue(0.0);
  metric->setAllEdgeValue(0.0);
  select->setAllNodeValue(false);
  select->setAllEdgeValue(false);
  layout->setAllNodeValue(Coord(0,0,0)); //coordinates
  layout->setAllEdgeValue(vector<Coord>());//Vector of bends
  integer->setAllNodeValue(0);
  integer->setAllEdgeValue(0);
  sizes->setAllNodeValue(Size(0,0,0)); //width, height, depth
  sizes->setAllEdgeValue(Size(0,0,0)); //start_size, end_size, arrow_size
  colors->setAllNodeValue(Color(0,0,0,0));//Red, green, blue, alpha
  colors->setAllEdgeValue(Color(0,0,0,0));//Red, green, blue, alpha
  strings->setAllNodeValue("first");
  strings->setAllEdgeValue("first");
  meta->setAllNodeValue(graph); //an existing graph]]>
        	</programlisting>
        	<para>Following is the display (in the tulip GUI) of the list of a node associated values for the properties previously created :</para>
        	<graphic fileref="images/tuto_003_properties_1.png"/>
        </sect2>
        <sect2 id="code-example-iter-props"><title>4. Iterating over properties.</title>
        	<para>Once again, iteration is made with Iterators. The class graph has a member function <code>Iterator&lt; std::string &gt;* getLocalProperties ()</code> that returns an iterator on the local properties.</para>
        	
        	<para>Following is an example :</para>
        	<programlisting>
<![CDATA[  cout << "List of the properties present in the graph:" << endl;
  Iterator<string> *it=graph->getLocalProperties();
  while (it->hasNext()) {
    cout << it->next() << endl;
  } delete it;]]>
        	</programlisting>
        	
        	<para>You can also use the macro forEach.</para>
        </sect2>
                	<sect2 id="code-example-003-codesource"><title>Source Code</title>
        		<programlisting>
<![CDATA[#include <iostream>
#include <tulip/BooleanProperty.h>
#include <tulip/ColorProperty.h>
#include <tulip/DoubleProperty.h>
#include <tulip/GraphProperty.h>
#include <tulip/IntegerProperty.h>
#include <tulip/LayoutProperty.h>
#include <tulip/SizeProperty.h>
#include <tulip/StringProperty.h>

/**
 * Tutorial 003
 *
 * Create a graph and a properties of each type
 * And display properties present in the graph
 */

using namespace std;
using namespace tlp;

void buildGraph(Graph *graph) {
  //add three nodes
  node n1=graph->addNode();
  node n2=graph->addNode();
  node n3=graph->addNode();
  //add three edges
  graph->addEdge(n2,n3);
  graph->addEdge(n1,n2);
  graph->addEdge(n3,n1);
}

int main() {
  //create an empty graph
  Graph *graph=tlp::newGraph();
  //build the graph
  buildGraph(graph);

  //Get and create several properties
  DoubleProperty *metric=graph->getLocalProperty<DoubleProperty>("firstMetric");
  BooleanProperty *select=graph->getLocalProperty<BooleanProperty>("firstSelection");
  LayoutProperty *layout=graph->getLocalProperty<LayoutProperty>("firstLayout");
  IntegerProperty *integer=graph->getLocalProperty<IntegerProperty>("firstInteger");
  ColorProperty *colors=graph->getLocalProperty<ColorProperty>("firstColors");
  SizeProperty *sizes=graph->getLocalProperty<SizeProperty>("firstSizes");
  GraphProperty *meta=graph->getLocalProperty<GraphProperty>("firstMeta");
  StringProperty *strings=graph->getLocalProperty<StringProperty>("firstString");

  //initialize all the properties
  metric->setAllNodeValue(0.0);
  metric->setAllEdgeValue(0.0);
  select->setAllNodeValue(false);
  select->setAllEdgeValue(false);
  layout->setAllNodeValue(Coord(0,0,0)); //coordinates
  layout->setAllEdgeValue(vector<Coord>());//Vector of bends
  integer->setAllNodeValue(0);
  integer->setAllEdgeValue(0);
  sizes->setAllNodeValue(Size(0,0,0)); //width, height, depth
  sizes->setAllEdgeValue(Size(0,0,0)); //start_size, end_size, arrow_size
  colors->setAllNodeValue(Color(0,0,0,0));//Red, green, blue
  colors->setAllEdgeValue(Color(0,0,0,0));//Red, green, blue
  strings->setAllNodeValue("first");
  strings->setAllEdgeValue("first");
  meta->setAllNodeValue(graph); //an existing graph
  cout << "List of the properties present in the graph:" << endl;
  Iterator<string> *it=graph->getLocalProperties();
  while (it->hasNext()) {
    cout << it->next() << endl;
  } delete it;

  tlp::saveGraph (graph, "tutoproper.tlp");  
  delete graph;
  return EXIT_SUCCESS;
}]]>
        		</programlisting>
        	</sect2>
       
    </sect1>
    <sect1 id="code-examples-subgraph"><title>TUTORIAL 004 : Create your first subgraph.</title>
    		<para>This tutorial will teach you how to create subgraphs. At the end of it, we will have a hierarchy of 3 graphs.</para>
    		<para>Before anything consider the following function that creates 3 nodes and 3 edges (same as in tutorial 001 ):</para>
    		<programlisting>
<![CDATA[void buildGraph(Graph *graph) 
{
  //add three nodes
  node n1=graph->addNode();
  node n2=graph->addNode();
  node n3=graph->addNode();
  //add three edges
  graph->addEdge(n2,n3);
  graph->addEdge(n1,n2);
  graph->addEdge(n3,n1);
}]]>
        	</programlisting>
        	
        	<para>The creation of a subgraph is quite simple. You just have to use the function <code>Graph* addSubGraph (BooleanProperty* selection = 0) </code>. It will create and return a new SubGraph of the graph. The elements of the new subgraph are those selected in the selection(selection associated value equals true); if there is no selection an empty subgraph is returned. </para>
        	<para>In the following sample we create 3 empty subgraphs :</para>
        	
        	<programlisting>
<![CDATA[  //build three empty subgraphs
  Graph *subgraph0=graph->addSubGraph();
  Graph *subgraph1=graph->addSubGraph();
  Graph *subgraph2=subgraph1->addSubGraph();]]>
        	</programlisting>
        	
        	<para>We now need to create some nodes and edges :</para>
        	<programlisting>
<![CDATA[   //add node inside subgraphs
  buildGraph(subgraph0);
  buildGraph(subgraph1);
  buildGraph(subgraph2);]]>
        	</programlisting>
        	
        	<para>Following is the hierarchy we have just created, displayed with tulip :</para>
        	<graphic fileref="images/tuto_004_subgraph_1.png" />
        	
        	
        	<para>We can check that by iterating on our graph's subgraphs using the function <code>Iterator&lt; Graph * &gt;* Graph::getSubGraphs()</code> :</para>
        	<programlisting>
<![CDATA[  //iterate subgraph (0 and 1 normally ) and output them
  Iterator<Graph *> *itS=graph->getSubGraphs();
  while (itS->hasNext())
    cout << itS->next() << endl;
  delete itS;]]>
        	</programlisting>
        	
        	 <sect2 id="code-example-004-code"><title>Source Code</title>
        	<programlisting>
<![CDATA[#include <iostream>
#include <tulip/Graph.h>

/**
 * Tutorial 004
 *
 * Create a graph and three subgraphs,
 * display all the structure using iterators
 */

using namespace std;
using namespace tlp;

void buildGraph(Graph *graph) {
  //add three nodes
  node n1=graph->addNode();
  node n2=graph->addNode();
  node n3=graph->addNode();
  //add three edges
  graph->addEdge(n2,n3);
  graph->addEdge(n1,n2);
  graph->addEdge(n3,n1);
}

int main() {
  //create an empty graph
  Graph *graph=tlp::newGraph();

  //build the graph
  buildGraph(graph);

  //build two empty subgraph
  Graph *subgraph0=graph->addSubGraph();
  Graph *subgraph1=graph->addSubGraph();
  Graph *subgraph2=subgraph1->addSubGraph();

  //add node inside subgraphs
  buildGraph(subgraph0);
  buildGraph(subgraph1);
  buildGraph(subgraph2);

  //iterate subgraph (0 and 1 normally ) and output them
  Iterator<Graph *> *itS=graph->getSubGraphs();
  while (itS->hasNext()) 
    cout << itS->next() << endl;
  delete itS;

  delete graph;
  return EXIT_SUCCESS;
}]]>
        	</programlisting>
        </sect2>

    </sect1>
    <sect1 id="code-examples-propertiessub"><title>TUTORIAL 005 : Properties and subgraphs</title>
    		<para>In this tutorial, we will show you how to use properties with subgraphs, how to deal with properties in a big hierarchy. To do so, we will create a graph with some properties, several subgraphs with other properties and iterate over local and inherited properties.</para>
    		<sect2 id="code-example-propertiessub-intro"><title>1. Introduction </title>
    			<para>We will first begin with the creation of the graph and its properties :</para>
    			<programlisting>
<![CDATA[int main() {
  //create an empty graph
  Graph *graph=tlp::newGraph();

  //build the graph
  buildGraph(graph);

  //Get and create several properties
  BooleanProperty *select=graph->getLocalProperty<BooleanProperty>("firstSelection");
  graph->getLocalProperty<ColorProperty>("firstColors");
  graph->getLocalProperty<DoubleProperty>("firstMetric");

  //init the selection in order to use it for building clone subgraph
  select->setAllNodeValue(true);
  select->setAllEdgeValue(true);]]>
        		</programlisting>
        		<note><para>The function <code>void buildGraph(Graph *g)</code>, is the one implemented in Tutorial 004.</para></note>
        		<para>In the sample of code above, we create a graph with 3 properties : firstSelection (select), fisrtColors and firstMetric. We then set all nodes and edges "firstSelection" associated value to true which means that all nodes and edges are selected.</para>
        		<para>We, then, create two subgraphs out of our selection (the entire graph) : </para>
        		
        		<programlisting>
<![CDATA[  //Create a hierarchy of subgraph (they all own the same elements)
  Graph *subgraph1=graph->addSubGraph(select);
  Graph *subgraph2=subgraph1->addSubGraph(select);]]>
        		</programlisting>    
        		<para>And, to finish this section, we add some new properties to those two subgraphs :</para>
        		<programlisting>
<![CDATA[   //create a property in subgraph1 (redefinition of the one defined in graph)
  subgraph1->getLocalProperty<DoubleProperty>("firstMetric");

  //create a new property in subgraph1
  subgraph1->getLocalProperty<DoubleProperty>("secondMetric");

  //create a new property in subgraph3
  subgraph2->getLocalProperty<DoubleProperty>("thirdMetric");]]>
        		</programlisting>
        		<para>The property "firstMetric" will be redefined but not the two other ones.</para>
    		</sect2>
    		<sect2 id="code-example-propertiessub-sub1"><title>2. Properties of subgraph1 </title>
    			<para>A good way to see what we have created is to iterate over the local properties of subgraph1 and in a second time iterate over inherited properties. </para>
    			<para>Following is a sample and its output that enables the iteration over local properties :</para>
    			<programlisting>
<![CDATA[  cout << "List of the local properties present in the subgraph1:" << endl;   
  Iterator<string> *it=subgraph1->getLocalProperties();    		    
  while (it->hasNext()) {                                 		    
    cout << it->next() << endl;                                           
  } delete it;          
  
  
_________________________________________________________________________  

 
[root@atlas tutorial-005]# ./tutorial 
List of the local properties present in the subgraph1:
firstMetric	
secondMetric]]>
        		</programlisting>
        		
        		
		       
			
        		<para>As you can see the only local properties that has subgraph1 are "firstMetric" and "secondMetric". Indeed, "firstMetric" has been redefined, and, "thirdMetric" has been created with subgraph2.</para>
        		<para>Following is a sample and its output that enables the iteration over inherited properties :</para>
        		<programlisting>
<![CDATA[  cout << "List of the inherited properties present in the subgraph1:" << endl;  
  it=subgraph1->getInheritedProperties();                        		        
  while (it->hasNext()) {                                 		        
    cout << it->next() << endl;                                               
  } delete it;                                                                
  
_________________________________________________________________________  

 List of the local properties present in the subgraph1:  
   firstColors       		
   firstSelection]]>
        		</programlisting>
        		<para>As you can see, subgraph1 just has two inherited properties since "firstMetric" has been redefined.</para>
        		
			<para>Following is a sample of code that lists all the properties of a graph, the inherited properties and local properties :</para>
			<programlisting>
<![CDATA[  cout << "List of properties present in the subgraph1:" << endl;
  it=subgraph1->getProperties();
  while (it->hasNext()) {
    cout << it->next() << endl;
  } delete it;
  
_________________________________________________________________________    
  
List of properties present in the subgraph1:
firstMetric
secondMetric
firstColors
firstSelection]]>
        		</programlisting>

    		</sect2>
    		<sect2 id="code-example-propertiessub-sub2"><title>3. Properties of subgraph2 </title>
    			<para>As we did with subgraph1, we will now iterate over the local properties of subgraph2 in a first time and in a second time iterate over its inherited properties. </para>
    			<para>Following is a sample and its output that enables the iteration over local properties :</para>
    			<programlisting>
<![CDATA[  cout << "List of the local properties present in the subgraph2:" << endl;  
  it=subgraph2->getLocalProperties();    		                            
  while (it->hasNext()) {                                 		    
    cout << it->next() << endl;                                           
   } delete it;                                                            

_________________________________________________________________________

[root@atlas tutorial-005]# ./tutorial
 List of the local properties present in the subgraph2:
 thirdMetric]]>
        		</programlisting>
        		<para>The only local properties that has subgraph1 is thirdMetric.</para>
        		<para>Following is a sample and its output that enables the iteration over inherited properties :</para>
        		<programlisting>
<![CDATA[  cout << "List of the inherited properties present in the subgraph2:" << endl;   
  it=subgraph2->getInheritedProperties();                        		        
  while (it->hasNext()) {                                 		        
    cout << it->next() << endl;                                                 
  } delete it;                                                                        		
      		
_________________________________________________________________________ 
      		
List of the local properties present in the subgraph2:      		
firstColors     		
firstMetric     		
firstSelection      		
secondMetric]]>
        		</programlisting>
        		<para>As you can see, subgraph2 has a lot of inherited properties since he is the subgraph of subgraph1 which is the subgraph of the root graph. </para>
        		
    		</sect2>
    		<sect2 id="code-example-005-code"><title>Source Code</title>
    			
    			<programlisting>
<![CDATA[#include <iostream>
#include <tulip/BooleanProperty.h>
#include <tulip/ColorProperty.h>
#include <tulip/DoubleProperty.h>

/**
 * Tutorial 005
 *
 * Create a graph hierarchy with several properties
 * Display the inherited and local properties in each graph
 */

using namespace std;
using namespace tlp;

void buildGraph(Graph *graph) {
  //add three nodes
  node n1=graph->addNode();
  node n2=graph->addNode();
  node n3=graph->addNode();
  //add three edges
  graph->addEdge(n2,n3);
  graph->addEdge(n1,n2);
  graph->addEdge(n3,n1);
}

int main() {
  //create an empty graph
  Graph *graph=tlp::newGraph();

  //build the graph
  buildGraph(graph);

  //Get and create several properties
  BooleanProperty *select=graph->getLocalProperty<BooleanProperty>("firstSelection");
  graph->getLocalProperty<ColorProperty>("firstColors");
  graph->getLocalProperty<DoubleProperty>("firstMetric");

  //init the selection in order to use it for building clone subgraph
  select->setAllNodeValue(true);
  select->setAllEdgeValue(true);

  //Create a hierarchy of subgraph (there are all the same)
  Graph *subgraph1=graph->addSubGraph(select);
  Graph *subgraph2=subgraph1->addSubGraph(select);

  //create a property in subgraph1 (redefinition of the one defined in graph)
  subgraph1->getLocalProperty<DoubleProperty>("firstMetric");

  //create a new property in subgraph1
  subgraph1->getLocalProperty<DoubleProperty>("secondMetric");

  //create a new property in subgraph3
  subgraph2->getLocalProperty<DoubleProperty>("thirdMetric");

  cout << "List of the local properties present in the subgraph1:" << endl;
  Iterator<string> *it=subgraph1->getLocalProperties();
  while (it->hasNext()) {
    cout << it->next() << endl;
  } delete it;

  cout << "List of inherited properties present in the subgraph1:" << endl;
  it=subgraph1->getInheritedProperties();
  while (it->hasNext()) {
    cout << it->next() << endl;
  } delete it;


  cout << "List of properties present in the subgraph1:" << endl;
  it=subgraph1->getProperties();
  while (it->hasNext()) {
    cout << it->next() << endl;
  } delete it;


  cout << "List of the local properties present in the subgraph2:" << endl;
  it=subgraph2->getLocalProperties();
  while (it->hasNext()) {
    cout << it->next() << endl;
  } delete it;

  cout << "List of inherited properties present in the subgraph2:" << endl;
  it=subgraph2->getInheritedProperties();
  while (it->hasNext()) {
    cout << it->next() << endl;
  } delete it;

  delete graph;
  return EXIT_SUCCESS;
}]]>
        		</programlisting>
    			
    		</sect2>
    </sect1>
    <sect1 id="code-examples-edge-order"><title>TUTORIAL 006 : Edges order.</title>
    	<para>In this tutorial, we will learn how to change edges order in the graph edges adjacency list (please visit <ulink url="http://en.wikipedia.org/wiki/Acyclic_Graph#Adjacency_and_degree">Wikipedia: Adjacency and degree</ulink> for more details ). Indeed, it can be useful to sort the edges considering a metric.</para>
		    <sect2 id="code-example-edgesorder-intro"><title>1. Creation of the graph and its edges </title>
		    	<para>We will create a graph with 4 nodes and 4 edges. Their "id number" will start from 0 just like in the figure below :</para>
		    	<graphic fileref="images/tuto_006_edgeorder_1.png" />
		    	<para>Following is the sample of code that created such a graph: </para>
		    	<programlisting>
<![CDATA[int main() {
  //create an empty graph
  Graph *graph=tlp::newGraph();

  //build the graph
  node n0=graph->addNode();
  node n1=graph->addNode();
  node n2=graph->addNode();
  node n3=graph->addNode();

  //add three edges
  edge e0=graph->addEdge(n1,n2);
  edge e1=graph->addEdge(n0,n1);
  edge e2=graph->addEdge(n2,n0);
  edge e3=graph->addEdge(n3,n0);]]>
        		</programlisting>
        		<para>As you can see, node 0 has three edges : edge 1,edge 2 and edge 3. And if we display its edges adjacency list (see last section for function <code> void displayAdjacency(node n, Graph *graph) </code> ) we obtain the following output : </para>
        		<programlisting><![CDATA[ 1 2 3 ]]> </programlisting>
		    </sect2>
		    <sect2 id="code-example-edgesorder-"><title>2. Swap edges</title>
		    <para>Swapping edges can be easily done with the function, <code> void Graph::swapEdgeOrder ( const node, const edge,const  edge)</code> that will, as said swap two edges in the adjacent list of a node. Following is an example of its use : </para>
		    <programlisting>
<![CDATA[  //swap e1 and e3
  graph->swapEdgeOrder(n0, e1, e3);]]>
        	    </programlisting>
        	    <para>As you can see, the adjacency list has changed :</para>
        	    <programlisting> <![CDATA[ 3 2 1 ]]> </programlisting>
  
		    </sect2>
		    <sect2 id="code-example-edgesorder-setorder"><title>3. Setting an order</title>
		    	<para>An other way to change the edges order is to use a vector of type edge and the function : <code> void Graph::setEdgeOrder (const node, const std::vector &lt; edge  &gt; )</code>, following is an example that will replace e1 and e3 in their original order :</para>
		     <programlisting>
<![CDATA[  vector<edge> tmp(2);
  tmp[0]=e1;
  tmp[1]=e3;
  graph->setEdgeOrder(n0,tmp);]]>
        	    </programlisting>
        	    <para>And the new order : </para>
        	    <programlisting> <![CDATA[ 1 2 3 ]]> </programlisting>
        	    
		    </sect2>
		    <sect2 id="code-example-006-code"><title>Source Code</title>
		    	<programlisting>
<![CDATA[#include <iostream>
#include <tulip/Graph.h>
#include <tulip/MutableContainer.h>

/**
 * Tutorial 006
 *
 * Create a graph
 * Order the edges around the nodes
 */

using namespace std;
using namespace tlp;

void buildGraph(Graph *graph) {
  //add three nodes
  node n0=graph->addNode();
  node n1=graph->addNode();
  node n2=graph->addNode();
  //add three edges
  graph->addEdge(n1,n2);
  graph->addEdge(n0,n1);
  graph->addEdge(n2,n0);
}

void displayAdjacency(node n, Graph *graph) {
  Iterator<edge>*ite=graph->getInOutEdges(n);
  while(ite->hasNext())
    cout << ite->next().id << " ";
  delete ite;
  cout << endl;
}

int main() {
  //create an empty graph
  Graph *graph=tlp::newGraph();

  //build the graph
  node n0=graph->addNode();
  node n1=graph->addNode();
  node n2=graph->addNode();
  node n3=graph->addNode();

  //add three edges
  edge e0=graph->addEdge(n1,n2);
  edge e1=graph->addEdge(n0,n1);
  edge e2=graph->addEdge(n2,n0);
  edge e3=graph->addEdge(n3,n0);

  tlp::saveGraph(graph, "adj1.tlp");

  //display current order of edge around n1
  displayAdjacency(n0,graph);
  
  //swap e1 and e3
  graph->swapEdgeOrder(n0,e1,e3);
  

  //display the new order of edge around n1
  displayAdjacency(n0,graph);

  vector<edge> tmp(2);
  tmp[0]=e1;
  tmp[1]=e3;
  graph->setEdgeOrder(n0,tmp);
  //display the new order of edge around n1
  displayAdjacency(n0,graph);
  delete graph;
  return EXIT_SUCCESS;
}]]> </programlisting>
		    	
		    </sect2>
    </sect1>
     <sect1 id="code-examples-mutablecont"><title>TUTORIAL 007 : Mutable Collection</title>
     		<para>In this small tutorial, we will learn how to use the Mutable Container (an efficient associative container) of the tulip API that enables :</para>
     		<itemizedlist>
     			<listitem><para>
     				A tradeoff between speed and memory.
     			</para></listitem>
     			<listitem><para>
     				To manage fragmented index
     			</para></listitem>
     		</itemizedlist>
     		<para>The direct access in this container is forbidden, but it exist a getter and a setter :</para>
     		<itemizedlist>
     			<listitem><para> <code>const ReturnType&lt;TYPE
&gt;::ConstValue MutableContainer&lt;type&gt;::get(const unsigned int i) const</code> that returns a reference instead of a copy in order to minimize the number copy of objects, user must be aware that calling the set function can devalidate this reference
			</para></listitem>
			<listitem><para>
			 <code> void MutableContainer&lt;type&gt;::set( const unsigned int i,const TYPE value).</code>
			 </para></listitem>
		</itemizedlist>
     		<para>The MutableContainer has two more methods :</para>
     		<itemizedlist>
     			<listitem><para>
     				<code>void setAll (const TYPE value)</code>
     			</para></listitem>
     			<listitem><para>
     				<code>IteratorValue* findAll(const TYPE &amp;value, bool equal = true) const</code> 
     			</para></listitem>
     		</itemizedlist>
     		<para>Following is a small example of its use :</para>
     		<programlisting>
<![CDATA[  //declaration of a new MutableContainer 
  MutableContainer<int> t;
  
  //set all element to 0
  t.setAll(0);
  //except element of index 1 set to 1.
  t.set(1,1);
  
  //display on standard output
  cout << t.get(1) << "and" << t.get(2) << endl;]]>
        	    </programlisting>
     </sect1>
     <sect1 id="code-examples-graphs-tests"><title>TUTORIAL 008 : Graph Tests</title>
     		<para>The tulip API has special functions to test if a graph is element of a specific class of graph. Moreover results are buffered and automatically updated if it is possible in constant time. </para>
     		<para>Specific functions are available for each test.</para>
     		<para>Each class of graph has its own header file. Following is a list of those header files and an example of their use :</para>
     		<itemizedlist>
     			<listitem><para>
     				tulip/AcyclicTest.h
     				<programlisting> <![CDATA[AcyclicTest::isAcyclic(graph);]]>
        	    		</programlisting>
     			</para></listitem>
     			<listitem><para>
     				tulip/BiconnectedTest.h
     				<programlisting> <![CDATA[BiconnectedTest::isBiconnected(graph);]]>
        	    		</programlisting>
     			</para></listitem>
     			<listitem><para>
     				tulip/ConnectedTest.h
     				<programlisting> <![CDATA[ConnectedTest::isConnected(graph);]]>
        	    		</programlisting>
     			</para></listitem>
     			<listitem><para>
     				tulip/OuterPlanarTest.h
     				<programlisting> <![CDATA[PlanarityTest::isOuterPlanar(graph);]]>
        	    		</programlisting>
     			</para></listitem>
     			<listitem><para>
     				tulip/PlanarityTest.h
     				<programlisting> <![CDATA[PlanarityTest::isPlanar(graph);]]>
        	    		</programlisting>
     			</para></listitem>
     			<listitem><para>
     				tulip/SimpleTest.h
     				<programlisting> <![CDATA[SimpleTest::isSimple(graph);]]>
        	    		</programlisting>
     			</para></listitem>
     			<listitem><para>
     				tulip/TreeTest.h
     				<programlisting> <![CDATA[ TreeTest::isTree(graph);]]>
        	    		</programlisting>
     			</para></listitem>
     			<listitem><para>
     				tulip/TriconnectedTest.h
     				<programlisting> <![CDATA[TriconnectedTest::isTriconnected(graph);]]>
        	    		</programlisting>
     			</para></listitem>
     		</itemizedlist>
     </sect1>
     <sect1 id="code-examples-observablegraph"><title>TUTORIAL 009 : ObservableGraph</title>
     	<para>
     		In this tutorial, we will show you how to use the class ObservableGraph that enables to receive notification when a graph is updated.
     	</para>
     	<para>First, we will create a class that inherits from ObservableGraph, and then use it and see what this new class is able to "do".</para>
     	<sect2 id="code-exmple-obser1"><title>1. Our new class, GraphObserverTest :</title>
     		<para>Header files and namespaces :</para>
     		<para>To continue this tutorial, we need to include the following files, and namespaces.</para>
     		<programlisting>
<![CDATA[#include <iostream>
#include <set>
//- - - - - - - - - - - - -
#include <tulip/TlpTools.h>
#include <tulip/Graph.h>
#include <tulip/ObservableGraph.h>
//- - - - - - - - - - - - -

using namespace std;
using namespace tlp;]]>
        	</programlisting>
        	
        	<para>As said before, we will create a new class that inherits from ObservableGraph. This class will have several functions to be notified when a node or an edge is deleted or added or reversed (edge).</para>
        	<para>Following is the class GraphObserverTest :</para>
        	<programlisting>
<![CDATA[class GraphObserverTest : public GraphObserver {
public:
  GraphObserverTest() {
  }

private:
  void addEdge(Graph * g,const edge e) {
    cout << "edge :" << e.id << " has been added" << endl;
  }
  void delEdge(Graph *,const edge e) {
    cout << "edge :" << e.id << " is about to be deleted" << endl;
  }
  void reverseEdge(Graph *,const edge e) {
    cout << "edge :" << e.id << " is about to be reversed" << endl;
  }
  void addNode(Graph * g,const node n) {
    cout << "node :" << n.id << " has been added" << endl;
  }
  void delNode(Graph *,const node n) {
    cout << "node :" << n.id << " is about to be deleted" << endl;
  }
  void destroy(Graph *g) {
    cout << "graph : " << g->getId() << " is about to be deleted" << endl;
  }
};]]>
        	</programlisting>
        	<para>Those methods are redefinitions of their homologues in the super class.</para>
        	
     	</sect2>
        <sect2 id="code-example-obsmain"><title>2. The Main function</title>
        	<para>Following in the main function with some explanations :</para>
        	<programlisting>
<![CDATA[int main(int argc, char **argv) {
  Graph *graph = tlp::newGraph();]]>
        	</programlisting>
        	<para>Nothing really new here, just the creation of the graph.</para>
        	<programlisting>
<![CDATA[  //- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  GraphObserverTest graphObserverTest;
  graph->addGraphObserver(&graphObserverTest);
  //- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -]]>
        	</programlisting>
        	<para> We add the instance of our class GraphObserverTest with the function <code> Graph::addObserver </code>.
        	</para>
        	<para>We then perform some modifications on the graph :</para>
        	<programlisting>
<![CDATA[  node n1 = graph->addNode();
  node n0 = graph->addNode();
  edge e0  = graph->addEdge(n0, n1);
  graph->reverse(e0);
  graph->delNode(n0);
  delete graph;
  //- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  return EXIT_SUCCESS;
}]]>
        	</programlisting>
        	<para>Following is the output of this program :</para>
        	<programlisting>
<![CDATA[node :0 has been added
node :1 has been added
edge :0 has been added
edge :0 is about to be reversed
node :0 is about to be deleted 
edge :0 is about to be deleted]]>
        	</programlisting>
        </sect2>
     </sect1>
</chapter>