y.layout.hierarchic.incremental
Class HierarchicLayouter

java.lang.Object
  y.layout.CanonicMultiStageLayouter
      y.layout.hierarchic.incremental.HierarchicLayouter

All Implemented Interfaces:

Layouter

public class HierarchicLayouter
extends CanonicMultiStageLayouter

This class arranges graphs in a hierarchic/layered fashion and supports complete re-layout as well as incremental graph layout.

Note that class IncrementalHierarchicLayouter offers a facade to this class which is easier to use. Hence, we strongly recommend to not directly use class HierarchicLayouter.

Layout Style

The nodes are distributed into layers such that most of the edges point to the main layout direction. The order of the nodes within the layers ensures that the number of edge crossings is as small as possible. There are different edge routing styles available. Edges can be orthogonal, polyline or octilinear.

Hierarchical diagrams are commonly used for the visualization of hierarchical data, since they facilitate the identification of dependencies and relationships among the nodes of the graph. Possible application domains are the following: workflow visualization, call graph visualization, entity-relationship diagrams, biochemical pathways and network management.

Hierarchic Layout obtained with default settings

Concept

The layout algorithm runs in three main phases:

Layering

The nodes are distributed into layers by means of getLayerer(). If the layout orientation is top-to-bottom, the nodes in each layer are arranged horizontally while the layers are ordered vertically top-to-bottom.

Sequencing

The order of the nodes in each layer is determined such that the number of edge crossings is as small as possible. To specify the sequencing algorithm, use setSequencer(Sequencer).

Drawing

The layout algorithm assigns the final coordinates to all nodes and routes the edges.

Features

In order to customize this layout algorithm, modify the Layerer, Sequencer, PortAllocator, DrawingDistanceCalculator, and NodePlacer instances.

This layout algorithm is able to incrementally add new elements to an existing drawing of a graph. In order to add elements incrementally, register a DataProvider with the graph using the INCREMENTAL_HINTS_DPKEY DataProvider key and associate the hints obtained from the IncrementalHintsFactory with the elements to be added incrementally.

NodeLayoutDescriptor and EdgeLayoutDescriptor instances can be used for specifying individual information (e.g. distances or routing styles) for each node and edge in the graph. The descriptors are bound to the graph using DataProviders registered with NODE_LAYOUT_DESCRIPTOR_DPKEY or EDGE_LAYOUT_DESCRIPTOR_DPKEY.

HierarchicLayouter supports two approaches to connect edges on a specific side or even an exact location to a node. PortConstraints define a single constraint for the ports of an edge. To realize more complex port restrictions, several PortCandidates or PortCandidateSets can be assigned to edges or nodes. If an edge with registered PortCandidates connects to nodes with PortCandidateSets, the layouter will try to match both collections to find an appropriate port. In case there is no matching port candidate, a PortCandidate specified for the edge is preferred. Since their simultaneous existence at the same node may be ambiguous, it is not recommended to use a combination of PortConstraints and PortCandidates in the same layout.

This algorithm specifies a LabelLayoutTranslator instance as the current CanonicMultiStageLayouter.getLabelLayouter() and configures it such that the node labels are passed to it by setting LabelLayoutTranslator.setTranslateNodeLabelsEnabled(boolean) to true.

In order to enable integrated edge labeling of this algorithm, make sure LabelLayoutTranslator is registered and edge labels are being translated and written back after the layout.

Moreover, this algorithm supports layer and sequence constraints. These constraints can be specified using a LayerConstraintFactory and SequenceConstraintFactory, respectively.

See Also:

IncrementalHierarchicLayouter, Layerer, Sequencer, PortAllocator, DrawingDistanceCalculator, NodePlacer

Nested Class Summary

static class

HierarchicLayouter.IncrementalHint This class describes hint objects used internally by HierarchicLayouter.

Field Summary

static java.lang.Object	EDGE_LAYOUT_DESCRIPTOR_DPKEY A DataProvider key for providing layout information for each edge
static java.lang.Object	INCREMENTAL_HINTS_DPKEY A DataProvider key for specifying incremental hints Incremental hints are created using an incremental hints factory.
static java.lang.Object	INCREMENTAL_NODES_DPKEY A DataProvider key for internal use only.
static java.lang.Object	LAYER_VALUE_HOLDER_DPKEY A DataAcceptor key for publishing the layer IDs for all nodes in the graph.
static java.lang.Object	NODE_LAYOUT_DESCRIPTOR_DPKEY A DataProvider key for providing layout information for each node
static java.lang.Object	SEQUENCE_VALUE_HOLDER_DPKEY A DataAcceptor key for publishing the index inside their layer for all nodes in the graph.
static java.lang.Object	SWIMLANE_DESCRIPTOR_DPKEY A DataProvider key for providing information about swimlanes If this key is present during the layout, the layout algorithm will arrange nodes in swimlanes.

