y.layout
Class PortCandidate

java.lang.Object
  y.layout.PortCandidate

public class PortCandidate
extends java.lang.Object

This class represents a candidate port on which edges can be connected to their source and/or target node.

The notion of PortCandidates extends the one of PortConstraints. In contrast to PortConstraints, they can be associated with both edges and nodes. Moreover, more than one PortCandidate can be specified for an edge or a node.

Edge PortCandidates can be introduced to define specific sides or exact locations on which a given edge can be connected to its source or target node.
Information about edge PortCandidates is held by DataProviders that are registered with the graph using keys SOURCE_PCLIST_DPKEY (to specify PortCandidates for an edge on the source node) and TARGET_PCLIST_DPKEY (to specify PortCandidates for an edge on the target node). The DataProviders hold a collection of PortCandidates for each edge.

Node PortCandidates determine available ports on the nodes to which edges can be connected. This means that an edge of the graph can be connected to any of these node ports (unless edge PortCandidates are specified too).
To register and define node PortCandidates refer to PortCandidateSet.

A PortCandidate is described by the following attributes:

• Offsets: The X-offset (Y-offset) determines the horizontal (vertical) distance of the PortCandidate relative to the center of the node.
• Fixed or free: Fixed PortCandidates are defined using exact coordinates, whereas coordinates of free candidates are selected arbitrarily.
• Direction: Corresponds to the incoming or outgoing directions of the edges when connecting to a target or source node, respectively.
• Penalty cost: Represents the cost of usage of a PortCandidate. During the processing of an edge by a layout or routing algorithm, candidates of lower cost will be considered first.

If candidates are defined for nodes as well as for edges and if they should be properly matched by layout algorithms (i.e. detected as the same candidate), then it is important that the same PortCandidate instance is registered. It does not suffice to register candidates with the same parameter values.

Example of using edge port candidates. Edge port candidates are colored uniquely based on the edge with which they are associated.

Not all layout and routing algorithms are able to handle PortCandidates. Major layout algorithms that obey them are IncrementalHierarchicLayouter, EdgeRouter, ChannelEdgeRouter and BusRouter.

PortCandidateAssignmentStage can be appended to any layout algorithm that cannot handle port constraints in order to assign edges to the ports specified by PortConstraints or PortCandidates after calling the core layout algorithm.

In case that both PortConstraints and PortCandidates (on edges and/or nodes) are defined for a graph, the layout or the routing algorithm will try to match both of them in order to find an appropriate port. The matching process depends on the actual algorithm.

Field Summary

static int	AGAINST_THE_FLOW A port direction specifier indicating a port lying in the opposite direction of the main flow of the edge or of the overall layout.
static int	ANY A combination of all possible direction specifiers indicating that edges can connect to any side of a node.
static int	EAST A port direction specifier indicating a port on the east (i.e., right) side of a node.
static int	LEFT_IN_FLOW A port direction specifier indicating a port lying left of the direction of the main flow of the edge or of the overall layout.
static int	NORTH A port direction specifier indicating a port on the north (i.e., top) side of a node.
static int	RIGHT_IN_FLOW A port direction specifier indicating a port lying right of the direction of the main flow of the edge or of the overall layout.
static java.lang.Object	SOURCE_PCLIST_DPKEY A DataProvider key for specifying source port candidates for each edge.
static int	SOUTH A port direction specifier indicating a port on the south (i.e., bottom) side of a node.
static java.lang.Object	TARGET_PCLIST_DPKEY A DataProvider key for specifying target port candidates for each edge.
static int	WEST A port direction specifier indicating a port on the west (i.e., left) side of a node.
static int	WITH_THE_FLOW A port direction specifier indicating a port lying in the direction of the main flow of the edge or of the overall layout.

Constructor Summary

