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 | Protected Member Functions
IlvGraphLayout Class Referenceabstract

The base class for Graph Layout algorithms. More...

#include <ilviews/layout/gphlayout.h>

Inheritance diagram for IlvGraphLayout:
IlvBusLayout IlvHierarchicalLayout IlvOrthogonalLinkLayout IlvRandomLayout IlvTreeLayout

Public Member Functions

 IlvGraphLayout ()
 Constructor.
 
virtual void attach (IlvGrapher *grapher)
 Allows you to specify the grapher you want to lay out. More...
 
virtual void attach (IlvGraphModel *graphModel)
 Allows you to specify the graph model you want to lay out. More...
 
virtual void cleanObjectProperties (IlAny nodeOrLink)
 Deletes properties attached to the node or link. More...
 
virtual void detach ()
 Detaches the graph model from the layout instance. More...
 
virtual IlvRunTimeType getAllowedTime () const
 Returns the currently allowed time for the layout algorithm in milliseconds. More...
 
IlvMgrViewgetFirstManagerView () const
 Returns the first manager view attached to the graph model if any, and 0 otherwise.
 
IlvGraphergetGrapher () const
 Returns the grapher to lay out. More...
 
IlvGraphModelgetGraphModel () const
 Returns the graph model to lay out if a graph model is attached. More...
 
IlUInt getInstanceId () const
 A utility method that returns a unique integer value for each layout instance inside the same program.
 
void getLayoutRegion (IlvRect &rect) const
 Updates the rectangle rect passed as argument with the region that the drawing of the graph model must fit (exactly or approximately). More...
 
IlvGraphLayoutReportgetLayoutReport () const
 Returns the layout report, that is, an object containing information about the behavior of the layout algorithm for the previous run of layout. More...
 
virtual IlUShort getSeedValueForRandomGenerator ()
 Returns the user-defined seed value for the random generator. More...
 
IlBoolean isAnimate () const
 Returns IlTrue if the layout can perform a redraw of the graph model after each iteration or step of the layout algorithm. More...
 
IlBoolean isFitToView () const
 Returns IlTrue if the size of the graph drawing must fit (exactly or approximately) the size of a given manager view. More...
 
IlBoolean isFixed (IlAny nodeOrLink) const
 Returns IlTrue if the node or link nodeOrLink is specified as fixed. More...
 
IlBoolean isGeometryUpToDate () const
 Returns IlFalse if at least one node or link was moved or reshaped since the last time the layout was successfully performed on the same graph model or if the layout has never been performed successfully on the same graph model. More...
 
IlBoolean isIlvGrapherAttached () const
 Convenience method. More...
 
IlBoolean isLayoutRunning () const
 Specifies whether the layout algorithm is running. More...
 
virtual IlBoolean isLayoutTimeElapsed () const
 Returns IlTrue if, at the moment the method is called, the allowed layout time is exceeded; returns IlFalse otherwise. More...
 
IlBoolean isLinkConnectorReplacementAllowed () const
 Returns IlTrue if the replacement of the link connectors is allowed. More...
 
virtual IlBoolean isLinkReplacementAllowed () const
 Returns IlTrue if the replacement of the links is allowed. More...
 
virtual IlBoolean isMemorySavings () const
 Returns the current setting specifying whether priority is given to speed or memory usage.
 
virtual IlBoolean isParametersUpToDate () const
 Returns IlFalse if at least one parameter was modified since the last time the layout was successfully performed on the same graph or if the layout has never been performed successfully on the same graph. More...
 
virtual IlBoolean isPreserveFixedLinks () const
 Returns IlTrue if the layout is not allowed to reshape the links indicated as fixed by the user. More...
 
virtual IlBoolean isPreserveFixedNodes () const
 Returns IlTrue if the layout is not allowed to move the nodes indicated as fixed by the user. More...
 
IlBoolean isStructureUpToDate () const
 Indicates whether the graph model structure has been modified since the last layout was performed. More...
 
virtual IlBoolean isUseDefaultParameters () const
 Returns the current options for the parameters. More...
 
virtual IlBoolean isUseSeedValueForRandomGenerator ()
 Returns IlTrue if the user-defined seed value is used for the random generator and IlFalse otherwise. More...
 
void layoutRunning (IlBoolean)
 Updates the field _isLayoutRunning.
 
virtual void layoutStepPerformed ()
 This method can be called by the layout classes when a step (or iteration) of the layout algorithm has been performed. More...
 
IlvGraphLayoutReportperformLayout ()
 Starts the layout algorithm using the currently attached graph model and the current settings for the layout parameters. More...
 
void setAllowedTime (IlvRunTimeType time)
 Allows you to specify an upper bound for the duration of the layout algorithm. More...
 
void setAnimate (IlBoolean arg)
 If arg is IlTrue, all manager views attached to the graph model are redrawn after each iteration or step of the layout algorithm. More...
 
virtual void setFixed (IlAny nodeOrLink, IlBoolean val)
 Allows you to specify whether a node or a link is fixed. More...
 
void setGeometryUpToDate (IlBoolean)
 If the argument is IlFalse, notifies the layout instance that the geometry of the graph was changed since the last time the layout was successfully performed. More...
 
void setGrapher (IlvGrapher *grapher)
 Allows you to specify the grapher you want to lay out. More...
 
void setLayoutRegion (IlvMgrView *view)
 Allows you to specify that the size of the graph drawing must fit (exactly or approximately) the size of a given manager view. More...
 
void setLayoutRegion (IlvMgrView *view, const IlvRect &rect)
 Allows you to specify a region (the rectangle rect) that the layout must fit (exactly or approximately) with the dimensions of the rectangle rect being given in the manager view coordinates. More...
 
void setLayoutRegion (const IlvRect &rect)
 Allows you to specify a rectangle that the layout must fit (exactly or approximately). More...
 
void setLinkConnectorReplacementAllowed (IlBoolean allow)
 Enables or disables the link connector replacement. More...
 
