rwlogo
Rogue Wave Views 5.6

Rogue Wave Views
Graph Layout Package API Reference Guide

Product Documentation:

Rogue Wave Views
Documentation Home

List of all members | Public Member Functions
IlvGraphModel Class Referenceabstract

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:
IlvGrapherAdapter

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 IlvPointgetLinkPoints (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 IlListgetLinks ()=0
 Returns an enumeration of the links. More...
 
virtual IlListgetLinks (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 IlListgetLinksFrom (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 IlListgetLinksTo (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 IlListgetNeighbors (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 IlListgetNodes ()=0
 Returns an enumeration of the nodes. More...
 
virtual IlListgetNodesAndLinks ()
 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
 Returns IlTrue if the object is a valid link and IlFalse otherwise. More...
 
virtual IlBoolean isLinkBetween (IlAny node1, IlAny node2)
 Tests whether a link exists between two nodes. More...
 
virtual IlBoolean isNode (IlAny node)=0
 Returns IlTrue if an object is a valid node and IlFalse otherwise. 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:

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

Warning
[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:

Warning
[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
layoutThe layout instance origin of the notification.
reportThe layout report.
redrawIf IlTrue, the layout algorithm asks the graph model to redraw the graph.
See Also
beforeLayout
Warning
[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
layoutThe layout instance origin of the notification.
redrawIf 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
layoutThe 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
layoutThe 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
linkThe link.
Warning
[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
linkThe link.
indexThe 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
nodeThe node.
See Also
getLinksCountOf(IlAny)
getLinksFrom(IlAny)
getLinksTo(IlAny)
Warning
[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
nodeThe node.
Warning
[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.

See Also
getLinksTo
getLinks(IlAny)
Parameters
nodeThe origin node.

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
nodeThe node.
See Also
getLinksFrom
Warning
[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.

See Also
getLinksFrom
getLinks(IlAny)
Parameters
nodeThe destination node.

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
nodeThe node.
See Also
getLinksTo(IlAny)
Warning
[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
keyThe 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
nodeThe node.
Warning
[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
nodeThe node.
Warning
[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
nodeThe node.
linkThe link used to find the opposite of node.
Warning
[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
nodeOrLinkThe node or link for which the property is to be set.
keyThe 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
linkThe link.
Warning
[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
nodeOrLinkThe node or link for which the property is to be set.
keyThe 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

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

Parameters
linkThe object to test.

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

Returns IlTrue if an object is a valid node and IlFalse otherwise.

Parameters
nodeThe object to test.

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
nodeThe node.
xThe new x-position.
yThe new y-position.
redrawIf 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
linkThe link to be reshaped.
fromPointThe connection point of the link on the origin node.
pointsThe array of points.
startIndexThe start position in the array of points.
lengthThe number of intermediate points.
toPointThe connection point of the link on the destination node.
redrawIf IlTrue, the link is redrawn.
Warning
[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
nodeOrLinkThe node or link for which the property is to be set.
keyThe key string for the property.
valueThe 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

© Copyright 2012, Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave is a registered trademark of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.