Search this API

y.layout
Class PortCandidate

java.lang.Object
  extended by 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:

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.

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.

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

© Copyright 2000-2021,
yWorks GmbH.
All rights reserved.