y.layout.hierarchic.incremental
Class NodeLayoutDescriptor

java.lang.Object
  y.layout.hierarchic.incremental.NodeLayoutDescriptor

public class NodeLayoutDescriptor
extends java.lang.Object

This class is used by HierarchicLayouter during the various phases to provide the drawing details of the nodes of the graph.

A NodeLayoutDescriptor instance can be specified individually for single nodes using a DataProvider that returns a NodeLayoutDescriptor instance for each node of the graph, or null if no NodeLayoutDescriptor is bound to an edge. The DataProvider is registered with the graph with key HierarchicLayouter.NODE_LAYOUT_DESCRIPTOR_DPKEY.

This class is designed as a class to allow future additions of new getter methods.

Not all of these values will be used for all kinds of edges and any kind of algorithm.

See Also:

HierarchicLayouter.NODE_LAYOUT_DESCRIPTOR_DPKEY, EdgeLayoutDescriptor

Field Summary

static byte	NODE_LABEL_MODE_CONSIDER_FOR_DRAWING A constant that makes the algorithm consider node labels for node placement and routing, but not for self-loops.
static byte	NODE_LABEL_MODE_CONSIDER_FOR_ROUTING A constant that makes the algorithm consider node labels during routing only.
static byte	NODE_LABEL_MODE_CONSIDER_FOR_SELF_LOOPS A constant that makes the algorithm consider node labels for self-loops, node placement and routing.
static byte	NODE_LABEL_MODE_NEVER A constant that prevents node labels from being considered during the layout.
static byte	PORT_ASSIGNMENT_DEFAULT A port assignment strategy that distributes ports evenly along the border of the node.
static byte	PORT_ASSIGNMENT_ON_GRID A port assignment strategy that places all edges on grid lines.
static byte	PORT_ASSIGNMENT_ON_SUBGRID A port assignment strategy that places all edges on grid lines or sub-grid lines.

Constructor Summary

NodeLayoutDescriptor()
Creates a new instance of a NodeLayoutDescriptor with the default values.

Method Summary

YPoint	getGridReference() Returns the node's reference point that will be placed on a grid coordinate.
double	getLayerAlignment() Returns the alignment of the node of this NodeLayoutDescriptor instance within its layer.
double	getMinimumDistance() Returns the preferred minimum distance to obstacles.
double	getMinimumLayerHeight() Returns the minimum height of the layer to which this node is assigned.
byte	getNodeLabelMode() Returns the mode that determines how node labels are handled by the algorithm during the layout.
byte	getPortAssignment() Returns the assignment strategy which distributes the ports along the node borders.
double	getPortBorderGapRatio(int side) Returns the port border gap ratio for the port distribution at a given side of the node.
void	setGridReference(YPoint gridReference) Specifies the node's reference point that will be placed on a grid coordinate.
void	setLayerAlignment(double alignment) Specifies the alignment of the node of this NodeLayoutDescriptor instance within its layer.
void	setMinimumDistance(double distance) Specifies the preferred minimum distance to obstacles.
void	setMinimumLayerHeight(double height) Specifies the minimum height of the layer to which this node is assigned.
void	setNodeLabelMode(byte mode) Specifies the mode that determines how node labels are handled by the algorithm during the layout.
void	setPortAssignment(byte portAssignment) Specifies the assignment strategy which distributes the ports along the node borders.
void	setPortBorderGapRatio(int side, double ratio) Specifies the port border gap ratio for the port distribution at a given side of the node.
void	setPortBorderGapRatios(double ratio) Specifies the port border gap ratio for the port distribution on all sides of the node.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PORT_ASSIGNMENT_DEFAULT

public static final byte PORT_ASSIGNMENT_DEFAULT

A port assignment strategy that distributes ports evenly along the border of the node.

This is the default port assignment strategy of IncrementalHierarchicLayouter.

See Also:

setPortAssignment(byte), Constant Field Values

Sample Graph:

PORT_ASSIGNMENT_ON_GRID

public static final byte PORT_ASSIGNMENT_ON_GRID

A port assignment strategy that places all edges on grid lines.

If there are not enough grid lines for each port, ports may overlap. In case there is no grid line available at the side of a node, the ports are placed centered at that side.

This port assignment can only be used if the grid spacing is greater than 0.

See Also:

setPortAssignment(byte), Constant Field Values

Sample Graph:

Grid size 20