Fields inherited from interface y.layout.Layouter

EDGE_ID_DPKEY, NODE_ID_DPKEY, NODE_TYPE_DPKEY, SELECTED_EDGES, SELECTED_NODES

Constructor Summary

HierarchicLayouter()
Creates a new HierarchicLayouter instance with the default settings.

Method Summary

boolean	canLayoutCore(LayoutGraph graph) Accepts general graphs without exceptions.
protected DrawingDistanceCalculator	createDrawingDistanceCalculator() Factory method that is called lazily upon first usage by getDrawingDistanceCalculator() if the given DrawingDistanceCalculator instance is null.
protected EdgeReverser	createEdgeReverser() Factory method called during doLayoutCore(LayoutGraph) and reates an appropriate EdgeReverser implementation.
protected Grouping	createGrouping(LayoutGraph graph) Factory method that is called during doLayoutCore(LayoutGraph) and creates a Grouping instance in case of a grouped graph.
IncrementalHintsFactory	createIncrementalHintsFactory() Creates an IncrementalHintsFactory implementation used for obtaining hint objects associated with nodes and edges of the graph prior to the invocation of the layout algorithm.
protected Layerer	createIncrementalLayerer() Factory method called during doLayoutCore(LayoutGraph) and creates an appropriate Layerer implementation.
protected void	createItemData(LayoutGraph g, ItemFactory itemFactory) Callback method that is called during doLayoutCore(LayoutGraph), creates the NodeData and EdgeData instances and binds them to the elements using the given itemFactory.
protected LayoutStage	createLabelLayouter() Factory method called during the initialization of this HierarchicLayouter instance that creates a label layouter.
LayerConstraintFactory	createLayerConstraintFactory(Graph graph) Creates a layer constraint factory that allows to create hints that affect the assignment of the nodes to layers.
protected Layerer	createLayerer() Factory method that is called lazily upon first usage by getLayerer() if no Layerer instance is given as input.
protected Layers	createLayers(LayoutDataProvider ldp) Factory method called during doLayoutCore(LayoutGraph) and creates an appropriate Layers implementation using the given LayoutDataProvider instance.
protected NodePlacer	createNodePlacer() Factory method that is called lazily upon first usage by getNodePlacer() if the given NodePlacer instance is null.
protected PortAllocator	createPortAllocator() Factory method that is called lazily upon first usage by getPortAllocator() if the given PortAllocator instance is null.
protected PortConstraintOptimizer	createPortConstraintOptimizer() Factory method that is called lazily upon first usage by getPortConstraintOptimizer() if the given PortConstraintOptimizer instance is null.
SequenceConstraintFactory	createSequenceConstraintFactory(Graph graph) Creates sequence constraints that affect the sequence of the nodes within each layer.
protected Sequencer	createSequencer() Factory method that is called lazily upon first usage by getSequencer() if the given Sequencer instance is null.
protected Sequencer	createSubgraphLayerSequencer() Factory method called during doLayoutCore(LayoutGraph) and creates a Sequencer implementation that can sequence subgraphs incrementally.
void	doLayoutCore(LayoutGraph graph) Calculates a hierarchic layout of the given graph.
java.lang.Object	getAlgorithmProperty(java.lang.Object key) Provides access to implementation specific properties of the algorithms used.
DrawingDistanceCalculator	getDrawingDistanceCalculator() Returns the DrawingDistanceCalculator instance responsible for determining the minimum distances between elements that belong to the same layer.
protected DataProvider	getEdgeLayoutDescriptors(LayoutGraph graph) Callback method called during doLayoutCore(LayoutGraph) and returns a DataProvider that holds the EdgeLayoutDescriptor information.
double	getGridSpacing() Returns the equidistant spacing between the horizontal and vertical grid lines.
protected DataProvider	getIncrementalHints(LayoutGraph graph) Callback method called during doLayoutCore(LayoutGraph) and returns a DataProvider that holds the HierarchicLayouter.IncrementalHints information.
Layerer	getLayerer() Returns the Layerer instance responsible for generating the layer assignment (first phase of the layout algorithm).
long	getMaximalDuration() Returns the time limit (in milliseconds) set for the layout algorithm.
protected DataProvider	getNodeLayoutDescriptors(LayoutGraph graph) Callback method called during doLayoutCore(LayoutGraph) and returns a DataProvider that holds the NodeLayoutDescriptor information.
NodePlacer	getNodePlacer() Returns the NodePlacer instance responsible for the assignment of the x-(sequence) and preliminary y-coordinates of the nodes.
PortAllocator	getPortAllocator() Returns the PortAllocator instance responsible for assigning port coordinates to the adjacent edges of each node.
PortConstraintOptimizer	getPortConstraintOptimizer() Returns the PortConstraintOptimizer instance responsible for optimizing the assignment of port constraints to the adjacent edges of each node.
Sequencer	getSequencer() Returns the Sequencer instance responsible for calculating the sequence of nodes within each layer (second phase of the layout algorithm).
protected DataProvider	getSwimLaneDescriptors(LayoutGraph graph) Callback method called during doLayoutCore(LayoutGraph) and returns a DataProvider that holds the SwimLaneDescriptor information.
boolean	isComponentLayouterEnabled() Returns whether or not the ComponentLayouter should be enabled.
protected void	publishLayers(LayoutGraph graph, Layers layers) Callback method that publishes the layering information.
protected void	publishSequences(LayoutGraph graph, Layers layers, LayoutDataProvider ldp) Callback method that publishes the sequencing information.
protected void	reduceBendCount(LayoutGraph graph) Removes the bends which are obviously not necessary.
protected void	reduceBendCount(LayoutGraph graph, double bendReductionThreshold) Removes the bends which are obviously not necessary.
void	setAlgorithmProperty(java.lang.Object key, java.lang.Object propertyValue) Provides access to implementation specific properties of the algorithms used.
void	setComponentLayouterEnabled(boolean enabled) Specifies whether or not the ComponentLayouter should be enabled.
void	setDrawingDistanceCalculator(DrawingDistanceCalculator drawingDistanceCalculator) Specifies the DrawingDistanceCalculator instance responsible for determining the minimum distances between elements that belong to the same layer.
void	setGridSpacing(double gridSpacing) Specifies the equidistant spacing between the horizontal and vertical grid lines.
void	setLayerer(Layerer layerer) Specifies the Layerer instance responsible for generating the layer assignment (first phase of the layout algorithm).
void	setMaximalDuration(long maximalDuration) Specifies the time limit (in milliseconds) set for the layout algorithm.
void	setNodePlacer(NodePlacer placer) Specifies the NodePlacer instance responsible for the assignment of the x-(sequence) and preliminary y-coordinates of the nodes.
void	setPortAllocator(PortAllocator allocator) Specifies the PortAllocator instance responsible for assigning port coordinates to the adjacent edges of each node.
void	setPortConstraintOptimizer(PortConstraintOptimizer optimizer) Specifies the PortConstraintOptimizer instance responsible for optimizing the assignment of port constraints to the adjacent edges of each node.
void	setSequencer(Sequencer sequencer) Specifies the Sequencer instance responsible for calculating the sequence of nodes within each layer (second phase of the layout algorithm).

