IlvGraphModel defines a suitable generic API for graphs that have to be laid out with Rogue Wave Views graph layout algorithms. More...

#include <ilviews/layout/graphmod.h>

Inheritance diagram for IlvGraphModel:

Public Member Functions
	IlvGraphModel ()
	Creates a new `IlvGraphModel`.

virtual void	afterAnimationStep ()
	Notifies the graph model that a layout animation step has finished. More...

virtual void	afterLayout (IlvGraphLayout layout, IlvGraphLayoutReport report, IlBoolean redraw)
	Notifies the graph model that a layout session has finished. More...

virtual void	beforeAnimationStep ()
	Notifies the graph model that a layout animation step has been started. More...

virtual void	beforeLayout (IlvGraphLayout *layout, IlBoolean redraw)
	Notifies the graph model that a layout session has been started. More...

virtual void	boundingBox (IlAny nodeOrLink, IlvRect &rect)=0
	Calculates the bounding box of a node or a link. More...

virtual void	ensureReshapeableLinks (IlvGraphLayout *layout)
	Ensures that all the links in the grapher can be reshaped. More...

virtual void	ensureStraightLineLinks (IlvGraphLayout *layout)
	Ensures that all the links in the grapher are straight-line links. More...

void	geometryChanged (IlBoolean)
	Notifies the graph model that the geometry of the graph has changed (nodes or links were moved or reshaped). More...

virtual IlAny	getFrom (IlAny link)=0
	Returns the origin node of a link. More...

virtual IlvPoint	getLinkPointAt (IlAny link, IlUInt index)
	Returns the point of a link at a specified index. More...

virtual IlvPoint *	getLinkPoints (IlAny link, IlUInt &count)=0
	Returns the points that define a link. More...

virtual IlInt	getLinkPointsCount (IlAny link)=0
	Returns the number of points that define a link. More...

virtual IlList *	getLinks ()=0
	Returns an enumeration of the links. More...

virtual IlList *	getLinks (IlAny node)
	Returns an enumeration of all the links that have node as their origin or destination. More...

virtual IlUInt	getLinksCount ()
	Returns the number of links. More...

virtual IlUInt	getLinksCountOf (IlAny node)
	Returns the number of links adjacent to a node. More...

virtual IlList *	getLinksFrom (IlAny node)=0
	Returns an enumeration of all the links that have node as their origin. More...

virtual IlUInt	getLinksFromCount (IlAny node)
	Returns the number of links that have node as their origin. More...

virtual IlList *	getLinksTo (IlAny node)=0
	Returns an enumeration of all the links that have node as their destination. More...

virtual IlUInt	getLinksToCount (IlAny node)
	Returns the number of links that have node as their destination. More...

virtual IlUInt	getLinkWidth (IlAny)
	Returns the width of a link. More...

virtual const char *	getMessage (const char *key) const =0
	Returns the message string associated with the message identifier key. More...

virtual IlList *	getNeighbors (IlAny node)
	Returns an enumeration of all the nodes that are the "neighbors" of node; that is, the nodes that have a common link with node. More...

virtual IlUInt	getNodeDegree (IlAny node)
	Returns the degree of a node, that is, the number of neighbors that the node has. More...

virtual IlList *	getNodes ()=0
	Returns an enumeration of the nodes. More...

virtual IlList *	getNodesAndLinks ()
	Returns an enumeration of the nodes and links. More...

virtual IlUInt	getNodesCount ()
	Returns the number of nodes. More...

virtual IlAny	getOpposite (IlAny link, IlAny node)
	Returns the opposite node of a link. More...

virtual IlAny	getProperty (IlAny nodeOrLink, const char *key)
	Returns the value of a property. More...

virtual IlAny	getTo (IlAny link)=0
	Returns the destination node of a link. More...

const char *	getUniqueName (const char *=0)
	Method to be used everywhere in the package to choose names for properties that must be unique for a given graph model instance.

