y.layout.hierarchic
Class IncrementalHierarchicLayouter

java.lang.Object
  y.layout.CanonicMultiStageLayouter
      y.layout.hierarchic.IncrementalHierarchicLayouter

All Implemented Interfaces:

Layouter

public class IncrementalHierarchicLayouter
extends CanonicMultiStageLayouter

This layout algorithm arranges graphs in a hierarchic fashion.

Layout Style

The nodes are distributed into layers so 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, octilinear or curved (see RoutingStyle for details).

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 getFromScratchLayerer() or getFixedElementsLayerer(), respectively. 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 setFromScratchSequencer(Sequencer) or setFixedElementsSequencer(Sequencer).

Drawing

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

Features

This layout algorithm is able to create hierarchic layouts from scratch or add new elements to the existing sketch drawing incrementally. In order to add elements incrementally to the current sketch or let the algorithm optimize certain elements in the current sketch, set the layout mode to LAYOUT_MODE_INCREMENTAL. Then register a DataProvider (e.g. use Maps.createHashedDataMap()) 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 HierarchicLayouter.NODE_LAYOUT_DESCRIPTOR_DPKEY or HierarchicLayouter.EDGE_LAYOUT_DESCRIPTOR_DPKEY. If there is no descriptor assigned to some nodes/edges, a default descriptor will be used. To set default descriptors use setNodeLayoutDescriptor(NodeLayoutDescriptor) and setEdgeLayoutDescriptor(EdgeLayoutDescriptor).

IncrementalHierarchicLayouter 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 algorithm 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. For the matching to work properly, the candidates in both collection need to be the same instances. 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. Furthermore, PortCandidates with multiple directions (e.g. EAST or WEST) are not supported. To model that an edge should connect at one of several sides, define multiple candidates instead, where each candidate has a single direction.

The edge grouping feature of this layout algorithm is restricted to normal, hierarchic edges. Edges with recursive edge style EdgeLayoutDescriptor.RECURSIVE_EDGE_STYLE_DIRECTED or EdgeLayoutDescriptor.RECURSIVE_EDGE_STYLE_UNDIRECTED will not be grouped. They are also not grouped when enabling automatic edge grouping.

The port grouping feature (see PortConstraintKeys.SOURCE_PORT_GROUP_ID_DPKEY and PortConstraintKeys.TARGET_PORT_GROUP_ID_DPKEY) allows to specify edges that share the same port location at their source/target. However, unlike as for edge grouping, edges with port groups will be routed independently without sharing segments. Port grouping has similar restrictions as the edge grouping feature. In addition, port grouping is not considered for self-loops.

The IncrementalHierarchicLayouter also supports node types as a subordinate criterion during the sequencing of nodes within their layer. More precisely, the sequencing algorithm prefers to place nodes of the same type next to each other if this does not induce additional crossings or conflicts with other constraints (like node groups, swimlanes, or sequence constraints). The algorithm uses an additional local optimization heuristic to improve the placement with respect to node types and, thus, does not guarantee optimal results. Furthermore, this additional step may increase the required runtime. Note that node types do not affect the layer assignment.

IncrementalHierarchicLayouter allows restricting the maximum duration which may be a suitable option to reduce the runtime required for large graphs. Note that restricting the maximum duration may result in a lower layout quality. Furthermore, the actual runtime may exceed the maximum duration since the layout algorithm still has to find a valid solution.

For edges incident to group nodes, the IncrementalHierarchicLayouter only considers weak PortConstraints.

Field Summary

static java.lang.Object	ALTERNATIVE_EDGE_PATH_DPKEY A DataProvider key for associating alternative paths for edges connecting to groups, group content or folder nodes.
static java.lang.Object	ALTERNATIVE_GROUP_BOUNDS_DPKEY A DataProvider key for associating an alternative bounds with the collapsed/expanded group.
static java.lang.Object	BUS_DESCRIPTOR_DPKEY A DataProvider key for specifying the bus to which an edge belongs to.
static byte	COMPONENT_ARRANGEMENT_COMPACT A component arrangement policy that achieves a 1:1 aspect ratio for the graph.
static byte	COMPONENT_ARRANGEMENT_TOPMOST A component arrangement policy that aligns the components with their topmost layer.
static java.lang.Object	CRITICAL_EDGE_DPKEY A DataProvider key for defining the priority of critical edges.
static java.lang.Object	EDGE_CROSSING_COST_DPKEY A DataProvider key for specifying individual crossing costs of the edges.
static java.lang.Object	EDGE_DIRECTEDNESS_DPKEY A DataProvider key for specifying the directedness of edges.
static java.lang.Object	EDGE_THICKNESS_DPKEY A DataProvider key for specifying the thickness of the edges.
static java.lang.Object	FOLDER_NODES_DPKEY A DataProvider key for marking folder nodes.
static java.lang.Object	GROUP_BORDER_CROSSING_COST_DPKEY A DataProvider key for specifying individual crossing costs for vertical borders of group nodes.
static java.lang.Object	INCREMENTAL_HINTS_DPKEY A DataProvider key for specifying incremental hints.
static java.lang.Object	LAYER_VALUE_HOLDER_DPKEY A DataAcceptor key for publishing the layer IDs for all nodes in the graph.
static byte	LAYERING_STRATEGY_BFS A layering strategy based on a breadth first search (BFS).
static byte	LAYERING_STRATEGY_FROM_SKETCH A layering strategy which derives the layers from the initial coordinates of the nodes.
static byte	LAYERING_STRATEGY_HIERARCHICAL_DOWNSHIFT A layering strategy which applies a fast heuristic that improves the layering done by LAYERING_STRATEGY_HIERARCHICAL_TOPMOST by shifting some nodes down.
static byte	LAYERING_STRATEGY_HIERARCHICAL_OPTIMAL A layering strategy which places each node in the optimal layer to minimize the layer distances.
static byte	LAYERING_STRATEGY_HIERARCHICAL_TIGHT_TREE A layering strategy which applies a heuristic to approximate the optimal layering.
static byte	LAYERING_STRATEGY_HIERARCHICAL_TOPMOST A layering strategy which places each node in the highest possible layer without passing its predecessor in the topological order of nodes.
static byte	LAYERING_STRATEGY_UNKNOWN A dummy layering strategy which describes a strategy that is not part of the default strategies.
static byte	LAYERING_STRATEGY_USER_DEFINED A layering strategy which uses a layer assignment specified by the user.
static byte	LAYOUT_MODE_FROM_SCRATCH A layout mode that will recompute the complete layout from scratch.
static byte	LAYOUT_MODE_INCREMENTAL A layout mode that allows to keep some nodes fixed and insert the remaining nodes incrementally.
static byte	POLICY_ALIGN_GROUPS_BOTTOM A group layering alignment strategy which aligns groups and normal nodes that occupy the same layer to the bottom with respect to their inner layers.
static byte	POLICY_ALIGN_GROUPS_CENTER A group layering alignment strategy which aligns groups and normal nodes that occupy the same layer to the center with respect to their inner layers.
static byte	POLICY_ALIGN_GROUPS_TOP A group layering alignment strategy which aligns groups and normal nodes that occupy the same layer to the top with respect to their inner layers.
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	SUB_COMPONENT_ID_DPKEY A DataProvider key for specifying custom sub-components of the input graph.
static java.lang.Object	SUB_COMPONENT_LAYOUT_ALGORITHM_DPKEY A DataProvider key for specifying a layout algorithm for each sub-component.
static java.lang.Object	SWIMLANE_DESCRIPTOR_DPKEY A DataProvider key for defining swimlanes for the nodes.
static java.lang.Object	UNIFORM_PORT_ASSIGNMENT_GROUPS_DPKEY A DataProvider key for specifying whether or not the ports of edges incident to a specific group node should be uniformly distributed.

Fields inherited from interface y.layout.Layouter

EDGE_ID_DPKEY, NODE_ID_DPKEY, NODE_TYPE_DPKEY, SELECTED_EDGES, SELECTED_NODES

Constructor Summary

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

Method Summary

