Avoid::ShapeConnectionPin Class Reference

The ShapeConnectionPin class represents a fixed point or "pin" on a shape that can be connected to. More...

#include <connectionpin.h>

Collaboration diagram for Avoid::ShapeConnectionPin:

Public Member Functions
	ShapeConnectionPin (ShapeRef *shape, const unsigned int classId, const double xOffset, const double yOffset, const bool proportional, const double insideOffset, const ConnDirFlags visDirs)
	Constructs a ShapeConnectionPin at a specified absolute or proportional position relative to the parent shape. More...
	ShapeConnectionPin (JunctionRef *junction, const unsigned int classId, const ConnDirFlags visDirs=ConnDirNone)
	Constructs a ShapeConnectionPin on a JunctionRef. More...
void	setConnectionCost (const double cost)
	Sets a cost used when selecting whether connectors should be be attached to this connection pin. More...
const Point	position (const Polygon &newPoly=Polygon()) const
	Returns the position of this connection pin. More...
ConnDirFlags	directions (void) const
	Returns the directions in which this connection pin has visibility. More...
void	setExclusive (const bool exclusive)
	Sets whether the pin is exclusive, i.e., only one connector can attach to it. This defaults to true for connection pins with visibility in a specific directions and false for pins with visibility in all directions. More...
bool	isExclusive (void) const
	Returns whether the connection pin is exclusive, i.e., only one connector can attach to it. More...

Detailed Description

The ShapeConnectionPin class represents a fixed point or "pin" on a shape that can be connected to.

A pin has a position that is specified relative to its parent shape.
When the shape is moved or resized, the pin will be automatically moved accordingly. Connectors attached to the pin will be rerouted.

Pins have a visibility direction and numeric ID used to identify them. This ID, known as their classId, may be shared by multiple pins on the same shape. You can use classIds when you want libavoid to choose from multiple potential choices (e.g., to specify multiple types of pins such as "input" or "output" pins on circuit elements).

If you would like connectors that attach to a single specific position on a shape, then just give each pin a unique classId (for that shape) and tell the connector to attach to that particular pin.

Pins may optionally be given a connection cost, via setConnectionCost(). In the case of multiple pins with the same classId, this causes the lower-cost pins to be chosen first, rather than libavoid choosing the best pin with that classId based solely on connector path cost.

Pins can be exclusive, which means subsequent connectors routed to the same classId will choose a different pin. Pins with a specified direction are exclusive by default, those with visibility in all directions are non-exclusive by default. This behaviour can be changed by calling the ShapeConnectionPin::setExclusive() method. Exclusive pins may only have a single connector attached to them.

Constructor & Destructor Documentation

ShapeConnectionPin() [1/2]

Avoid::ShapeConnectionPin::ShapeConnectionPin	(	ShapeRef *	shape,
		const unsigned int	classId,
		const double	xOffset,
		const double	yOffset,
		const bool	proportional,
		const double	insideOffset,
		const ConnDirFlags	visDirs
	)

Constructs a ShapeConnectionPin at a specified absolute or proportional position relative to the parent shape.

Ownership of this ShapeConnectionPin is passed to the parent shape.

The connection point position offsets can be specified as absolute or proportional. If absolute, the xOffset and yOffset values are absolute offsets relative to the lower X and Y shape rectangle border positions. If proportional, the xOffset and yOffset values represent proportions of the shape's total width and height using a floating point value between 0 and 1.
Note that if you need the connection pin to appear at an exact position this may not be possible via proportional positions due to numerical inaccuracy in floating point multiplications. In this case you should use absolute offsets instead.

There are some predefined values for specifying the xOffset and yOffset arguments for proportional offsets:

• ATTACH_POS_TOP = 0
• ATTACH_POS_LEFT = 0
• ATTACH_POS_CENTRE = 0.5
• ATTACH_POS_BOTTOM = 1
• ATTACH_POS_RIGHT = 1 And two more for specifying absolute offsets:
• ATTACH_POS_MIN_OFFSET = offset of zero
• ATTACH_POS_MAX_OFFSET = offset of shape width/height

Importantly, shape connection pins will be moved automatically when the parent shape is moved or resized. Attachment for connectors will be chosen based on the classId specified to ConnEnd and these connectors will be subsequently rerouted.