protected	PortCandidate(double xOffset, double yOffset, boolean fixed, int directionMask, double cost) Deprecated. Factory method createCandidate(double, double, int, double) should be used instead.
protected	PortCandidate(double xOffset, double yOffset, int directionMask) Deprecated. Factory method createCandidate(double, double, int) should be used instead.
protected	PortCandidate(int directionMask) Deprecated. Factory method createCandidate(int)} should be used instead.
protected	PortCandidate(int directionMask, double cost) Deprecated. Factory method createCandidate(int, double) should be used instead.

Method Summary

static PortCandidate	createCandidate(double xOffset, double yOffset, int directionMask) Factory method that creates a fixed PortCandidate instance with zero cost of usage, the given direction and the given offset values.
static PortCandidate	createCandidate(double xOffset, double yOffset, int directionMask, double cost) Factory method that creates a fixed PortCandidate instance with the given cost of usage, direction and offset values.
static PortCandidate	createCandidate(int directionMask) Factory method that creates a free PortCandidate instance with the given direction and zero cost of usage.
static PortCandidate	createCandidate(int directionMask, double cost) Factory method that creates a free PortCandidate instance with the given direction and cost of usage.
static PortCandidate	createCandidate(PortConstraint fromPortConstraint) Factory method that returns a free PortCandidate instance with zero cost of usage and the direction specified by the side of the given PortConstraint.
boolean	equals(java.lang.Object other) Returns whether or not this PortCandidate is equal to another PortCandidate based on their internal attributes.
double	getCost() Returns the penalty cost for using this PortCandidate instance.
int	getDirection() Returns the direction of this PortCandidate.
int	getDirectionForLayoutOrientation(byte layoutOrientation) Returns the direction of this PortCandidate instance with respect to the given layout orientation.
double	getXOffset() Returns the X-offset of the PortCandidate with respect to the center of the corresponding node.
double	getXOffsetForLayoutOrientation(byte layoutOrientation) Returns the X-offset of the PortCandidate with respect to the center of the corresponding node for the given layout orientation.
double	getXOffsetForLayoutOrientation(byte layoutOrientation, int mirrorMask) Returns the X-offset of the PortCandidate with respect to the center of the corresponding node for the given layout orientation and mirror mask.
double	getYOffset() Returns the Y-offset of the PortCandidate with respect to the center of the corresponding node.
double	getYOffsetForLayoutOrientation(byte layoutOrientation) Returns the Y-offset of the PortCandidate with respect to the center of the corresponding node for the given layout orientation.
double	getYOffsetForLayoutOrientation(byte layoutOrientation, int mirrorMask) Returns the Y-offset of the PortCandidate with respect to the center of the corresponding node for the given layout orientation and mirror mask.
int	hashCode() Returns a hash code value for this PortCandidate instance based on the internal attributes.
boolean	isFixed() Returns whether or not this PortCandidate is fixed.
boolean	isInDirection(int directionMask) Returns whether or not this PortCandidate lies in the given direction.
PortConstraint	toPortConstraint() A utility method that converts the current PortCandidate instance to a PortConstraint.
PortConstraint	toPortConstraintForLayoutOrientation(byte layoutOrientation) A utility method that converts the current PortCandidate instance to a PortConstraint with respect to the given layout orientation.
java.lang.String	toString() Returns a string representation of this PortCandidate instance.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

NORTH

public static final int NORTH

A port direction specifier indicating a port on the north (i.e., top) side of a node.

See Also:

Constant Field Values

EAST

public static final int EAST

A port direction specifier indicating a port on the east (i.e., right) side of a node.

See Also:

Constant Field Values

WEST

public static final int WEST

A port direction specifier indicating a port on the west (i.e., left) side of a node.

See Also:

Constant Field Values

SOUTH

public static final int SOUTH

A port direction specifier indicating a port on the south (i.e., bottom) side of a node.

See Also:

Constant Field Values

WITH_THE_FLOW

public static final int WITH_THE_FLOW