boolean	canLayoutCore(LayoutGraph graph) Accepts general graphs without exceptions.
protected void	configureCoreLayout(LayoutGraph graph, HierarchicLayouter coreLayouter) Configures the core layout algorithm with the settings of this IncrementalHierarchicLayouter instance.
protected EdgeLayoutDescriptor	createEdgeLayoutDescriptor() Returns a new EdgeLayoutDescriptor instance that will be used during the various phases of the layout algorithm to determine the drawing details of the edges of the graph.
protected HierarchicLayouter	createHierarchicLayouter() Returns a new HierarchicLayouter instance.
IncrementalHintsFactory	createIncrementalHintsFactory() Returns a IncrementalHintsFactory instance that must be used to obtain hints to be associated with graph elements that should be laid out incrementally.
LayerConstraintFactory	createLayerConstraintFactory(Graph graph) Returns a LayerConstraintFactory instance that can be used for specifying layer constraints for the given graph.
protected NodeLayoutDescriptor	createNodeLayoutDescriptor() Returns a new NodeLayoutDescriptor instance that will be used during the various phases of the layout algorithm to determine the drawing details of the nodes of the graph.
SequenceConstraintFactory	createSequenceConstraintFactory(LayoutGraph graph) Returns a SequenceConstraintFactory instance that can be used for specifying sequence constraints for the given graph.
void	doLayout(LayoutGraph graph) Calculates a hierarchic layout of the given graph.
void	doLayoutCore(LayoutGraph graph) Delegates the calculation of the hierarchic layout to a configured HierarchicLayouter instance.
byte	getComponentArrangementPolicy() Returns the policy that specifies how to arrange connected components.
protected DefaultDrawingDistanceCalculator	getDefaultDrawingDistanceCalculator() Returns the DefaultDrawingDistanceCalculator that is registered with the layout algorithm by default.
EdgeLayoutDescriptor	getEdgeLayoutDescriptor() Returns the EdgeLayoutDescriptor instance used for all those edges that do not have a specific layout descriptor assigned.
double	getEdgeToEdgeDistance() Returns the minimum distance between two directly consecutive edges that pass through the same layer.
Layerer	getFixedElementsLayerer() Returns the Layerer instance that obtains the layering for fixed nodes during the incremental layout run.
Sequencer	getFixedElementsSequencer() Returns the Sequencer instance that calculates the sequence of the fixed nodes during the incremental layout run.
Layerer	getFromScratchLayerer() Returns the Layerer instance that obtains the layering for the nodes if the layout algorithm runs in From Scratch mode.
byte	getFromScratchLayeringStrategy() Returns a predefined layering strategy for the from scratch layerer.
Sequencer	getFromScratchSequencer() Returns the Sequencer instance that calculates the node sequence if the layout algorithm runs in From Scratch mode.
double	getGridSpacing() Returns the equidistant spacing between the horizontal and vertical grid lines.
byte	getGroupAlignmentPolicy() Returns the group layer alignment strategy used for recursive group layering.
HierarchicLayouter	getHierarchicLayouter() Returns the current layout algorithm instance.
byte	getLayoutMode() Returns the layout mode this layouter should use for upcoming layouts.
long	getMaximalDuration() Returns the time limit (in milliseconds) set for the layout algorithm.
double	getMinimumLayerDistance() Returns the minimum distance between two adjacent layers.
protected int	getMirrorMask() Returns the mirror mask of the orientation layouter.
NodeLayoutDescriptor	getNodeLayoutDescriptor() Returns the NodeLayoutDescriptor instance used for all those nodes that do not have a specific layout descriptor assigned.
NodePlacer	getNodePlacer() Returns the NodePlacer instance that will calculate the final node placement of the layout.
double	getNodeToEdgeDistance() Returns the minimum distance between an edge and an adjacent node in one layer.
double	getNodeToNodeDistance() Returns the minimum distance between two adjacent nodes in one layer.
static Edge	getOriginalEdge(Edge edge, LayoutDataProvider layoutDataProvider) Returns the corresponding original edge instance for a given edge.
boolean	isAutomaticEdgeGroupingEnabled() Returns whether or not edges are grouped automatically.
boolean	isBackloopRoutingEnabled() Returns whether or not reversed edges should be routed as back-loops.
boolean	isBackloopRoutingForSelfloopsEnabled() Returns whether or not self-loops should be routed in a similar manner as back-loops.
boolean	isConsiderNodeLabelsEnabled() Returns whether or not the layout algorithm considers node labels when calculating node positions to avoid overlaps.
boolean	isGroupCompactionEnabled() Returns whether or not layer compaction for recursive group layering is active.
boolean	isIntegratedEdgeLabelingEnabled() Returns whether or not the layout algorithm reserves space for labels and places them.
boolean	isLayerSeparationEnabled() Returns whether or not to separate layers.
boolean	isOrthogonallyRouted() Returns whether or not edges should be routed orthogonally.
boolean	isRecursiveGroupLayeringEnabled() Returns whether or not groups are respected during the layering stage.
boolean	isStopAfterLayeringEnabled() Specifies whether or not to stop the layout algorithm after the layering step.
boolean	isStopAfterSequencingEnabled() Returns whether or not to stop the layout algorithm after the sequencing step.
void	setAutomaticEdgeGroupingEnabled(boolean automaticEdgeGroupingEnabled) Specifies whether or not edges are grouped automatically.
void	setBackloopRoutingEnabled(boolean backLoopRoutingEnabled) Specifies whether or not reversed edges should be routed as back-loops.
void	setBackloopRoutingForSelfloopsEnabled(boolean backLoopRoutingForSelfLoopsEnabled) Specifies whether or not self-loops should be routed in a similar manner as back-loops.
void	setComponentArrangementPolicy(byte policy) Specifies the policy that specifies how to arrange connected components.
void	setConsiderNodeLabelsEnabled(boolean enabled) Specifies whether or not the layout algorithm considers node labels when calculating node positions to avoid overlaps.
void	setEdgeLayoutDescriptor(EdgeLayoutDescriptor edgeLayoutDescriptor) Specifies the EdgeLayoutDescriptor instance used for all those edges that do not have a specific layout descriptor assigned.
void	setEdgeToEdgeDistance(double distance) Sets the minimum distance between two directly consecutive edges that pass through the same layer.
void	setFixedElementsLayerer(Layerer fixedElementsLayerer) Specifies the Layerer instance that obtains the layering for fixed nodes during the incremental layout run.
void	setFixedElementsSequencer(Sequencer fixedElementsSequencer) Specifies the Sequencer instance that calculates the sequence of the fixed nodes during the incremental layout run.
void	setFromScratchLayerer(Layerer layerer) Specifies the Layerer instance that obtains the layering for the nodes if the layout algorithm runs in From Scratch mode.
void	setFromScratchLayeringStrategy(byte strategy) Specifies a predefined layering strategy for the from scratch layerer.
void	setFromScratchSequencer(Sequencer sequencer) Specifies the Sequencer instance that calculates the node sequence if the layout algorithm runs in From Scratch mode.
void	setGridSpacing(double gridSpacing) Specifies the equidistant spacing between the horizontal and vertical grid lines.
void	setGroupAlignmentPolicy(byte groupAlignmentPolicy) Specifies the group layer alignment strategy used for recursive group layering.
void	setGroupCompactionEnabled(boolean groupCompactionEnabled) Specifies whether or not layer compaction for recursive group layering is active.
void	setIntegratedEdgeLabelingEnabled(boolean enabled) Specifies whether or not the layout algorithm reserves space for labels and places them.
void	setLayerSeparationEnabled(boolean layerSeparationEnabled) Specifies whether or not to separate layers.
void	setLayoutMode(byte layoutMode) Specifies the layout mode this layouter should use for upcoming layouts.
void	setMaximalDuration(long maximalDuration) Specifies the time limit (in milliseconds) set for the layout algorithm.
void	setMinimumLayerDistance(double distance) Sets the minimum distance between two adjacent layers.
void	setNodeLayoutDescriptor(NodeLayoutDescriptor nodeLayoutDescriptor) Specifies the NodeLayoutDescriptor instance used for all those nodes that do not have a specific layout descriptor assigned.
void	setNodePlacer(NodePlacer nodePlacer) Specifies the NodePlacer instance that will calculate the final node placement of the layout.
void	setNodeToEdgeDistance(double d) Sets the minimum distance between an edge and an adjacent node in one layer.
void	setNodeToNodeDistance(double distance) Sets the minimum distance between two adjacent nodes in one layer.
void	setOrthogonallyRouted(boolean orthogonal) Specifies whether or not edges should be routed orthogonally.
void	setRecursiveGroupLayeringEnabled(boolean recursiveGroupLayeringEnabled) Specifies whether or not groups are respected during the layering stage.
void	setStopAfterLayeringEnabled(boolean stopAfterLayering) Specifies whether or not to stop the layout algorithm after the layering step.
void	setStopAfterSequencingEnabled(boolean stopAfterSequencing) Specifies whether or not to stop the layout algorithm after the sequencing step.
protected void	unconfigureCoreLayout(LayoutGraph graph, HierarchicLayouter coreLayouter) Disposes of the core layout algorithm.

Methods inherited from class y.layout.CanonicMultiStageLayouter

appendStage, calcLayout, calcLayout, canLayout, checkGroupNodeSize, checkNodeSize, doLayout, enableOnlyCore, getComponentLayouter, getGroupNodeHider, getLabelLayouter, getLayoutOrientation, getOrientationLayouter, getParallelEdgeLayouter, getSelfLoopLayouter, getSubgraphLayouter, isComponentLayouterEnabled, isGroupNodeHidingEnabled, isLabelLayouterEnabled, isOrientationLayouterEnabled, isParallelEdgeLayouterEnabled, isSelfLoopLayouterEnabled, isSubgraphLayouterEnabled, prependStage, removeStage, setComponentLayouter, setComponentLayouterEnabled, 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

EDGE_DIRECTEDNESS_DPKEY

public static final java.lang.Object EDGE_DIRECTEDNESS_DPKEY

A DataProvider key for specifying the directedness of edges.

Generally, the hierarchic layout algorithm assigns nodes to layers such that most of the edges point in the main layout direction. The directedness of an edge specifies whether it should comply with this strategy. More precisely, a value of 1 means that the edge should fully comply, a value of -1 that it should comply inversely (the edge should point against the main layout direction), and a value of 0 means that the direction doesn't matter at all and the endpoints of the edges may be placed at the same layer. If there are conflicting preferences, edges with higher absolute values are more likely to point in the desired direction.

If no DataProvider is registered with this key, the algorithm assumes that all edges have directedness 1.

Considering the edge directedness requires a special layering algorithm. Hence, IncrementalHierarchicLayouter ignores the specified layerer and automatically switches to the ConstraintIncrementalLayerer in such cases.

Sample Graphs:

Layout result when dashed edges are undirected, i.e., have directedness 0

Layout result when all edges are directed, i.e., have directedness 1

EDGE_CROSSING_COST_DPKEY

public static final java.lang.Object EDGE_CROSSING_COST_DPKEY

A DataProvider key for specifying individual crossing costs of the edges.

The crossing costs of the edges are considered during the crossing minimization phase. The total crossing costs are minimized using a heuristic where the cost of a crossing between two edges is defined as the product of the edges' crossing costs.

If no individual crossing costs are defined, each crossing has a cost of 1. A crossing with an edge that has a cost of zero is cost-free and such a crossing will therefore not be avoided.

Edges that are very important can get larger crossing costs than other edges in order to improve their readability. Consider assigning higher crossing costs to critical edges, as critical edges are not automatically favored during the crossing minimization phase.

The implemented crossing minimization is a heuristic. Therefore, there is no guarantee that crossing a certain edge is actually avoided, even though it has high crossing costs.

GROUP_BORDER_CROSSING_COST_DPKEY

public static final java.lang.Object GROUP_BORDER_CROSSING_COST_DPKEY

A DataProvider key for specifying individual crossing costs for vertical borders of group nodes.

Like edge crossing costs, these costs are considered during the crossing minimization phase. The total costs are minimized using a heuristic where the cost of a crossing between a group node border and an edge is defined as the product of the respective group border crossing cost and the edge crossing cost.

If no individual crossing costs are defined, the cost for crossing a group node border is 5. This means that by default, a crossing between an edge and a group node border is more expensive than a crossing between two edges. Also note that a crossing with a group node border that has a cost of zero is cost-free and such a crossing will therefore not be avoided.

In case of a vertical layout orientation (default), these costs only apply to vertical group borders. If the layout orientation is horizontal (e.g. left-to-right), the costs only apply to horizontal group borders.

Avoid using very large cost values. Due to the fact that costs need to be multiplied and summed up, this might lead to overflows and undesired results.

See Also:

EDGE_CROSSING_COST_DPKEY

CRITICAL_EDGE_DPKEY

public static final java.lang.Object CRITICAL_EDGE_DPKEY

A DataProvider key for defining the priority of critical edges.