virtual IlBoolean	hasProperty (IlAny nodeOrLink, const char *key)
	Returns `IlTrue` if the property exists and `IlFalse` otherwise. More...

virtual IlBoolean	isLink (IlAny link)=0
	Indicates if an object is a link. More...

virtual IlBoolean	isLinkBetween (IlAny node1, IlAny node2)
	Tests whether a link exists between two nodes. More...

virtual IlBoolean	isNode (IlAny node)=0
	Indicates if an object is a node. More...

virtual void	moveNode (IlAny node, IlInt x, IlInt y, IlBoolean redraw)=0
	Changes the position of the specified node. More...

virtual void	reshapeLink (IlAny link, IlvPoint fromPoint, IlvPoint *points, IlUInt startIndex, IlUInt length, IlvPoint toPoint, IlBoolean redraw)=0
	Reshapes all the points of a link. More...

virtual void	setProperty (IlAny nodeOrLink, const char *key, IlAny value)
	Sets the value of a property for a node or a link. More...

void	structureChanged (IlBoolean)
	Notifies the graph-model-event listeners that the topology of the graph has changed (nodes or links were added or removed). More...

Detailed Description

IlvGraphModel defines a suitable generic API for graphs that have to be laid out with Rogue Wave Views graph layout algorithms.

Library: ilvlayout

Instead of asking programmers to extend their data objects from a predefined base class, it allows the use of any application object as a graph, a node, or a link. This makes it much easier to add graph layout features to existing applications.

All the layout algorithms provided in Rogue Wave Views are designed to lay out a graph model. This allows any application to use them even when not based on the Rogue Wave Views grapher (IlvGrapher). However, to make things simple for the common case of applications that use an IlvGrapher it is not mandatory to work directly with the graph model, except when using some of the advanced features such as filtering (see the methods IlvGrapherAdapter::setFilter() and IlvGrapherAdapter::addLayer()).

This class is abstract. Since its purpose is not to provide a concrete implementation of a graph data structure, a complete implementation must be provided by "adapter" classes.
To create a concrete Graph Model you need to provide an implementation for the abstract methods in an "adapter" class. The adapters extend the graph model and must use an underlying graph data structure. A special adapter class, IlvGrapherAdapter is provided in order to use an IlvGrapher as the underlying graph data structure.

Note that if an application uses the class IlvGrapher, the grapher can be attached directly to the layout instance, without explicitly using a graph model (see the method IlvGraphLayout::attach(IlvGrapher*)). In this case, the appropriate adapter (IlvGrapherAdapter) will be created internally. If necessary, it can be retrieved using the method IlvGraphLayout::getGraphModel(), which in this case returns an instance of IlvGrapherAdapter.

The methods defined in this class can be divided into the following categories:

Methods that provide information about the topology (structure) of the graph. For instance: getNodes(), getLinks(), getNeighbors(), and so on.
Methods that provide information about the geometry of the graph. For instance: boundingBox(), getLinkPoints().
Methods that allow the layout algorithm to modify the geometry of the graph. For instance: moveNode() and reshapeLink().
Methods that provide useful services such as the notification of changes of the graph, the capability to store "property objects" for nodes and links, and so on.

Some of these methods are abstract and must be implemented by the adapter class. (Note that the IlvGrapherAdapter provides implementation for all the methods.)

Note: The efficiency of the layout algorithms directly depends on the efficiency of the implementation of the adapter class, as well as on the efficiency of the implementation of the underlying graph data structure.

To improve performance, you can replace in the adapter class the default implementation of the nonabstract methods with an overridden version that is optimized for your particular graph data structure. The IlvGrapherAdapter provides the optimized methods for the Rogue Wave Views grapher (IlvGrapher).

The default implementations of the following methods, although functional, are particularly inefficient. Any time the underlying graph allows a more efficient implementation, these methods should be overridden:

Note: Any adapter (subclass of IlvGraphModel) that uses an IlvGrapher as an underlying graph must be implemented as a subclass of IlvGrapherAdapter.

See also: IlvGraphLayout::attach(), IlvGrapherAdapter.