Methods inherited from class y.layout.CanonicMultiStageLayouter

appendStage, calcLayout, calcLayout, canLayout, checkGroupNodeSize, checkNodeSize, doLayout, doLayout, enableOnlyCore, getComponentLayouter, getGroupNodeHider, getLabelLayouter, getLayoutOrientation, getOrientationLayouter, getParallelEdgeLayouter, getSelfLoopLayouter, getSubgraphLayouter, isGroupNodeHidingEnabled, isLabelLayouterEnabled, isOrientationLayouterEnabled, isParallelEdgeLayouterEnabled, isSelfLoopLayouterEnabled, isSubgraphLayouterEnabled, prependStage, removeStage, setComponentLayouter, setGroupNodeHider, setGroupNodeHidingEnabled, setLabelLayouter, setLabelLayouterEnabled, setLayoutOrientation, setOrientationLayouter, setOrientationLayouterEnabled, setParallelEdgeLayouter, setParallelEdgeLayouterEnabled, setSelfLoopLayouter, setSelfLoopLayouterEnabled, setSubgraphLayouter, setSubgraphLayouterEnabled

Methods inherited from class java.lang.Object

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

Field Detail

INCREMENTAL_HINTS_DPKEY

public static final java.lang.Object INCREMENTAL_HINTS_DPKEY

A DataProvider key for specifying incremental hints

Incremental hints are created using an incremental hints factory.

See Also:

INCREMENTAL_HINTS_DPKEY, IncrementalHintsFactory

EDGE_LAYOUT_DESCRIPTOR_DPKEY

public static final java.lang.Object EDGE_LAYOUT_DESCRIPTOR_DPKEY

A DataProvider key for providing layout information for each edge

