The Router class represents a libavoid router instance. More...

#include <router.h>

Collaboration diagram for Avoid::Router:

Public Member Functions
	Router (const unsigned int flags)
	Constructor for router instance. More...

virtual	~Router ()
	Destructor for router instance. More...

void	setTransactionUse (const bool transactions)
	Allows setting of the behaviour of the router in regard to transactions. This controls whether transactions are used to queue changes and process them efficiently at once or they are instead processed immediately. More...

bool	transactionUse (void) const
	Reports whether the router groups actions into transactions. More...

bool	processTransaction (void)
	Finishes the current transaction and processes all the queued object changes efficiently. More...

void	deleteShape (ShapeRef *shape)
	Delete a shape from the router scene. More...

void	moveShape (ShapeRef *shape, const Polygon &newPoly, const bool first_move=false)
	Move or resize an existing shape within the router scene. More...

void	moveShape (ShapeRef *shape, const double xDiff, const double yDiff)
	Move an existing shape within the router scene by a relative distance. More...

void	deleteJunction (JunctionRef *junction)
	Remove a junction from the router scene. More...

void	deleteConnector (ConnRef *connector)
	Remove a connector from the router scene. More...

void	moveJunction (JunctionRef *junction, const Point &newPosition)
	Move an existing junction within the router scene. More...

void	moveJunction (JunctionRef *junction, const double xDiff, const double yDiff)
	Move an existing junction within the router scene by a relative distance. More...

void	setRoutingParameter (const RoutingParameter parameter, const double value=chooseSensibleParamValue)
	Sets values for routing parameters, including routing penalties. More...

double	routingParameter (const RoutingParameter parameter) const
	Returns the current value for a particular routing parameter of a given type. More...

void	setRoutingOption (const RoutingOption option, const bool value)
	Turn specific routing options on or off. More...

bool	routingOption (const RoutingOption option) const
	Returns the current state for a specific routing option. More...

void	setRoutingPenalty (const RoutingParameter penType, const double penVal=chooseSensibleParamValue)
	Sets or removes penalty values that are applied during connector routing. More...

HyperedgeRerouter *	hyperedgeRerouter (void)
	Returns a pointer to the hyperedge rerouter for the router. More...

void	outputInstanceToSVG (std::string filename=std::string())
	Generates an SVG file containing debug output and code that can be used to regenerate the instance. More...

virtual unsigned int	newObjectId (void) const
	Returns the object ID used for automatically generated objects, such as during hyperedge routing. More...

bool	objectIdIsUnused (const unsigned int id) const
	Returns whether or not the given ID is already used. More...

virtual bool	shouldContinueTransactionWithProgress (unsigned int elapsedTime, unsigned int phaseNumber, unsigned int totalPhases, double proportion)
	A method called at regular intervals during transaction processing to report progress and ask if the Router should continue the transaction. More...

HyperedgeNewAndDeletedObjectLists	newAndDeletedObjectListsFromHyperedgeImprovement (void) const
	Returns a HyperedgeNewAndDeletedObjectLists detailing the lists of junctions and connectors created and deleted during hyperedge improvement. More...

void	setTopologyAddon (TopologyAddonInterface *topologyAddon)
	Set an addon for doing orthogonal topology improvement. More...

Detailed Description

The Router class represents a libavoid router instance.

Usually you would keep a separate Router instance for each diagram or layout you have open in your application.

Constructor & Destructor Documentation

◆ Router()

Avoid::Router::Router ( const unsigned int flags )

Constructor for router instance.

Parameters

[in] flags One or more Avoid::RouterFlag options to control the behaviour of the router.

References Avoid::clusterCrossingPenalty, Avoid::idealNudgingDistance, Avoid::improveHyperedgeRoutesMovingAddingAndDeletingJunctions, Avoid::improveHyperedgeRoutesMovingJunctions, Avoid::nudgeOrthogonalSegmentsConnectedToShapes, Avoid::nudgeOrthogonalTouchingColinearSegments, Avoid::nudgeSharedPathsWithCommonEndPoint, Avoid::OrthogonalRouting, Avoid::penaliseOrthogonalSharedPathsAtConnEnds, Avoid::performUnifyingNudgingPreprocessingStep, Avoid::PolyLineRouting, and Avoid::segmentPenalty.

◆ ~Router()

Avoid::Router::~Router ( )

virtual

Destructor for router instance.

Note: Destroying a router instance will delete all remaining shapes and connectors, thereby invalidating any existing pointers to them.

Member Function Documentation

◆ deleteConnector()

void Avoid::Router::deleteConnector ( ConnRef * connector )

Remove a connector from the router scene.

