com.yworks.yfiles.layout

Class PortCandidate

java.lang.Object

com.yworks.yfiles.layout.PortCandidate

public class PortCandidate
extends 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 IDataProviders that are registered with the graph using keys SOURCE_PORT_CANDIDATE_COLLECTION_DPKEY (to specify PortCandidates for an edge on the source node) and TARGET_PORT_CANDIDATE_COLLECTION_DPKEY (to specify PortCandidates for an edge on the target node). The IDataProviders 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.

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 HierarchicLayout, EdgeRouter, ChannelEdgeRouter and BusRouter.

PortPlacementStage 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

Fields

Modifier and Type	Field and Description
static EdgeDpKey<Collection<PortCandidate>>	SOURCE_PORT_CANDIDATE_COLLECTION_DPKEY A DataProvider key for specifying source port candidates for each edge.
static EdgeDpKey<Collection<PortCandidate>>	TARGET_PORT_CANDIDATE_COLLECTION_DPKEY A DataProvider key for specifying target port candidates for each edge.

Method Summary

Modifier and Type	Method and Description
static PortCandidate	createCandidate(double xOffset, double yOffset, PortDirections directionMask) Factory method that creates a fixed PortCandidate instance with the given cost of usage, direction and offset values.
static PortCandidate	createCandidate(double xOffset, double yOffset, PortDirections directionMask, double cost) Factory method that creates a fixed PortCandidate instance with the given cost of usage, direction and offset values.
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.
static PortCandidate	createCandidate(PortDirections directionMask) Factory method that creates a free PortCandidate instance with the given direction and zero cost of usage.
static PortCandidate	createCandidate(PortDirections directionMask, double cost) Factory method that creates a free PortCandidate instance with the given direction and cost of usage.
boolean	equals(Object other) Returns whether or not this PortCandidate is equal to another PortCandidate based on their internal attributes.
double	getCost() Gets the penalty cost for using this PortCandidate instance.
PortDirections	getDirection() Gets the direction of this PortCandidate.
PortDirections	getDirectionForLayoutOrientation(LayoutOrientation layoutOrientation) Returns the direction of this PortCandidate instance with respect to the given layout orientation.
double	getXOffset() Gets the X-offset of the PortCandidate with respect to the center of the corresponding node.
double	getXOffsetForLayoutOrientation(LayoutOrientation layoutOrientation) Returns the X-offset of the PortCandidate with respect to the center of the corresponding node for the given layout orientation.
double	getXOffsetForLayoutOrientation(LayoutOrientation layoutOrientation, MirrorModes 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() Gets the Y-offset of the PortCandidate with respect to the center of the corresponding node.
double	getYOffsetForLayoutOrientation(LayoutOrientation layoutOrientation) Returns the Y-offset of the PortCandidate with respect to the center of the corresponding node for the given layout orientation.
double	getYOffsetForLayoutOrientation(LayoutOrientation layoutOrientation, MirrorModes 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() Gets whether or not this PortCandidate is fixed.
boolean	isInDirection(PortDirections 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(LayoutOrientation layoutOrientation) A utility method that converts the current PortCandidate instance to a PortConstraint with respect to the given layout orientation.
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

SOURCE_PORT_CANDIDATE_COLLECTION_DPKEY

public static final EdgeDpKey<Collection<PortCandidate>> SOURCE_PORT_CANDIDATE_COLLECTION_DPKEY

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

TARGET_PORT_CANDIDATE_COLLECTION_DPKEY

public static final EdgeDpKey<Collection<PortCandidate>> TARGET_PORT_CANDIDATE_COLLECTION_DPKEY

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

Method Detail

createCandidate

public static final PortCandidate createCandidate(double xOffset,
                                                  double yOffset,
                                                  PortDirections directionMask)

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

Parameters:

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

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

directionMask - any combination of the default direction specifiers

Returns:

a new PortCandidate instance

createCandidate

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

Factory method that creates a fixed PortCandidate instance with the given cost of usage, direction and 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

cost - the penalty cost for using this PortCandidate instance

Returns:

a new PortCandidate instance

createCandidate

public static final 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

createCandidate

public static final PortCandidate createCandidate(PortDirections 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 final PortCandidate createCandidate(PortDirections directionMask,
                                                  double cost)

Factory method that creates a 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

Returns:

a new PortCandidate instance

equals

public boolean equals(Object other)

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

Overrides:

equals in class 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()

Gets the penalty cost for using this PortCandidate instance.

Returns:

the penalty cost of this PortCandidate

getDirection

public PortDirections getDirection()

Gets the direction of this PortCandidate.

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

Returns:

the direction of this PortCandidate

See Also:

getDirectionForLayoutOrientation(LayoutOrientation)

getDirectionForLayoutOrientation

public PortDirections getDirectionForLayoutOrientation(LayoutOrientation 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, Direction should be used instead.

Returns:

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

See Also:

getDirection()

getXOffset

public double getXOffset()

Gets 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(LayoutOrientation) should be used instead.

Returns:

the X-offset of this PortCandidate

getXOffsetForLayoutOrientation

public double getXOffsetForLayoutOrientation(LayoutOrientation 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, XOffset should be used instead.

Parameters:

layoutOrientation - the layout orientation

Returns:

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

getXOffsetForLayoutOrientation

public double getXOffsetForLayoutOrientation(LayoutOrientation layoutOrientation,
                                             MirrorModes 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, XOffset 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

getYOffset

public double getYOffset()

Gets 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(LayoutOrientation) should be used instead.

Returns:

the Y-offset of this PortCandidate

getYOffsetForLayoutOrientation

public double getYOffsetForLayoutOrientation(LayoutOrientation 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, YOffset should be used instead.

Parameters:

layoutOrientation - the layout orientation

Returns:

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

getYOffsetForLayoutOrientation

public double getYOffsetForLayoutOrientation(LayoutOrientation layoutOrientation,
                                             MirrorModes 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, YOffset 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

hashCode

public int hashCode()

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

Overrides:

hashCode in class Object

Returns:

a hash code value

isFixed

public boolean isFixed()

Gets 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

isInDirection

public boolean isInDirection(PortDirections 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

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(LayoutOrientation) should be used instead.

Returns:

a PortConstraint that matches this PortCandidate

toPortConstraintForLayoutOrientation

public PortConstraint toPortConstraintForLayoutOrientation(LayoutOrientation 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

toString

public String toString()

Returns a string representation of this PortCandidate instance.

Overrides:

toString in class Object

Returns:

a string representation of the PortCandidate