See Also:

EdgeData.getEdgeLayoutDescriptor()

NODE_LAYOUT_DESCRIPTOR_DPKEY

public static final java.lang.Object NODE_LAYOUT_DESCRIPTOR_DPKEY

A DataProvider key for providing layout information for each node

See Also:

NodeData.getNodeLayoutDescriptor()

SWIMLANE_DESCRIPTOR_DPKEY

public static final java.lang.Object SWIMLANE_DESCRIPTOR_DPKEY

A DataProvider key for providing information about swimlanes

If this key is present during the layout, the layout algorithm will arrange nodes in swimlanes. The information about the swimlanes is finally written back to the descriptor instances.

Instances can be shared among multiple nodes in the same lane, but don't have to be shared.

See Also:

SwimLaneDescriptor, NodeData.getSwimLaneDescriptor()

LAYER_VALUE_HOLDER_DPKEY

public static final java.lang.Object LAYER_VALUE_HOLDER_DPKEY

A DataAcceptor key for publishing the layer IDs for all nodes in the graph.

For each non-group node, the index of the node's layer will be stored in this DataAcceptor after the layout run.

Instead of a DataAcceptor also a DataProvider storing values of type IntValueHolder can be registered. Then the IntValueHolder instance gets filled with the layer information of the corresponding nodes.

If no DataProvider is registered with this key, the layer information of the nodes is dropped.

See Also:

IncrementalHierarchicLayouter.LAYER_VALUE_HOLDER_DPKEY

SEQUENCE_VALUE_HOLDER_DPKEY

public static final java.lang.Object SEQUENCE_VALUE_HOLDER_DPKEY

A DataAcceptor key for publishing the index inside their layer for all nodes in the graph.

For each non-group node, the index (position) of the node within its layer will be stored in this DataAcceptor after the layout run.

Instead of a DataAcceptor also a DataProvider storing values of type IntValueHolder can be registered. Then the IntValueHolder instance gets filled with the sequence information of the corresponding nodes.

If no DataProvider is registered with this key, the sequence information of the nodes is dropped.

See Also:

IncrementalHierarchicLayouter.SEQUENCE_VALUE_HOLDER_DPKEY

INCREMENTAL_NODES_DPKEY

public static final java.lang.Object INCREMENTAL_NODES_DPKEY

A DataProvider key for internal use only.

Constructor Detail

HierarchicLayouter

public HierarchicLayouter()

Creates a new HierarchicLayouter instance with the default settings.

See Also:

createLayerer(), createIncrementalLayerer(), createSequencer(), createDrawingDistanceCalculator(), createNodePlacer()

Method Detail

createLabelLayouter

protected LayoutStage createLabelLayouter()

Factory method called during the initialization of this HierarchicLayouter instance that creates a label layouter.

In order to use the integrated node label awareness feature one has to use a LabelLayoutTranslator instance and set LabelLayoutTranslator.setTranslateNodeLabelsEnabled(boolean) to true. Likewise, in order to make use of the integrated edge labeling LabelLayoutTranslator.setTranslateEdgeLabelsEnabled(boolean) must be set to true and also LabelLayoutTranslator.setWriteBackEdgeLabelsEnabled(boolean) must be set to true (which is the default).

Returns:

a new LabelLayoutTranslator instance

createLayerer

protected Layerer createLayerer()

Factory method that is called lazily upon first usage by getLayerer() if no Layerer instance is given as input.

The default implementation returns a new MultiComponentLayerer(new WeightedLayerer()) instance. It may be overridden to return a custom Layerer instance.

Returns:

a Layerer instance

See Also:

getLayerer(), MultiComponentLayerer, OldLayererWrapper, WeightedLayerer

setComponentLayouterEnabled

public void setComponentLayouterEnabled(boolean enabled)

Specifies whether or not the ComponentLayouter should be enabled.

Overrides:

setComponentLayouterEnabled in class CanonicMultiStageLayouter

Default Value:

The default value is false. ComponentLayouter is disabled.

Parameters:

enabled - true if ComponentLayouter should be enabled, false otherwise

See Also:

CanonicMultiStageLayouter.isComponentLayouterEnabled(), CanonicMultiStageLayouter.setComponentLayouter(LayoutStage), ComponentLayouter

isComponentLayouterEnabled

public boolean isComponentLayouterEnabled()

Returns whether or not the ComponentLayouter should be enabled.

Overrides:

isComponentLayouterEnabled in class CanonicMultiStageLayouter

Returns:

true if ComponentLayouter is enabled, false otherwise

See Also:

setComponentLayouterEnabled(boolean)

