PortCandidateSet (yFiles-for-JavaFX-Complete-3.0 API)

java.lang.Object
- com.yworks.yfiles.layout.PortCandidateSet

```
public class PortCandidateSet
extends Object
```
This class associates PortCandidates with the nodes of a graph.
PortCandidates defined on nodes specify sides or even exact locations at which edges can be connected. This means that an edge can be connected to any of the available node ports (unless edge PortCandidates are specified too). Each node PortCandidate has a capacity, i.e., a maximum number of edges allowed to connect to it.

Information about PortCandidates on nodes is held by a IDataProvider that stores a PortCandidateSet for each node and is registered with the graph using key NODE_PORT_CANDIDATE_SET_DPKEY.

The PortCandidates are retrieved from the PortCandidateSet through a PortCandidateSet.IEntry that holds the information about the actual PortCandidate. This object is also used for retrieving the best candidate from a PortCandidateSet based on the cost (lower costs are considered first) and the available capacity of each candidate. Custom searching for the best PortCandidate can be achieved by implementing PortCandidateSet.ICandidateMatcher interface.

Example of node port candidates. Circular ports represent node port candidates on source nodes of each edge. Square and rectangular ports are possible port candidates on the target node. Rectangular ports have zero cost of usage and unit capacity whereas square rectangles have unit cost and capacity.

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.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static interface`	`PortCandidateSet.ICandidateMatcher` A `PortCandidateSet.ICandidateMatcher` retrieves the best matching `entries` from a `PortCandidateSet`.
`static interface`	`PortCandidateSet.IEntry` This interface represents an entry of a `PortCandidateSet` and provides access to the actual `PortCandidate` instance and the maximum number of edges allowed to connect to it.

Field Summary

Fields
Modifier and Type Field and Description

static NodeDpKey<PortCandidateSet> NODE_PORT_CANDIDATE_SET_DPKEY
A DataProvider key for specifying a port candidate set for each node.

Fields
Modifier and Type	Field and Description
`static NodeDpKey<PortCandidateSet>`	`NODE_PORT_CANDIDATE_SET_DPKEY` A `DataProvider` key for specifying a port candidate set for each node.

Constructor Summary

Constructors
Constructor and Description

PortCandidateSet()
Creates a new empty PortCandidateSet instance.

Constructors
Constructor and Description
`PortCandidateSet()` Creates a new empty `PortCandidateSet` instance.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`add(PortCandidate p)` Adds a `PortCandidate` with the given capacity to this `PortCandidateSet`.
`void`	`add(PortCandidate p, int connections)` Adds a `PortCandidate` with the given capacity to this `PortCandidateSet`.
`PortCandidateSet.ICandidateMatcher`	`createMatcher()` Creates a `PortCandidateSet.ICandidateMatcher` that retrieves `entries` from this `PortCandidateSet`.
`int`	`getConnectionCount()` Gets the total number of connections allowed by the `PortCandidate`s described by this `PortCandidateSet` or `Integer.MAX_VALUE` if the number is unbounded.
`protected double`	`getCost(PortCandidateSet.IEntry entry, Edge edge, boolean source, double xOffset, double yOffset)` Calculates the penalty cost for the usage of the given `entry` and the given parameters.
`IEnumerator<Object>`	`getEntries()` Gets an `IEnumerator` over the list of candidate `entries` of this `PortCandidateSet`.
`protected double`	`getPriority(PortCandidateSet.IEntry entry, Edge edge, boolean source)` Calculates the priority of the given `entry`.
`void`	`remove(PortCandidateSet.IEntry entry)` Removes the given `entry` from the list of candidate entries.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - NODE_PORT_CANDIDATE_SET_DPKEY
```
public static final NodeDpKey<PortCandidateSet> NODE_PORT_CANDIDATE_SET_DPKEY
```
    A DataProvider key for specifying a port candidate set for each node.
- Constructor Detail
  - PortCandidateSet
```
public PortCandidateSet()
```
    Creates a new empty PortCandidateSet instance.
    Addition of PortCandidates to this set can be performed using add(PortCandidate, int).
- Method Detail
  - add
```
public final void add(PortCandidate p)
```
    Adds a PortCandidate with the given capacity to this PortCandidateSet.
    The capacity value defines the maximum number of edges allowed to connect to the candidate. If no limitation for this number exists, Integer.MAX_VALUE can be used.
    
    The capacity must be greater than zero.
    
    Throws:
    
    IllegalArgumentException - if the given capacity is less than or equal to zero
    
    Parameters:
    
    p - the PortCandidate to add
  - add
```
public void add(PortCandidate p,
                int connections)