Critical edges highlight different edge paths that are relevant for a user. The layouter tries to vertically align each node pair that is connected by a critical edge. Conflicts between different critical edges are always resolved in favor of the higher priority.

Critical edges do not automatically affect the result of the crossing minimization phase. If crossings between critical edges should be avoided, one can assign individual crossing costs by using EDGE_CROSSING_COST_DPKEY. Critical edges need to get a larger crossing cost than other, non-critical edges. This is recommended if critical edges should not only highlight a relevant path but also crossings with them should be avoided. Note, however, that the crossing minimization is only a heuristic and there is no guarantee for an optimal solution in all cases.

Critical edges are always connected to the center port. Hence, the edge distribution is no longer uniform.

Sample Graphs:

EDGE_THICKNESS_DPKEY

public static final java.lang.Object EDGE_THICKNESS_DPKEY

A DataProvider key for specifying the thickness of the edges.

The specified non-negative thickness is considered when calculating minimum distances so that there are no overlaps between edges and other graph elements. By default, each edge has thickness 0.

The port assignments on grid and on sub-grid ignore the thickness of edges.

Sample Graphs:

Edge thickness 0

Edges with different thickness values

BUS_DESCRIPTOR_DPKEY

public static final java.lang.Object BUS_DESCRIPTOR_DPKEY

A DataProvider key for specifying the bus to which an edge belongs to.

All edges with the same BusDescriptor instance adjacent to a specific node (the root) and having the same direction are arranged in a compact, bus-like way. The edge directedness is also considered here. The direction defines the placement of the bus structure in the following way:

• Bus nodes connected by out-edges are placed in the layers starting with the layer that comes directly after the layer of the root (e.g. below the root for top-to-bottom layout orientation).
• Bus nodes connected by in-edges are placed in the layers ending with the layer that comes directly before the layer of the root (e.g. above the root for top-to-bottom layout orientation).

The bus substructures are arranged using a style that yields more compact layout results. Edges to the child nodes, the so-called bus nodes, are routed using a shared segment that connects to the common root node. The bus nodes are arranged using several layers above or below the root node such that the whole substructure has a compact area. By default, each bus layer contains equally many bus nodes, bus nodes of adjacent layers are center-aligned and the shared bus segment is routed in the middle of the nodes. This produces compact, symmetric arrangements of the bus structures.

The arrangement can also be customized for each bus individually, by using the settings offered by BusDescriptor. It allows to configure the number of bus nodes before and after the common bus segment.

There apply some restrictions for bus structures:

• Bus structures can not be nested/interleaved. More precisely, each node can only be part of a single bus. Note that the root node is considered to be a part of the bus, i.e., if a node is a bus node it can not be a root node of another bus at the same time.
• Only nodes that are in the same partition grid cell or same swimlane as the root node are included in the bus structure.
• The bus nodes must all belong to the same group node. Also, a group node can not be part of a bus structure; neither as bus element nor as root.
• For bus edges, the integrated edge labeling feature does not place port labels as close to the actual port as it does for other edges (see LabelLayoutConstants.PLACE_AT_SOURCE_PORT and LabelLayoutConstants.PLACE_AT_TARGET_PORT).
• Edge grouping constraints at the side of the bus root node are ignored for bus edges; the grouping induced by the bus structure is considered to be stronger.
• If in incremental layout mode, the bus edges are always treated in an incremental way such that the bus-style routing remains consistent (e.g. if a fixed bus edge contains bends that suggest another route, they are ignored). The reason is that the bus-style layout of the structures has higher priority. Furthermore, the location of the bus segment relative to the elements is not derived from the sketch but depends on the settings BusDescriptor.getMaximumNodesBeforeBus() and BusDescriptor.getMaximumNodesAfterBus() as well as the before/after constraints (see BusDescriptor.PLACE_BEFORE_BUS_DPKEY). This means that it can happen that a fixed bus node which was placed before the bus in the input drawing may be placed after the bus if the bus was enlarged due to the insertion of incremental bus nodes.
• It is not recommended to define buses inside a group node which has an incremental group hint. Fixed bus nodes inside such a group are not necessarily kept fix but are treated like an incrementally inserted node.

The bus-like arrangement is especially suitable for star structures (i.e. a node with a high in- or out-degree) which can otherwise consume a lot of area and make the layout less compact. Ideally, the bus nodes have no other edges aside from the bus edge.

When two parallel edges have the same BusDescriptor, only one edge will be treated as a bus edge.

If layering constraints are specified using LayerConstraintFactory, they are not considered for bus nodes because the bus structure is layered independently.

See Also:

BusDescriptor, BusDescriptor.PLACE_BEFORE_BUS_DPKEY, BusDescriptor.ROOT_OFFSET_DPKEY

Sample Graphs:

A graph with no buses

The same graph with a bus structure consisting of 15 edges (bus edges are highlighted)

The same graph with a bus structure and a different bus segment alignment (bus edges are highlighted)

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:

HierarchicLayouter.INCREMENTAL_HINTS_DPKEY, IncrementalHintsFactory

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:

HierarchicLayouter.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:

HierarchicLayouter.SEQUENCE_VALUE_HOLDER_DPKEY

SWIMLANE_DESCRIPTOR_DPKEY

public static final java.lang.Object SWIMLANE_DESCRIPTOR_DPKEY

A DataProvider key for defining swimlanes for the nodes.

The layout algorithm will arrange nodes in swimlanes according to the registered descriptors.

Layout information about the swimlanes is finally written back to the descriptor instances. Instances can be shared among multiple nodes in the same lane.

See Also:

HierarchicLayouter.SWIMLANE_DESCRIPTOR_DPKEY

ALTERNATIVE_GROUP_BOUNDS_DPKEY

public static final java.lang.Object ALTERNATIVE_GROUP_BOUNDS_DPKEY

A DataProvider key for associating an alternative bounds with the collapsed/expanded group.

When running in incremental layout mode, the alternative bounds of the collapsed/expanded group will be used during the layering and sequencing phase of the algorithm.

The alternative bounds helps to achieve more stable layout results when collapsing/expanding groups in incremental layout mode. More precisely, the alternative bounds specifies the original size of the expanded/collapsed group (i.e., before expanding/collapsing).

To further improve the results you should also specify alternative edge paths for edges adjacent to such groups. In addition, recursive group layering should be enabled and recursive edge style should be set to EdgeLayoutDescriptor.RECURSIVE_EDGE_STYLE_DIRECTED. Edges that end at a group itself or a folder node should not have port candidates or port constraints at this end (because this may destroy the recursive directed edge style required to obtain stable results).

The algorithm assumes that there is at most one node with associated alternative bounds.

See Also:

ALTERNATIVE_EDGE_PATH_DPKEY

ALTERNATIVE_EDGE_PATH_DPKEY

public static final java.lang.Object ALTERNATIVE_EDGE_PATH_DPKEY

A DataProvider key for associating alternative paths for edges connecting to groups, group content or folder nodes.

When running in incremental layout mode, the alternative edge paths are considered during the routing of fixed (i.e., non-incremental) edges.

The alternative paths should be used in conjunction with alternative group bounds to achieve more stable layout results when collapsing/expanding a group node as follows:

1. Collapsing: edges adjacent to the group itself and edges where one of the endpoints (source/target) lies inside the group should get the path before collapsing the group as alternative path. If both endpoints are either inside or outside the group, no alternative path is required.
2. Expanding: edges adjacent to the expanded folder node (which is now a group) should get the path before expanding as alternative path.

See Also:

ALTERNATIVE_GROUP_BOUNDS_DPKEY

FOLDER_NODES_DPKEY

public static final java.lang.Object FOLDER_NODES_DPKEY

A DataProvider key for marking folder nodes.

When using recursive edge styles in incremental mode, edges will also start at the bottom and end at the top of marked folder nodes. This will keep the edge routes more stable since the connection sides won't change.

SUB_COMPONENT_ID_DPKEY

public static final java.lang.Object SUB_COMPONENT_ID_DPKEY

A DataProvider key for specifying custom sub-components of the input graph.

A sub-component is arranged by another layout algorithm and its layout is finally embedded into the global hierarchical layout. This feature allows, for example, to highlight special sub-structures by arranging them in a different fashion. The sub-layout algorithm must be specified by a DataProvider registered with the graph with key SUB_COMPONENT_LAYOUT_ALGORITHM_DPKEY. The first found Layouter instance bound to any node of a sub-component is applied as algorithm for that sub-component.

Carefully note that nodes of a sub-component can be connected to nodes of another sub-component as well as to nodes that are not part of any sub-component. Edges that model these connections are so-called inter-edges. For inter-edges there apply some restrictions with respect to the supported features:

• Their general style can somewhat differ from other, normal hierarchical edges. They do not fully comply with all RoutingStyle settings.
• The backloop routing style is not applied for the part of an inter-edge that connects to a sub-component node.
• The minimum first segment length and the minimum last segment length can not always be fulfilled for the side of an inter-edge that lies inside a sub-component. It is still kept on the side outside of sub-components.
• The node-to-edge distance can not always be kept between inter-edges and nodes inside a sub-component. This will mostly appear if a sub-component has a rather large number of inter-edges connecting to it.
• The integrated edge labeling does not guarantee full support for all PreferredPlacementDescriptor configurations for inter-edges. This affects the side of the inter-edge that lies inside a sub-component and when the label should be placed near the component node, i.e., using settings LabelLayoutConstants.PLACE_AT_SOURCE, LabelLayoutConstants.PLACE_AT_SOURCE_PORT, LabelLayoutConstants.PLACE_AT_TARGET or LabelLayoutConstants.PLACE_AT_TARGET_PORT.

Sub-components can be defined on grouped graphs with the following restrictions:

• All sub-component nodes must be on the same hierarchy level if the group node itself is not part of the sub-component.
• If a group is assigned to a sub-component, all its descendants (including other group nodes) must be in that component, too.

When running in incremental mode, it is still up to the sub-layout algorithm to decide whether to treat a sub-component element as incremental or fixed. If the given layout of the sub-component should be considered, then the from-sketch mode of the used layout algorithm needs to be enabled (if such a mode is supported).

Layering and sequencing constraints are supported for sub-components in the following way: all constraints from the sub-component nodes are transferred to the component itself. Constraints between nodes of the same component are ignored. In the same way, a given layering provided by GivenLayersLayerer is supported for sub-components.

It is possible to define another IncrementalHierarchicLayouter instance as layout algorithm responsible for a sub-component. This way, different hierarchical layout styles can be conveniently combined into one layout (e.g. layouts with different orientations). The best layout results are achieved if a sub-component is connected to other parts only by very few inter-edges.