getMaximalDuration

public long getMaximalDuration()

Returns the time limit (in milliseconds) set for the layout algorithm.

Values have to be greater than or equal to 0.

Restricting the maximum duration may result in a lower layout quality. Furthermore, the real runtime may exceed the maximum duration since the layout algorithm still has to find a valid solution.

Returns:

a non-negative value that specifies the time limit

See Also:

setMaximalDuration(long)

setMaximalDuration

public void setMaximalDuration(long maximalDuration)

Specifies the time limit (in milliseconds) set for the layout algorithm.

Values have to be greater than or equal to 0.

Restricting the maximum duration may result in a lower layout quality. Furthermore, the real runtime may exceed the maximum duration since the layout algorithm still has to find a valid solution.

Default Value:

The default value is Long.MAX_VALUE. The layout algorithm runs unrestricted.

Parameters:

maximalDuration - a non-negative value that specifies the time limit

Throws:

java.lang.IllegalArgumentException - if the maximum duration is negative

See Also:

getMaximalDuration()

createSequencer

protected Sequencer createSequencer()

Factory method that is called lazily upon first usage by getSequencer() if the given Sequencer instance is null.

The default implementation returns a DefaultLayerSequencer instance. It may be overridden to return a custom Sequencer instance.

Returns:

a Sequencer instance

See Also:

getSequencer(), DefaultLayerSequencer

createDrawingDistanceCalculator

protected DrawingDistanceCalculator createDrawingDistanceCalculator()

Factory method that is called lazily upon first usage by getDrawingDistanceCalculator() if the given DrawingDistanceCalculator instance is null.

The default implementation returns a DefaultDrawingDistanceCalculator instance. It may be overridden to return a custom DefaultDrawingDistanceCalculator instance.

Creating a custom implementation of DrawingDistanceCalculator will make the properties IncrementalHierarchicLayouter.setNodeToNodeDistance(double), IncrementalHierarchicLayouter.setNodeToEdgeDistance(double) and IncrementalHierarchicLayouter.setEdgeToEdgeDistance(double) superfluous. Those properties delegate to DefaultDrawingDistanceCalculator and will throw an IllegalStateException if a different class is used. Adjustments of those distances need to be done directly on the custom implementation of DrawingDistanceCalculator.

Returns:

a DrawingDistanceCalculator instance

See Also:

getDrawingDistanceCalculator()

createPortAllocator

protected PortAllocator createPortAllocator()

Factory method that is called lazily upon first usage by getPortAllocator() if the given PortAllocator instance is null.

The default implementation returns a DefaultPortAllocator instance. It may be overridden to return a custom PortAllocator instance.

Returns:

a PortAllocator instance

See Also:

getPortAllocator()

createPortConstraintOptimizer

protected PortConstraintOptimizer createPortConstraintOptimizer()

Factory method that is called lazily upon first usage by getPortConstraintOptimizer() if the given PortConstraintOptimizer instance is null.

The default implementation returns null. It may be overridden to return a custom PortConstraintOptimizer instance.

Returns:

null

See Also:

getPortConstraintOptimizer()

createNodePlacer

protected NodePlacer createNodePlacer()

Factory method that is called lazily upon first usage by getNodePlacer() if the given NodePlacer instance is null.

The default implementation returns a SimplexNodePlacer instance. It may be overridden to return a custom NodePlacer instance.

Returns:

a NodePlacer instance

See Also:

getNodePlacer(), SimplexNodePlacer

setLayerer

public void setLayerer(Layerer layerer)

Specifies the Layerer instance responsible for generating the layer assignment (first phase of the layout algorithm).

To set the default layerer, see createLayerer().

Parameters:

layerer - the given Layerer instance

Throws:

java.lang.IllegalArgumentException - if the specified Layerer is null

See Also:

createLayerer()

getLayerer

public Layerer getLayerer()

Returns the Layerer instance responsible for generating the layer assignment (first phase of the layout algorithm).

To set the default layerer, see createLayerer().

Returns:

the current Layerer instance

See Also:

setLayerer(Layerer), createLayerer()

setSequencer

public void setSequencer(Sequencer sequencer)

Specifies the Sequencer instance responsible for calculating the sequence of nodes within each layer (second phase of the layout algorithm).

To set the default sequencer, see createSequencer().

Parameters:

sequencer - the given Sequencer instance

Throws:

java.lang.IllegalArgumentException - if the specified Sequencer is null

See Also:

createSequencer()

getSequencer

public Sequencer getSequencer()

Returns the Sequencer instance responsible for calculating the sequence of nodes within each layer (second phase of the layout algorithm).