If no value is given for the visDirs argument, then visibility is automatically determined based on the position of the connection point. Points on the shape boundary will have visibility from the shape out of that edge while points in the interior will have visibility in all directions. Note: Pins with visibility in a specific direction are exclusive by default, whereas those with visibility in all directions are non-exclusive by default.

The insideOffset argument can be used to set a distance to automatically offset the point within the shape. This is useful for orthogonal routing, where you usually want the connection point to lie inside the shape rather than exactly on its boundary. This offset will only be applied for connection pins specified with a position exactly on the shape boundary.

Parameters

[in]	shape	A pointer to the containing parent shape's ShapeRef.
[in]	classId	A non-zero integer used to identify this pin and other equivalent connection point, and used to specify attachment via the ConnEnd class.
[in]	xOffset	The X offset for the connection pin from the shape's lower X border position.
[in]	yOffset	The Y offset for the connection pin from the shape's lower Y border position.
[in]	proportional	A boolean specifying whether the X and Y offsets are proportional or not.
[in]	insideOffset	A distance to offset the connection point inside the shape if it lies on the boundary. Use 0.0 for no offset.
[in]	visDirs	One or more Avoid::ConnDirFlag options specifying the directions that this connection point has visibility. Use ConnDirNone to have visibility be directional if a pin is on the shape edge or in all directions otherwise.

ShapeConnectionPin() [2/2]

Avoid::ShapeConnectionPin::ShapeConnectionPin	(	JunctionRef *	junction,
		const unsigned int	classId,
		const ConnDirFlags	visDirs = ConnDirNone
	)

Constructs a ShapeConnectionPin on a JunctionRef.

Ownership of this ShapeConnectionPin is passed to the parent junction.

This will usually be automatically called by the JunctionRef constructor to give the Junction four ShapeConnectionPins, facing up, down, left and right.

Parameters

[in]	junction	A pointer to the containing parent junction's JunctionRef.
[in]	classId	An integer used to mark the class or group of this connection point, used for specifying attachment to ConnEnd.
[in]	visDirs	One or more Avoid::ConnDirFlag options specifying the directions that this connection point has visibility.

References Avoid::JunctionRef::position().

Here is the call graph for this function:

Member Function Documentation

directions()

ConnDirFlags Avoid::ShapeConnectionPin::directions

(

void

)

const

Returns the directions in which this connection pin has visibility.

Returns

The visibility directions for this connection pin.

References Avoid::ConnDirAll, Avoid::ConnDirDown, Avoid::ConnDirLeft, Avoid::ConnDirRight, and Avoid::ConnDirUp.

Referenced by Avoid::ConnEnd::directions().

Here is the caller graph for this function:

isExclusive()

bool Avoid::ShapeConnectionPin::isExclusive

(

void

)

const

Returns whether the connection pin is exclusive, i.e., only one connector can attach to it.

Returns

A boolean denoting whether this pin is exclusive.

position()

const Point Avoid::ShapeConnectionPin::position

(

const Polygon &

newPoly = Polygon()

)

const

Returns the position of this connection pin.

Returns

The position of this connection pin.

References Avoid::Polygon::empty(), Avoid::Box::max, Avoid::Box::min, Avoid::PolygonInterface::offsetBoundingBox(), Avoid::ShapeRef::polygon(), Avoid::JunctionRef::position(), Avoid::Point::vn, Avoid::Point::x, and Avoid::Point::y.

Referenced by Avoid::ConnEnd::position().

Here is the call graph for this function:

Here is the caller graph for this function:

setConnectionCost()

void Avoid::ShapeConnectionPin::setConnectionCost

(

const double

cost

)

Sets a cost used when selecting whether connectors should be be attached to this connection pin.

Parameters

[in]

cost

A routing cost applied to a route when selecting this connection pin.

setExclusive()

void Avoid::ShapeConnectionPin::setExclusive

(

const bool

exclusive

)

Sets whether the pin is exclusive, i.e., only one connector can attach to it. This defaults to true for connection pins with visibility in a specific directions and false for pins with visibility in all directions.

Parameters

[in]

exclusive

A bool representing whether this pin should be exclusive.

Referenced by Avoid::JunctionRef::JunctionRef().

Here is the caller graph for this function:

---

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

• libavoid/connectionpin.h
• libavoid/connectionpin.cpp