Member Function Documentation

virtual void IlvGraphModel::afterAnimationStep ( )

virtual

Notifies the graph model that a layout animation step has finished.

If appropriate, this method is called by the layout algorithms after each animation step, even if an exception is thrown during the layout process.

The default implementation does nothing. To support the animation mechanism, this method can be overridden by an adapter in order to redraw the graph after each step of the layout.

See also: beforeAnimationStep().

Reimplemented in IlvGrapherAdapter.

virtual void IlvGraphModel::afterLayout	(	IlvGraphLayout *	layout,
		IlvGraphLayoutReport *	report,
		IlBoolean	redraw
	)

virtual

Notifies the graph model that a layout session has finished.

This method is always called by IlvGraphLayout::performLayout() after the method IlvGraphLayout::layout() has finished, even if an exception is thrown during the layout process.

The default implementation does nothing. Any implementation of this method must redraw the graph if the method isRedrawEnabled() returns IlTrue.

Parameters

layout	The layout instance origin of the notification.
report	The layout report.
redraw	If `IlTrue`, the layout algorithm asks the graph model to redraw the graph.

See also: beforeLayout().

Note: You can detect if the layout was performed successfully using the test report->getCode() == IlvGraphLayoutReport::LayoutDone.

Reimplemented in IlvGrapherAdapter.

virtual void IlvGraphModel::beforeAnimationStep ( )

virtual

Notifies the graph model that a layout animation step has been started.

If appropriate, this method is called by the layout algorithms before each animation step.

The default implementation does nothing. If necessary, you can override this method in order to perform preliminary operations before the animation step.

See also: afterAnimationStep().

Reimplemented in IlvGrapherAdapter.

virtual void IlvGraphModel::beforeLayout	(	IlvGraphLayout *	layout,
		IlBoolean	redraw
	)

virtual

Notifies the graph model that a layout session has been started.

This method is always called by IlvGraphLayout::performLayout() before the call to the method IlvGraphLayout::layout().

The default implementation does nothing. If necessary, you can override this method in order to perform preliminary operations before the layout.

Parameters

layout	The layout instance origin of the notification.
redraw	If `IlTrue`, the layout algorithm will ask the graph model to redraw the graph when the method `afterLayout()` is called.

See also: afterLayout().

Reimplemented in IlvGrapherAdapter.

virtual void IlvGraphModel::boundingBox	(	IlAny	nodeOrLink,
		IlvRect &	rect
	)

pure virtual

Calculates the bounding box of a node or a link.

Updates the argument rect with the bounding rectangle of a node or a link.

Implemented in IlvGrapherAdapter.

virtual void IlvGraphModel::ensureReshapeableLinks ( IlvGraphLayout * layout )

virtual

Ensures that all the links in the grapher can be reshaped.

This method is called by layout algorithms that need to reshape the links.

The default implementation does nothing. This method is overridden in the IlvGrapherAdapter class.

Parameters

layout The layout instance that needs reshapeable links.

See also: ensureStraightLineLinks().

Reimplemented in IlvGrapherAdapter.

virtual void IlvGraphModel::ensureStraightLineLinks ( IlvGraphLayout * layout )

virtual

Ensures that all the links in the grapher are straight-line links.

This method is called by layout algorithms that need straight-line links.

The default implementation does nothing. This method is overridden in the IlvGrapherAdapter class.

Parameters

layout The layout instance that needs straight-line links.

See also: ensureReshapeableLinks().

Reimplemented in IlvGrapherAdapter.

void IlvGraphModel::geometryChanged ( IlBoolean )

Notifies the graph model that the geometry of the graph has changed (nodes or links were moved or reshaped).

It is the responsibility of the adapter classes to call this method any time the geometry of the graph is changed (for example, when changes are due to user interaction). However, this method must not be called when the geometry of the graph changes because of calls to the methods provided by the graph model (for example, moveNode() and reshapeLink()).

This notification is needed to allow the graph layout algorithms to detect changes in the graph and to avoid reperforming the layout when it is not needed.

See also: addGraphModelListener().

virtual IlAny IlvGraphModel::getFrom ( IlAny link )

pure virtual

Returns the origin node of a link.

Parameters

link The link.

Note: Any implementation of this method must throw an IlvLayoutException if link is not a link of the graph.

Implemented in IlvGrapherAdapter.

virtual IlvPoint IlvGraphModel::getLinkPointAt	(	IlAny	link,
		IlUInt	index
	)

virtual

Returns the point of a link at a specified index.

The values of indexes start from zero, which must correspond to the connection point of the link on its origin node. The last point on the link must correspond to the connection point of the link on its destination node.

The default implementation returns the point at the specified index in the array returned by the method getLinkPoints().

Parameters

link	The link.
index	The index of the point on the polyline link.

Reimplemented in IlvGrapherAdapter.

virtual IlvPoint* IlvGraphModel::getLinkPoints	(	IlAny	link,
		IlUInt &	count
	)

pure virtual

Returns the points that define a link.

The point at index 0 must correspond to the connection point of the link on the origin node. The point at index getLinkPointsCount(link) - 1 must correspond to the connection point of the link on the destination node.

Implemented in IlvGrapherAdapter.

virtual IlInt IlvGraphModel::getLinkPointsCount ( IlAny link )

pure virtual

Returns the number of points that define a link.

Returns the number of points that define a link, including the connection points of the link on the origin and destination nodes.

Implemented in IlvGrapherAdapter.

virtual IlList* IlvGraphModel::getLinks ( )

pure virtual

Returns an enumeration of the links.

See also: getLinksCount(); getNodes(); getNodesAndLinks()

Implemented in IlvGrapherAdapter.

virtual IlList* IlvGraphModel::getLinks ( IlAny node )

virtual

Returns an enumeration of all the links that have node as their origin or destination.

The default implementation uses the enumerations returned by the methods getLinksFrom(IlAny) and getLinksTo(IlAny) to build the enumeration of all the links.

Parameters

node The node.

See also: getLinksCountOf(IlAny); getLinksFrom(IlAny); getLinksTo(IlAny).

Note: Any implementation of this method must throw an IlvLayoutException if node is not a node of the graph.

Reimplemented in IlvGrapherAdapter.

virtual IlUInt IlvGraphModel::getLinksCount ( )

virtual

Returns the number of links.

The default implementation simply counts the number of links as returned by the method getLinks().

See also: getLinks(); getLinksFromCount(); getLinksToCount()

virtual IlUInt IlvGraphModel::getLinksCountOf ( IlAny node )

virtual

Returns the number of links adjacent to a node.

The default implementation simply counts the number of links returned by the method getLinks(IlAny).

Parameters

node The node.

Note: If you override this method, you must throw an IlvLayoutException if node is not a node of the graph.

Reimplemented in IlvGrapherAdapter.

virtual IlList* IlvGraphModel::getLinksFrom ( IlAny node )

pure virtual

Returns an enumeration of all the links that have node as their origin.

Parameters

node	The origin node.

See also: getLinksTo(); getLinks(IlAny).

Implemented in IlvGrapherAdapter.

virtual IlUInt IlvGraphModel::getLinksFromCount ( IlAny node )

virtual

Returns the number of links that have node as their origin.

The default implementation simply counts the number of links returned by the method getLinksFrom().

Parameters

node The node.

See also: getLinksFrom().

Note: If you override this method, you must throw an IlvLayoutException if node is not a node of the graph.

Reimplemented in IlvGrapherAdapter.

virtual IlList* IlvGraphModel::getLinksTo ( IlAny node )

pure virtual

Returns an enumeration of all the links that have node as their destination.

Parameters

node	The destination node.

See also: getLinksFrom(); getLinks(IlAny).

Implemented in IlvGrapherAdapter.

virtual IlUInt IlvGraphModel::getLinksToCount ( IlAny node )

virtual

Returns the number of links that have node as their destination.

The default implementation simply counts the number of links returned by the method getLinksTo(IlAny).

Parameters

node The node.

See also: getLinksTo(IlAny).

Note: If you override this method, you must throw an IlvLayoutException if node is not a node of the graph.

Reimplemented in IlvGrapherAdapter.

virtual IlUInt IlvGraphModel::getLinkWidth ( IlAny )

virtual

Returns the width of a link.

The default implementation returns 1.

Reimplemented in IlvGrapherAdapter.

virtual const char* IlvGraphModel::getMessage ( const char * key ) const

pure virtual

Returns the message string associated with the message identifier key.

All messages are available in the file ilviews/layout/views.dbm. You can parse this file in order to build your message database. The format of this file is "key" "message_value".

Parameters

key	The message identifier searched for.

Implemented in IlvGrapherAdapter.

virtual IlList* IlvGraphModel::getNeighbors ( IlAny node )

virtual

Returns an enumeration of all the nodes that are the "neighbors" of node; that is, the nodes that have a common link with node.

The default implementation browses the links connected to node (the method getLinks(IlAny) is called) and returns an enumeration that gives you access to each of their opposite nodes (the method getOpposite(IlAny, IlAny) is called). An IlvLayoutException is thrown if the argument is not a node of the graph.

In the case of multiple links between node and one of its neighbors, the neighbor will be contained in the enumeration the number of times equal to the number of links.

Parameters

node The node.

Note: Any implementation of this method must throw an IllegalArgumentException if node is not a node of the graph.

Reimplemented in IlvGrapherAdapter.

virtual IlUInt IlvGraphModel::getNodeDegree ( IlAny node )

virtual

Returns the degree of a node, that is, the number of neighbors that the node has.

The default implementation counts the number of elements in the enumeration returned by the method getNeighbors(IlAny). However, if a node is contained in the enumeration returned by the method getNeighbors(IlAny) several times (for example, because node has more than one common link with a neighbor), this neighbor is counted just once.

Parameters

node The node.

Note: Any overridden implementation must be careful not to count the same neighbor several times.

virtual IlList* IlvGraphModel::getNodes ( )

pure virtual

Returns an enumeration of the nodes.

See also: getNodesCount(); getLinks(); getNodesAndLinks()

Implemented in IlvGrapherAdapter.

virtual IlList* IlvGraphModel::getNodesAndLinks ( )

virtual

Returns an enumeration of the nodes and links.

The default implementation builds an enumeration of the nodes and links that uses the enumerations returned by the methods getNodes() and getLinks().

See also: getNodes(); getLinks(); getNodesCount(); getLinksCount().

Reimplemented in IlvGrapherAdapter.

virtual IlUInt IlvGraphModel::getNodesCount ( )

virtual

Returns the number of nodes.

The default implementation simply counts the number of nodes as returned by the method getNodes().

See also: getNodes()

virtual IlAny IlvGraphModel::getOpposite	(	IlAny	link,
		IlAny	node
	)

virtual

Returns the opposite node of a link.

The default implementation determines the opposite node using calls of methods() getFrom and getTo().

Parameters

node	The node.
link	The link used to find the opposite of node.

Note: Any implementation of this method must throw an IlvLayoutException if link is not a link of the graph.

Reimplemented in IlvGrapherAdapter.

virtual IlAny IlvGraphModel::getProperty	(	IlAny	nodeOrLink,
		const char *	key
	)

virtual

Returns the value of a property.

The method returns 0 if the property does not exist.

Parameters

nodeOrLink	The node or link for which the property is to be set.
key	The key string for the property.

See also: setProperty(IlAny, const char*, IlAny).

Reimplemented in IlvGrapherAdapter.

virtual IlAny IlvGraphModel::getTo ( IlAny link )

pure virtual

Returns the destination node of a link.

Parameters

link The link.

Note: Any implementation of this method must throw an IlvLayoutException if link is not a link of the graph.

Implemented in IlvGrapherAdapter.

