Public Member Functions | List of all members
Avoid::Router Class Reference

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

#include <router.h>

Public Member Functions

 Router (const unsigned int flags)
 Constructor for router instance. More...
 
 ~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 effeciently 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 addShape (ShapeRef *shape)
 Add a shape to the router scene. More...
 
void removeShape (ShapeRef *shape)
 Remove 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 addJunction (JunctionRef *junction)
 Add a junction from the router scene. More...
 
void removeJunction (JunctionRef *junction)
 Remove a junction 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 setOrthogonalNudgeDistance (const double dist)
 Sets a spacing distance for overlapping orthogonal connectors to be nudged apart. More...
 
double orthogonalNudgeDistance (void) const
 Returns the spacing distance that overlapping orthogonal connecotrs are nudged apart. More...
 
void setRoutingPenalty (const PenaltyType penType, const double penVal=chooseSensiblePenalty)
 Sets or removes penalty values that are applied during connector routing. More...
 
double routingPenalty (const PenaltyType penType) const
 Returns the current penalty value for a particular routing penalty case. 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

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

Constructor for router instance.

Parameters
[in]flagsOne or more Avoid::RouterFlag options to control the behaviour of the router.
Avoid::Router::~Router ( )

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

void Avoid::Router::addJunction ( JunctionRef junction)

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

Parameters
[in]junctionPointer reference to the junction being added.
void Avoid::Router::addShape ( ShapeRef shape)

Add a shape to the router scene.

This shape will be considered to be an obstacle. Calling this method will cause connectors intersecting the added shape to 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]shapePointer reference to the shape being added.
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]junctionPointer reference to the junction being moved.
[in]newPositionThe new position for the junction.
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]junctionPointer reference to the junction being moved.
[in]xDiffThe distance to move the junction in the x dimension.
[in]yDiffThe distance to move the junction in the y dimension.
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]shapePointer reference to the shape being moved/resized.
[in]newPolyThe new polygon boundary for the shape.
[in]first_moveThis option is used for some advanced (currently undocumented) behaviour and it should be ignored for the moment.
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]shapePointer reference to the shape being moved.
[in]xDiffThe distance to move the shape in the x dimension.
[in]yDiffThe distance to move the shape in the y dimension.
double Avoid::Router::orthogonalNudgeDistance ( void  ) const

Returns the spacing distance that overlapping orthogonal connecotrs are nudged apart.

Returns
The current spacing distance used for orthogonal nudging.
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
void Avoid::Router::removeJunction ( 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.

Parameters
[in]junctionPointer reference to the junction being removed.
void Avoid::Router::removeShape ( ShapeRef shape)

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

Parameters
[in]shapePointer reference to the shape being removed.
double Avoid::Router::routingPenalty ( const PenaltyType  penType) const

Returns the current penalty value for a particular routing penalty case.

Parameters
[in]penTypeThe type of penalty, a PenaltyType.
Returns
The penalty value for the specified penalty case.
void Avoid::Router::setOrthogonalNudgeDistance ( const double  dist)

Sets a spacing distance for overlapping orthogonal connectors to be nudged apart.

By default, this distance is set to a value of 4.

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

Parameters
[in]distThe distance to be used for orthogonal nudging.
void Avoid::Router::setRoutingPenalty ( const PenaltyType  penType,
const double  penVal = chooseSensiblePenalty 
)

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

By default, libavoid will 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 improve the aesthetics of the routes generated. These different penalties are specified and explained by the PenaltyType enum.

If a value of zero or Avoid::noPenalty is given then the penalty for this case will be removed. If no penalty argument (or a negative value) is specified when calling this method, then a sensible penalty value will be automatically chosen.

Parameters
[in]penTypeThe type of penalty, a PenaltyType.
[in]penValThe value to be applied for each occurance of the penalty case.
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 effeciently 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 tranactions. 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]transactionsA boolean value specifying whether to use transactions.
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: