The IlvGraphModel Class

Options > Graph Layout > Using Advanced Features > Using the Graph Model > The IlvGraphModel Class

The IlvGraphModel class is an abstract class. Because it does not provide a concrete implementation of a graph data structure, a complete implementation must be provided by “adapter” classes. The adapters extend the IlvGraphModel class and must use an underlying graph data structure. A special adapter class called IlvGrapherAdapter is provided so that an IlvGrapher can be used as the underlying graph data structure.

Note: If an application uses the IlvGrapher class, the grapher can be attached directly to the layout instance without explicitly using a graph model. (See the IlvGraphLayout::attach(IlvGrapher) method.) In this case, the appropriate adapter (IlvGrapherAdapter) will be created internally. This adapter can be retrieved using the IlvGraphLayout::getGraphModel() method, which will return an instance of IlvGrapherAdapter.

The methods defined in the IlvGraphModel class can be divided into several categories that provide information on the structure of the graph, the geometry of the graph, modification of the graph geometry, and notification of changes in the graph.

Information on the Structure of the Graph

The following methods of the IlvGraphModel class allow the layout algorithms to retrieve information on the structure of the graph:

IlList getNodesAndLinks()

IlList getNodes()

IlUInt IlvGraphModel::getNodesCount()

IlList getLinks()

IlUInt IlvGraphModel::getLinksCount()

IlBoolean isNode(IlAny obj)

IlBoolean isLink(IlAny obj)

IlList getLinks(IlAny node)

IlUInt IlvGraphModel::getLinksCount(IlAny node)

IlList getLinksFrom(IlAny node)

IlUInt getLinksFromCount(IlAny node)

IlList getLinksTo(IlAny node)

IlUInt IlvGraphModel::getLinksToCount(IlAny node)

IlList getNeighbors(IlAny node)

IlUInt IlvGraphModel::getNodeDegree(IlAny node)

IlAny getFrom(IlAny link)

IlAny getTo(IlAny link)

IlAny getOpposite(IlAny link, IlAny node)

IlBoolean isLinkBetween(IlAny node1, IlAny node2)

Most of these methods have a name and definition very similar to the corresponding methods of the IlvGrapher class. The main difference is that the arguments of the IlvGraphModel methods are IlAny instead of IlvGraphic or IlvLinkImage.

Information on the Geometry of the Graph

The following methods of the IlvGraphModel class allow the layout algorithms to retrieve information on the geometry of the graph:

boundingBox(IlAny nodeOrLink, IlvRect& rect)

IlvPoint* getLinkPoints(IlAny link, IlUInt& count)

IlvPoint getLinkPointAt(IlAny link, IlUInt index)

IlInt getLinkPointsCount(IlAny link)

IlUInt getLinkWidth(IlAny link)

The boundingBox method is called by a layout algorithm whenever it needs to get the position and the dimension of a node or a link. The other methods are used mainly by link layout algorithms.

Modification of the Geometry of the Graph

The following methods of the IlvGraphModel class allow a layout algorithm to modify the geometry of the graph:

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

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

Layout algorithms that compute new coordinates for the nodes use the IlvGraphModel::moveNode method. Link layout algorithms that compute new shapes for the links call one of the IlvGraphModel::reshapeLink methods.

Notification of Changes

The following methods of the IlvGraphModel class allow a layout algorithm to be notified of changes in the graph:

void IlvGraphModel::addGraphModelListener(IlvGraphModelListener* listener)

void IlvGraphModel::removeGraphModelListener(IlvGraphModelListener* listener)

void IlvGraphModel::fireGraphModelEvent(IlvGraphModelEvent& event)

A “change” in the graph can be a structure change (that is, a node or a link was added or removed) or a geometry change (that is, a node or a link was moved or reshaped). The graph model event listener mechanism provides a means to keep the layout algorithms informed of these changes. When the layout algorithm is restarted on the same graph, it is able to detect whether the graph has changed since the last time the layout was successfully performed. If necessary, the layout can be performed again. If there is no change in the graph, the layout algorithm can avoid unnecessary work by not performing the layout.

The graph model event listener is a subclass of the IlvGraphModelListener class. To receive the graph model events (that is, instances of the IlvGraphModelEvent class), a subclass of the IlvGraphModelListener class must register itself using the IlvGraphModel::addGraphModelListener method of the IlvGraphModel class.

Note: The creation of the graph model event listener is handled transparently by the IlvGraphLayout class. Therefore, there is usually no need to manipulate this listener directly.

Storing and Retrieving Data Objects (“Properties”)

The following methods of the IlvGraphModel class allow a layout algorithm to store data objects for each node:

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

IlAny getProperty(IlAny nodeOrLink, const char* key)

The layout algorithm may need to associate a set of properties with the nodes and links of the graph. Properties are a set of key-value pairs, where the key is a const char* object and the value can be any kind of information value.

Note: Creating a property and associating it with a node and link is handled transparently by the layout algorithm whenever it is necessary. Therefore, there is usually no need to manipulate the properties directly. However, if needed, you can do this in your own subclass of IlvGraphLayout. In this case, you must define cleanObjectProperties in your subclass.

Published date: 05/24/2022

Last modified date: 02/24/2022