If the router is using transactions, then this action will occur the next time Router::processTransaction() is called. See Router::setTransactionUse() for more information.

You should not use the connector reference again after this call. The router will handle freeing of the connector's memory.

Parameters

[in] connector Pointer reference to the connector being removed.

◆ deleteJunction()

void Avoid::Router::deleteJunction ( JunctionRef * junction )

Remove a junction from the router scene.

If the router is using transactions, then this action will occur the next time Router::processTransaction() is called. See Router::setTransactionUse() for more information.

You should not use the junction reference again after this call. The router will handle freeing of the junction's memory.

Parameters

[in] junction Pointer reference to the junction being removed.

References processTransaction().

Here is the call graph for this function:

◆ deleteShape()

void Avoid::Router::deleteShape ( ShapeRef * shape )

Delete a shape from the router scene.

Connectors that could have a better (usually shorter) path after the removal of this shape will be marked as needing to be rerouted.

If the router is using transactions, then this action will occur the next time Router::processTransaction() is called. See Router::setTransactionUse() for more information.

You should not use the shape reference again after this call. The router will handle freeing of the shape's memory.

Parameters

[in] shape Pointer reference to the shape being removed.

References processTransaction().

Here is the call graph for this function:

◆ hyperedgeRerouter()

HyperedgeRerouter * Avoid::Router::hyperedgeRerouter ( void )

Returns a pointer to the hyperedge rerouter for the router.

Returns: A HyperedgeRerouter object that can be used to register hyperedges for rerouting.

◆ moveJunction() [1/2]

void Avoid::Router::moveJunction	(	JunctionRef *	junction,
		const Point &	newPosition
	)

Move an existing junction within the router scene.

Connectors that are attached to this junction will be rerouted as a result of the move.

If the router is using transactions, then this action will occur the next time Router::processTransaction() is called. See Router::setTransactionUse() for more information.

Parameters

[in]	junction	Pointer reference to the junction being moved.
[in]	newPosition	The new position for the junction.

References processTransaction().

Referenced by moveJunction().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ moveJunction() [2/2]

void Avoid::Router::moveJunction	(	JunctionRef *	junction,
		const double	xDiff,
		const double	yDiff
	)

Move an existing junction within the router scene by a relative distance.

Connectors that are attached to this junction will be rerouted as a result of the move.

If the router is using transactions, then this action will occur the next time Router::processTransaction() is called. See Router::setTransactionUse() for more information.

Parameters

[in]	junction	Pointer reference to the junction being moved.
[in]	xDiff	The distance to move the junction in the x dimension.
[in]	yDiff	The distance to move the junction in the y dimension.

References moveJunction(), Avoid::JunctionRef::position(), and Avoid::Point::x.

Here is the call graph for this function:

◆ moveShape() [1/2]

void Avoid::Router::moveShape	(	ShapeRef *	shape,
		const Polygon &	newPoly,
		const bool	first_move = `false`
	)

Move or resize an existing shape within the router scene.

A new polygon for the shape can be given to effectively move or resize the shape with the scene. Connectors that intersect the new shape polygon, or that could have a better (usually shorter) path after the change, will be marked as needing to be rerouted.

If the router is using transactions, then this action will occur the next time Router::processTransaction() is called. See Router::setTransactionUse() for more information.

Parameters

[in]	shape	Pointer reference to the shape being moved/resized.
[in]	newPoly	The new polygon boundary for the shape.
[in]	first_move	This option is used for some advanced (currently undocumented) behaviour and it should be ignored for the moment.

References processTransaction().

Referenced by moveShape().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ moveShape() [2/2]

void Avoid::Router::moveShape	(	ShapeRef *	shape,
		const double	xDiff,
		const double	yDiff
	)

Move an existing shape within the router scene by a relative distance.

Connectors that intersect the shape's new position, or that could have a better (usually shorter) path after the change, will be marked as needing to be rerouted.

If the router is using transactions, then this action will occur the next time Router::processTransaction() is called. See Router::setTransactionUse() for more information.

Parameters

[in]	shape	Pointer reference to the shape being moved.
[in]	xDiff	The distance to move the shape in the x dimension.
[in]	yDiff	The distance to move the shape in the y dimension.

References moveShape(), Avoid::ShapeRef::polygon(), and Avoid::Polygon::translate().

Here is the call graph for this function:

◆ newAndDeletedObjectListsFromHyperedgeImprovement()

HyperedgeNewAndDeletedObjectLists Avoid::Router::newAndDeletedObjectListsFromHyperedgeImprovement ( void ) const

Returns a HyperedgeNewAndDeletedObjectLists detailing the lists of junctions and connectors created and deleted during hyperedge improvement.