For the layout of a sub-component, the specified sub-component layout algorithm is fully responsible. Thus, the supported features and layout style are defined solely by that algorithm.

Sub-components may not be nested, that is, a sub-component is not allowed to contain nodes that belong to yet another sub-component. Nesting of sub-components results in an exception.

See Also:

SUB_COMPONENT_LAYOUT_ALGORITHM_DPKEY

SUB_COMPONENT_LAYOUT_ALGORITHM_DPKEY

public static final java.lang.Object SUB_COMPONENT_LAYOUT_ALGORITHM_DPKEY

A DataProvider key for specifying a layout algorithm for each sub-component.

A sub-component is arranged by the layout algorithm defined by this mapping and its layout is finally embedded into the global hierarchical layout. The first non-null instance mapped to any sub-component node is used for the whole sub-component. For more details about this feature and how to define sub-components, please see SUB_COMPONENT_ID_DPKEY.

See Also:

SUB_COMPONENT_ID_DPKEY

UNIFORM_PORT_ASSIGNMENT_GROUPS_DPKEY

public static final java.lang.Object UNIFORM_PORT_ASSIGNMENT_GROUPS_DPKEY

A DataProvider key for specifying whether or not the ports of edges incident to a specific group node should be uniformly distributed.

This setting only affects the two sides of a group node that are in flow and against the flow of the layout orientation. For example, for orientation LayoutOrientation.TOP_TO_BOTTOM only the edges incident to the top and bottom group node side are considered but not the edges at the left and right side.

If no DataProvider is registered with this key, then the ports at group nodes are not explicitly distributed in a uniform way.

The uniform group port assignment considers the edge-to-edge distance such that two ports keep the specified distance to each other. Group nodes may in consequence be enlarged to satisfy that constraints, potentially generating less compact layouts. The distance from the group node border to the first/last port on each group side may be influenced by using group node insets.

Importantly, it is not guaranteed that the group node ports of a specific side can be uniformly distributed. In the following cases ports of a specific side are not uniformly distributed:

1. There are edges that cross the group node border because they connect to a child node of the group.
2. There is a self-loop at the group node which has its source and target port at the same group node side.

Forcing group nodes to have uniform ports can have several side-effects and also affect other parts of the layout. In general, results can become less compact and there might be more bends, because bends may be introduced where they would not be necessary when ports are not uniformly distributed.

Enabling uniform group ports for at least one group node may significantly increase the runtime of the algorithm. Also, the uniform distribution may be skipped in case that the maximum duration is restricted and there is no time left.

Sample Graphs:

false for all group nodes

true for all group nodes

COMPONENT_ARRANGEMENT_COMPACT

public static final byte COMPONENT_ARRANGEMENT_COMPACT

A component arrangement policy that achieves a 1:1 aspect ratio for the graph.

After layering the single components with the core layerer, the components will be merged such that an 1:1 aspect ratio is fulfilled best.

See Also:

setComponentArrangementPolicy(byte), Constant Field Values

Sample Graph:

Compact component arrangement

COMPONENT_ARRANGEMENT_TOPMOST

public static final byte COMPONENT_ARRANGEMENT_TOPMOST

A component arrangement policy that aligns the components with their topmost layer.

After layering the single components with the core layerer, the components are aligned with their topmost layer.

See Also:

setComponentArrangementPolicy(byte), Constant Field Values

Sample Graph:

Topmost component arrangement

LAYOUT_MODE_INCREMENTAL

public static final byte LAYOUT_MODE_INCREMENTAL

A layout mode that allows to keep some nodes fixed and insert the remaining nodes incrementally.

Fixed elements will be handled by the fixed elements sequencer and fixed elements layerer. Incremental elements will be added during the layering or the sequencing phase. They are handled by from scratch layerer and fixed elements layerer respectively.

See Also:

IncrementalHintsFactory.createLayerIncrementallyHint(Object), setLayoutMode(byte), setFixedElementsSequencer(Sequencer), setFixedElementsLayerer(Layerer), Constant Field Values

LAYOUT_MODE_FROM_SCRATCH

public static final byte LAYOUT_MODE_FROM_SCRATCH

A layout mode that will recompute the complete layout from scratch.

All elements will be handled by the same layerer and sequencer.

See Also:

setLayoutMode(byte), setFromScratchSequencer(Sequencer), setFromScratchLayerer(Layerer), Constant Field Values

LAYERING_STRATEGY_HIERARCHICAL_TOPMOST

public static final byte LAYERING_STRATEGY_HIERARCHICAL_TOPMOST

A layering strategy which places each node in the highest possible layer without passing its predecessor in the topological order of nodes.

All nodes with indegree zero will be assigned to the topmost layer of the layout. The number of separate layers will be as small as possible.

See Also:

setFromScratchLayeringStrategy(byte), Constant Field Values

Sample Graph:

Topmost hierarchic layering

LAYERING_STRATEGY_HIERARCHICAL_OPTIMAL

public static final byte LAYERING_STRATEGY_HIERARCHICAL_OPTIMAL

A layering strategy which places each node in the optimal layer to minimize the layer distances.

The layer distance of an edge is the absolute difference between the layer numbers of its source and target node. The layer assignment will minimize the overall sum of the layer distances of all edges in the layout.

See Also:

setFromScratchLayeringStrategy(byte), Constant Field Values

Sample Graph:

Optimal hierarchic layering

LAYERING_STRATEGY_HIERARCHICAL_TIGHT_TREE

public static final byte LAYERING_STRATEGY_HIERARCHICAL_TIGHT_TREE

A layering strategy which applies a heuristic to approximate the optimal layering.

The quality of the result may not be as good as with optimal layering but it is usually achieved faster.

See Also:

setFromScratchLayeringStrategy(byte), Constant Field Values

Sample Graph:

Tight tree layering

LAYERING_STRATEGY_HIERARCHICAL_DOWNSHIFT

public static final byte LAYERING_STRATEGY_HIERARCHICAL_DOWNSHIFT

A layering strategy which applies a fast heuristic that improves the layering done by LAYERING_STRATEGY_HIERARCHICAL_TOPMOST by shifting some nodes down.

The quality of the result is usually worse than the one produced by LAYERING_STRATEGY_HIERARCHICAL_TIGHT_TREE.

See Also:

setFromScratchLayeringStrategy(byte), Constant Field Values

Sample Graph:

Downshift hierarchic layering

LAYERING_STRATEGY_BFS

public static final byte LAYERING_STRATEGY_BFS

A layering strategy based on a breadth first search (BFS).

All edges will span at most one layer in the resulting drawing. Edges between nodes that belong to the same layer are possible.

The nodes that will be placed in the first layer can be provided by a data provider bound to the input graph using the key BFSLayerer.CORE_NODES. If this data provider is not given, then nodes that have no incoming edges are placed in the first layer.

See Also:

setFromScratchLayeringStrategy(byte), Constant Field Values

Sample Graph:

BFS layering

LAYERING_STRATEGY_FROM_SKETCH

public static final byte LAYERING_STRATEGY_FROM_SKETCH

A layering strategy which derives the layers from the initial coordinates of the nodes.

It tries to find a layering that is similar to the one in the input graph. The layout algorithm may place nodes in the same layer, even though they are connected by an edge.

In a vertically oriented layout, nodes that overlap vertically are placed in the same layer. The same holds for a horizontally oriented layout in the case where the nodes overlap horizontally.

See Also:

setFromScratchLayeringStrategy(byte), Constant Field Values

LAYERING_STRATEGY_USER_DEFINED

public static final byte LAYERING_STRATEGY_USER_DEFINED

A layering strategy which uses a layer assignment specified by the user.

The nodes' layer assignment must be provided by a data provider bound to the input graph using the key GivenLayersLayerer.LAYER_ID_KEY.

This layering strategy allows edges whose source and target share a layer.

See Also:

setFromScratchLayeringStrategy(byte), Constant Field Values

LAYERING_STRATEGY_UNKNOWN

public static final byte LAYERING_STRATEGY_UNKNOWN

A dummy layering strategy which describes a strategy that is not part of the default strategies.

See Also:

getFromScratchLayeringStrategy(), Constant Field Values

POLICY_ALIGN_GROUPS_TOP

public static final byte POLICY_ALIGN_GROUPS_TOP

A group layering alignment strategy which aligns groups and normal nodes that occupy the same layer to the top with respect to their inner layers.

This only applies when recursive group layering is enabled.

See Also:

setGroupAlignmentPolicy(byte), setRecursiveGroupLayeringEnabled(boolean), Constant Field Values

Sample Graph:

Group alignment top

POLICY_ALIGN_GROUPS_CENTER

public static final byte POLICY_ALIGN_GROUPS_CENTER

A group layering alignment strategy which aligns groups and normal nodes that occupy the same layer to the center with respect to their inner layers.

This only applies when recursive group layering is enabled.

See Also:

setGroupAlignmentPolicy(byte), setRecursiveGroupLayeringEnabled(boolean), Constant Field Values

Sample Graph:

Group alignment center

POLICY_ALIGN_GROUPS_BOTTOM

public static final byte POLICY_ALIGN_GROUPS_BOTTOM

A group layering alignment strategy which aligns groups and normal nodes that occupy the same layer to the bottom with respect to their inner layers.

This only applies when recursive group layering is enabled.

See Also:

setGroupAlignmentPolicy(byte), setRecursiveGroupLayeringEnabled(boolean), Constant Field Values

Sample Graph:

Group alignment bottom

Constructor Detail

IncrementalHierarchicLayouter

public IncrementalHierarchicLayouter()

Creates a new IncrementalHierarchicLayouter instance with the default settings.

Method Detail

getGroupAlignmentPolicy

public byte getGroupAlignmentPolicy()

Returns the group layer alignment strategy used for recursive group layering.

Returns:

one of the default group alignment policies

See Also:

setGroupAlignmentPolicy(byte), setRecursiveGroupLayeringEnabled(boolean)

setGroupAlignmentPolicy

public void setGroupAlignmentPolicy(byte groupAlignmentPolicy)

Specifies the group layer alignment strategy used for recursive group layering.

Default Value:

The default value is POLICY_ALIGN_GROUPS_CENTER. Groups and normal nodes are center aligned.

Parameters:

groupAlignmentPolicy - one of the default group alignment policies

Throws:

java.lang.IllegalArgumentException - if an unknown group alignment policy is given

See Also:

getGroupAlignmentPolicy(), setRecursiveGroupLayeringEnabled(boolean)

isGroupCompactionEnabled

