Rogue Wave Views Graph Layout Package API Reference Guide |
Rogue Wave Views Documentation Home |
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>
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... | |
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:
getNodes()
, getLinks()
, getNeighbors()
, and so on. boundingBox()
, getLinkPoints()
. moveNode()
and reshapeLink()
. Some of these methods are abstract and must be implemented by the adapter class. (Note that the IlvGrapherAdapter
provides implementation for all the methods.)
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:
getNodesCount()
getLinksCount()
getLinksCountOf(IlAny)
getLinksFromCount(IlAny)
getLinksToCount(IlAny)
IlvGraphModel
) that uses an IlvGrapher
as an underlying graph must be implemented as a subclass of IlvGrapherAdapter
.IlvGraphLayout::attach()
, IlvGrapherAdapter
.
|
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.
beforeAnimationStep()
. Reimplemented in IlvGrapherAdapter.
|
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
.
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. |
beforeLayout()
.report->getCode() == IlvGraphLayoutReport::LayoutDone
. Reimplemented in IlvGrapherAdapter.
|
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.
afterAnimationStep()
. Reimplemented in IlvGrapherAdapter.
|
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.
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. |
afterLayout()
. Reimplemented in IlvGrapherAdapter.
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 |
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.
layout | The layout instance that needs reshapeable links. |
ensureStraightLineLinks()
. Reimplemented in IlvGrapherAdapter.
|
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.
layout | The layout instance that needs straight-line links. |
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.
addGraphModelListener()
. Returns the origin node of a link.
link | The link. |
IlvLayoutException
if link is not a link of the graph. Implemented in IlvGrapherAdapter.
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()
.
link | The link. |
index | The index of the point on the polyline link. |
Reimplemented in IlvGrapherAdapter.
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.
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.
|
pure virtual |
Returns an enumeration of the links.
Implemented in IlvGrapherAdapter.
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.
node | The node. |
IlvLayoutException
if node is not a node of the graph. Reimplemented in IlvGrapherAdapter.
|
virtual |
Returns the number of links.
The default implementation simply counts the number of links as returned by the method getLinks()
.
Returns the number of links adjacent to a node.
The default implementation simply counts the number of links returned by the method getLinks(IlAny)
.
node | The node. |
IlvLayoutException
if node is not a node of the graph. Reimplemented in IlvGrapherAdapter.
Returns an enumeration of all the links that have node as their origin.
node | The origin node. |
getLinksTo()
getLinks(IlAny)
. Implemented in IlvGrapherAdapter.
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()
.
node | The node. |
getLinksFrom()
.IlvLayoutException
if node is not a node of the graph. Reimplemented in IlvGrapherAdapter.
Returns an enumeration of all the links that have node as their destination.
node | The destination node. |
getLinksFrom()
getLinks(IlAny)
. Implemented in IlvGrapherAdapter.
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)
.
node | The node. |
getLinksTo(IlAny)
.IlvLayoutException
if node is not a node of the graph. Reimplemented in IlvGrapherAdapter.
Returns the width of a link.
The default implementation returns 1.
Reimplemented in IlvGrapherAdapter.
|
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"
.
key | The message identifier searched for. |
Implemented in IlvGrapherAdapter.
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.
node | The node. |
IllegalArgumentException
if node is not a node of the graph. Reimplemented in IlvGrapherAdapter.
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.
node | The node. |
|
pure virtual |
Returns an enumeration of the nodes.
Implemented in IlvGrapherAdapter.
|
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()
.
Reimplemented in IlvGrapherAdapter.
|
virtual |
Returns the number of nodes.
The default implementation simply counts the number of nodes as returned by the method getNodes()
.
getNodes()
Returns the opposite node of a link.
The default implementation determines the opposite node using calls of methods()
getFrom and getTo()
.
node | The node. |
link | The link used to find the opposite of node. |
IlvLayoutException
if link is not a link of the graph. Reimplemented in IlvGrapherAdapter.
Returns the value of a property.
The method returns 0
if the property does not exist.
nodeOrLink | The node or link for which the property is to be set. |
key | The key string for the property. |
Reimplemented in IlvGrapherAdapter.
Returns the destination node of a link.
link | The link. |
IlvLayoutException
if link is not a link of the graph. Implemented in IlvGrapherAdapter.
Returns IlTrue
if the property exists and IlFalse
otherwise.
nodeOrLink | The node or link for which the property is to be set. |
key | The key string for the property. |
Reimplemented in IlvGrapherAdapter.
Indicates if an object is a link.
link | The object to test. |
IlTrue
if the object is a valid link and IlFalse
otherwise. Implemented in IlvGrapherAdapter.
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.
Indicates if an object is a node.
node | The object to test. |
IlTrue
if node is a valid node and IlFalse
otherwise. Implemented in IlvGrapherAdapter.
|
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()
).
node | The node. |
x | The new x-position. |
y | The new y-position. |
redraw | If IlTrue , the node is redrawn. |
Implemented in IlvGrapherAdapter.
|
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.
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. |
Implemented in IlvGrapherAdapter.
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.
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. |
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.
addGraphModelListener()
. © Copyright 2018, 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.