This method will only return information once the router has processed the transaction. You should read and act on this information before processTransaction() is called again.

After calling this you should no longer refer to any of the objects in the "deleted" lists — the router will delete these and free their memory at its convenience.

Returns: A HyperedgeNewAndDeletedObjectLists containing lists of junctions and connectors created and deleted.

◆ newObjectId()

unsigned int Avoid::Router::newObjectId ( void ) const

virtual

Returns the object ID used for automatically generated objects, such as during hyperedge routing.

Reimplement this in a subclass to set specific IDs for new objects.

Note: Your implementation should return a value that does not fail objectIdIsUnused().

Returns: The ID for a new object.

◆ objectIdIsUnused()

bool Avoid::Router::objectIdIsUnused ( const unsigned int id ) const

Returns whether or not the given ID is already used.

You should only need this if you reimplement newObjectId().

Parameters

[in] id An ID to test.

Returns: A boolean denoting that the given ID is unused.

◆ outputInstanceToSVG()

void Avoid::Router::outputInstanceToSVG ( std::string filename = std::string() )

Generates an SVG file containing debug output and code that can be used to regenerate the instance.

If transactions are being used, then this method should be called after processTransaction() has been called, so that it includes any changes being queued by the router.

Parameters

[in] filename A string indicating the filename (without extension) for the output file. Defaults to "libavoid-debug.svg" if no filename is given.

References Avoid::Polygon::at(), Avoid::ReferencingPolygon::at(), Avoid::Polygon::curvedPolyline(), Avoid::ConnRef::displayRoute(), Avoid::Polygon::empty(), Avoid::ClusterRef::id(), Avoid::ConnRef::id(), Avoid::Box::max, Avoid::Box::min, Avoid::ClusterRef::polygon(), Avoid::Polygon::ps, Avoid::JunctionRef::recommendedPosition(), Avoid::ClusterRef::rectangularPolygon(), Avoid::ConnRef::route(), Avoid::Polygon::size(), Avoid::ReferencingPolygon::size(), Avoid::Polygon::ts, Avoid::Point::x, and Avoid::Point::y.

Referenced by dialect::LeaflessOrthoRouter::route().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ processTransaction()

bool Avoid::Router::processTransaction ( void )

Finishes the current transaction and processes all the queued object changes efficiently.

This method will efficiently process all moves, additions and deletions that have occurred since processTransaction() was last called.

If transactionUse() is false, then all actions will have been processed immediately and this method will do nothing.

Returns: A boolean value describing whether there were any actions to process.

See also: setTransactionUse

Referenced by deleteJunction(), deleteShape(), moveJunction(), moveShape(), dialect::RoutingAdapter::route(), and dialect::LeaflessOrthoRouter::route().

Here is the caller graph for this function:

◆ routingOption()

bool Avoid::Router::routingOption ( const RoutingOption option ) const

Returns the current state for a specific routing option.

Parameters

[in] option The type of routing option, a RoutingOption.

Returns: A boolean representing the option state.

◆ routingParameter()

double Avoid::Router::routingParameter ( const RoutingParameter parameter ) const

Returns the current value for a particular routing parameter of a given type.

Parameters

[in] parameter The type of parameter, a RoutingParameter.

Returns: The value for the specified routing parameter.

◆ setRoutingOption()

void Avoid::Router::setRoutingOption	(	const RoutingOption	option,
		const bool	value
	)

Turn specific routing options on or off.

Parameters

[in]	option	The type of routing option, a RoutingOption.
[in]	value	A boolean representing the option state.

Referenced by dialect::doHOLA(), and dialect::LeaflessOrthoRouter::LeaflessOrthoRouter().

Here is the caller graph for this function:

◆ setRoutingParameter()

void Avoid::Router::setRoutingParameter	(	const RoutingParameter	parameter,
		const double	value = `chooseSensibleParamValue`
	)

Sets values for routing parameters, including routing penalties.

libavoid uses a set of parameters to allow the user more control over routing style and quality. These different parameters are described and explained by the RoutingParameter enum. All parameters have sensible defaults.

Regarding routing penalties, libavoid will by default produce shortest path routes between the source and destination points for each connector. There are several penalties that can be applied during this stage to penalise certain conditions and thus improve the aesthetics of the routes generated.
If a value of zero or Avoid::zeroParamValue is given then the particular parameter value or penalty will be removed. If no parameter value argument (or a negative value) is specified when calling this method, then a sensible penalty value will be automatically chosen.

This method does not re-trigger processing of connectors. The new parameter value will be used the next time rerouting is performed.

Parameters

[in]	parameter	The type of penalty, a RoutingParameter.
[in]	value	The value to be set for that parameter.