public boolean isGroupCompactionEnabled()

Returns whether or not layer compaction for recursive group layering is active.

The number of node layers is decreased if possible without reversing edge directions. The resulting layering tries to keep the layer span of a group node low (i.e., the height of a group for layout orientation top-to-bottom). Note that a lower number of layers usually leads to an increased overall width (for layout orientation top-to-bottom).

This feature works best when an instance of TopologicalLayerer is used for layer assignment. If this feature is enabled, an alignment policy that is set with setGroupAlignmentPolicy(byte) is ignored.

This property only influences the layer compactness (i.e., vertical compactness for layout orientation top-to-bottom). In order to obtain more compact group nodes with respect to the required width (i.e., horizontal compactness) use property SimplexNodePlacer.setGroupCompactionStrategy(int).

Group compaction only applies when recursive group layering is enabled. During non-recursive layering, groups are ignored completely.

Returns:

true if group compaction is active, false otherwise

See Also:

setRecursiveGroupLayeringEnabled(boolean), setGroupCompactionEnabled(boolean), SimplexNodePlacer.setGroupCompactionStrategy(int)

setGroupCompactionEnabled

public void setGroupCompactionEnabled(boolean groupCompactionEnabled)

Specifies whether or not layer compaction for recursive group layering is active.

The number of node layers is decreased if possible without reversing edge directions. The resulting layering tries to keep the layer span of a group node low (i.e., the height of a group for layout orientation top-to-bottom). Note that a lower number of layers usually leads to an increased overall width (for layout orientation top-to-bottom).

This feature works best when an instance of TopologicalLayerer is used for layer assignment. If this feature is enabled, an alignment policy that is set with setGroupAlignmentPolicy(byte) is ignored.

This property only influences the layer compactness (i.e., vertical compactness for layout orientation top-to-bottom). In order to obtain more compact group nodes with respect to the required width (i.e., horizontal compactness) use property SimplexNodePlacer.setGroupCompactionStrategy(int).

Group compaction only applies when recursive group layering is enabled. During non-recursive layering, groups are ignored completely.

Default Value:

The default value is false. The layer compaction is disabled.

Parameters:

groupCompactionEnabled - true if group compaction is active, false otherwise

See Also:

isGroupCompactionEnabled(), setRecursiveGroupLayeringEnabled(boolean), SimplexNodePlacer.setGroupCompactionStrategy(int)

Sample Graphs:

false

true

getComponentArrangementPolicy

public byte getComponentArrangementPolicy()

Returns the policy that specifies how to arrange connected components.

Returns:

one of the default component arrangement policies

See Also:

setComponentArrangementPolicy(byte)

setComponentArrangementPolicy

public void setComponentArrangementPolicy(byte policy)

Specifies the policy that specifies how to arrange connected components.

Default Value:

The default value is COMPONENT_ARRANGEMENT_TOPMOST. Connected components are aligned with their first layer.

Parameters:

policy - one of the default component arrangement policies

Throws:

java.lang.IllegalArgumentException - if the specified policy does not match a default component arrangement policy

See Also:

getComponentArrangementPolicy()

getMaximalDuration

public long getMaximalDuration()

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

Values have to be greater 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 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()

isRecursiveGroupLayeringEnabled

public boolean isRecursiveGroupLayeringEnabled()

Returns whether or not groups are respected during the layering stage.

If this option is enabled, groups are layered recursively, i.e.

• nodes in the same group always occupy adjacent layers
• layer intervals spanned by different group nodes are either disjoint or nested

If it is disabled, group information is ignored for the layering step.

If the graph is flat, this setting is ignored.

In case group compaction is enabled, groups are layered non-recursively.

Returns:

true if group information is used, false otherwise

See Also:

setRecursiveGroupLayeringEnabled(boolean), setGroupCompactionEnabled(boolean)

setRecursiveGroupLayeringEnabled

public void setRecursiveGroupLayeringEnabled(boolean recursiveGroupLayeringEnabled)

Specifies whether or not groups are respected during the layering stage.

If this option is enabled, groups are layered recursively, i.e.

• nodes in the same group always occupy adjacent layers
• layer intervals spanned by different group nodes are either disjoint or are nested

If it is disabled, group information is ignored for the layering step.

If the graph is flat, this setting is ignored.

In case group compaction is enabled, groups are layered non-recursively.

Default Value:

The default value is true. Groups are layered recursively.

Parameters:

recursiveGroupLayeringEnabled - true if group information is used, false otherwise

See Also:

isRecursiveGroupLayeringEnabled(), setGroupCompactionEnabled(boolean)

Sample Graphs:

false

true

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

isBackloopRoutingEnabled

public boolean isBackloopRoutingEnabled()

Returns whether or not reversed edges should be routed as back-loops.

When this option is enabled, back-loops attach to the same node sides as the other edges, i.e., for layout orientation top-to-bottom, they leave their source at the bottom and enter their target at the top.

Port constraints and port candidates are still considered.

This setting is ignored for edges with recursive edge styles EdgeLayoutDescriptor.RECURSIVE_EDGE_STYLE_DIRECTED and EdgeLayoutDescriptor.RECURSIVE_EDGE_STYLE_UNDIRECTED, including edges where source or target are not inside a group node.

Returns:

true if back-loop routing is applied, false otherwise

See Also:

setBackloopRoutingEnabled(boolean)

setBackloopRoutingEnabled

public void setBackloopRoutingEnabled(boolean backLoopRoutingEnabled)

Specifies whether or not reversed edges should be routed as back-loops.

When this option is enabled, back-loops attach to the same node sides as the other edges, i.e., for layout orientation top-to-bottom, they leave their source at the bottom and enter their target at the top.

Port constraints and port candidates are still considered.

This setting is ignored for edges with recursive edge styles EdgeLayoutDescriptor.RECURSIVE_EDGE_STYLE_DIRECTED and EdgeLayoutDescriptor.RECURSIVE_EDGE_STYLE_UNDIRECTED, including edges where source or target are not inside a group node.

Default Value:

The default value is false. There is no back-loop routing applied to reversed edges.

Parameters:

backLoopRoutingEnabled - true if back-loop routing should be applied, false otherwise

Sample Graphs:

false

true

isBackloopRoutingForSelfloopsEnabled

public boolean isBackloopRoutingForSelfloopsEnabled()

Returns whether or not self-loops should be routed in a similar manner as back-loops.

Self-loops will start at the bottom of their attached nodes and end at the top of them.

Port constraints and port candidates are still considered.

Back-loop routing for self-loops only applies if back-loop routing is enabled.

Returns:

true if self-loops should be routed like back-loops, false otherwise

See Also:

setBackloopRoutingForSelfloopsEnabled(boolean), isBackloopRoutingEnabled()

setBackloopRoutingForSelfloopsEnabled

public void setBackloopRoutingForSelfloopsEnabled(boolean backLoopRoutingForSelfLoopsEnabled)

Specifies whether or not self-loops should be routed in a similar manner as back-loops.

Self-loops will start at the bottom of their attached nodes and end at the top of them.

Port constraints and port candidates are still considered.

Back-loop routing for self-loops only applies if back-loop routing is enabled.

Default Value:

The default value is false. There is no back-loop routing applied to self-loops.

Parameters:

backLoopRoutingForSelfLoopsEnabled - true if self-loops should be routed like back-loops, false otherwise

See Also:

isBackloopRoutingForSelfloopsEnabled(), isBackloopRoutingEnabled()

Sample Graphs:

false

true

isAutomaticEdgeGroupingEnabled

public boolean isAutomaticEdgeGroupingEnabled()

Returns whether or not edges are grouped automatically.

The automatic edge grouping tries to group a high number of edges without changing the semantic of the graph, i.e., it groups edges either at a common source node or a common target node. Edge groupings often allow more compact layouts since grouped edges are routed in a bus-style manner.

Edges are only grouped at their source (target) node if they do not have port constraints, port candidates or port group ids (see PortConstraintKeys.SOURCE_PORT_GROUP_ID_DPKEY and PortConstraintKeys.TARGET_PORT_GROUP_ID_DPKEY) at this node. Furthermore, edges cannot be grouped at a node with specified port candidate set.

User specified edge groups are not considered.

Returns:

true if the edge grouping should be applied, false otherwise

See Also:

setAutomaticEdgeGroupingEnabled(boolean)

setAutomaticEdgeGroupingEnabled

public void setAutomaticEdgeGroupingEnabled(boolean automaticEdgeGroupingEnabled)

Specifies whether or not edges are grouped automatically.

The automatic edge grouping tries to group a high number of edges without changing the semantic of the graph, i.e., it groups edges either at a common source node or a common target node. Edge groupings often allow more compact layouts since grouped edges are routed in a bus-style manner.

Edges are only grouped at their source (target) node if they do not have port constraints, port candidates or port group ids (see PortConstraintKeys.SOURCE_PORT_GROUP_ID_DPKEY and PortConstraintKeys.TARGET_PORT_GROUP_ID_DPKEY) at this node. Furthermore, edges cannot be grouped at a node with specified port candidate set.

User specified edge groups are not considered.

Default Value:

The default value is false. Edges are not grouped automatically.

Parameters:

automaticEdgeGroupingEnabled - true if the edge grouping should be applied, false otherwise

See Also:

isAutomaticEdgeGroupingEnabled()

Sample Graphs:

false

true

setOrthogonallyRouted

public void setOrthogonallyRouted(boolean orthogonal)

Specifies whether or not edges should be routed orthogonally.

When orthogonal routing is enabled, all resulting edge paths will be composed of vertical and horizontal segments, only.

This is a convenience method that sets the routing style for the default edge layout descriptor to orthogonal.

Default Value:

The default value is false. Edges are not orthogonally routed.

Parameters:

orthogonal - true if edges are routed orthogonally, false otherwise

See Also:

isOrthogonallyRouted()

Sample Graphs:

false

true

isOrthogonallyRouted

public boolean isOrthogonallyRouted()

Returns whether or not edges should be routed orthogonally.

When orthogonal routing is enabled, all resulting edge paths will be composed of vertical and horizontal segments, only.

This is a convenience method that sets the routing style for the default edge layout descriptor to orthogonal.

Returns:

true if edges are routed orthogonally, false otherwise

See Also:

setOrthogonallyRouted(boolean)

setIntegratedEdgeLabelingEnabled

public void setIntegratedEdgeLabelingEnabled(boolean enabled)

Specifies whether or not the layout algorithm reserves space for labels and places them.

To define the desired placement for each label add a PreferredPlacementDescriptor on EdgeLabelLayout.