PORT_ASSIGNMENT_ON_SUBGRID

public static final byte PORT_ASSIGNMENT_ON_SUBGRID

A port assignment strategy that places all edges on grid lines or sub-grid lines.

If there are not enough grid lines for each port, the grid gets subdivided with sub-grid lines until each edge has space for its port.

This port assignment can only be used if the grid spacing is greater than 0.

See Also:

setPortAssignment(byte), Constant Field Values

Sample Graph:

Major grid size 20 - sub-grid 10

NODE_LABEL_MODE_NEVER

public static final byte NODE_LABEL_MODE_NEVER

A constant that prevents node labels from being considered during the layout.

It is used by getNodeLabelMode() and setNodeLabelMode(byte).

See Also:

setNodeLabelMode(byte), Constant Field Values

NODE_LABEL_MODE_CONSIDER_FOR_SELF_LOOPS

public static final byte NODE_LABEL_MODE_CONSIDER_FOR_SELF_LOOPS

A constant that makes the algorithm consider node labels for self-loops, node placement and routing.

It is used by getNodeLabelMode() and setNodeLabelMode(byte).

See Also:

setNodeLabelMode(byte), Constant Field Values

NODE_LABEL_MODE_CONSIDER_FOR_DRAWING

public static final byte NODE_LABEL_MODE_CONSIDER_FOR_DRAWING

A constant that makes the algorithm consider node labels for node placement and routing, but not for self-loops.

It is used by getNodeLabelMode() and setNodeLabelMode(byte).

See Also:

setNodeLabelMode(byte), Constant Field Values

NODE_LABEL_MODE_CONSIDER_FOR_ROUTING

public static final byte NODE_LABEL_MODE_CONSIDER_FOR_ROUTING

A constant that makes the algorithm consider node labels during routing only.

It is used by getNodeLabelMode() and setNodeLabelMode(byte).

See Also:

setNodeLabelMode(byte), Constant Field Values

Constructor Detail

NodeLayoutDescriptor

public NodeLayoutDescriptor()

Creates a new instance of a NodeLayoutDescriptor with the default values.

Method Detail

setPortBorderGapRatio

public void setPortBorderGapRatio(int side,
                                  double ratio)

Specifies the port border gap ratio for the port distribution at a given side of the node.

This ratio determines the gap between a corner of the node and the first assigned port.

The ratio should be greater than 0.

A value of 0.0d results in ports being placed directly on the corner of the node (if there is more than one port).

A value of 0.5d results in ports being distributed along the side of the node so that the distance between the corner of the node and the first port is half as wide as the distance between two adjacent ports.

A value of Double.POSITIVE_INFINITY results in all ports being centered at the side in one point.

Default Value:

The default value is 0.5d. Ports are distributed along the sides of the node.

Parameters:

side - the zero-based clockwise side index for top-to-bottom layouts (i.e., top is 0)

ratio - the given ratio

Throws:

java.lang.IllegalArgumentException - if the given ratio is negative

See Also:

setPortBorderGapRatios(double)

Sample Graphs:

Port border gap ratio 0.0d - node 1 has port constraint PortConstraint.SOUTH while nodes 2,3,4 have port constraints PortConstraint.NORTH.

Port border gap ratio 0.5d - node 1 has port constraint PortConstraint.SOUTH while nodes 2,3,4 have port constraints PortConstraint.NORTH.

setPortBorderGapRatios

public void setPortBorderGapRatios(double ratio)

Specifies the port border gap ratio for the port distribution on all sides of the node.

This ratio determines the gap between a corner of the node and the first assigned port.

The ratio should be greater than 0.

A value of 0.0d results in ports being placed directly on the corner of the node (if there is more than one port).

A value of 0.5d results in ports being distributed along the side of the node so that the distance between the corner of the node and the first port is half as wide as the distance between two adjacent ports.

A value of Double.POSITIVE_INFINITY results in all ports being centered at the side in one point.

Default Value:

The default value is 0.5d. Ports are distributed along the sides of the node.

Parameters:

ratio - the given ratio

Throws:

java.lang.IllegalArgumentException - if the given ratio is negative

See Also:

setPortBorderGapRatio(int, double)

Sample Graphs:

Port border gap ratio 0.0d - node 1 has port constraint PortConstraint.WEST and PortConstraint.EAST while nodes 2,3,4 have port constraints PortConstraint.SOUTH.