To set the default sequencer, see createSequencer().

Returns:

the current Sequencer instance

See Also:

createSequencer(), setSequencer(Sequencer)

setNodePlacer

public void setNodePlacer(NodePlacer placer)

Specifies the NodePlacer instance responsible for the assignment of the x-(sequence) and preliminary y-coordinates of the nodes.

To set the default node placer, see createNodePlacer().

Parameters:

placer - the given NodePlacer instance

Throws:

java.lang.IllegalArgumentException - if the specified NodePlacer is null

See Also:

createNodePlacer()

getNodePlacer

public NodePlacer getNodePlacer()

Returns the NodePlacer instance responsible for the assignment of the x-(sequence) and preliminary y-coordinates of the nodes.

To set the default node placer, see createNodePlacer().

Returns:

the current NodePlacer instance

See Also:

setNodePlacer(NodePlacer), createNodePlacer()

setPortAllocator

public void setPortAllocator(PortAllocator allocator)

Specifies the PortAllocator instance responsible for assigning port coordinates to the adjacent edges of each node.

To set the default port allocator, see createPortAllocator().

Parameters:

allocator - the given PortAllocator instance

Throws:

java.lang.IllegalArgumentException - if the specified PortAllocator is null

See Also:

createPortAllocator()

getPortAllocator

public PortAllocator getPortAllocator()

Returns the PortAllocator instance responsible for assigning port coordinates to the adjacent edges of each node.

To set the default port allocator, see createPortAllocator().

Returns:

the current PortAllocator instance

See Also:

setPortAllocator(PortAllocator), createPortAllocator()

setPortConstraintOptimizer

public void setPortConstraintOptimizer(PortConstraintOptimizer optimizer)

Specifies the PortConstraintOptimizer instance responsible for optimizing the assignment of port constraints to the adjacent edges of each node.

To set the default port allocator, see createPortConstraintOptimizer().

Parameters:

optimizer - the given PortConstraintOptimizer instance

See Also:

createPortConstraintOptimizer()

getPortConstraintOptimizer

public PortConstraintOptimizer getPortConstraintOptimizer()

Returns the PortConstraintOptimizer instance responsible for optimizing the assignment of port constraints to the adjacent edges of each node.

To set the default port allocator, see createPortConstraintOptimizer().

Returns:

the current PortConstraintOptimizer instance

See Also:

setPortConstraintOptimizer(PortConstraintOptimizer), createPortConstraintOptimizer()

setDrawingDistanceCalculator

public void setDrawingDistanceCalculator(DrawingDistanceCalculator drawingDistanceCalculator)

Specifies the DrawingDistanceCalculator instance responsible for determining the minimum distances between elements that belong to the same layer.

To set the default port allocator, see createDrawingDistanceCalculator().

Specifying a custom implementation of DrawingDistanceCalculator will make the properties IncrementalHierarchicLayouter.setNodeToNodeDistance(double), IncrementalHierarchicLayouter.setNodeToEdgeDistance(double) and IncrementalHierarchicLayouter.setEdgeToEdgeDistance(double) superfluous. Those properties delegate to DefaultDrawingDistanceCalculator and will throw an IllegalStateException if a different class is used. Adjustments of those distances need to be done directly on the custom implementation of DrawingDistanceCalculator.

Parameters:

drawingDistanceCalculator - the given DrawingDistanceCalculator instance

Throws:

java.lang.IllegalArgumentException - if the specified DrawingDistanceCalculator is null

See Also:

createDrawingDistanceCalculator()

getDrawingDistanceCalculator

public DrawingDistanceCalculator getDrawingDistanceCalculator()

Returns the DrawingDistanceCalculator instance responsible for determining the minimum distances between elements that belong to the same layer.

To set the default port allocator, see createDrawingDistanceCalculator().

Specifying a custom implementation of DrawingDistanceCalculator will make the properties IncrementalHierarchicLayouter.setNodeToNodeDistance(double), IncrementalHierarchicLayouter.setNodeToEdgeDistance(double) and IncrementalHierarchicLayouter.setEdgeToEdgeDistance(double) superfluous. Those properties delegate to DefaultDrawingDistanceCalculator and will throw an IllegalStateException if a different class is used. Adjustments of those distances need to be done directly on the custom implementation of DrawingDistanceCalculator.

Returns:

the given DrawingDistanceCalculator instance

See Also:

createDrawingDistanceCalculator(), setDrawingDistanceCalculator(DrawingDistanceCalculator)

getGridSpacing

public double getGridSpacing()

Returns the equidistant spacing between the horizontal and vertical grid lines.