This method is a convenience method that assures that the labeling algorithm is of type LabelLayoutTranslator and LabelLayoutTranslator.setTranslateEdgeLabelsEnabled(boolean) is set to true.

When enabling this property, any previously specified labeling algorithm will be overwritten and when disabling it, any currently specified labeling algorithm will be disabled via property CanonicMultiStageLayouter.setLabelLayouterEnabled(boolean). Therefore, it is recommended to only use this convenience property instead of manually changing the mentioned other properties.

Default Value:

The default value is false. Integrated edge labeling is disabled.

Parameters:

enabled - true if integrated edge labeling should be enabled, false otherwise

Throws:

java.lang.IllegalStateException - if integrated labeling should be enabled but the current labeling algorithm is not of type LabelLayoutTranslator

See Also:

isIntegratedEdgeLabelingEnabled()

Sample Graphs:

disabled

true

isIntegratedEdgeLabelingEnabled

public boolean isIntegratedEdgeLabelingEnabled()

Returns whether or not the layout algorithm reserves space for labels and places them.

To define the desired placement for each label add a PreferredPlacementDescriptor on EdgeLabelLayout.

This method is a convenience method that assures that the labeling algorithm is of type LabelLayoutTranslator and LabelLayoutTranslator.setTranslateEdgeLabelsEnabled(boolean) is set to true.

When enabling this property, any previously specified labeling algorithm will be overwritten and when disabling it, any currently specified labeling algorithm will be disabled via property CanonicMultiStageLayouter.setLabelLayouterEnabled(boolean). Therefore, it is recommended to only use this convenience property instead of manually changing the mentioned other properties.

Returns:

true if integrated edge labeling is enabled, false otherwise

Throws:

java.lang.IllegalStateException - if no properly configured LabelLayoutTranslator is registered even though integrated labeling was enabled earlier (can happen when manually specifying the labeling algorithm).

See Also:

setIntegratedEdgeLabelingEnabled(boolean)

setConsiderNodeLabelsEnabled

public void setConsiderNodeLabelsEnabled(boolean enabled)

Specifies whether or not the layout algorithm considers node labels when calculating node positions to avoid overlaps.

This method is a convenience method that assures that the labeling algorithm is of type LabelLayoutTranslator and LabelLayoutTranslator.setTranslateNodeLabelsEnabled(boolean) is set to true.

Enabling this option may overwrite the current labeling algorithm. Hence, to combine this option with a generic edge labeling algorithm, the generic labeling has to be applied in an additional step after calculating the layout.

Default Value:

The default value is false. Node labels are not considered.

Parameters:

enabled - true if the layout algorithm should take the node labels into account, false otherwise

Throws:

java.lang.IllegalStateException - if this property should be enabled but the current labeling algorithm is not of type LabelLayoutTranslator

Sample Graphs:

false

true

isConsiderNodeLabelsEnabled

public boolean isConsiderNodeLabelsEnabled()

Returns whether or not the layout algorithm considers node labels when calculating node positions to avoid overlaps.

This method is a convenience method that assures that the labeling algorithm is of type LabelLayoutTranslator and LabelLayoutTranslator.setTranslateNodeLabelsEnabled(boolean) is set to true.

Enabling this option may overwrite the current labeling algorithm. Hence, to combine this option with a generic edge labeling algorithm, the generic labeling has to be applied in an additional step after calculating the layout.

Returns:

true if the layout algorithm takes the node labels into account, false otherwise

Throws:

java.lang.IllegalStateException - if no properly configured LabelLayoutTranslator is registered even though this property was enabled earlier (can happen when manually specifying the labeling algorithm).

See Also:

setConsiderNodeLabelsEnabled(boolean)

setMinimumLayerDistance

public void setMinimumLayerDistance(double distance)

Sets the minimum distance between two adjacent layers.

The specified distance should have a non-negative value.

Default Value:

The default value is 20.

Parameters:

distance - the non-negative minimum distance

Throws:

java.lang.IllegalArgumentException - if the distance is negative

See Also:

getMinimumLayerDistance()

Sample Graphs:

Layer distance 10

Layer distance 100

getMinimumLayerDistance

public double getMinimumLayerDistance()

Returns the minimum distance between two adjacent layers.

The distance should have a non-negative value.

Returns:

the non-negative minimum distance

See Also:

setMinimumLayerDistance(double)

isStopAfterLayeringEnabled

public boolean isStopAfterLayeringEnabled()

Specifies whether or not to stop the layout algorithm after the layering step.

By then, each node will be assigned to a layer. Since the sequencing and drawing phases are skipped, the order of the nodes within a layer matches the initial order of the nodes, edges won't be routed and the nodes won't get coordinates assigned.

The calculated layering information can be retrieved from the DataProvider registered with the key LAYER_VALUE_HOLDER_DPKEY.

The layout algorithm may be stopped here if only the layer assignment is important and the sequencing or the actual drawing is not needed. For example, an initial layout run may be needed to determine the layering for a second layout run that will work with this information. Then stopping after layering will save runtime.

The bounds of group nodes depend on the locations of their content and the routes of connecting edges. Therefore, they are not yet calculated after the layering phase and will have width and height 1. Similarly, rows and columns of a partition grid do not get proper computed positions and computed height/width values.

Returns:

true if the layout algorithm should stop after the layering phase, false if the complete layout should be calculated

See Also:

setStopAfterLayeringEnabled(boolean), LAYER_VALUE_HOLDER_DPKEY

setStopAfterLayeringEnabled

public void setStopAfterLayeringEnabled(boolean stopAfterLayering)

Specifies whether or not to stop the layout algorithm after the layering step.

By then, each node will be assigned to a layer. Since the sequencing and drawing phases are skipped, the order of the nodes within a layer matches the initial order of the nodes, edges won't be routed and the nodes won't get coordinates assigned.

The calculated layering information can be retrieved from the DataProvider registered with the key LAYER_VALUE_HOLDER_DPKEY.

The layout algorithm may be stopped here if only the layer assignment is important and the sequencing or the actual drawing is not needed. For example, an initial layout run may be needed to determine the layering for a second layout run that will work with this information. Then stopping after layering will save runtime.

The bounds of group nodes depend on the locations of their content and the routes of connecting edges. Therefore, they are not yet calculated after the layering phase and will have width and height 1. Similarly, rows and columns of a partition grid do not get proper computed positions and computed height/width values.

Default Value:

The default value is false. The algorithm calculates the complete layout.

Parameters:

stopAfterLayering - true if the layout algorithm should stop after the layering phase, false if the complete layout should be calculated

See Also:

LAYER_VALUE_HOLDER_DPKEY

isStopAfterSequencingEnabled

public boolean isStopAfterSequencingEnabled()

Returns whether or not to stop the layout algorithm after the sequencing step.

By then, each node will be assigned to a layer and will have a place in the sequence of nodes in this layer. Since the drawing phase is skipped, edges won't be routed and the nodes won't get coordinates assigned.

The calculated layering and sequencing information can be retrieved from the DataProviders registered with the keys LAYER_VALUE_HOLDER_DPKEY and SEQUENCE_VALUE_HOLDER_DPKEY.

The layout algorithm may be stopped here if only the location within the layers is important and the actual drawing is not needed. For example, an initial layout run may be needed to determine the layering and the sequencing for a second layout run that will work with this information. Then stopping after sequencing will save runtime.

The bounds of group nodes depend on the locations of their content and the routes of connecting edges. Therefore, they are not yet calculated after the layering phase and will have width and height 1. Similarly, rows and columns of a partition grid do not get proper computed positions and computed height/width values.

Returns:

true if the layout algorithm should stop after the sequencing phase, false if the complete layout should be calculated

See Also:

setStopAfterSequencingEnabled(boolean), SEQUENCE_VALUE_HOLDER_DPKEY, LAYER_VALUE_HOLDER_DPKEY

setStopAfterSequencingEnabled

public void setStopAfterSequencingEnabled(boolean stopAfterSequencing)

Specifies whether or not to stop the layout algorithm after the sequencing step.

By then, each node will be assigned to a layer and will have a place in the sequence of nodes in this layer. Since the drawing phase is skipped, edges won't be routed and the nodes won't get coordinates assigned.

The calculated layering and sequencing information can be retrieved from the DataProviders registered with the keys LAYER_VALUE_HOLDER_DPKEY and SEQUENCE_VALUE_HOLDER_DPKEY.

The layout algorithm may be stopped here if only the location within the layers is important and the actual drawing is not needed. For example, an initial layout run may be needed to determine the layering and the sequencing for a second layout run that will work with this information. Then stopping after sequencing will save runtime.

The bounds of group nodes depend on the locations of their content and the routes of connecting edges. Therefore, they are not yet calculated after the layering phase and will have width and height 1. Similarly, rows and columns of a partition grid do not get proper computed positions and computed height/width values.

Default Value:

The default value is false. The algorithm calculates the complete layout.

Parameters:

stopAfterSequencing - true if the layout algorithm should stop after the sequencing phase, false if the complete layout should be calculated

See Also:

SEQUENCE_VALUE_HOLDER_DPKEY, LAYER_VALUE_HOLDER_DPKEY

setNodeToNodeDistance

public void setNodeToNodeDistance(double distance)

Sets the minimum distance between two adjacent nodes in one layer.

All values have to be greater than or equal to 0.

If nodes should use different distances, you can map them to different NodeLayoutDescriptor instances (see HierarchicLayouter.NODE_LAYOUT_DESCRIPTOR_DPKEY) with custom minimum distance values.

Default Value:

The default value is 30.

Parameters:

distance - the non-negative minimum distance

Throws:

java.lang.IllegalArgumentException - if the distance is negative

java.lang.IllegalStateException - if the current DrawingDistanceCalculator is not an instance of DefaultDrawingDistanceCalculator

See Also:

getNodeToNodeDistance()

Sample Graphs:

Node distance 10

Node distance 100

getNodeToNodeDistance

public double getNodeToNodeDistance()

Returns the minimum distance between two adjacent nodes in one layer.

All values have to be greater than or equal to 0.

If nodes should use different distances, you can map them to different NodeLayoutDescriptor instances (see HierarchicLayouter.NODE_LAYOUT_DESCRIPTOR_DPKEY) with custom minimum distance values.

Returns:

the non-negative minimum distance

See Also:

setNodeToNodeDistance(double)

setNodeToEdgeDistance

public void setNodeToEdgeDistance(double d)

Sets the minimum distance between an edge and an adjacent node in one layer.

All values have to be greater than or equal to 0.