Port border gap ratio 0.5d - node 1 has port constraint PortConstraint.WEST and PortConstraint.EAST while nodes 2,3,4 have port constraints PortConstraint.SOUTH.

Port border gap ratio 0.5d - node 1 has port constraint PortConstraint.WEST and PortConstraint.EAST while nodes 2,3,4 have port constraints PortConstraint.SOUTH.

getPortBorderGapRatio

public double getPortBorderGapRatio(int side)

Returns the port border gap ratio for the port distribution at a given side of the node.

This ratio determines the gap between a corner of the node and the first assigned port.

The ratio should be greater than 0.

A value of 0.0d results in ports being placed directly on the corner of the node (if there is more than one port).

A value of 0.5d results in ports being distributed along the side of the node so that the distance between the corner of the node and the first port is half as wide as the distance between two adjacent ports.

A value of Double.POSITIVE_INFINITY results in all ports being centered at the side in one point.

Parameters:

side - the zero-based clockwise side index for top-to-bottom layouts (i.e., top is 0)

Returns:

the border gap ratio of a given side

See Also:

setPortBorderGapRatios(double), setPortBorderGapRatio(int, double)

setLayerAlignment

public void setLayerAlignment(double alignment)

Specifies the alignment of the node of this NodeLayoutDescriptor instance within its layer.

• A value of 0.0d corresponds to top-alignment.
• A value of 0.5d corresponds to center-alignment.
• A value of 1.0d corresponds to bottom-alignment.

This value should be within [0,1] interval.

Default Value:

The default value is 0.5d. Nodes are center-aligned within their corresponding layers.

Parameters:

alignment - a value from [0,1] interval

Throws:

java.lang.IllegalArgumentException - if the alignment is not within [0.0d .. 1.0d]

Sample Graphs:

Top-alignment (0.0d)

Center-alignment (0.5d)

Bottom-alignment (1.0d)

getLayerAlignment

public double getLayerAlignment()

Returns the alignment of the node of this NodeLayoutDescriptor instance within its layer.

• A value of 0.0d corresponds to top-alignment.
• A value of 0.5d corresponds to center-alignment.
• A value of 1.0d corresponds to bottom-alignment.

This value should be within [0,1] interval.

Default Value:

The default value is 0.5d. Nodes are center-aligned within their corresponding layers.

Returns:

a value from [0,1] interval

See Also:

setLayerAlignment(double)

setNodeLabelMode

public void setNodeLabelMode(byte mode)

Specifies the mode that determines how node labels are handled by the algorithm during the layout.

To enable this feature, information about the layout of the node labels must be provided. If IncrementalHierarchicLayouter is used for the layout, method IncrementalHierarchicLayouter.setConsiderNodeLabelsEnabled(boolean) should be set to true. Otherwise, one has to assure that e.g., via an instance of LabelLayoutTranslator, the algorithm receives the appropriate information.

Default Value:

The default value is NODE_LABEL_MODE_CONSIDER_FOR_DRAWING. Node labels will be considered for node placement and routing, but not for self-loops.

Parameters:

mode - one of the predefined constants

Throws:

java.lang.IllegalArgumentException - if the constant is unknown.

See Also:

IncrementalHierarchicLayouter.setConsiderNodeLabelsEnabled(boolean)

getNodeLabelMode

public byte getNodeLabelMode()

Returns the mode that determines how node labels are handled by the algorithm during the layout.

To enable this feature, information about the layout of the node labels must be provided. If IncrementalHierarchicLayouter is used for the layout, method IncrementalHierarchicLayouter.setConsiderNodeLabelsEnabled(boolean) should be set to true. Otherwise, one has to assure that e.g., via an instance of LabelLayoutTranslator, the algorithm receives the appropriate information.

Returns:

one of the predefined constants

See Also:

IncrementalHierarchicLayouter.setConsiderNodeLabelsEnabled(boolean), setNodeLabelMode(byte)

setMinimumLayerHeight

public void setMinimumLayerHeight(double height)

Specifies the minimum height of the layer to which this node is assigned.

Values should be equal or greater than 0.

This feature is especially useful if it is combined with different layer alignments.

Default Value:

The default value is 0.0d.

Parameters:

height - a non-negative minimum height

Throws:

java.lang.IllegalArgumentException - if the minimum height is negative

Sample Graphs:

@y.figure Minimum layer height 0.0d (the bottom center node has layer alignment 1.0, all other nodes layer alignment 0.0)

@y.figure Minimum layer height 50.0d (the bottom center node has layer alignment 1.0, all other nodes layer alignment 0.0)

getMinimumLayerHeight

public double getMinimumLayerHeight()

Returns the minimum height of the layer to which this node is assigned.

Values should be equal or greater than 0.

This feature is especially useful if it is combined with different layer alignments.

Returns:

a non-negative minimum height

See Also:

setMinimumLayerHeight(double)

setMinimumDistance

public void setMinimumDistance(double distance)

Specifies the preferred minimum distance to obstacles.

Currently, this distance only affects the following scenarios:

• Distance between group nodes and other elements (horizontally and vertically).
• The distance of normal nodes and group node to borders of a partition grid cell or swimlane.
• The segment length of self-loops associated with this node.

The minimum distance should be greater than 0.

This setting does not affect the distance between normal nodes or between an edge and a normal node. These distances can be globally specified using IncrementalHierarchicLayouter.setNodeToNodeDistance(double) and IncrementalHierarchicLayouter.setNodeToEdgeDistance(double), respectively. If individual spacings around nodes are required, NodeHalos can be defined.

Default Value:

The default value is 5.0d.

Parameters:

distance - the minimum distance to obstacles

Throws:

java.lang.IllegalArgumentException - if the minimum length is negative

Sample Graphs:

Minimum distance 5.0

Minimum distance 50.0

getMinimumDistance

public double getMinimumDistance()

Returns the preferred minimum distance to obstacles.

Currently, this distance only affects the following scenarios:

• Distance between group nodes and other elements (horizontally and vertically).
• The distance of normal nodes and group node to borders of a partition grid cell or swimlane.
• The segment length of self-loops associated with this node.

The minimum distance should be greater than 0.

This setting does not affect the distance between normal nodes or between an edge and a normal node. These distances can be globally specified using IncrementalHierarchicLayouter.setNodeToNodeDistance(double) and IncrementalHierarchicLayouter.setNodeToEdgeDistance(double), respectively. If individual spacings around nodes are required, NodeHalos can be defined.

Returns:

the minimum distance to obstacles

See Also:

setMinimumDistance(double)

getGridReference

public YPoint getGridReference()

Returns the node's reference point that will be placed on a grid coordinate.

The reference point is specified as offset to the center of the node. Hence, if for example the upper left corner of the node should be placed on a grid coordinate, you have to use -width/2 as x-offset and -height/2 as y-offset.

The grid reference point will only be considered if there actually is a grid.

Returns:

the reference point for grid placement

setGridReference

public void setGridReference(YPoint gridReference)

Specifies the node's reference point that will be placed on a grid coordinate.

The reference point is specified as offset to the center of the node. Hence, if for example the upper left corner of the node should be placed on a grid coordinate, you have to use -width/2 as x-offset and -height/2 as y-offset.

The grid reference point will only be considered if there actually is a grid.

Default Value:

The default value is YPoint.ORIGIN. The reference point is YPoint.ORIGIN and the center of the node is placed on the grid.

Parameters:

gridReference - the reference point for grid placement

Throws:

java.lang.IllegalArgumentException - if the given grid reference is null

getPortAssignment

public byte getPortAssignment()

Returns the assignment strategy which distributes the ports along the node borders.

Port assignments PORT_ASSIGNMENT_DEFAULT, PORT_ASSIGNMENT_ON_GRID and PORT_ASSIGNMENT_ON_SUBGRID are currently only supported in DefaultPortAllocator. A custom implementation of PortAllocator will have to handle these assignments itself or will replace them with its own behavior.

Returns:

one of the predefined port assignment strategies

See Also:

setPortAssignment(byte)

setPortAssignment

public void setPortAssignment(byte portAssignment)

Specifies the assignment strategy which distributes the ports along the node borders.

Port assignments PORT_ASSIGNMENT_DEFAULT, PORT_ASSIGNMENT_ON_GRID and PORT_ASSIGNMENT_ON_SUBGRID are currently only supported in DefaultPortAllocator. A custom implementation of PortAllocator will have to handle these assignments itself or will replace them with its own behavior.

Default Value:

The default value is PORT_ASSIGNMENT_DEFAULT. Ports are distributed evenly along the border of the node.

Parameters:

portAssignment - one of the predefined port assignment strategies