A port direction specifier indicating a port lying in the direction of the main flow of the edge or of the overall layout.

The exact direction is domain-specific.

See Also:

Constant Field Values

AGAINST_THE_FLOW

public static final int AGAINST_THE_FLOW

A port direction specifier indicating a port lying in the opposite direction of the main flow of the edge or of the overall layout.

The exact direction is domain-specific.

See Also:

Constant Field Values

LEFT_IN_FLOW

public static final int LEFT_IN_FLOW

A port direction specifier indicating a port lying left of the direction of the main flow of the edge or of the overall layout.

The exact direction is domain-specific.

See Also:

Constant Field Values

RIGHT_IN_FLOW

public static final int RIGHT_IN_FLOW

A port direction specifier indicating a port lying right of the direction of the main flow of the edge or of the overall layout.

The exact direction is domain-specific.

See Also:

Constant Field Values

ANY

public static final int ANY

A combination of all possible direction specifiers indicating that edges can connect to any side of a node.

See Also:

Constant Field Values

SOURCE_PCLIST_DPKEY

public static final java.lang.Object SOURCE_PCLIST_DPKEY

A DataProvider key for specifying source port candidates for each edge.

TARGET_PCLIST_DPKEY

public static final java.lang.Object TARGET_PCLIST_DPKEY

A DataProvider key for specifying target port candidates for each edge.

Constructor Detail

PortCandidate

protected PortCandidate(double xOffset,
                        double yOffset,
                        boolean fixed,
                        int directionMask,
                        double cost)

Deprecated. Factory method createCandidate(double, double, int, double) should be used instead.

Creates a new instance of PortCandidate with the given cost of usage, direction specifier and offset values.

Parameters:

xOffset - the X-offset relative to the center of the given node

yOffset - the Y-offset relative to the center of the given node

fixed - true if this is a fixed PortCandidate, false otherwise

directionMask - any combination of the default direction specifiers

cost - the penalty cost for using this PortCandidate

PortCandidate

protected PortCandidate(double xOffset,
                        double yOffset,
                        int directionMask)

Deprecated. Factory method createCandidate(double, double, int) should be used instead.

Creates a new fixed PortCandidate instance with zero cost of usage, the given direction specifier and the given offset values.

Parameters:

xOffset - the X-offset relative to the center of the given node

yOffset - the Y-offset relative to the center of the given node

directionMask - any combination of the default direction specifiers

PortCandidate

protected PortCandidate(int directionMask)

Deprecated. Factory method createCandidate(int)} should be used instead.

Creates a new free PortCandidate instance with the given direction and zero cost of usage.

Parameters:

directionMask - any combination of the default direction specifiers

PortCandidate

protected PortCandidate(int directionMask,
                        double cost)

Deprecated. Factory method createCandidate(int, double) should be used instead.

Creates a new free PortCandidate instance with the given direction and cost of usage.

Parameters:

directionMask - any combination of the default direction specifiers

cost - the penalty cost for using this PortCandidate

Method Detail

isInDirection

public boolean isInDirection(int directionMask)

Returns whether or not this PortCandidate lies in the given direction.

Parameters:

directionMask - one of the default direction specifiers

Returns:

true if this PortCandidate lies in the given direction, false otherwise

getDirection

public int getDirection()

Returns the direction of this PortCandidate.

If the direction is required to be calculated with respect to the actual layout orientation, getDirectionForLayoutOrientation(byte) should be used instead.

Returns:

the direction of this PortCandidate

See Also:

getDirectionForLayoutOrientation(byte)

isFixed

public boolean isFixed()

Returns whether or not this PortCandidate is fixed.

Fixed PortCandidates are defined using exact coordinates, whereas coordinates of free candidates are selected arbitrarily.

Returns:

true if this PortCandidate is fixed, false otherwise

getXOffset

public double getXOffset()

Returns the X-offset of the PortCandidate with respect to the center of the corresponding node.