If nodes/edges should use different distances, you can map them to different NodeLayoutDescriptor /EdgeLayoutDescriptor instances (see HierarchicLayouter.NODE_LAYOUT_DESCRIPTOR_DPKEY and HierarchicLayouter.EDGE_LAYOUT_DESCRIPTOR_DPKEY) with custom minimum distance values.

Default Value:

The default value is 15.

Parameters:

d - the non-negative minimum distance

Throws:

java.lang.IllegalArgumentException - if the distance is negative

java.lang.IllegalStateException - if the current DrawingDistanceCalculator is not an instance of DefaultDrawingDistanceCalculator

See Also:

getNodeToEdgeDistance()

Sample Graphs:

Node-edge distance 10

Node-edge distance 100

getNodeToEdgeDistance

public double getNodeToEdgeDistance()

Returns the minimum distance between an edge and an adjacent node in one layer.

All values have to be greater than or equal to 0.

If nodes/edges should use different distances, you can map them to different NodeLayoutDescriptor /EdgeLayoutDescriptor instances (see HierarchicLayouter.NODE_LAYOUT_DESCRIPTOR_DPKEY and HierarchicLayouter.EDGE_LAYOUT_DESCRIPTOR_DPKEY) with custom minimum distance values.

Returns:

the non-negative minimum distance

See Also:

setNodeToEdgeDistance(double)

setEdgeToEdgeDistance

public void setEdgeToEdgeDistance(double distance)

Sets the minimum distance between two directly consecutive edges that pass through the same layer. More precisely, the specified value is the minimum distance between the two vertical segments of these edges that traverse the layer. The algorithm does not consider this value if the layer contains other elements lying between the two edges (e.g., nodes or group node borders).

All values have to be greater than or equal to 0.

If edges should use different distances, you can map them to different EdgeLayoutDescriptor instances (see HierarchicLayouter.EDGE_LAYOUT_DESCRIPTOR_DPKEY) with custom minimum distance values.

Default Value:

The default value is 20.

Parameters:

distance - the non-negative minimum distance

Throws:

java.lang.IllegalArgumentException - if the distance is negative

java.lang.IllegalStateException - if the current DrawingDistanceCalculator is not an instance of DefaultDrawingDistanceCalculator

See Also:

getEdgeToEdgeDistance()

Sample Graphs:

Edge distance 10

Edge distance 100

getEdgeToEdgeDistance

public double getEdgeToEdgeDistance()

Returns the minimum distance between two directly consecutive edges that pass through the same layer. More precisely, the specified value is the minimum distance between the two vertical segments of these edges that traverse the layer. The algorithm does not consider this value if the layer contains other elements lying between the two edges (e.g., nodes or group node borders).

All values have to be greater than or equal to 0.

If edges should use different distances, you can map them to different EdgeLayoutDescriptor instances (see HierarchicLayouter.EDGE_LAYOUT_DESCRIPTOR_DPKEY) with custom minimum distance values.

Returns:

the non-negative minimum distance

See Also:

setEdgeToEdgeDistance(double)

setLayerSeparationEnabled

public void setLayerSeparationEnabled(boolean layerSeparationEnabled)

Specifies whether or not to separate layers.

In case layers are not separated, nodes of a layer may extend into adjacent layers. Otherwise, nodes of different layers are strictly separated, i.e., layers are placed below each other.

The alignment of nodes within their layer is not affected by this property.

Default Value:

The default value is true. Layers are separated.

Parameters:

layerSeparationEnabled - true if layers should be separated, false otherwise

Sample Graphs:

true

false

isLayerSeparationEnabled

public boolean isLayerSeparationEnabled()

Returns whether or not to separate layers.

In case layers are not separated, nodes of a layer may extend into adjacent layers. Otherwise, nodes of different layers are strictly separated, i.e., layers are placed below each other.

The alignment of nodes within their layer is not affected by this property.

Returns:

true if layers are separated, false otherwise

See Also:

setLayerSeparationEnabled(boolean)

getDefaultDrawingDistanceCalculator

protected DefaultDrawingDistanceCalculator getDefaultDrawingDistanceCalculator()

Returns the DefaultDrawingDistanceCalculator that is registered with the layout algorithm by default.

Returns:

the current DefaultDrawingDistanceCalculator instance

Throws:

java.lang.IllegalStateException - if the current instance returned by HierarchicLayouter.getDrawingDistanceCalculator() is not an instance of DefaultDrawingDistanceCalculator

createHierarchicLayouter

protected HierarchicLayouter createHierarchicLayouter()

Returns a new HierarchicLayouter instance.

This method may be overridden to create a new HierarchicLayouter object with different configuration settings.

This factory method provides the initial HierarchicLayouter instance.

Returns:

a new HierarchicLayouter instance

getHierarchicLayouter

public HierarchicLayouter getHierarchicLayouter()

Returns the current layout algorithm instance.

By default, this method will return a HierarchicLayouter instance created with createHierarchicLayouter().

Returns:

the HierarchicLayouter instance

See Also:

createHierarchicLayouter()

setFromScratchLayeringStrategy

public void setFromScratchLayeringStrategy(byte strategy)

Specifies a predefined layering strategy for the from scratch layerer.

The layouter assigns the nodes to separate layers. The nodes within each layer will be placed on the same horizontal layer. The layers will be arranged vertically starting with the small-numbered layers.

An important layering strategy for the hierarchic layout style is called Hierarchical Layering. A hierarchical layering tries to assign nodes to layers in a way such that as much edges of the graph as possible will point to the main layout direction, i.e., the start nodes of the edges will be in a layer with a smaller number than the corresponding end nodes. Also, a hierarchical layering will never put two connected nodes in the same layer.

This method wraps the internal implementations into a MultiComponentLayerer instance so that it is possible to specify the behavior of the algorithm if the component layouter is disabled.

Default Value:

The default value is LAYERING_STRATEGY_HIERARCHICAL_OPTIMAL

Parameters:

strategy - one of the predefined layering strategies

Throws:

java.lang.IllegalArgumentException - if an unknown strategy is given

See Also:

getFromScratchLayeringStrategy()

getFromScratchLayeringStrategy

public byte getFromScratchLayeringStrategy()

Returns a predefined layering strategy for the from scratch layerer.

The layouter assigns the nodes to separate layers. The nodes within each layer will be placed on the same horizontal layer. The layers will be arranged vertically starting with the small-numbered layers.

An important layering strategy for the hierarchic layout style is called Hierarchical Layering. A hierarchical layering tries to assign nodes to layers in a way such that as much edges of the graph as possible will point to the main layout direction, i.e., the start nodes of the edges will be in a layer with a smaller number than the corresponding end nodes. Also, a hierarchical layering will never put two connected nodes in the same layer.

This method wraps the internal implementations into a MultiComponentLayerer instance so that it is possible to specify the behavior of the algorithm if the component layouter is disabled.

Returns:

one of the predefined layering strategies

See Also:

setFromScratchLayeringStrategy(byte)

getOriginalEdge

public static Edge getOriginalEdge(Edge edge,
                                   LayoutDataProvider layoutDataProvider)

Returns the corresponding original edge instance for a given edge.

This convenience method allows to retrieve the original edge - which is part of the input graph - when customizing the hierarchic layout algorithm and dealing with potentially artificial dummy edges which are inserted during the hierarchical layout procedure.

If the given edge is already an original edge, it will immediately be returned.

Parameters:

edge - the edge for which the original input edge is retrieved

layoutDataProvider - the layout data provider holding layout information of the hierarchical layout

Returns:

the original input edge corresponding to the given edge

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

doLayout

public void doLayout(LayoutGraph graph)

Calculates a hierarchic layout of the given graph.

Specified by:

doLayout in interface Layouter

Overrides:

doLayout 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

See Also:

CanonicMultiStageLayouter.appendStage(LayoutStage), CanonicMultiStageLayouter.prependStage(LayoutStage), CanonicMultiStageLayouter.doLayoutCore(LayoutGraph)

doLayoutCore

public void doLayoutCore(LayoutGraph graph)

Delegates the calculation of the hierarchic layout to a configured HierarchicLayouter instance.

IncrementalHierarchicLayouter applies its own configuration to HierarchicLayouter and also prepares the graph for layout.

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

getMirrorMask

protected int getMirrorMask()

Returns the mirror mask of the orientation layouter.

It may be overridden in order to configure a different mirror mask.

Returns:

the mirror mask

configureCoreLayout

protected void configureCoreLayout(LayoutGraph graph,
                                   HierarchicLayouter coreLayouter)

Configures the core layout algorithm with the settings of this IncrementalHierarchicLayouter instance.

This method is called by doLayoutCore(LayoutGraph) before the actual layout is calculated. It may be overridden in order to manually reconfigure the core layout algorithm.

This implementation will temporarily set a PCListOptimizer if a DataProvider is registered with PortCandidateSet.NODE_DP_KEY and no HierarchicLayouter.getPortConstraintOptimizer() is assigned.

Everything that is added to the graph or the core layout algorithm needs to be removed in unconfigureCoreLayout(LayoutGraph, HierarchicLayouter).

Parameters:

graph - the input graph

coreLayouter - the given core layout algorithm instance

unconfigureCoreLayout

protected void unconfigureCoreLayout(LayoutGraph graph,
                                     HierarchicLayouter coreLayouter)

Disposes of the core layout algorithm.

This method is called by doLayoutCore(LayoutGraph) after the actual layout is calculated. It may be overridden in order to revert a custom configuration made in configureCoreLayout(LayoutGraph, HierarchicLayouter).

This implementation will remove the PCListOptimizer that was created in case a DataProvider is registered with PortCandidateSet.NODE_DP_KEY and no HierarchicLayouter.getPortConstraintOptimizer() was initially assigned.

Everything that was added to the graph or the core layout algorithm in configureCoreLayout(LayoutGraph, HierarchicLayouter) needs to be removed here.

Parameters:

graph - the input graph

coreLayouter - the given core layout algorithm instance

createIncrementalHintsFactory

public IncrementalHintsFactory createIncrementalHintsFactory()

Returns a IncrementalHintsFactory instance that must be used to obtain hints to be associated with graph elements that should be laid out incrementally.

Use this factory and a DataProvider that is registered to the graph using the INCREMENTAL_HINTS_DPKEY key to associate appropriate hints with the graph elements that should be laid out incrementally by the algorithm.

Returns:

a new IncrementalHintsFactory instance

See Also:

HierarchicLayouter.createIncrementalHintsFactory(), INCREMENTAL_HINTS_DPKEY, Graph.addDataProvider(Object,DataProvider), setLayoutMode(byte), LAYOUT_MODE_INCREMENTAL

