Qtilities::Core::ObserverDotWriter Class Reference

The ObserverDotWriter class generate dot scripts to create dot graphs for an observer tree. More...

#include <ObserverDotWriter.h>

List of all members.

Public Member Functions
bool	addEdgeAttribute (Observer *parent, QObject *child, const QString &attribute, const QString &value)
	Adds an edge attribute between two nodes in the graph.
bool	addGraphAttribute (const QString &attribute, const QString &value)
	Adds a node attribute to a node in the graph.
bool	addNodeAttribute (QObject *node, const QString &attribute, const QString &value)
	Adds a node attribute to a node in the graph.
QHash< QByteArray, QString >	edgeAttributes (Observer *parent, QObject *child) const
	Returns a list of all attributes on a node in the graph.
QString	generateDotScript () const
	Function which will generate the dot script for the specified observer context.
QHash< QString, QString >	graphAttributes () const
	Returns a list of all attributes on a node in the graph.
QHash< QByteArray, QString >	nodeAttributes (QObject *node) const
	Returns a list of all attributes on a node in the graph.
Observer *	observerContext () const
	Gets a pointer to the observer context.
	ObserverDotWriter (Observer *observer=0)
	Default constructor.
	ObserverDotWriter (const ObserverDotWriter &other)
	Copy constructor.
ObserverDotWriter &	operator= (const ObserverDotWriter &other)
	Overloaded = operator.
bool	removeEdgeAttribute (Observer *parent, QObject *child, const QString &attribute)
	Removes a node attribute from a node in the graph.
bool	removeGraphAttribute (const QString &attribute)
	Removes a node attribute from a node in the graph.
bool	removeNodeAttribute (QObject *node, const QString &attribute)
	Removes a node attribute from a node in the graph.
virtual bool	saveToFile (const QString &fileName) const
	Saves the dot script to a file.
bool	setObserverContext (Observer *observer)
	Sets the observer context.
virtual	~ObserverDotWriter ()
	Destructor.

---

Detailed Description

The ObserverDotWriter class generate dot scripts to create dot graphs for an observer tree.

The ObserverDotWriter class is used to generate scripts in the dot language which can be parsed by a number of program to create dot graphs. For an overview of the dot language, a good place to start is The Dot Guide. To find software which can generate graphs from dot scripts, a good place to start is Graphviz.

Creating A Graph

To create a dot script for an observer tree is easy. For example:

// Create tree structure:
TreeNode* node = new TreeNode("Root Node");
node->addItem("Item 1");
node->addItem("Item 2");
node->addItem("Item 3");

// Create a dot script for this tree:
ObserverDotWriter dotGraph(node);
dotGraph.generateDotScript();
dotGraph.saveToFile("output_file.gv");

The resulting dot script looks like this:

digraph "Root Node" {
    0 [label="Root Node"];
    0 -> 1;
    0 -> 2;
    0 -> 3;
    1 [label="Item 1"];
    2 [label="Item 2"];
    3 [label="Item 3"];
}

Next we can run the script using the Gvedit application found in the GraphViz distribution to create graph. Different layout engines are available for the scripts created by ObserverDotWriter and here we will only show a couple of them. First the output of the dot layout engine is shown:

Example Graph (Dot Layout Engine)

Next the output of the circo layout engine is shown:

Example Graph (Circo Layout Engine)

Since tree items can be attached to multiple nodes, it is possible to create more complex graphs easily as well. Lets look at an example:

// Create tree structure:
TreeNode* node = new TreeNode("Root Node");
TreeNode* nodeA = node->addNode("Node A");
TreeNode* nodeB = node->addNode("Node B");
nodeA->addItem("Item 1");
nodeA->addItem("Item 2");
TreeItem* sharedItem = nodeA->addItem("Shared Item");
nodeB->attachSubject(sharedItem);
nodeB->addItem("Item 3");
nodeB->addItem("Item 4");

// Create a dot script for this tree:
ObserverDotWriter dotGraph(node);
dotGraph.generateDotScript();
dotGraph.saveToFile(QtilitiesApplication::applicationSessionPath() + "/output_file.gv");

The resulting dot script looks like this:

digraph "Root Node" {
    0 [label="Root Node"];
    0 -> 1;
    0 -> 5;
    1 [label="Node A"];
    1 -> 2;
    1 -> 3;
    1 -> 4;
    2 [label="Item 1"];
    3 [label="Item 2"];
    4 [label="Shared Item"];
    5 [label="Node B"];
    5 -> 4;
    5 -> 6;
    5 -> 7;
    6 [label="Item 3"];
    7 [label="Item 4"];
}

The graph produced by the dot layout engine is shown below:

Example Graph (Dot Layout Engine)

The same graph produced by the twopi layout engine is shown below:

Example Graph (Twopi Layout Engine)

Customizing A Graph

The ObserverDotWriter class allows complete customization of the graph it creates. Before looking at the different ways to customize a graph, a short overview of the parts of the graph to which properties can be applied must be given.

• The graph itself
• Nodes in the graph
• Connections between nodes (edge attributes)

The properties that can be applied to each of these are detailed in the The Dot Guide and will not be repeated here. For all properties the defaults of the dot language is used since ObserverDotWriter does not add them to the script if they are not specified.

Graph Attributes

It is possible to add any graph attribute specified in the dot language to a your graph. For example:

// Create tree structure:
TreeNode* node = new TreeNode("Root Node");
node->addItem("Item 1");
node->addItem("Item 2");
node->addItem("Item 3");

// Create a dot script for this tree:
ObserverDotWriter dotGraph(node);
dotGraph.addGraphAttribute("label","Graph Title");
dotGraph.generateDotScript();
dotGraph.saveToFile("output_file.gv");

The resulting dot script looks like this:

digraph "Root Node" {
    label = "Graph Title";
    0 [label="Root Node"];
    0 -> 1;
    0 -> 2;
    0 -> 3;
    1 [label="Item 1"];
    2 [label="Item 2"];
    3 [label="Item 3"];
}

Node Attributes

It is possible to add any node attribute specified in the dot language to a node in your graph. For example:

// Create tree structure:
TreeNode* node = new TreeNode("Root Node");
node->addItem("Item 1");
node->addItem("Item 2");
node->addItem("Item 3");

// Create a dot script for this tree:
ObserverDotWriter dotGraph(node);
dotGraph.addNodeAttribute(node,"color","red");
dotGraph.generateDotScript();
dotGraph.saveToFile("output_file.gv");

The resulting dot script looks like this:

digraph "Root Node" {
    0 [label="Root Node" color="red"];
    0 -> 1;
    0 -> 2;
    0 -> 3;
    1 [label="Item 1"];
    2 [label="Item 2"];
    3 [label="Item 3"];
}

Edge Attributes

It is possible to add any edge attribute specified in the dot language between two nodes in your graph. For example:

// Create tree structure:
TreeNode* node = new TreeNode("Root Node");
TreeItem* item1 = node->addItem("Item 1");
TreeItem* item2 = node->addItem("Item 2");
node->addItem("Item 3");

// Create a dot script for this tree:
ObserverDotWriter dotGraph(node);
dotGraph.addEdgeAttribute(node,item1,"label","\"My label\"");
dotGraph.addEdgeAttribute(node,item1,"style","bold");
dotGraph.addEdgeAttribute(node,item12,"color","red");
dotGraph.generateDotScript();
dotGraph.saveToFile("output_file.gv");

The resulting dot script looks like this:

digraph "Root Node" {
    label = "Graph Title";
    0 [label="Root Node" color="red"];
    0 -> 1 [label="My label",style=bold];
    0 -> 2 [color=red];
    0 -> 3;
    1 [label="Item 1"];
    2 [label="Item 2"];
    3 [label="Item 3"];
}

Note the needed extra " characters for the label attribute.

Combining all of the different attributes that we've set above, we get a graph like this:

Example Graph With Attributes (Dot Layout Engine)

This class was added in Qtilities v1.0.