virtual void setLinkReplacementAllowed (IlBoolean)
 Enables or disables the link replacement. More...
 
virtual void setMemorySavings (IlBoolean arg)
 If arg is IlTrue, the layout algorithm uses the implementation that consumes less memory. More...
 
void setParametersUpToDate (IlBoolean)
 If the argument is IlFalse, notifies the layout instance that a parameter value was changed. More...
 
virtual void setPreserveFixedLinks (IlBoolean arg)
 If arg is IlTrue, the layout is not allowed to reshape the links indicated as fixed by the user. More...
 
virtual void setPreserveFixedNodes (IlBoolean arg)
 If the argument is IlTrue, the layout is not allowed to move the nodes indicated as fixed by the user. More...
 
virtual void setSeedValueForRandomGenerator (IlUShort seedValue)
 Allows you to specify a seed value for the random generator. More...
 
void setStructureUpToDate (IlBoolean)
 If the argument is IlFalse, notifies the layout instance that the structure of the graph was changed since the last time the layout was successfully performed. More...
 
virtual void setUseDefaultParameters (IlBoolean arg)
 If the argument is IlTrue, the layout uses the default values of all the parameters, that is, the "get..." and "is..." methods return the default values. More...
 
virtual void setUseSeedValueForRandomGenerator (IlBoolean)
 Allows you to specify whether the user-defined seed value should be used for the random generator. More...
 
virtual IlBoolean supportsAllowedTime () const
 Indicates whether the layout class can stop the layout computation when a user-defined allowed time is exceeded. More...
 
virtual IlBoolean supportsAnimation () const
 Indicates whether the layout class performs a redraw of the graph model after each step or iteration. More...
 
virtual IlBoolean supportsLayoutRegion () const
 Indicates whether the layout class can control the size of the graph drawing to fit (exactly or approximately) a user-defined region (a rectangle) or a user-defined manager view. More...
 
virtual IlBoolean supportsMemorySavings () const
 Indicates whether the layout class can perform the layout using two partially different implementations. More...
 
virtual IlBoolean supportsPreserveFixedLinks () const
 Indicates whether the layout class allows the user to specify fixed links. More...
 
virtual IlBoolean supportsPreserveFixedNodes () const
 Indicates whether the layout class allows the user to specify fixed nodes. More...
 
virtual IlBoolean supportsRandomGenerator () const
 Indicates whether the layout class uses randomly-generated numbers (or randomly-chosen parameters) for which it can accept a user-defined seed value. More...
 
void unfixAllLinks ()
 Removes the fixed attributes from all links in the graph model. More...
 
void unfixAllNodes ()
 Removes the fixed attribute from all nodes in the graph model. More...
 

Protected Member Functions

virtual IlvGraphLayoutReportcreateLayoutReport ()
 Returns a new instance of the layout report. More...
 
virtual IlBoolean isLayoutNeeded () const
 Verifies that it is necessary to perform the layout. More...
 
virtual void layout ()=0
 Executes the layout. More...
 

Detailed Description

The base class for Graph Layout algorithms.

Library: ilvlayout

Rogue Wave Views provides special support for applications that need to display graphs (also called networks) of nodes and links. Using the IlvGrapher class, any graphic object can be defined to behave like a node and can be connected to other nodes via links, which themselves can have many different forms. Used in conjunction with layout algorithms (those provided in this package or those written by the user by subclassing this class), this feature is often used to create network topologies for telecommunications networks and systems management applications.

The use of the Graph Layout package is no longer restricted to applications using an IlvGrapher to store and display the graph. You can now use external graph data source structures. This is achieved through the class IlvGraphModel. This abstract class defines the API that is necessary to allow the graph layout algorithms to work. To use an external graph, all you need to do is implement an adapter that connects the graph with the generic graph model. For details, see the class IlvGraphModel.

The class IlvGraphLayout is abstract and cannot be used directly. You must use one of its subclasses provided in this package.

You can also create your own subclasses to implement other layout algorithms. Note that, in order to be applied on any graph, the layout algorithms must be written using the API of the graph model instead of the API of IlvGrapher.

The class contains layout parameters or options that can be useful for different layout algorithms. Note that the implementation of the layout() method is solely responsible for whether or not the current settings of the parameters are taken into account.

If you want to perform the layout on a subgraph of an IlvGrapher (that is, on a subset of the nodes and links of the original graph), you can use a filter (see the class IlvLayoutGraphicFilter and the method IlvGrapherAdapter::setFilter(IlvLayoutGraphicFilter*)). The filter allows the layout algorithm to know, for each node and link of a graph, if it must be taken into account or completely ignored.

To learn more about the layout algorithms and the corresponding IlvGraphLayout subclasses, read the sections of the Reference Manual describing those classes and the Graph Layout chapter of the User's Manual.

See Also
IlvRandomLayout
IlvTreeLayout
IlvBusLayout
IlvOrthogonalLinkLayout
IlvGraphModel
IlvGrapherAdapter
IlvGrapher.

Member Function Documentation

virtual void IlvGraphLayout::attach ( IlvGrapher grapher)
virtual

Allows you to specify the grapher you want to lay out.

This method automatically creates an IlvGrapherAdapter to encapsulate the grapher. This IlvGrapherAdapter is owned by the layout and will be deleted by the detach method. Then, the adapter is attached to the layout instance by calling the method attach(IlvGraphModel*).

You must attach the grapher before performing the layout, that is, before calling the method performLayout.

Parameters
grapherThe grapher to be laid out.
See Also
attach(IlvGraphModel*)
detach
getGraphModel
getGrapher.
Warning
[note] This call reinitializes to their default values the parameters related to the layout region (see setLayoutRegion(const IlvRect&)).
virtual void IlvGraphLayout::attach ( IlvGraphModel graphModel)
virtual

Allows you to specify the graph model you want to lay out.

You must attach the graph model before performing the layout, that is, before calling the method performLayout.