When the spacing is negative or zero, no grid is defined, otherwise nodes and edges are placed on multiples of the grid spacing.

The grid feature doesn't work together with exact (layer/sequence) coordinate hints.

Returns:

the grid spacing

See Also:

setGridSpacing(double), IncrementalHintsFactory

setGridSpacing

public void setGridSpacing(double gridSpacing)

Specifies the equidistant spacing between the horizontal and vertical grid lines.

When the spacing is negative or zero, no grid is defined, otherwise nodes and edges are placed on multiples of the grid spacing.

The grid feature doesn't work together with exact (layer/sequence) coordinate hints.

Default Value:

The default value is 0. There is no grid specified.

Parameters:

gridSpacing - the grid spacing

See Also:

getGridSpacing(), IncrementalHintsFactory

Sample Graphs:

No grid

Grid spacing 20

canLayoutCore

public boolean canLayoutCore(LayoutGraph graph)

Accepts general graphs without exceptions.

Specified by:

canLayoutCore in class CanonicMultiStageLayouter

Parameters:

graph - the input graph

Returns:

true for all input graphs

getAlgorithmProperty

public java.lang.Object getAlgorithmProperty(java.lang.Object key)

Provides access to implementation specific properties of the algorithms used. Used for internal purposes.

Parameters:

key - the key to a property

Returns:

the associated property value or null

See Also:

setAlgorithmProperty(Object,Object)

setAlgorithmProperty

public void setAlgorithmProperty(java.lang.Object key,
                                 java.lang.Object propertyValue)

Provides access to implementation specific properties of the algorithms used. Used for internal purposes.

Parameters:

key - the key to a property

propertyValue - the value to associate with the key

See Also:

setAlgorithmProperty(Object,Object)

doLayoutCore

public void doLayoutCore(LayoutGraph graph)

Calculates a hierarchic layout of the given graph.

Specified by:

doLayoutCore in class CanonicMultiStageLayouter

The given graph will not be copied during the layout process and the layout will be immediately applied to the given graph.

Parameters:

graph - the input graph

createGrouping

protected Grouping createGrouping(LayoutGraph graph)

Factory method that is called during doLayoutCore(LayoutGraph) and creates a Grouping instance in case of a grouped graph.

Parameters:

graph - the input graph

Returns:

a Grouping instance or null if the graph is not grouped

getIncrementalHints

protected DataProvider getIncrementalHints(LayoutGraph graph)

Callback method called during doLayoutCore(LayoutGraph) and returns a DataProvider that holds the HierarchicLayouter.IncrementalHints information.

The DataProvider holding the information about HierarchicLayouter.IncrementalHints is registered with the graph using key INCREMENTAL_HINTS_DPKEY.

Parameters:

graph - the input graph

Returns:

a DataProvider instance or null

See Also:

INCREMENTAL_HINTS_DPKEY

getEdgeLayoutDescriptors

protected DataProvider getEdgeLayoutDescriptors(LayoutGraph graph)

Callback method called during doLayoutCore(LayoutGraph) and returns a DataProvider that holds the EdgeLayoutDescriptor information.

The DataProvider holding the information about the node layout is registered with the graph using key EDGE_LAYOUT_DESCRIPTOR_DPKEY.

Parameters:

graph - the input graph

Returns:

a DataProvider instance or null

See Also:

EdgeLayoutDescriptor, EDGE_LAYOUT_DESCRIPTOR_DPKEY

getNodeLayoutDescriptors

protected DataProvider getNodeLayoutDescriptors(LayoutGraph graph)

Callback method called during doLayoutCore(LayoutGraph) and returns a DataProvider that holds the NodeLayoutDescriptor information.

The DataProvider holding the information about the node layout is registered with the graph using key NODE_LAYOUT_DESCRIPTOR_DPKEY.

Parameters:

graph - the input graph

Returns:

a DataProvider instance or null

See Also:

NodeLayoutDescriptor, NODE_LAYOUT_DESCRIPTOR_DPKEY

getSwimLaneDescriptors

protected DataProvider getSwimLaneDescriptors(LayoutGraph graph)

Callback method called during doLayoutCore(LayoutGraph) and returns a DataProvider that holds the SwimLaneDescriptor information.

The DataProvider holding the information about swimlanes is registered with the graph using key SWIMLANE_DESCRIPTOR_DPKEY.

Parameters:

graph - the input graph

Returns:

a DataProvider instance or null

See Also:

SwimLaneDescriptor, SWIMLANE_DESCRIPTOR_DPKEY

createItemData

protected void createItemData(LayoutGraph g,
                              ItemFactory itemFactory)