virtual IlBoolean IlvGraphModel::hasProperty	(	IlAny	nodeOrLink,
		const char *	key
	)

virtual

Returns IlTrue if the property exists and IlFalse otherwise.

Parameters

nodeOrLink	The node or link for which the property is to be set.
key	The key string for the property.

See also: setProperty(IlAny, const char*, IlAny); getProperty(IlAny, const char*).

Reimplemented in IlvGrapherAdapter.

virtual IlBoolean IlvGraphModel::isLink ( IlAny link )

pure virtual

Indicates if an object is a link.

Parameters

link	The object to test.

Returns: IlTrue if the object is a valid link and IlFalse otherwise.

Implemented in IlvGrapherAdapter.

virtual IlBoolean IlvGraphModel::isLinkBetween	(	IlAny	node1,
		IlAny	node2
	)

virtual

Tests whether a link exists between two nodes.

The default implementation browses the links that have node1 and node2 as their origin (the method getLinksFrom(IlAny) is called) and checks the other extremity for each link (the method getTo(IlAny) is called).

Reimplemented in IlvGrapherAdapter.

virtual IlBoolean IlvGraphModel::isNode ( IlAny node )

pure virtual

Indicates if an object is a node.

Parameters

node	The object to test.

Returns: IlTrue if node is a valid node and IlFalse otherwise.

Implemented in IlvGrapherAdapter.

virtual void IlvGraphModel::moveNode	(	IlAny	node,
		IlInt	x,
		IlInt	y,
		IlBoolean	redraw
	)

pure virtual

Changes the position of the specified node.

The x and y coordinates correspond to the top-left corner of the rectangle that defines the node (see also the method boundingBox()).

Parameters

node	The node.
x	The new x-position.
y	The new y-position.
redraw	If `IlTrue`, the node is redrawn.

Implemented in IlvGrapherAdapter.

virtual void IlvGraphModel::reshapeLink	(	IlAny	link,
		IlvPoint	fromPoint,
		IlvPoint *	points,
		IlUInt	startIndex,
		IlUInt	length,
		IlvPoint	toPoint,
		IlBoolean	redraw
	)

pure virtual

Reshapes all the points of a link.

Reshapes all the points of a link given an array of IlvPoint, the start position in the array of points, the number of intermediate points, and the connection points.

The default implementation does nothing. It simply returns IlFalse.

If the new shape of the link must be a direct link, without any intermediate points, call the method with 0 for the points argument. The values of the arguments startIndex and length are ignored.

Parameters

link	The link to be reshaped.
fromPoint	The connection point of the link on the origin node.
points	The array of points.
startIndex	The start position in the array of points.
length	The number of intermediate points.
toPoint	The connection point of the link on the destination node.
redraw	If `IlTrue`, the link is redrawn.

Note: This method must be overridden by any adapter class that supports link layout.

Implemented in IlvGrapherAdapter.

virtual void IlvGraphModel::setProperty	(	IlAny	nodeOrLink,
		const char *	key,
		IlAny	value
	)

virtual

Sets the value of a property for a node or a link.

If value is 0, the property is removed. Otherwise, the property value is set to value.

The default implementation uses an internal hash table to store the binding between the node or link, the value of the property, and its key.

Parameters

nodeOrLink	The node or link for which the property is to be set.
key	The key string for the property.
value	The new value of the property.

See also: getProperty(IlAny, const char*).

Reimplemented in IlvGrapherAdapter.

void IlvGraphModel::structureChanged ( IlBoolean )

Notifies the graph-model-event listeners that the topology of the graph has changed (nodes or links were added or removed).

It is the responsibility of the adapter classes to call this method any time the structure of the graph is changed (for example, when changes are due to user interaction). However, this method must not be called when the geometry of the graph changes due to calls to the methods provided by the graph model (moveNode(), reshapeLink()).

This notification is needed in order to allow the graph layout algorithms to detect changes in the graph and to avoid reperforming the layout when it is not needed.

See also: addGraphModelListener().

Public Member Functions

Detailed Description

Member Function Documentation