The X-offset encodes the horizontal distance of the port relative to the center of a node. If the PortCandidate is not fixed (i.e., free), the X-offset is zero.

If the X-offset is required to be calculated with respect to the actual layout orientation, getXOffsetForLayoutOrientation(byte) should be used instead.

Returns:

the X-offset of this PortCandidate

getYOffset

public double getYOffset()

Returns the Y-offset of the PortCandidate with respect to the center of the corresponding node.

The Y-offset encodes the vertical distance of the port relative to the center of a node. If the PortCandidate is not fixed (i.e., free), the Y-offset is zero.

If the Y-offset is required to be calculated with respect to the actual layout orientation, method getYOffsetForLayoutOrientation(byte) should be used instead.

Returns:

the Y-offset of this PortCandidate

createCandidate

public static PortCandidate createCandidate(int directionMask)

Factory method that creates a free PortCandidate instance with the given direction and zero cost of usage.

Parameters:

directionMask - any combination of the default direction specifiers

Returns:

a new PortCandidate instance

createCandidate

public static PortCandidate createCandidate(int directionMask,
                                            double cost)

Factory method that creates a free PortCandidate instance with the given direction and cost of usage.

For high costs, it may be necessary to adjust over-usage penalties to avoid extending the maximum connections, e.g., increase the value for property PCListOptimizer.setOverUsagePenalty(double) in IncrementalHierarchicLayouter.

Parameters:

directionMask - any combination of the default direction specifiers

cost - the penalty cost for using this PortCandidate

Returns:

a new PortCandidate instance

createCandidate

public static PortCandidate createCandidate(double xOffset,
                                            double yOffset,
                                            int directionMask)

Factory method that creates a fixed PortCandidate instance with zero cost of usage, the given direction and the given offset values.

Parameters:

directionMask - any combination of the default direction specifiers

xOffset - the X-offset relative to the center of the node

yOffset - the Y-offset relative to the center of the node

Returns:

a new PortCandidate instance

createCandidate

public static PortCandidate createCandidate(double xOffset,
                                            double yOffset,
                                            int directionMask,
                                            double cost)

Factory method that creates a fixed PortCandidate instance with the given cost of usage, direction and offset values.

For high costs, it may be necessary to adjust over-usage penalties to avoid extending the maximum connections, e.g., increase the value for property PCListOptimizer.setOverUsagePenalty(double) in IncrementalHierarchicLayouter.

Parameters:

directionMask - any combination of the default direction specifiers

xOffset - the X-offset relative to the center of the node

yOffset - the Y-offset relative to the center of the node

cost - the penalty cost for using this PortCandidate instance

Returns:

a new PortCandidate instance

createCandidate

public static PortCandidate createCandidate(PortConstraint fromPortConstraint)

Factory method that returns a free PortCandidate instance with zero cost of usage and the direction specified by the side of the given PortConstraint.

Parameters:

fromPortConstraint - the PortConstraint whose side should be used as direction

Returns:

a new PortCandidate instance

hashCode

public int hashCode()

Returns a hash code value for this PortCandidate instance based on the internal attributes.

Overrides:

hashCode in class java.lang.Object

Returns:

a hash code value

toPortConstraint

public PortConstraint toPortConstraint()

A utility method that converts the current PortCandidate instance to a PortConstraint.

The side of the created PortConstraint matches the direction of this PortCandidate.

If this PortCandidate is fixed, the resulting PortConstraint will be strong.

If the matching PortConstraint should be determined with respect to a certain layout orientation, method toPortConstraintForLayoutOrientation(byte) should be used instead.

Returns:

a PortConstraint that matches this PortCandidate

toPortConstraintForLayoutOrientation

public PortConstraint toPortConstraintForLayoutOrientation(byte layoutOrientation)

A utility method that converts the current PortCandidate instance to a PortConstraint with respect to the given layout orientation.