This method first calls detach if another graph model is already attached. Note that this call reinitializes to their default values the parameters related to the layout region (see setLayoutRegion(const IlvRect&)) and the layers to be taken into account during the layout (see IlvGrapherAdapter::addLayer(IlvManagerLayer*)). Note also that the IlvGraphModel passed as argument is not owned by the layout and will not be deleted in the detach method.

Parameters
graphModelThe graph model you want to lay out.
See Also
attach(IlvGrapher*)
detach
getGraphModel.
virtual void IlvGraphLayout::cleanObjectProperties ( IlAny  nodeOrLink)
virtual

Deletes properties attached to the node or link.

When you perform the layout, some properties are attached to objects and this method is responsible for removing them from the object and deleting them.

See Also
IlvGraphLayout::cleanObjectProperties(IlAny).

Reimplemented in IlvHierarchicalLayout, IlvTreeLayout, IlvBusLayout, and IlvOrthogonalLinkLayout.

virtual IlvGraphLayoutReport* IlvGraphLayout::createLayoutReport ( )
protectedvirtual

Returns a new instance of the layout report.

This method can be overriden in order to create subclasses of IlvGraphLayoutReport. The default implementation returns a new instance of IlvGraphLayoutReport.

createLayoutReport is called by performLayout. The returned object is stored internally in the layout instance and will be returned by the method performLayout.

This method can be used to obtain information about the behavior of the layout algorithm if the information is added in the layout report inside the implementation of the layout method, where it can be obtained using getLayoutReport.

While the layout method is running, you can also obtain the layout report outside this method using the layout-event listener mechanism (see #addGraphLayoutEventListener).

Returns
A new instance of the layout report.
See Also
getLayoutReport
IlvGraphLayoutReport
performLayout
#addGraphLayoutEventListener.
virtual void IlvGraphLayout::detach ( )
virtual

Detaches the graph model from the layout instance.

When a new graph model is attached to the layout instance, it is not necessary to detach the previously attached graph model because this is done automatically when the methods attach(IlvGrapher*) or attach(IlvGraphModel*) are called.

This method performs cleaning operations on the graph model (for example, properties added to the graph model objects are removed) and reinitializes the parameters related to animation and the layout region.

Subclasses can override this method to remove additional information stored in the graph model.

See Also
setAnimate(IlBoolean))
setLayoutRegion(const IlvRect&)
attach(IlvGrapher*)
attach(IlvGraphModel*).
Warning
[note] You must call this method when you no longer need the layout instance; otherwise some objects may not be deleted.

Reimplemented in IlvHierarchicalLayout, IlvTreeLayout, IlvBusLayout, and IlvOrthogonalLinkLayout.

virtual IlvRunTimeType IlvGraphLayout::getAllowedTime ( ) const
virtual

Returns the currently allowed time for the layout algorithm in milliseconds.

Warning
[note] The method performLayout does NOT automatically stop the layout when the allowed time is exceeded. It is the responsibility of the implementation of the layout() method to do this.
Returns
The currently allowed time for the layout algorithm in milliseconds.
See Also
supportsAllowedTime
setAllowedTime(IlvRunTimeType)
isLayoutTimeElapsed.
IlvGrapher* IlvGraphLayout::getGrapher ( ) const

Returns the grapher to lay out.

Returns
The grapher to lay out if a grapher is attached directly (using the method attach(IlvGrapher*)) or via an IlvGrapherAdapter (using the method attach(IlvGraphModel*)). Otherwise, the method returns 0.
See Also
setGrapher(IlvGrapher*)
attach(IlvGrapher*).
IlvGraphModel* IlvGraphLayout::getGraphModel ( ) const

Returns the graph model to lay out if a graph model is attached.

Otherwise, the method returns 0.

See Also
attach(IlvGraphModel*)
attach(IlvGrapher*).
Warning
[note] If an IlvGrapher is attached directly using attach(IlvGrapher*), the method returns the instance of IlvGrapherAdapter that has been created internally.
void IlvGraphLayout::getLayoutRegion ( IlvRect rect) const

Updates the rectangle rect passed as argument with the region that the drawing of the graph model must fit (exactly or approximately).

Note that, if the attached graph is an IlvGrapher or an IlvGrapherAdapter, the dimensions of the rectangle are in the manager coordinates, and not in the manager view coordinates.

Several cases can occur depending on whether the last method called is setLayoutRegion(IlvMgrView*, const IlvRect&), setLayoutRegion(IlvMgrView*), or setLayoutRegion(const IlvRect&):

  1. If the last method is setLayoutRegion(const IlvRect&), it updates the rectangle without transformation performed.
  2. If the last method is setLayoutRegion(IlvMgrView*, const IlvRect&), it updates the rectangle transformed to the manager coordinates using the transformer of the view.
  3. If the last method is setLayoutRegion(IlvMgrView*), it updates the rectangle with the dimensions x=0, y=0 and the width/height equal to the current width/height of the view. These dimensions are transformed to the manager coordinates using the transformer of the view.
  4. The default behavior corresponds to the case where none of these methods is called. If at least one manager view is attached to the graph model, it returns a rectangle with the dimensions x=0, y=0 and the width/height equal to the current width/height of the first attached view, transformed to the manager coordinates using the transformer of the view. If no view is attached, the isEmpty method returns IlTrue if it is called on rect.

The implementation of the method layout() in subclasses of IlvGraphLayout is solely responsible for whether the rectangle returned by this method is taken into account when calculating the layout.

Warning
[note] The current value of the parameter updated by the setUseDefaultParameters(IlBoolean) method does not affect the result of this method.
Parameters
rectThe rectangle to be updated with the layout region.
See Also
supportsLayoutRegion
setLayoutRegion(IlvMgrView*, const IlvRect&)
setLayoutRegion(IlvMgrView*)
setLayoutRegion(const IlvRect&).
IlvGraphLayoutReport* IlvGraphLayout::getLayoutReport ( ) const

Returns the layout report, that is, an object containing information about the behavior of the layout algorithm for the previous run of layout.