---

Constructor & Destructor Documentation

Qtilities::Core::ObserverDotWriter::ObserverDotWriter

(

Observer *

observer = 0

)

Default constructor.

Parameters:

observer

The observer for which the script must be generated. The observer will also become the parent of this class.

---

Member Function Documentation

bool Qtilities::Core::ObserverDotWriter::addEdgeAttribute	(	Observer *	parent,
		QObject *	child,
		const QString &	attribute,
		const QString &	value
	)

Adds an edge attribute between two nodes in the graph.

See The Dot Guide for a list of possible edge attributes. Overwrites existing attribute with the same name if it exists. If either of the nodes you specify are not part of the top level observer tree (see observerContext()) then this function will fail and return false.

Parameters:

parent	A pointer to the parent observer.
child	The child underneath the parent observer.
attribute	The name of the attribute to be added.
value	The value of the attribute.

Returns:

True if successfull, false otherwise.

bool Qtilities::Core::ObserverDotWriter::addGraphAttribute	(	const QString &	attribute,
		const QString &	value
	)

Adds a node attribute to a node in the graph.

See The Dot Guide for a list of possible graph attributes. Overwrites existing attribute with the same name if it exists.

Parameters:

attribute	The name of the attribute to be added.
value	The value of the attribute.

Returns:

True if successfull, false otherwise.

bool Qtilities::Core::ObserverDotWriter::addNodeAttribute	(	QObject *	node,
		const QString &	attribute,
		const QString &	value
	)

Adds a node attribute to a node in the graph.

See The Dot Guide for a list of possible node attributes. Overwrites existing attribute with the same name if it exists. If the node you specify is not part of the observer tree (see observerContext()) then this function will fail and return false.

Parameters:

node	A pointer to the node.
attribute	The name of the attribute to be added.
value	The value of the attribute.

Returns:

True if successfull, false otherwise.

QHash< QByteArray, QString > Qtilities::Core::ObserverDotWriter::edgeAttributes	(	Observer *	parent,
		QObject *	child
	)		const

Returns a list of all attributes on a node in the graph.

Returns:

A QHash with attribute names a keys and their corresponding values as values.

QString Qtilities::Core::ObserverDotWriter::generateDotScript

(

)

const

Function which will generate the dot script for the specified observer context.

Note:

If no observer context have been specified, this function will return QString().

QHash< QString, QString > Qtilities::Core::ObserverDotWriter::graphAttributes

(

)

const

Returns a list of all attributes on a node in the graph.

Returns:

A QHash with attribute names a keys and their corresponding values as values.

QHash< QByteArray, QString > Qtilities::Core::ObserverDotWriter::nodeAttributes

(

QObject *

node

)

const

Returns a list of all attributes on a node in the graph.

Returns:

A QHash with attribute names a keys and their corresponding values as values.

bool Qtilities::Core::ObserverDotWriter::removeEdgeAttribute	(	Observer *	parent,
		QObject *	child,
		const QString &	attribute
	)

Removes a node attribute from a node in the graph.

Parameters:

node	A pointer to the node.
attribute	The name of the attribute to be removed.

Returns:

True if successfull, false otherwise (also when the property did not exist).

bool Qtilities::Core::ObserverDotWriter::removeGraphAttribute

(

const QString &

attribute

)

Removes a node attribute from a node in the graph.

Parameters:

attribute

The name of the attribute to be removed.

Returns:

True if successfull, false otherwise.

bool Qtilities::Core::ObserverDotWriter::removeNodeAttribute	(	QObject *	node,
		const QString &	attribute
	)

Removes a node attribute from a node in the graph.

Parameters:

node	A pointer to the node.
attribute	The name of the attribute to be removed.

Returns:

True if successfull, false otherwise (also when the property did not exist).

bool Qtilities::Core::ObserverDotWriter::saveToFile ( const QString &  fileName ) const

virtual

Saves the dot script to a file.

Function which will write the dot script generated using the generateDotScript() function to the specified file.

Note:

If no observer context have been specified, this function will return false.