The side of the created PortConstraint is the direction of this PortCandidate interpreted for the given orientation.

If this PortCandidate is fixed, the resulting PortConstraint will be strong.

If the matching PortConstraint should not be determined with respect to a certain layout orientation, method toPortConstraint() should be used instead.

Returns:

a PortConstraint that matches this PortCandidate with respect to the given orientation

equals

public boolean equals(java.lang.Object other)

Returns whether or not this PortCandidate is equal to another PortCandidate based on their internal attributes.

Overrides:

equals in class java.lang.Object

Parameters:

other - the reference PortCandidate object with which to compare

Returns:

true if this object is the same as the PortCandidate argument, false otherwise

getCost

public double getCost()

Returns the penalty cost for using this PortCandidate instance.

Returns:

the penalty cost of this PortCandidate

getDirectionForLayoutOrientation

public int getDirectionForLayoutOrientation(byte layoutOrientation)

Returns the direction of this PortCandidate instance with respect to the given layout orientation.

If the direction mask is not required to be calculated with respect to the actual layout orientation, getDirection() should be used instead.

Returns:

the direction of this PortCandidate with respect to the given layout orientation

See Also:

getDirection()

getXOffsetForLayoutOrientation

public double getXOffsetForLayoutOrientation(byte layoutOrientation,
                                             int mirrorMask)

Returns the X-offset of the PortCandidate with respect to the center of the corresponding node for the given layout orientation and mirror mask.

The X-offset encodes the horizontal distance of the port relative to the center of a node. If the PortCandidate is not fixed (i.e., free), the X-offset is equal to zero.

If the X-offset is not required to be calculated for the actual layout orientation, getXOffset() should be used instead.

Parameters:

layoutOrientation - the layout orientation

mirrorMask - the mirror mask

Returns:

the X-offset of the port with respect to the given orientation and mirror mask

getYOffsetForLayoutOrientation

public double getYOffsetForLayoutOrientation(byte layoutOrientation,
                                             int mirrorMask)

Returns the Y-offset of the PortCandidate with respect to the center of the corresponding node for the given layout orientation and mirror mask.

The Y-offset encodes the vertical distance of the port relative to the center of a node. If the PortCandidate is not fixed (i.e., free), the Y-offset is equal to zero.

If the Y-offset is not required to be calculated for the actual layout orientation, getYOffset() should be used instead.

Parameters:

layoutOrientation - the layout orientation

mirrorMask - the mirror mask

Returns:

the Y-offset of the PortCandidate with respect to the given orientation and mirror mask

getXOffsetForLayoutOrientation

public double getXOffsetForLayoutOrientation(byte layoutOrientation)

Returns the X-offset of the PortCandidate with respect to the center of the corresponding node for the given layout orientation.

The X-offset encodes the horizontal distance of the port relative to the center of a node. If the PortCandidate is not fixed (i.e., free), the X-offset is equal to zero.

If the X-offset is not required to be calculated for the actual layout orientation, getXOffset() should be used instead.

Parameters:

layoutOrientation - the layout orientation

Returns:

the X-offset of the PortCandidate with respect to the given layout orientation

getYOffsetForLayoutOrientation

public double getYOffsetForLayoutOrientation(byte layoutOrientation)

Returns the Y-offset of the PortCandidate with respect to the center of the corresponding node for the given layout orientation.

The Y-offset encodes the vertical distance of the port relative to the center of a node. If the PortCandidate is not fixed (i.e., free), the Y-offset is equal to zero.

If the Y-offset is not required to be calculated for the actual layout orientation, getYOffset() should be used instead.

Parameters:

layoutOrientation - the layout orientation

Returns:

the Y-offset of the PortCandidate with respect to the given layout orientation

toString

public java.lang.String toString()

Returns a string representation of this PortCandidate instance.

Overrides:

toString in class java.lang.Object

Returns:

a string representation of the PortCandidate