If this method is called before the first call of performLayout, it returns 0. After calling performLayout, it returns the layout report filled with information on the previous run. The layout report is created by createLayoutReport() during the first run of layout. It is stored internally in the layout instance and reused in further runs of layout. It is destroyed when the layout instance is destroyed.

See Also
createLayoutReport.
virtual IlUShort IlvGraphLayout::getSeedValueForRandomGenerator ( )
virtual

Returns the user-defined seed value for the random generator.

For example, you can use this parameter in the implementation of the layout method in the following way:

Returns
The seed value specified by the setSeedValueForRandomGenerator(IlUShort) method.
See Also
supportsRandomGenerator
setSeedValueForRandomGenerator(IlUShort)
setUseSeedValueForRandomGenerator(IlBoolean)
isUseSeedValueForRandomGenerator.
IlBoolean IlvGraphLayout::isAnimate ( ) const

Returns IlTrue if the layout can perform a redraw of the graph model after each iteration or step of the layout algorithm.

The subclasses of IlvGraphLayout supporting this mechanism must override supportsAnimation() and make it return IlTrue.

See Also
setAnimate(IlBoolean)
supportsAnimation.
IlBoolean IlvGraphLayout::isFitToView ( ) const

Returns IlTrue if the size of the graph drawing must fit (exactly or approximately) the size of a given manager view.

This is the case if the layout region was set by a view passed to the method setLayoutRegion. It returns IlFalse if the layout region was set by a rectangle passed to the method setLayoutRegion(IlvMgrView*) or setLayoutRegion(IlvMgrView*, const IlvRect&).

See Also
supportsLayoutRegion
setLayoutRegion(IlvMgrView*, const IlvRect&)
setLayoutRegion(IlvMgrView*)
setLayoutRegion(const IlvRect&).
IlBoolean IlvGraphLayout::isFixed ( IlAny  nodeOrLink) const

Returns IlTrue if the node or link nodeOrLink is specified as fixed.

Otherwise, the method returns IlFalse.

Parameters
nodeOrLinkThe object to test if it is fixed or not.
See Also
setFixed(IlAny, IlBoolean)
setPreserveFixedNodes(IlBoolean)
isPreserveFixedNodes
unfixAllNodes
supportsPreserveFixedNodes
setPreserveFixedLinks(IlBoolean)
isPreserveFixedLinks
unfixAllLinks
supportsPreserveFixedLinks.
IlBoolean IlvGraphLayout::isGeometryUpToDate ( ) const

Returns IlFalse if at least one node or link was moved or reshaped since the last time the layout was successfully performed on the same graph model or if the layout has never been performed successfully on the same graph model.

This method is automatically called by isLayoutNeeded().

Returns
IlTrue if no changes occurred, and IlFalse otherwise.
See Also
performLayout
setGeometryUpToDate
isLayoutNeeded.
Warning
[note] When the layout is performed successfully (that is, getCode() called on the layout report returns IlvGraphLayoutReport::LayoutDone), the layout instance is automatically notified that the geometry of the graph is up-to-date. It is also automatically notified of the modifications of the geometry of the graph model using a manager-contents-changed listener.
IlBoolean IlvGraphLayout::isIlvGrapherAttached ( ) const

Convenience method.

This internal method must be called only if we are sure that there is an attached graph.

Returns
IlTrue if the attached graph model is an IlvGrapherAdapter, and IlFalse otherwise.
virtual IlBoolean IlvGraphLayout::isLayoutNeeded ( ) const
protectedvirtual

Verifies that it is necessary to perform the layout.

The default implementation returns IlFalse if no changes occurred on the graph model (no nodes or links were inserted, removed, reshaped, or moved) and no parameters changed since the last time the layout was successfully performed using this layout instance. Otherwise, the method returns IlTrue. (The methods isStructureUpToDate(), isGeometryUpToDate, and isParametersUpToDate() are called.)

Returns
IlTrue if it is necessary to perform the layout, and IlFalse otherwise.
See Also
isStructureUpToDate
isGeometryUpToDate
isParametersUpToDate.
IlBoolean IlvGraphLayout::isLayoutRunning ( ) const

Specifies whether the layout algorithm is running.

The layout is considered as started once the method performLayout is called. It is considered as completed after this method returns.

Returns
IlTrue if the layout has been started and is not yet completed. Returns IlFalse otherwise.
See Also
performLayout.
virtual IlBoolean IlvGraphLayout::isLayoutTimeElapsed ( ) const
virtual

Returns IlTrue if, at the moment the method is called, the allowed layout time is exceeded; returns IlFalse otherwise.

You can call this method inside the implementation of the method layout().

Returns
IlTrue or IlFalse depending on whether the allowed time is elapsed.
See Also
supportsAllowedTime
setAllowedTime(IlvRunTimeType)
getAllowedTime.
IlBoolean IlvGraphLayout::isLinkConnectorReplacementAllowed ( ) const

Returns IlTrue if the replacement of the link connectors is allowed.

Returns IlFalse otherwise.

See Also
setLinkConnectorReplacementAllowed.
virtual IlBoolean IlvGraphLayout::isLinkReplacementAllowed ( ) const
virtual

Returns IlTrue if the replacement of the links is allowed.

Returns IlFalse otherwise.

See Also
setLinkReplacementAllowed.
virtual IlBoolean IlvGraphLayout::isParametersUpToDate ( ) const
virtual

Returns IlFalse if at least one parameter was modified since the last time the layout was successfully performed on the same graph or if the layout has never been performed successfully on the same graph.

Returns IlTrue if no parameters changed since the last time the layout was successfully performed on the same graph model.

If a layout class supports the layout region mechanism (that is, supportsLayoutRegion() returns IlTrue) and if a manager view must be taken into account for the computation of the layout region in the manager coordinates (see getLayoutRegion()), an additional test is performed to verify that the size of the manager view changed. The method returns IlFalse if a change occurred. Note that any change of the manager view through calls to setLayoutRegion(IlvMgrView*, const IlvRect&) or setLayoutRegion(IlvMgrView*) is considered as a parameter change.