```
    Adds a PortCandidate with the given capacity to this PortCandidateSet.
    The capacity value defines the maximum number of edges allowed to connect to the candidate. If no limitation for this number exists, Integer.MAX_VALUE can be used.
    
    The capacity must be greater than zero.
    
    Throws:
    
    IllegalArgumentException - if the given capacity is less than or equal to zero
    
    Parameters:
    
    p - the PortCandidate to add
    
    connections - the capacity of the given port
  - createMatcher
```
public PortCandidateSet.ICandidateMatcher createMatcher()
```
    Creates a PortCandidateSet.ICandidateMatcher that retrieves entries from this PortCandidateSet.
    Each next best matching candidate is determined based on its cost, its current available capacity and based on whether or not its direction is consistent with the desired one.
    
    This method may be overridden to support custom implementations of PortCandidateSet.ICandidateMatcher.
    
    Returns:
    
    a new PortCandidateSet.ICandidateMatcher instance
  - getConnectionCount
```
public int getConnectionCount()
```
    Gets the total number of connections allowed by the PortCandidates described by this PortCandidateSet or Integer.MAX_VALUE if the number is unbounded.
    
    Returns:
    
    the number of connections allowed by this PortCandidateSet
  - getCost
```
protected double getCost(PortCandidateSet.IEntry entry,
                         Edge edge,
                         boolean source,
                         double xOffset,
                         double yOffset)
```
    Calculates the penalty cost for the usage of the given entry and the given parameters.
    The cost is equal to the cost of usage of the associated port candidate.
    
    This method may be overridden to customize the calculation of the cost of usage of an entry.
    
    Parameters:
    
    entry - the entry for which the cost is computed
    
    edge - the edge that will connect to the PortCandidate associated with the entry
    
    source - true if the given edge connects to its source node, false otherwise
    
    xOffset - the preferred X-offset of the port relative to the center of the node
    
    yOffset - the preferred Y-offset of the port relative to the center of the node
    
    Returns:
    
    the penalty cost for the usage of the given PortCandidateSet.IEntry
  - getEntries
```
public IEnumerator<Object> getEntries()
```
    Gets an IEnumerator over the list of candidate entries of this PortCandidateSet.
    
    Returns:
    
    an IEnumerator over the list of PortCandidateSet.IEntrys
  - getPriority
```
protected double getPriority(PortCandidateSet.IEntry entry,
                             Edge edge,
                             boolean source)
```
    Calculates the priority of the given entry.
    Higher priority means that the entry will be considered earlier by a PortCandidateSet.ICandidateMatcher.
    
    This method may be overridden to customize the calculation of the priority of entries.
    
    Parameters:
    
    entry - the entry for which the cost is computed
    
    edge - the edge that will connect to the PortCandidate associated with the entry
    
    source - true if the given edge connects to its source node, false otherwise
    
    Returns:
    
    the priority of the given PortCandidateSet.IEntry
  - remove
```
public void remove(PortCandidateSet.IEntry entry)
```
    Removes the given entry from the list of candidate entries.
    
    Parameters:
    
    entry - the entry to remove

Class PortCandidateSet

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

NODE_PORT_CANDIDATE_SET_DPKEY

Constructor Detail

PortCandidateSet

Method Detail

add

add

createMatcher

getConnectionCount

getCost

getEntries

getPriority

remove