createSequenceConstraintFactory

public SequenceConstraintFactory createSequenceConstraintFactory(LayoutGraph graph)

Returns a SequenceConstraintFactory instance that can be used for specifying sequence constraints for the given graph.

For these sequence constraints to have any effect, the Sequencer that determines the in-layer node order (sequence) has to support constraints. Both, DefaultLayerSequencer and the incremental sequencer used internally support sequence constraints.

You can create a SequenceConstraintFactory without binding it to a graph instance initially by passing a null parameter. In that case, you must bind the returned instance to the graph instance before calculating a layout:

   IncrementalHierarchicLayouter ihl = ...;
   SequenceConstraintFactory cf = ihl.createSequenceConstraintFactory(null);
   ...
   Graph g = ...;
   g.addDataProvider(SequenceConstraintFactory.SEQUENCE_CONSTRAINTS_MEMENTO_DPKEY,
   DataProviders.createConstantDataProvider(cf.getMemento()));
   //Calculate layout
 

SequenceConstraintFactory instances have to be disposed of after use. Disposing of the factory will also remove all constraints previously specified for the factory's associated graph. Creating sequence constraints with a disposed of factory will throw an IllegalStateException.

Parameters:

graph - the input graph

Returns:

a SequenceConstraintFactory instance

See Also:

setFromScratchSequencer(Sequencer), setFixedElementsSequencer(Sequencer)

Sample Graphs:

A graph laid out with IncrementalHierarchicLayouter with default settings. The labels indicate the desired placement of certain nodes relative to a reference node.

After defining appropriate sequence constraints and running the layout again, the labeled nodes now have their intended placement.

createLayerConstraintFactory

public LayerConstraintFactory createLayerConstraintFactory(Graph graph)

Returns a LayerConstraintFactory instance that can be used for specifying layer constraints for the given graph.

The instance is usually bound to Graph instance graph, i.e., if the input graph for the layerer changes, a new instance must be retrieved. This instance can be used for creating constraints for this graph instance.

You can create an instance without binding it to a graph instance initially by passing a null parameter. In that case, you must bind the returned instance to the graph, see LayerConstraintFactory.LAYER_CONSTRAINTS_MEMENTO_DPKEY and LayerConstraintFactory.getMemento().

LayerConstraintFactory instances have to be disposed after use. Disposing the factory will also remove all constraints previously specified for the factory's associated graph. Creating layering constraints with a disposed factory will throw an IllegalStateException.

Parameters:

graph - the input graph

Returns:

a new LayerConstraintFactory instance

Sample Graphs:

A graph laid out with IncrementalHierarchicLayouter with default settings. The labels indicate the desired placement of certain nodes relative to a reference node.

After defining appropriate layer constraints and running the layout again, the labeled nodes now have their intended placement.

getFromScratchLayerer

public Layerer getFromScratchLayerer()

Returns the Layerer instance that obtains the layering for the nodes if the layout algorithm runs in From Scratch mode.

If the graph consists of multiple components, then the Layerer instance should be wrapped in MultiComponentLayerer.

Returns:

the Layerer instance

See Also:

setFromScratchLayerer(Layerer), setLayoutMode(byte)

setFromScratchLayerer

public void setFromScratchLayerer(Layerer layerer)

Specifies the Layerer instance that obtains the layering for the nodes if the layout algorithm runs in From Scratch mode.

If the graph consists of multiple components, then the Layerer instance should be wrapped in MultiComponentLayerer.

Default Value:

The default value is WeightedLayerer

Parameters:

layerer - the Layerer instance

Throws:

java.lang.IllegalArgumentException - if the Layerer is null

See Also:

setLayoutMode(byte)

getFromScratchSequencer

public Sequencer getFromScratchSequencer()

Returns the Sequencer instance that calculates the node sequence if the layout algorithm runs in From Scratch mode.

Returns:

the Sequencer instance

See Also:

getFromScratchLayerer(), setLayoutMode(byte), setFromScratchSequencer(Sequencer)

setFromScratchSequencer

public void setFromScratchSequencer(Sequencer sequencer)

Specifies the Sequencer instance that calculates the node sequence if the layout algorithm runs in From Scratch mode.

Default Value:

The default value is DefaultLayerSequencer

Parameters:

sequencer - the Sequencer instance

Throws:

java.lang.IllegalArgumentException - if the Sequencer is null

See Also:

setFromScratchLayerer(Layerer), setLayoutMode(byte)

getNodePlacer

public NodePlacer getNodePlacer()

Returns the NodePlacer instance that will calculate the final node placement of the layout.

Returns:

the NodePlacer instance

See Also:

setNodePlacer(NodePlacer)

setNodePlacer

public void setNodePlacer(NodePlacer nodePlacer)

Specifies the NodePlacer instance that will calculate the final node placement of the layout.

Default Value:

The default value is SimplexNodePlacer

Parameters:

nodePlacer - the NodePlacer instance

Throws:

java.lang.IllegalArgumentException - if the NodePlacer is null

See Also:

getNodePlacer()

getFixedElementsLayerer

public Layerer getFixedElementsLayerer()

Returns the Layerer instance that obtains the layering for fixed nodes during the incremental layout run.

Returns:

the Layerer instance used for fixed nodes

See Also:

setFixedElementsLayerer(Layerer), setLayoutMode(byte)

setFixedElementsLayerer

public void setFixedElementsLayerer(Layerer fixedElementsLayerer)

Specifies the Layerer instance that obtains the layering for fixed nodes during the incremental layout run.

Default Value:

The default value is AsIsLayerer

Parameters:

fixedElementsLayerer - the Layerer instance used for fixed nodes

Throws:

java.lang.IllegalArgumentException - if the Layerer is null

See Also:

setLayoutMode(byte)

getFixedElementsSequencer

public Sequencer getFixedElementsSequencer()

Returns the Sequencer instance that calculates the sequence of the fixed nodes during the incremental layout run.

Returns:

the Sequencer instance used for fixed elements

See Also:

setFixedElementsSequencer(Sequencer), setLayoutMode(byte)

setFixedElementsSequencer

public void setFixedElementsSequencer(Sequencer fixedElementsSequencer)

Specifies the Sequencer instance that calculates the sequence of the fixed nodes during the incremental layout run.

Default Value:

The default value is AsIsSequencer

Parameters:

fixedElementsSequencer - the Sequencer instance used for fixed elements

Throws:

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

See Also:

setLayoutMode(byte)

getLayoutMode

public byte getLayoutMode()

Returns the layout mode this layouter should use for upcoming layouts.

Depending on the mode the layout algorithm will use different Layerer and Sequencer implementations.

Returns:

the new layout mode

See Also:

setLayoutMode(byte), getFromScratchLayerer(), getFromScratchSequencer(), getFixedElementsLayerer(), getFixedElementsSequencer()

setLayoutMode

public void setLayoutMode(byte layoutMode)

Specifies the layout mode this layouter should use for upcoming layouts.

Depending on the mode the layout algorithm will use different Layerer and Sequencer implementations.

Default Value:

The default value is LAYOUT_MODE_FROM_SCRATCH

Parameters:

layoutMode - the new layout mode

Throws:

java.lang.IllegalArgumentException - if the given layout mode is unknown

See Also:

getLayoutMode(), getFromScratchLayerer(), getFromScratchSequencer(), getFixedElementsLayerer(), getFixedElementsSequencer()

createEdgeLayoutDescriptor

protected EdgeLayoutDescriptor createEdgeLayoutDescriptor()

Returns a new EdgeLayoutDescriptor instance that will be used during the various phases of the layout algorithm to determine the drawing details of the edges of the graph.

This method may be overridden to create a new EdgeLayoutDescriptor instance with different configuration settings.

Returns:

a new EdgeLayoutDescriptor instance

getEdgeLayoutDescriptor

public EdgeLayoutDescriptor getEdgeLayoutDescriptor()

Returns the EdgeLayoutDescriptor instance used for all those edges that do not have a specific layout descriptor assigned.

By default, this method will return a EdgeLayoutDescriptor instance created with createEdgeLayoutDescriptor().

Returns:

the current EdgeLayoutDescriptor instance

See Also:

setEdgeLayoutDescriptor(EdgeLayoutDescriptor), HierarchicLayouter.EDGE_LAYOUT_DESCRIPTOR_DPKEY

setEdgeLayoutDescriptor

public void setEdgeLayoutDescriptor(EdgeLayoutDescriptor edgeLayoutDescriptor)

Specifies the EdgeLayoutDescriptor instance used for all those edges that do not have a specific layout descriptor assigned.

Default Value:

The default value is EdgeLayoutDescriptor

Parameters:

edgeLayoutDescriptor - the current EdgeLayoutDescriptor instance

Throws:

java.lang.IllegalArgumentException - if the EdgeLayoutDescriptor is null

See Also:

HierarchicLayouter.EDGE_LAYOUT_DESCRIPTOR_DPKEY

createNodeLayoutDescriptor

protected NodeLayoutDescriptor createNodeLayoutDescriptor()

Returns a new NodeLayoutDescriptor instance that will be used during the various phases of the layout algorithm to determine the drawing details of the nodes of the graph.

This method may be overridden to create a new NodeLayoutDescriptor instance with different configuration settings.

Returns:

a new NodeLayoutDescriptor instance

getNodeLayoutDescriptor

public NodeLayoutDescriptor getNodeLayoutDescriptor()

Returns the NodeLayoutDescriptor instance used for all those nodes that do not have a specific layout descriptor assigned.

By default, this method will return a NodeLayoutDescriptor instance created with createNodeLayoutDescriptor().

Returns:

the current NodeLayoutDescriptor instance

See Also:

setNodeLayoutDescriptor(NodeLayoutDescriptor), HierarchicLayouter.NODE_LAYOUT_DESCRIPTOR_DPKEY, createNodeLayoutDescriptor()

setNodeLayoutDescriptor

public void setNodeLayoutDescriptor(NodeLayoutDescriptor nodeLayoutDescriptor)

Specifies the NodeLayoutDescriptor instance used for all those nodes that do not have a specific layout descriptor assigned.

Default Value:

The default value is NodeLayoutDescriptor

Parameters:

nodeLayoutDescriptor - the current NodeLayoutDescriptor instance

Throws:

java.lang.IllegalArgumentException - if the given NodeLayoutDescriptor is null

See Also:

HierarchicLayouter.NODE_LAYOUT_DESCRIPTOR_DPKEY, createNodeLayoutDescriptor()