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

#include <ilviews/layout/gphlayout.h>

Inheritance diagram for IlvGraphLayout:

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

IlvMgrView *	getFirstManagerView () const
	Returns the first manager view attached to the graph model if any, and `0` otherwise.

IlvGrapher *	getGrapher () const
	Returns the grapher to lay out. More...

IlvGraphModel *	getGraphModel () 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...

IlvGraphLayoutReport *	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. 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...

IlvGraphLayoutReport *	performLayout ()
	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 IlvGraphLayoutReport *	createLayoutReport ()
	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

grapher The 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

graphModel The 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&):

If the last method is setLayoutRegion(const IlvRect&), it updates the rectangle without transformation performed.
If the last method is setLayoutRegion(IlvMgrView*, const IlvRect&), it updates the rectangle transformed to the manager coordinates using the transformer of the view.
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.
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

rect	The 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:

IlvRandomLayout* random;
if (isUseSeedValueForRandomGenerator())
    random = new IlvRandomLayout(getSeedValueForRandomGenerator());
else
    random = new IlvRandomLayout();

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

nodeOrLink The 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:

IlvRandomLayout* random;
if (isUseSeedValueForRandomGenerator())
    random = new IlvRandomLayout(getSeedValueForRandomGenerator());
else
    random = new IlvRandomLayout();

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.
    IlvGraphLayoutReport* layoutReport = getLayoutReport();
    IlBoolean atLeastOneNodeMoved = IlFalse;
    // Obtain the layout region.
    IlvRect rect
    getLayoutRegion(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.
    IlvRandomLayout* random = (isUseSeedValueForRandomGenerator())
        ? new Random(getSeedValueForRandomGenerator())
        : 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.
        layoutStepPerformed();
    }
    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

time	The 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

nodeOrLink	The object to be fixed or not.
val	The 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

grapher The 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

view	The 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

view	The 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.
rect	The 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

seedValue The 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:

IlvRandomLayout* random;
if (isUseSeedValueForRandomGenerator())
    random = new IlvRandomLayout(getSeedValueForRandomGenerator());
else
    random = new IlvRandomLayout();

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

Rogue Wave ViewsGraph Layout Package API Reference Guide

Public Member Functions

Protected Member Functions

Detailed Description

Member Function Documentation

Rogue Wave Views
Graph Layout Package API Reference Guide