This method is automatically called by isLayoutNeeded().

Warning
[note] When the layout is performed successfully (that is, getCode() called on the layout report returns IlvGraphLayoutReport::LayoutDone), the layout instance is automatically notified that the parameters are now up-to-date.
See Also
performLayout
setParametersUpToDate
isLayoutNeeded.
virtual IlBoolean IlvGraphLayout::isPreserveFixedLinks ( ) const
virtual

Returns IlTrue if the layout is not allowed to reshape the links indicated as fixed by the user.

Returns IlFalse if the layout is free to reshape all the links.

See Also
setPreserveFixedLinks(IlBoolean)
setFixed(IlAny, IlBoolean)
#isFixed(IlAny)
supportsPreserveFixedLinks
unfixAllLinks.
virtual IlBoolean IlvGraphLayout::isPreserveFixedNodes ( ) const
virtual

Returns IlTrue if the layout is not allowed to move the nodes indicated as fixed by the user.

Returns IlFalse if the layout is free to move all the nodes.

See Also
setPreserveFixedNodes(IlBoolean)
setFixed(IlAny, IlBoolean)
#isFixed(IlAny)
supportsPreserveFixedNodes
unfixAllNodes.
IlBoolean IlvGraphLayout::isStructureUpToDate ( ) const

Indicates whether the graph model structure has been modified since the last layout was performed.

Returns IlFalse if at least one modification occurred in the graph model structure (a node or link was added or removed) since the last time the layout was successfully performed on the same graph model using this layout instance or if the layout has never been performed successfully on the same graph model.

The following are considered to be modifications of the structure: adding or removing a node or link, modifying the filter (see IlvGrapherAdapter::setFilter(IlvLayoutGraphicFilter*)), or modifying one of the layers to be taken into account during the layout (see IlvGrapherAdapter::addLayer(IlvManagerLayer*)).

This method is automatically called by isLayoutNeeded().

Returns
IlTrue if no changes occurred, and IlFalse otherwise.
See Also
performLayout
isLayoutNeeded
setStructureUpToDate.
Warning
[note] When the layout is performed successfully (that is, getCode() called on the layout report returns IlvGraphLayoutReport::LayoutDone), the layout instance is automatically notified that the structure is up-to-date. It is also automatically notified of the topological modifications of the graph model using a manager-contents-changed listener.
virtual IlBoolean IlvGraphLayout::isUseDefaultParameters ( ) const
virtual

Returns the current options for the parameters.

See Also
setUseDefaultParameters.
virtual IlBoolean IlvGraphLayout::isUseSeedValueForRandomGenerator ( )
virtual

Returns IlTrue if the user-defined seed value is used for the random generator and IlFalse otherwise.

For example, you can use this parameter in the implementation of the layout() method in the following way:

Returns
IlTrue or IlFalse depending on whether the user-defined seed value is used or not.
See Also
supportsRandomGenerator
setSeedValueForRandomGenerator(IlUShort)
getSeedValueForRandomGenerator
setUseSeedValueForRandomGenerator(IlBoolean).
virtual void IlvGraphLayout::layout ( )
protectedpure virtual

Executes the layout.

This method must be implemented by each layout algorithm (subclasses of IlvGraphLayout). This method computes the coordinates of the nodes in the graph model and moves the nodes to the new positions using the method IlvGraphModel::moveNode(IlAny, IlInt, IlInt, IlBoolean). The method can also perform reshape operations on the nodes or the links.

When writing the implementation of this method, you can obtain an instance of the layout report using getLayoutReport() and store particular information about the behavior of the layout algorithm in the layout report. You can also notify the layout-event listeners using the method layoutStepPerformed().

When the layout algorithm is finished and if the layout is performed successfully, you should call the method setCode with the argument IlvGraphLayoutReport::LayoutDone on the layout report instance.

Here is a sample implementation for a Random layout:

void layout()
{
// Obtain the graph model.
IlvGraphModel* graphModel = getGraphModel();
// Obtain the layout report.
IlBoolean atLeastOneNodeMoved = IlFalse;
// Obtain the layout region.
IlvRect rect
IlvPos xMin = rect.x();
IlvPos yMin = rect.y();
IlvPos xMax = rect.x() + rect.w();
IlvPos yMax = rect.y() + rect.h();
// Initialize the random generator.
: new Random();
// Get an enumeration of the nodes.
IlList* nodes = graphModel->getNodes();
IlList::Cell l = node->getFirst()
// Browse the nodes.
while (l) {
IlAny node = l->getValue();
// get the next l before the eventually continue command
l = l->getNext();
// Skip fixed nodes.
if (isPreserveFixedNodes() && isFixed(node))
continue;
// Compute coordinates.
IlvPos x = xMin + (xMax - xMin) * random->nextFloat();
IlvPos y = yMin + (yMax - yMin) * random->nextFloat();
// Move the node to the computed position.
graphModel.moveNode(node, x, y);
atLeastOneNodeMoved = true;
// Notify listeners on layout events.
}
if (atLeastOneNodeMoved)
layoutReport->setCode(IlvGraphLayoutReport::LayoutDone);
else
layoutReport->setCode(IlvGraphLayoutReport::NoMoveableNode);
// Delete the list returned by IlvGraphModel::getNodes()
delete nodes;
delete random;
}
See Also
getLayoutReport
IlvGraphLayoutReport
layoutStepPerformed.

Implemented in IlvTreeLayout, IlvOrthogonalLinkLayout, IlvBusLayout, IlvHierarchicalLayout, and IlvRandomLayout.

virtual void IlvGraphLayout::layoutStepPerformed ( )
virtual

This method can be called by the layout classes when a step (or iteration) of the layout algorithm has been performed.

The method notifies the listeners of the layout events (if any).

This method is intended to be called from the implementation of the method layout().

See Also
#addGraphLayoutEventListener
#removeGraphLayoutEventListener
GraphLayoutEvent
layout.
IlvGraphLayoutReport* IlvGraphLayout::performLayout ( )