Callback method that is called during doLayoutCore(LayoutGraph), creates the NodeData and EdgeData instances and binds them to the elements using the given itemFactory.

Parameters:

g - the input graph

itemFactory - the given ItemFactory instance

createSubgraphLayerSequencer

protected Sequencer createSubgraphLayerSequencer()

Factory method called during doLayoutCore(LayoutGraph) and creates a Sequencer implementation that can sequence subgraphs incrementally.

By default, a suitable private implementation of Sequencer is returned. It may be overridden to return custom implementations of the Sequencer interface.

Returns:

a Sequencer implementation

createLayers

protected Layers createLayers(LayoutDataProvider ldp)

Factory method called during doLayoutCore(LayoutGraph) and creates an appropriate Layers implementation using the given LayoutDataProvider instance.

By default, a suitable private implementation of Layers is returned. It may be overridden to return custom implementations of the Layers interface.

Parameters:

ldp - the given LayoutDataProvider instance

Returns:

a Layers implementation

createIncrementalLayerer

protected Layerer createIncrementalLayerer()

Factory method called during doLayoutCore(LayoutGraph) and creates an appropriate Layerer implementation.

By default, a ConstraintIncrementalLayerer instance with a TopologicalLayerer instance as argument is returned. This method may be overridden to return a custom Layerer implementation.

Returns:

a Layerer implementation

createEdgeReverser

protected EdgeReverser createEdgeReverser()

Factory method called during doLayoutCore(LayoutGraph) and reates an appropriate EdgeReverser implementation.

By default, a suitable private implementation of EdgeReverser is returned. It may be overridden to return a custom EdgeReverser implementation.

Returns:

an implementation

publishLayers

protected void publishLayers(LayoutGraph graph,
                             Layers layers)

Callback method that publishes the layering information.

The layering information is stored in a DataProvider registered with the graph using key LAYER_VALUE_HOLDER_DPKEY.

Parameters:

graph - the input graph

layers - the Layers implementation that provides the layering information

See Also:

LAYER_VALUE_HOLDER_DPKEY

publishSequences

protected void publishSequences(LayoutGraph graph,
                                Layers layers,
                                LayoutDataProvider ldp)

Callback method that publishes the sequencing information.

The sequencing information is stored in a DataProvider registered with the graph using key SEQUENCE_VALUE_HOLDER_DPKEY.

Parameters:

graph - the input graph

layers - the Layers implementation that provides the layering and sequencing information

ldp - the LayoutDataProvider implementation which provides access to the NodeData and EdgeData instances

See Also:

SEQUENCE_VALUE_HOLDER_DPKEY

reduceBendCount

protected void reduceBendCount(LayoutGraph graph)

Removes the bends which are obviously not necessary.

By default, this method removes collinear bends from the graph. A bend point is considered to be collinear if it lies on a line with its preceding and succeeding bend point. It may be overridden for a custom implementation of bend removal.

Parameters:

graph - the input graph

reduceBendCount

protected void reduceBendCount(LayoutGraph graph,
                               double bendReductionThreshold)

Removes the bends which are obviously not necessary.

By default, this method removes collinear bends from the graph. A bend point is considered to be collinear if it lies on a line with its preceding and succeeding bend point. It may be overridden for a custom implementation of bend removal.

Parameters:

graph - the input graph

bendReductionThreshold - this method removes a bend, if its horizontal/vertical distance to the closest collinear bend is above this value

createIncrementalHintsFactory

public IncrementalHintsFactory createIncrementalHintsFactory()

Creates an IncrementalHintsFactory implementation used for obtaining hint objects associated with nodes and edges of the graph prior to the invocation of the layout algorithm.

HierarchicLayouter.IncrementalHints can be obtained from a DataProvider that is registered with the graph using key INCREMENTAL_HINTS_DPKEY.

Returns:

an IncrementalHintsFactory instance

See Also:

INCREMENTAL_HINTS_DPKEY

createSequenceConstraintFactory

public SequenceConstraintFactory createSequenceConstraintFactory(Graph graph)

Creates sequence constraints that affect the sequence of the nodes within each layer.

By default, a suitable private implementation of SequenceConstraintFactory is returned.

Parameters:

graph - the given graph

Returns:

a SequenceConstraintFactory instance

createLayerConstraintFactory

public LayerConstraintFactory createLayerConstraintFactory(Graph graph)

Creates a layer constraint factory that allows to create hints that affect the assignment of the nodes to layers.

By default, a suitable private implementation of LayerConstraintFactory is returned.

Parameters:

graph - the given graph

Returns:

a LayerConstraintFactory instance