References Avoid::anglePenalty, Avoid::clusterCrossingPenalty, Avoid::crossingPenalty, Avoid::fixedSharedPathPenalty, Avoid::idealNudgingDistance, Avoid::portDirectionPenalty, and Avoid::segmentPenalty.

Referenced by dialect::LeaflessOrthoRouter::LeaflessOrthoRouter(), setRoutingPenalty(), and dialect::LeaflessOrthoRouter::setShapeBufferDistanceIELScalar().

Here is the caller graph for this function:

◆ setRoutingPenalty()

void Avoid::Router::setRoutingPenalty	(	const RoutingParameter	penType,
		const double	penVal = `chooseSensibleParamValue`
	)

Sets or removes penalty values that are applied during connector routing.

Note: This is a convenience wrapper for the setRoutingParameter()

Parameters

[in]	penType	The type of penalty, a RoutingParameter.
[in]	penVal	The value to be applied for each occurrence of the penalty case.

References setRoutingParameter().

Here is the call graph for this function:

◆ setTopologyAddon()

void Avoid::Router::setTopologyAddon ( TopologyAddonInterface * topologyAddon )

Set an addon for doing orthogonal topology improvement.

It is expected that you would use the topology::AvoidTopologyAddon() from libtopology rather than write your own. This is done so that libavoid does not have to depend on libtopology.

◆ setTransactionUse()

void Avoid::Router::setTransactionUse ( const bool transactions )

Allows setting of the behaviour of the router in regard to transactions. This controls whether transactions are used to queue changes and process them efficiently at once or they are instead processed immediately.

It is more efficient to perform actions like shape movement, addition or deletion as batch tasks, and reroute the necessary connectors just once after these actions have been performed. For this reason, libavoid allows you to group such actions into "transactions" that are processed efficiently when the processTransaction() method is called.

By default, the router will process all actions as transactions. If transactionUse() is set to false, then all actions will get processed immediately, and cause immediate routing callbacks to all affected connectors after each action.

Parameters

[in] transactions A boolean value specifying whether to use transactions.

◆ shouldContinueTransactionWithProgress()

bool Avoid::Router::shouldContinueTransactionWithProgress	(	unsigned int	elapsedTime,
		unsigned int	phaseNumber,
		unsigned int	totalPhases,
		double	proportion
	)

virtual

A method called at regular intervals during transaction processing to report progress and ask if the Router should continue the transaction.

You can subclass the Avoid::Router class to implement your own behaviour, such as to show a progress bar or cancel the transaction at the user's request.

Note that you can get a sense of progress by looking at the phaseNumber divided by the totalPhases and the progress in the current phase, but be aware that phases and the intervals and proportions at which this method is called will vary, sometime unpredictably.

You can return false to request that the Router abort the current transaction. Be aware that it may not abort in some phases. For others it may need to clean up some state before it is safe for you to interact with it again. Hence you should wait for a final call to this method with the phase Avoid::TransactionPhaseCompleted before continuing.

Note: Your implementation of this method should be very fast as it will be called many times. Also, you should not change or interact with the Router instance at all during these calls. Wait till you have received a call with the Avoid::TransactionPhaseCompleted phase.

Parameters

elapsedTime	The number of msec spent on the transaction since it began.
phaseNumber	A Router::TransactionPhases representing the current phase of the transaction.
totalPhases	The total number of phases to be performed during the transaction.
proportion	A double representing the progress in the current phase. Value will be between 0–1.

Returns: Whether the router should continue the transaction. This is true in the default (empty) implementation.

◆ transactionUse()

bool Avoid::Router::transactionUse ( void ) const

Reports whether the router groups actions into transactions.

Returns: A boolean value describing whether transactions are in use.

See also: setTransactionUse; processTransaction

The documentation for this class was generated from the following files:

libavoid/router.h
libavoid/router.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Router()

◆ ~Router()

Member Function Documentation

◆ deleteConnector()

◆ deleteJunction()

◆ deleteShape()

◆ hyperedgeRerouter()

◆ moveJunction() [1/2]

◆ moveJunction() [2/2]

◆ moveShape() [1/2]

◆ moveShape() [2/2]

◆ newAndDeletedObjectListsFromHyperedgeImprovement()

◆ newObjectId()

◆ objectIdIsUnused()

◆ outputInstanceToSVG()

◆ processTransaction()

◆ routingOption()

◆ routingParameter()

◆ setRoutingOption()

◆ setRoutingParameter()

◆ setRoutingPenalty()

◆ setTopologyAddon()

◆ setTransactionUse()

◆ shouldContinueTransactionWithProgress()

◆ transactionUse()