Starts the layout algorithm using the currently attached graph model and the current settings for the layout parameters.

The implementation of this method calls during its first run the method createLayoutReport to obtain a new instance of the layout report. This instance is stored internally and can be used to obtain information about the behavior of the layout algorithm when the method returns. The layout report gets reused in further runs of layout. The implementation of the layout() method is solely responsible for adding this information in the layout report. Note that subclasses of IlvGraphLayout can override the method createLayoutReport and the layout report can be an instance of subclasses of IlvGraphLayoutReport.

If the graph is empty (that is, it contains no node) the appropriate code (IlvGraphLayoutReport::EmptyGrapher) is stored in the layout report and the method returns.

The method calls isLayoutNeeded() to determine whether it is necessary to perform the layout. If this method returns IlFalse, the appropriate code (IlvGraphLayoutReport::NotNeeded) is stored in the layout report and the method returns.

If the check is successfully performed, the method IlvGraphModel::beforeLayout(IlvGraphLayout*, IlBoolean) is called on the attached graph model with the redraw argument set to IlTrue. Then, the layout() method, which executes the layout algorithm, is called.

Warning
[note] While the layout() method is running, you can also obtain the layout report outside this method using the layout-event listener mechanism (see #addGraphLayoutEventListener).

If the layout is successfully performed (that is, if the method getCode() called on the layout report instance returns IlvGraphLayoutReport::LayoutDone), the layout instance is notified that the structure, the geometry, and the parameters are now up-to-date (see the methods isStructureUpToDate(), isGeometryUpToDate(), and isParametersUpToDate()).

In any case, the method IlvGraphModel::afterLayout(IlvGraphLayout*, IlvGraphLayoutReport*, IlBoolean) is finally called on the attached graph model with the redraw argument equal to IlTrue.

Returns
The instance of the layout report.
See Also
layout
isLayoutNeeded
isStructureUpToDate
isGeometryUpToDate
isParametersUpToDate.
void IlvGraphLayout::setAllowedTime ( IlvRunTimeType  time)

Allows you to specify an upper bound for the duration of the layout algorithm.

When an iterative layout algorithm is used, the iterations can be stopped when this time is exceeded. Noniterative algorithms can also use this parameter as an upper bound for the computation time. The default value is 32000 (32 seconds).

Warning
[note] The method performLayout does NOT automatically stop the layout when the allowed time is exceeded. It is the responsibility of the implementation of the layout() method to do this.
Parameters
timeThe allowed time in milliseconds.
See Also
supportsAllowedTime
getAllowedTime
isLayoutTimeElapsed.
void IlvGraphLayout::setAnimate ( IlBoolean  arg)

If arg is IlTrue, all manager views attached to the graph model are redrawn after each iteration or step of the layout algorithm.

Otherwise, no redraw operation is performed. You must perform the redraw yourself after the IlvGraphLayout::performLayout method returns. The default value is IlFalse.

See Also
isAnimate
supportsAnimation.
virtual void IlvGraphLayout::setFixed ( IlAny  nodeOrLink,
IlBoolean  val 
)
virtual

Allows you to specify whether a node or a link is fixed.

Fixed nodes are not moved during the layout only if the method isPreserveFixedNodes() returns IlTrue.
By default, no node is fixed.

Fixed links are not reshaped during the layout only if the method isPreserveFixedLinks() returns IlTrue.
By default, no link is fixed.

Parameters
nodeOrLinkThe object to be fixed or not.
valThe object is fixed depending on this value.
See Also
#isFixed(IlAny)
supportsPreserveFixedNodes
setPreserveFixedNodes(IlBoolean)
isPreserveFixedNodes
unfixAllNodes
supportsPreserveFixedLinks
setPreserveFixedLinks(IlBoolean)
isPreserveFixedLinks
unfixAllLinks.
void IlvGraphLayout::setGeometryUpToDate ( IlBoolean  )

If the argument is IlFalse, notifies the layout instance that the geometry of the graph was changed since the last time the layout was successfully performed.

Usually, you do not need to call this method. The method is automatically called with an IlTrue argument each time the layout is successfully performed.

See Also
isGeometryUpToDate
isLayoutNeeded.
void IlvGraphLayout::setGrapher ( IlvGrapher grapher)

Allows you to specify the grapher you want to lay out.

You must specify the grapher before performing the layout, that is, before calling the method performLayout.

This method simply calls attach(IlvGrapher*).

Parameters
grapherThe grapher you want to lay out.
See Also
attach(IlvGrapher*)
getGrapher.
void IlvGraphLayout::setLayoutRegion ( IlvMgrView view)

Allows you to specify that the size of the graph drawing must fit (exactly or approximately) the size of a given manager view.

Usually, the view argument is the manager view that is used for displaying the attached graph.

Parameters
viewThe view that the graph drawing must fit.
See Also
supportsLayoutRegion
#setLayoutRegion(IlvMgrView, const IlvRect&)
setLayoutRegion(const IlvRect&)
#getLayoutRegion(IlvRect&)
isFitToView().
void IlvGraphLayout::setLayoutRegion ( IlvMgrView view,
const IlvRect rect 
)

Allows you to specify a region (the rectangle rect) that the layout must fit (exactly or approximately) with the dimensions of the rectangle rect being given in the manager view coordinates.

Usually, the view argument is the manager view that is used for displaying the attached graph.

Parameters
viewThe manager view whose current transformer is to be used by #getLayoutRegion(IlvRect&) to translate the dimensions of the rect argument from manager view coordinates to manager coordinates.
rectThe region of the view that the layout must fit. Its dimensions must be given in the view coordinates.
See Also
supportsLayoutRegion
setLayoutRegion(IlvMgrView*)
setLayoutRegion(const IlvRect&)
#getLayoutRegion(IlvRect&)
isFitToView().
void IlvGraphLayout::setLayoutRegion ( const IlvRect rect)

Allows you to specify a rectangle that the layout must fit (exactly or approximately).

The dimensions of the rectangle must be specified in the manage (graph model) coordinates. You should use this method if you want to perform the layout with no manager view attached to the graph model or if you want to define the region to fit in the manager coordinates. If you want the layout to fit a region of a manager view, with its dimensions in manager view coordinates, use setLayoutRegion(IlvMgrView*, const IlvRect&).

See Also
supportsLayoutRegion
setLayoutRegion(IlvMgrView*)
setLayoutRegion(IlvMgrView*, const IlvRect&)
#getLayoutRegion(IlvRect&)
isFitToView().
void IlvGraphLayout::setLinkConnectorReplacementAllowed ( IlBoolean  allow)

Enables or disables the link connector replacement.

When Rogue Wave Views graphers are used, it is not possible to change the connection point of the links without using a link connector that supports this operation (see the class IlvGrapherPin). Therefore, a layout algorithm may need to add a pin to all the nodes.

Also, a layout algorithm that does not reshape the links may need to remove the pin from all the nodes.

This method is called by the methods IlvGrapherAdapter::ensureStraightLineLinks(IlBoolean) and IlvGrapherAdapter::ensureReshapeableLinks(IlBoolean) in order to know whether they are allowed to change the link connectors.

The default value is IlTrue.

See Also
isLinkConnectorReplacementAllowed
setLinkReplacementAllowed(IlBoolean)
IlvGrapherAdapter::ensureStraightLineLinks(IlBoolean)
IlvGrapherAdapter::ensureReshapeableLinks(IlBoolean).
virtual void IlvGraphLayout::setLinkReplacementAllowed ( IlBoolean  )
virtual

Enables or disables the link replacement.

When Rogue Wave Views graphers are used, not all links (of any class) can be reshaped. Therefore, if the link replacement is allowed, the layout algorithm may need to replace some links with new links of a different type.

For instance, a layout algorithm that needs to be able to insert, delete, and move the intermediate points of the links can replace links that are not reshapeable (for instance IlvLinkImage, IlvOneLinkImage, IlvDoubleLinkImage, IlvOneSplineLinkImage, and IlvDoubleSplineLinkImage with IlvPolylineLinkImage). To do this the layout algorithm calls the method IlvGraphModel::ensureReshapeableLinks.

Layout algorithms that need straight-line links can replace IlvOneLinkImage, IlvDoubleLinkImage, IlvOneSplineLinkImage, and IlvDoubleSplineLinkImage with IlvPolylineLinkImage (without intermediate points). To do this, the layout algorithm calls the method IlvGraphModel::ensureStraightLineLinks(IlBoolean).

When a link is replaced, the following attributes are copied from the old to the new link: origin and destination node, orientation, line width, maximum line width, foreground color, line join, end cap, and line style.

The default value is IlTrue.

See Also
isLinkReplacementAllowed
setLinkConnectorReplacementAllowed(IlBoolean)
IlvGraphModel::ensureStraightLineLinks(IlBoolean)
IlvGraphModel::ensureReshapeableLinks(IlBoolean).
virtual void IlvGraphLayout::setMemorySavings ( IlBoolean  arg)
virtual

If arg is IlTrue, the layout algorithm uses the implementation that consumes less memory.

The default value of the parameter is IlFalse.

This option should not have any effect on the resulting layout. However, the implementation of the layout() is solely responsible for the resulting layout.

void IlvGraphLayout::setParametersUpToDate ( IlBoolean  )

If the argument is IlFalse, notifies the layout instance that a parameter value was changed.

This method is automatically called with an IlFalse argument each time the value of a parameter is changed using the methods provided in this class or in its subclasses provided in Rogue Wave Views. If you add new parameters in your own subclass of IlvGraphLayout, you should call this method with an IlFalse argument each time they are modified.

The method is automatically called with an IlTrue argument each time the layout is successfully performed.

See Also
isParametersUpToDate
isLayoutNeeded.
virtual void IlvGraphLayout::setPreserveFixedLinks ( IlBoolean  arg)
virtual

If arg is IlTrue, the layout is not allowed to reshape the links indicated as fixed by the user.

If the argument is IlFalse, the layout is free to reshape all the links of the grapher. (This does not change the setting for the fixed links, which can still be used at any time in the future.)
The default value is IlFalse.

See Also
isPreserveFixedLinks
setFixed(IlAny, IlBoolean)
#isFixed(IlAny)
supportsPreserveFixedLinks
unfixAllLinks.
virtual void IlvGraphLayout::setPreserveFixedNodes ( IlBoolean  arg)
virtual

If the argument is IlTrue, the layout is not allowed to move the nodes indicated as fixed by the user.

If the argument is IlFalse, the layout is free to move all the nodes of the grapher. (This does not change the setting for the fixed nodes, which can still be used at any time in the future.)

The default value is IlFalse.

See Also
isPreserveFixedNodes
setFixed(IlAny, IlBoolean)
#isFixed(IlAny)
supportsPreserveFixedNodes
unfixAllNodes.
virtual void IlvGraphLayout::setSeedValueForRandomGenerator ( IlUShort  seedValue)
virtual

Allows you to specify a seed value for the random generator.

The default value is 0. The user-defined seed value is used only if you call setUseSeedValueForRandomGenerator(IlBoolean) with an IlTrue argument.

Parameters
seedValueThe new seed value for the random generator.
See Also
supportsRandomGenerator
getSeedValueForRandomGenerator
setUseSeedValueForRandomGenerator(IlBoolean)
isUseSeedValueForRandomGenerator.
void IlvGraphLayout::setStructureUpToDate ( IlBoolean  )

If the argument is IlFalse, notifies the layout instance that the structure of the graph was changed since the last time the layout was successfully performed.

Usually, you do not need to call this method. The method is automatically called with an IlTrue argument each time the layout is successfully performed.

See Also
isStructureUpToDate
isLayoutNeeded.
virtual void IlvGraphLayout::setUseDefaultParameters ( IlBoolean  arg)
virtual

If the argument is IlTrue, the layout uses the default values of all the parameters, that is, the "get..." and "is..." methods return the default values.

The default value of this parameter is IlFalse.

See Also
isUseDefaultParameters.
virtual void IlvGraphLayout::setUseSeedValueForRandomGenerator ( IlBoolean  )
virtual

Allows you to specify whether the user-defined seed value should be used for the random generator.

See Also
supportsRandomGenerator
setSeedValueForRandomGenerator(IlUShort)
getSeedValueForRandomGenerator
isUseSeedValueForRandomGenerator.
virtual IlBoolean IlvGraphLayout::supportsAllowedTime ( ) const
virtual

Indicates whether the layout class can stop the layout computation when a user-defined allowed time is exceeded.

The default implementation always returns IlFalse.

Subclasses can override this method in order to return IlTrue, that is, to indicate that this option is supported.

Returns
Always IlFalse.
See Also
setAllowedTime(IlvRunTimeType)
getAllowedTime
isLayoutTimeElapsed.

Reimplemented in IlvOrthogonalLinkLayout, IlvTreeLayout, and IlvHierarchicalLayout.

virtual IlBoolean IlvGraphLayout::supportsAnimation ( ) const
virtual

Indicates whether the layout class performs a redraw of the graph model after each step or iteration.

The default implementation always returns IlFalse.

Subclasses can override this method in order to return IlTrue, that is, to indicate that this option is supported.

See Also
setAnimate(IlBoolean)
isAnimate
Returns
Always IlFalse.

Reimplemented in IlvOrthogonalLinkLayout.

virtual IlBoolean IlvGraphLayout::supportsLayoutRegion ( ) const
virtual

Indicates whether the layout class can control the size of the graph drawing to fit (exactly or approximately) a user-defined region (a rectangle) or a user-defined manager view.

The default implementation always returns IlFalse.

Subclasses can override this method in order to return IlTrue, that is, to indicate that this option is supported.

See Also
setLayoutRegion(IlvMgrView*)
setLayoutRegion(IlvMgrView*, const IlvRect&)
setLayoutRegion(const IlvRect&)
#getLayoutRegion(IlvRect&).
Returns
Always IlFalse.

Reimplemented in IlvBusLayout, and IlvRandomLayout.

virtual IlBoolean IlvGraphLayout::supportsMemorySavings ( ) const
virtual

Indicates whether the layout class can perform the layout using two partially different implementations.

Indicates whether the layout class can perform the layout using two partially different implementations: one that gives priority to speed, the other that gives priority to memory usage. The choice of one or the other depends on the parameter specified using setMemorySavings(IlBoolean). The amount of memory savings depends on the implementation of the subclass of IlvGraphLayout. This setting does not affect the resulting layout.

The default implementation always returns IlFalse.

Subclasses can override this method in order to return IlTrue, that is, to indicate that this option is supported.

Returns
Always IlFalse.
See Also
setMemorySavings(IlBoolean)
isMemorySavings().
virtual IlBoolean IlvGraphLayout::supportsPreserveFixedLinks ( ) const
virtual

Indicates whether the layout class allows the user to specify fixed links.

Fixed links are not reshaped during the layout.
The default implementation always returns IlFalse. Subclasses can override this method in order to return IlTrue, that is, to indicate that this option is supported.

Returns
Always IlFalse.
See Also
setPreserveFixedLinks(IlBoolean)
isPreserveFixedLinks
setFixed(IlAny, IlBoolean)
#isFixed(IlAny)
unfixAllLinks.

Reimplemented in IlvOrthogonalLinkLayout, IlvTreeLayout, and IlvHierarchicalLayout.

virtual IlBoolean IlvGraphLayout::supportsPreserveFixedNodes ( ) const
virtual

Indicates whether the layout class allows the user to specify fixed nodes.

Fixed nodes are not moved during the layout.

The default implementation always returns IlFalse. Subclasses can override this method in order to return IlTrue, that is, to indicate that this option is supported.

Returns
Always IlFalse.
See Also
setPreserveFixedNodes(IlBoolean)
isPreserveFixedNodes
setFixed(IlAny, IlBoolean)
#isFixed(IlAny)
unfixAllNodes.

Reimplemented in IlvTreeLayout, IlvBusLayout, IlvHierarchicalLayout, and IlvRandomLayout.

virtual IlBoolean IlvGraphLayout::supportsRandomGenerator ( ) const
virtual

Indicates whether the layout class uses randomly-generated numbers (or randomly-chosen parameters) for which it can accept a user-defined seed value.

When you perform the same layout on the same graph several times and use the same user-defined seed value (or some other constant value), the same random numbers are generated and, if the algorithm is deterministic, you obtain the same drawing of the graph model. If you want different drawings each time you perform the layout, you can modify the seed value and call the method setUseSeedValueForRandomGenerator(IlBoolean) with an IlTrue argument.

For example, you can use this parameter in the implementation of the layout() method in the following way:

The default implementation always returns IlFalse.

Subclasses can override this method in order to return IlTrue, that is, to indicate that this option is supported.

Returns
Always IlFalse.
See Also
setSeedValueForRandomGenerator(IlUShort)
getSeedValueForRandomGenerator
setUseSeedValueForRandomGenerator(IlBoolean)
isUseSeedValueForRandomGenerator.

Reimplemented in IlvRandomLayout.

void IlvGraphLayout::unfixAllLinks ( )

Removes the fixed attributes from all links in the graph model.

See Also
supportsPreserveFixedLinks
setPreserveFixedLinks(IlBoolean)
isPreserveFixedLinks
setFixed(IlAny, IlBoolean)
#isFixed(IlAny).
void IlvGraphLayout::unfixAllNodes ( )

Removes the fixed attribute from all nodes in the graph model.

See Also
supportsPreserveFixedNodes
setPreserveFixedNodes(IlBoolean)
isPreserveFixedNodes
setFixed(IlAny, IlBoolean)
#isFixed(IlAny).

© 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.