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 class is a variant of the classic HierarchicLayouter implementation. It serves as a facade to HierarchicLayouter.

Instances can be used to simply 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 its mode to LAYOUT_MODE_INCREMENTAL and add a DataProvider (e.g. use Maps.createHashedDataMap()) using the INCREMENTAL_HINTS_DPKEY DataProvider key to the graph and associate the marks obtained from the IncrementalHintsFactory with the elements to be added incrementally.

Many settings of the layout can be controlled using the EdgeLayoutDescriptor and NodeLayoutDescriptor instances. The ones that are used during the layout run can be obtained from getEdgeLayoutDescriptor() and getNodeLayoutDescriptor() respectively.
If at the time of the invocation DataProvider instances are bound to the graph using either the HierarchicLayouter.EDGE_LAYOUT_DESCRIPTOR_DPKEY or HierarchicLayouter.NODE_LAYOUT_DESCRIPTOR_DPKEY keys, they will be wrapped and whenever they do not provide values the ones set in this instance will be used as fall-back values.

Here is a sample layout output:

The following example shows the result of an incremental layout with lots of port constraints (For clarity colored layers have been added to the diagram):

The last example shows the result of a layout run that considered swim lanes. Nodes with the same label have been placed into the same swim lane. Swim lanes have been ordered in ascending order of the label names. (For clarity lines have been added to the diagram that depict the bounds of the swim lanes):

See Also:

setLayoutMode(byte), INCREMENTAL_HINTS_DPKEY, createIncrementalHintsFactory(), HierarchicLayouter

Field Summary

static byte	COMPONENT_ARRANGEMENT_COMPACT Component arrangement constant that can be used in setComponentArrangementPolicy(byte)}.
static byte	COMPONENT_ARRANGEMENT_TOPMOST Component arrangement constant that can be used in setComponentArrangementPolicy(byte)}.
static Object	CRITICAL_EDGE_DPKEY DataProvider key used to store the priority (integer values) for "critical" edges.
static Object	INCREMENTAL_HINTS_DPKEY DataProvider key used to store incremental layout hints that can be retrieved from the IncrementalHintsFactory which itself can be obtained from the createIncrementalHintsFactory() method.
static Object	LAYER_VALUE_HOLDER_DPKEY Used for publishing the final layering information.
static byte	LAYERING_STRATEGY_BFS Layering strategy specifier.
static byte	LAYERING_STRATEGY_FROM_SKETCH Layering strategy specifier.
static byte	LAYERING_STRATEGY_HIERARCHICAL_DOWNSHIFT Layering strategy specifier.
static byte	LAYERING_STRATEGY_HIERARCHICAL_OPTIMAL Layering strategy specifier.
static byte	LAYERING_STRATEGY_HIERARCHICAL_TIGHT_TREE Layering strategy specifier.
static byte	LAYERING_STRATEGY_HIERARCHICAL_TOPMOST Layering strategy constant.
static byte	LAYERING_STRATEGY_UNKNOWN Dummy layering strategy specifier.
static byte	LAYERING_STRATEGY_USER_DEFINED Layering strategy specifier.
static byte	LAYOUT_MODE_FROM_SCRATCH Layout mode constant that can be used in setLayoutMode(byte).
static byte	LAYOUT_MODE_INCREMENTAL Layout mode constant that can be used in setLayoutMode(byte).
static byte	POLICY_ALIGN_GROUPS_BOTTOM Group layering alignment strategy specifier.
static byte	POLICY_ALIGN_GROUPS_CENTER Group layering alignment strategy specifier.
static byte	POLICY_ALIGN_GROUPS_TOP Group layering alignment strategy specifier.
static Object	SEQUENCE_VALUE_HOLDER_DPKEY Used for publishing the final sequencing information.
static Object	SWIMLANE_DESCRIPTOR_DPKEY DataProvider key used to store SwimLaneDescriptor instances for each node in the graph.

Fields inherited from interface y.layout.Layouter

EDGE_ID_DPKEY, NODE_ID_DPKEY, SELECTED_EDGES, SELECTED_NODES

Constructor Summary

IncrementalHierarchicLayouter()
Creates a new IncrementalHierarchicLayouter instance which is set to LAYOUT_MODE_FROM_SCRATCH initially

Method Summary

boolean	canLayoutCore(LayoutGraph graph) Determines whether this layouter can perform the core layout on the given graph.
protected void	configureCoreLayout(LayoutGraph graph, HierarchicLayouter ihl) Called before the actual layout is performed.
protected EdgeLayoutDescriptor	createEdgeLayoutDescriptor() Factory method that creates the default EdgeLayoutDescriptor.
protected HierarchicLayouter	createHierarchicLayouter() Factory method that creates the internally used HierarchicLayouter instance.
IncrementalHintsFactory	createIncrementalHintsFactory() Returns a IncrementalHintsFactory instance that must be used to obtain marks that can be associated with elements in the graph that will be laid out incrementally.
LayerConstraintFactory	createLayerConstraintFactory(Graph graph) Returns a LayerConstraintFactory instance that can be used to specify layer constraints for the given graph.
protected NodeLayoutDescriptor	createNodeLayoutDescriptor() Factory method that creates the default NodeLayoutDescriptor.
SequenceConstraintFactory	createSequenceConstraintFactory(LayoutGraph graph) Returns a SequenceConstraintFactory instance that can be used to specify sequence constraints for the given graph.
void	doLayoutCore(LayoutGraph g) Performs the actual layout using the currently set mode.
byte	getComponentArrangementPolicy() Returns the policy that is used 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 adjacent edges in one layer.
Layerer	getFixedElementsLayerer() Returns the Layerer instance that is used to obtain the layering for those nodes that are not marked to be laid out incrementally if the layouter is set to LAYOUT_MODE_INCREMENTAL.
Sequencer	getFixedElementsSequencer() Returns the Sequencer instance that is used to calculated the sequence of the nodes that are not marked to be laid out incrementally if the layouter is set to LAYOUT_MODE_INCREMENTAL.
Layerer	getFromScratchLayerer() Returns the Layerer instance that is used to obtain the layering for the nodes if the layouter is set to LAYOUT_MODE_FROM_SCRATCH.
byte	getFromScratchLayeringStrategy() Returns the currently set layering strategy for the from scratch layering.
Sequencer	getFromScratchSequencer() Returns the Sequencer instance that is used to calculate the node sequence if the layouter is set to LAYOUT_MODE_FROM_SCRATCH.
byte	getGroupAlignmentPolicy() Get the group layer alignment strategy used for recursive group layering.
HierarchicLayouter	getHierarchicLayouter() Returns the internally used HierarchicLayouter instance.
byte	getLayoutMode() Returns the layout mode this layouter is currently in.
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 orientation layouter's mirror mask.
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 be used to calculated the final node placement of the layout.
double	getNodeToEdgeDistance() Returns the minimum distance between two adjacent nodes in one layer.
double	getNodeToNodeDistance() Returns the minimum distance between two adjacent nodes in one layer.
boolean	isAutomaticEdgeGroupingEnabled() Whether or not automatic edge grouping should be applied.
boolean	isBackloopRoutingEnabled() Whether or not backloop routing should be applied.
boolean	isConsiderNodeLabelsEnabled() Returns whether or not node labels are taken into account when calculating node positions (thereby preventing possible node/node label or node label/node label overlaps).
boolean	isGroupCompactionEnabled() Return whether layer compaction for recursive group layering is active.
boolean	isIntegratedEdgeLabelingEnabled() Returns whether integrated edge labeling is enabled.
boolean	isOrthogonallyRouted() Returns whether or not edges should be routed orthogonally.
boolean	isRecursiveGroupLayeringEnabled() Return whether groups are respected during the layering stage.
void	setAutomaticEdgeGroupingEnabled(boolean automaticEdgeGroupingEnabled) If this option is set, edges are grouped automatically.
void	setBackloopRoutingEnabled(boolean backloopRoutingEnabled) If this option is set, reversed edges are routed in a backloop style, i.e., such that they attach to the same vertex sides as the other edges.
void	setComponentArrangementPolicy(byte policy) Sets the policy used for arranging connected components.
void	setConsiderNodeLabelsEnabled(boolean enabled) Specifies whether or not to consider node labels when calculating node positions (thereby preventing possible node/node label or node label/node label overlaps).
void	setEdgeLayoutDescriptor(EdgeLayoutDescriptor edgeLayoutDescriptor) Sets the EdgeLayoutDescriptor instance used for all those edges, that do not have a specific layout descriptor assigned.
void	setEdgeToEdgeDistance(double d) Sets the minimum distance between two adjacent edges in one layer.
void	setFixedElementsLayerer(Layerer fixedElementsLayerer) Sets the Layerer instance that is used to obtain the layering for those nodes that are not marked to be laid out incrementally if the layouter is set to LAYOUT_MODE_INCREMENTAL.
void	setFixedElementsSequencer(Sequencer fixedElementsSequencer) Sets the Sequencer instance that is used to calculated the sequence of the nodes that are not marked to be laid out incrementally if the layouter is set to LAYOUT_MODE_INCREMENTAL.
void	setFromScratchLayerer(Layerer layerer) Sets the Layerer instance that is used to obtain the layering for the nodes if the layouter is set to LAYOUT_MODE_FROM_SCRATCH.
void	setFromScratchLayeringStrategy(byte strategy) Convenience method that sets a predefined layering strategy for the from scratch layerer.
void	setFromScratchSequencer(Sequencer sequencer) Sets the Sequencer instance that is used to calculate the node sequence if the layouter is set to LAYOUT_MODE_FROM_SCRATCH.
void	setGroupAlignmentPolicy(byte groupAlignmentPolicy) Set the group layer alignment strategy used for recursive group layering.
void	setGroupCompactionEnabled(boolean groupCompactionEnabled) Set whether layer compaction for recursive group layering should be used.
void	setIntegratedEdgeLabelingEnabled(boolean enabled) Specifies whether or not to use integrated edge labeling.
void	setLayoutMode(byte layoutMode) Sets the layout mode this layouter should use for upcoming layouts.
void	setMaximalDuration(long maximalDuration) Sets a preferred time limit (in milliseconds) for the layout algorithm.
void	setMinimumLayerDistance(double d) Sets the minimum distance between two adjacent layers.
void	setNodeLayoutDescriptor(NodeLayoutDescriptor nodeLayoutDescriptor) Sets the NodeLayoutDescriptor instance used for all those nodes, that do not have a specific layout descriptor assigned.
void	setNodePlacer(NodePlacer nodePlacer) Sets the NodePlacer instance that will be used to calculated 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 d) Sets the minimum distance between two adjacent nodes in one layer.
void	setOrthogonallyRouted(boolean orthogonal) Determines whether or not edges should be routed orthogonally.
void	setRecursiveGroupLayeringEnabled(boolean recursiveGroupLayeringEnabled) Specifies whether groups are respected during the layering stage.
protected void	unconfigureCoreLayout(LayoutGraph graph, HierarchicLayouter ihl) Called after the actual layout is performed.

Methods inherited from class y.layout.CanonicMultiStageLayouter

appendStage, calcLayout, calcLayout, canLayout, checkGroupNodeSize, checkNodeSize, doLayout, 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

CRITICAL_EDGE_DPKEY

public static final Object CRITICAL_EDGE_DPKEY

DataProvider key used to store the priority (integer values) for "critical" edges. The layouter tries to vertically align each node pair that is connected by a critical edge (integer value > 0). This feature can for example be utilized to highlight different edge paths that are relevant for a user. Conflicts between different critical edges are always resolved in favor of the higher priority. Note: "critical" edges do no affect the result of the crossing minimization (Sequencer) phase. Hence, there may be crossings between two "critical" edges.

INCREMENTAL_HINTS_DPKEY

public static final Object INCREMENTAL_HINTS_DPKEY

DataProvider key used to store incremental layout hints that can be retrieved from the IncrementalHintsFactory which itself can be obtained from the createIncrementalHintsFactory() method.

See Also:

HierarchicLayouter.INCREMENTAL_HINTS_DPKEY

LAYER_VALUE_HOLDER_DPKEY

public static final Object LAYER_VALUE_HOLDER_DPKEY

Used for publishing the final layering information. If the DataProvider associated to this key is also a DataAcceptor, the integer layer id of each node is stored using the acceptor's setInt method. Otherwise, the provider's values should be of type IntValueHolder and the value holder's setValue method is used to store the integer layer ids of each node.

See Also:

HierarchicLayouter.LAYER_VALUE_HOLDER_DPKEY

SEQUENCE_VALUE_HOLDER_DPKEY

public static final Object SEQUENCE_VALUE_HOLDER_DPKEY

Used for publishing the final sequencing information. If the DataProvider associated to this key is also a DataAcceptor, the sequence order number of each node is stored using the acceptor's setInt method. Otherwise, the provider's values should be of type IntValueHolder and the value holder's setValue method is used to store the sequence order number of each node.

See Also:

HierarchicLayouter.SEQUENCE_VALUE_HOLDER_DPKEY

SWIMLANE_DESCRIPTOR_DPKEY

public static final Object SWIMLANE_DESCRIPTOR_DPKEY

DataProvider key used to store SwimLaneDescriptor instances for each node in the graph. If this key is present during the layout. The layout algorithm will arrange nodes in swim lanes. The information about the swim lanes is finally written back into the descriptor instances. Instances can be shared among multiple nodes in the same lane, but don't have to be shared.

See Also:

HierarchicLayouter.SWIMLANE_DESCRIPTOR_DPKEY

COMPONENT_ARRANGEMENT_COMPACT

public static final byte COMPONENT_ARRANGEMENT_COMPACT

Component arrangement constant that can be used in setComponentArrangementPolicy(byte)}. If the graph consists of multiple components this constant specifies that, after layering the single components with the core layerer, the components will all be merged such that an 1:1 aspect ratio is fulfilled best.

See Also:

setComponentArrangementPolicy(byte), getComponentArrangementPolicy(), Constant Field Values

COMPONENT_ARRANGEMENT_TOPMOST

public static final byte COMPONENT_ARRANGEMENT_TOPMOST

Component arrangement constant that can be used in setComponentArrangementPolicy(byte)}. If the graph consists of multiple components this constant specifies that, after layering the single components with the core layerer, the components are aligned with their topmost layer.

See Also:

setComponentArrangementPolicy(byte), getComponentArrangementPolicy(), Constant Field Values

LAYOUT_MODE_INCREMENTAL

public static final byte LAYOUT_MODE_INCREMENTAL

Layout mode constant that can be used in setLayoutMode(byte). This constant sets the layout algorithm to incremental mode, i.e. fixed elements will be handled by the fixedElementsSequencer and fixedElementsLayerer and elements marked for incremental layout will be added to the drawing later.

See Also:

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

LAYOUT_MODE_FROM_SCRATCH

public static final byte LAYOUT_MODE_FROM_SCRATCH

Layout mode constant that can be used in setLayoutMode(byte). This constant sets the layout algorithm to "from scratch mode", i.e. the algorithm will recompute the layout from scratch.

See Also:

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

LAYERING_STRATEGY_HIERARCHICAL_TOPMOST

public static final byte LAYERING_STRATEGY_HIERARCHICAL_TOPMOST

Layering strategy constant. A simple hierarchical layering variant. 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

LAYERING_STRATEGY_HIERARCHICAL_OPTIMAL

public static final byte LAYERING_STRATEGY_HIERARCHICAL_OPTIMAL

Layering strategy specifier. An optimal hierarchical layering strategy. The layer distance of an edge is the absolute difference between the layer numbers of its source and target node. Layer assignment will be done in such a way that the overall sum of the layer distances of all edges in the layout is minimal.

See Also:

setFromScratchLayeringStrategy(byte), Constant Field Values

LAYERING_STRATEGY_HIERARCHICAL_TIGHT_TREE

public static final byte LAYERING_STRATEGY_HIERARCHICAL_TIGHT_TREE

Layering strategy specifier. A heuristic that approximates the ranking done by LAYERING_STRATEGY_HIERARCHICAL_OPTIMAL.

See Also:

setFromScratchLayeringStrategy(byte), Constant Field Values

LAYERING_STRATEGY_HIERARCHICAL_DOWNSHIFT

public static final byte LAYERING_STRATEGY_HIERARCHICAL_DOWNSHIFT

Layering strategy specifier. A fast heuristic that improves the the ranking done by LAYERING_STRATEGY_HIERARCHICAL_TOPMOST by down shifting some nodes in the layering. The quality is usually worse than the one produced by Tight Tree Heuristic.

See Also:

setFromScratchLayeringStrategy(byte), Constant Field Values

LAYERING_STRATEGY_BFS

public static final byte LAYERING_STRATEGY_BFS

Layering strategy specifier. Layering 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

LAYERING_STRATEGY_FROM_SKETCH

public static final byte LAYERING_STRATEGY_FROM_SKETCH

Layering strategy specifier. A layer assignment strategy that uses the initial y-coordinates of the nodes (x-coordinates when the layout orientation is horizontal) to determine a node layering. It tries to find a layering that is similar to the one in the input graph. When this layering strategy is used, the layouter may place nodes in the same layer, even though they are connected by an edge. These inner layer edges are always routed in an orthogonal style.

See Also:

setFromScratchLayeringStrategy(byte), Constant Field Values

LAYERING_STRATEGY_USER_DEFINED

public static final byte LAYERING_STRATEGY_USER_DEFINED

Layering strategy specifier. The ranks of the nodes will be given by the user. The node ranks must be provided by a data provider bound to the input graph using the key GivenLayersLayerer.LAYER_ID_KEY. Like LAYERING_STRATEGY_FROM_SKETCH this layering allows inner layer edges.

See Also:

setFromScratchLayeringStrategy(byte), Constant Field Values

LAYERING_STRATEGY_UNKNOWN

public static final byte LAYERING_STRATEGY_UNKNOWN

Dummy layering strategy specifier. Returned by getFromScratchLayeringStrategy() if the current strategy is not known.

See Also:

Constant Field Values

POLICY_ALIGN_GROUPS_TOP

public static final byte POLICY_ALIGN_GROUPS_TOP

Group layering alignment strategy specifier. If recursive group layering is enabled, groups and normal nodes that occupy the same layer are top aligned with respect to their inner layers.

See Also:

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

POLICY_ALIGN_GROUPS_CENTER

public static final byte POLICY_ALIGN_GROUPS_CENTER

Group layering alignment strategy specifier. If recursive group layering is enabled, groups and normal nodes that occupy the same layer are center aligned with respect to their inner layers.

See Also:

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

POLICY_ALIGN_GROUPS_BOTTOM

public static final byte POLICY_ALIGN_GROUPS_BOTTOM

Group layering alignment strategy specifier. If recursive group layering is enabled, groups and normal nodes that occupy the same layer are bottom aligned with respect to their inner layers.

See Also:

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

Constructor Detail

IncrementalHierarchicLayouter

public IncrementalHierarchicLayouter()

Creates a new IncrementalHierarchicLayouter instance which is set to LAYOUT_MODE_FROM_SCRATCH initially

See Also:

setLayoutMode(byte)

Method Detail

getGroupAlignmentPolicy

public byte getGroupAlignmentPolicy()

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

Default value is POLICY_ALIGN_GROUPS_CENTER.

Returns:

a layering strategy specifier for relative group layer alignment

See Also:

setGroupAlignmentPolicy(byte), POLICY_ALIGN_GROUPS_TOP, POLICY_ALIGN_GROUPS_CENTER, POLICY_ALIGN_GROUPS_BOTTOM, setRecursiveGroupLayeringEnabled(boolean)

setGroupAlignmentPolicy

public void setGroupAlignmentPolicy(byte groupAlignmentPolicy)

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

Default value is POLICY_ALIGN_GROUPS_CENTER.

Parameters:

groupAlignmentPolicy - a layering strategy specifier for relative group layer alignment, one of POLICY_ALIGN_GROUPS_TOP, POLICY_ALIGN_GROUPS_CENTER or POLICY_ALIGN_GROUPS_BOTTOM

See Also:

getGroupAlignmentPolicy(), POLICY_ALIGN_GROUPS_TOP, POLICY_ALIGN_GROUPS_CENTER, POLICY_ALIGN_GROUPS_BOTTOM, setRecursiveGroupLayeringEnabled(boolean)

isGroupCompactionEnabled

public boolean isGroupCompactionEnabled()

Return whether layer compaction for recursive group layering is active.

Returns:

true iff group compaction is active.

See Also:

setRecursiveGroupLayeringEnabled(boolean), setGroupCompactionEnabled(boolean)

setGroupCompactionEnabled

public void setGroupCompactionEnabled(boolean groupCompactionEnabled)

Set whether layer compaction for recursive group layering should be used. If set to true, the recursive layering is compacted, i.e. node ranks are decreased if possible without reversing edge directions. This differs from non-recursive layering, where groups are ignored completely. The resulting layering tries to keep the layer span of a group node minimal, while minimizing the overall vertical space.

By default, this feature is disabled.

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

Parameters:

groupCompactionEnabled - true iff group compaction is active.

See Also:

isGroupCompactionEnabled(), setRecursiveGroupLayeringEnabled(boolean)

getComponentArrangementPolicy

public byte getComponentArrangementPolicy()

Returns the policy that is used to arrange connected components.

Defaults to COMPONENT_ARRANGEMENT_TOPMOST.

Returns:

one of

• COMPONENT_ARRANGEMENT_TOPMOST
• COMPONENT_ARRANGEMENT_COMPACT

See Also:

setComponentArrangementPolicy(byte)

setComponentArrangementPolicy

public void setComponentArrangementPolicy(byte policy)

Sets the policy used for arranging connected components.

Defaults to COMPONENT_ARRANGEMENT_TOPMOST.

Throws:

IllegalArgumentException - if the specified policy does not match one component arrangement policy constants.

Parameters:

policy - one of

• COMPONENT_ARRANGEMENT_TOPMOST
• COMPONENT_ARRANGEMENT_COMPACT

See Also:

getComponentArrangementPolicy()

getMaximalDuration

public long getMaximalDuration()

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

Returns:

the time limit.

See Also:

setMaximalDuration(long)

setMaximalDuration

public void setMaximalDuration(long maximalDuration)

Sets a preferred time limit (in milliseconds) for the layout algorithm. Note that restricting the maximal duration may result in a worse layout quality. Furthermore, the actual runtime may exceed the maximal duration since the layout algorithm still has to find a valid solution.

Parameters:

maximalDuration - the time limit.

See Also:

getMaximalDuration()

isRecursiveGroupLayeringEnabled

public boolean isRecursiveGroupLayeringEnabled()

Return whether groups are respected during the layering stage.

Returns:

true iff group information is used

See Also:

setRecursiveGroupLayeringEnabled(boolean)

setRecursiveGroupLayeringEnabled

public void setRecursiveGroupLayeringEnabled(boolean recursiveGroupLayeringEnabled)

Specifies whether groups are respected during the layering stage.

If set to true (and group compaction is not 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 this feature is disabled, group information is ignored for the layering step.
If the graph is flat, this setting is ignored.

By default, this feature is enabled.

Parameters:

recursiveGroupLayeringEnabled - true iff group information is used

See Also:

isRecursiveGroupLayeringEnabled()

isBackloopRoutingEnabled

public boolean isBackloopRoutingEnabled()

Whether or not backloop routing should be applied.

Returns:

true if backloop routing should be applied.

See Also:

setBackloopRoutingEnabled(boolean)

setBackloopRoutingEnabled

public void setBackloopRoutingEnabled(boolean backloopRoutingEnabled)

If this option is set, reversed edges are routed in a backloop style, i.e., such that they attach to the same vertex sides as the other edges. Note that port constraints and port candidates are still considered.

Parameters:

backloopRoutingEnabled - whether or not backloop routing should be applied.

isAutomaticEdgeGroupingEnabled

public boolean isAutomaticEdgeGroupingEnabled()

Whether or not automatic edge grouping should be applied.

Returns:

true if the edge grouping should be applied.

See Also:

setAutomaticEdgeGroupingEnabled(boolean)

setAutomaticEdgeGroupingEnabled

public void setAutomaticEdgeGroupingEnabled(boolean automaticEdgeGroupingEnabled)

If this option is set, 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. Note: Edges are only grouped at their source (target) node if they do not have a port constraint/port candidates at this node. Furthermore, edges cannot be grouped at a node with specified port candidates (see class PortCandidateSet). User specified edge groups are not considered.

Parameters:

automaticEdgeGroupingEnabled - whether or not automatic edge grouping should be applied.

setOrthogonallyRouted

public void setOrthogonallyRouted(boolean orthogonal)

Determines whether or not edges should be routed orthogonally. When set to true all resulting edge paths will be composed of vertical and horizontal segments, only. Default is false. Note that this is a convenience method delegates to getEdgeLayoutDescriptor().EdgeLayoutDescriptor.setOrthogonallyRouted(boolean).

Parameters:

orthogonal - whether to route this edge orthogonally

See Also:

isOrthogonallyRouted()

isOrthogonallyRouted

public boolean isOrthogonallyRouted()

Returns whether or not edges should be routed orthogonally. Return value true signals that all resulting edge paths will be composed of vertical and horizontal segments, only. Default is false. Note that this is a convenience method delegates to getEdgeLayoutDescriptor().EdgeLayoutDescriptor.isOrthogonallyRouted().

Returns:

whether to route this edge orthogonally

See Also:

setOrthogonallyRouted(boolean)

setIntegratedEdgeLabelingEnabled

public void setIntegratedEdgeLabelingEnabled(boolean enabled)

Specifies whether or not to use integrated edge labeling. This method is a convenience method that assures that the label layouter is of type LabelLayoutTranslator and LabelLayoutTranslator.setTranslateEdgeLabelsEnabled(boolean) is set to true

Throws:

IllegalStateException - if the current label layouter is not of type LabelLayoutTranslator.

Parameters:

enabled - whether to enable this feature

isIntegratedEdgeLabelingEnabled

public boolean isIntegratedEdgeLabelingEnabled()

Returns whether integrated edge labeling is enabled. This method is a convenience method that checks if the label layouter is of type LabelLayoutTranslator and LabelLayoutTranslator.isTranslateEdgeLabelsEnabled() returns true.
The default is false.

Throws:

IllegalStateException - if the current label layouter is not of type LabelLayoutTranslator.

Returns:

whether this feature is enabled.

setConsiderNodeLabelsEnabled

public void setConsiderNodeLabelsEnabled(boolean enabled)

Specifies whether or not to consider node labels when calculating node positions (thereby preventing possible node/node label or node label/node label overlaps). This method is a convenience method that assures that the label layouter is of type LabelLayoutTranslator and LabelLayoutTranslator.setTranslateNodeLabelsEnabled(boolean) is set to true. Note that setting this option may overwrite the currently set label layouter. 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.

Throws:

IllegalStateException - if the current label layouter is not of type LabelLayoutTranslator.

Parameters:

enabled - whether to enable this feature

isConsiderNodeLabelsEnabled

public boolean isConsiderNodeLabelsEnabled()

Returns whether or not node labels are taken into account when calculating node positions (thereby preventing possible node/node label or node label/node label overlaps). This method is a convenience method checks whether the label layouter is of type LabelLayoutTranslator and LabelLayoutTranslator.isTranslateNodeLabelsEnabled() returns true.
The default is false.

Throws:

IllegalStateException - if the current label layouter is not of type LabelLayoutTranslator.

Returns:

whether this feature is enabled.

setMinimumLayerDistance

public void setMinimumLayerDistance(double d)

Sets the minimum distance between two adjacent layers.

Parameters:

d - the minimum distance to use

getMinimumLayerDistance

public double getMinimumLayerDistance()

Returns the minimum distance between two adjacent layers. The default is 20.0d.

Returns:

the minimum distance to use

setNodeToNodeDistance

public void setNodeToNodeDistance(double d)

Sets the minimum distance between two adjacent nodes in one layer. See NodeLayoutDescriptor.getMinimumDistance() for related settings.

Parameters:

d - the minimum distance to use

getNodeToNodeDistance

public double getNodeToNodeDistance()

Returns the minimum distance between two adjacent nodes in one layer. The default is 30.0d.

Returns:

the minimum distance to use

setNodeToEdgeDistance

public void setNodeToEdgeDistance(double d)

Sets the minimum distance between an edge and an adjacent node in one layer. See NodeLayoutDescriptor.getMinimumDistance() and EdgeLayoutDescriptor.getMinimumDistance() for related settings.

Parameters:

d - the minimum distance to use

getNodeToEdgeDistance

public double getNodeToEdgeDistance()

Returns the minimum distance between two adjacent nodes in one layer. The default is 15.0d.

Returns:

the minimum distance to use

setEdgeToEdgeDistance

public void setEdgeToEdgeDistance(double d)

Sets the minimum distance between two adjacent edges in one layer. See EdgeLayoutDescriptor.getMinimumDistance() for related settings.

Parameters:

d - the minimum distance to use

getEdgeToEdgeDistance

public double getEdgeToEdgeDistance()

Returns the minimum distance between two adjacent edges in one layer. See EdgeLayoutDescriptor.getMinimumDistance() for related settings.

Returns:

the minimum distance to use

getDefaultDrawingDistanceCalculator

protected DefaultDrawingDistanceCalculator getDefaultDrawingDistanceCalculator()

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

Throws:

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

Returns:

the current DefaultDrawingDistanceCalculator

createHierarchicLayouter

protected HierarchicLayouter createHierarchicLayouter()

Factory method that creates the internally used HierarchicLayouter instance.

Returns:

new y.layout.hierarchic.incremental.HierarchicLayouter()

getHierarchicLayouter

public HierarchicLayouter getHierarchicLayouter()

Returns the internally used HierarchicLayouter instance.

Returns:

the internally used layouter instance.

See Also:

createHierarchicLayouter()

setFromScratchLayeringStrategy

public void setFromScratchLayeringStrategy(byte strategy)

Convenience method that sets 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. The rank of a node is the number of the layer it belongs to.

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 that as much as possible edges of the graph will point to the main layout direction, i.e. the start nodes of the edges will have a smaller rank than the corresponding end nodes. Also, a hierarchical layering will never put two connected nodes in the same layer.

By default the layering strategy LAYERING_STRATEGY_HIERARCHICAL_OPTIMAL is set.

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.

Parameters:

strategy - one of LAYERING_STRATEGY_HIERARCHICAL_TOPMOST, LAYERING_STRATEGY_HIERARCHICAL_DOWNSHIFT, LAYERING_STRATEGY_HIERARCHICAL_TIGHT_TREE, LAYERING_STRATEGY_HIERARCHICAL_OPTIMAL, LAYERING_STRATEGY_FROM_SKETCH, LAYERING_STRATEGY_USER_DEFINED or LAYERING_STRATEGY_BFS.

getFromScratchLayeringStrategy

public byte getFromScratchLayeringStrategy()

Returns the currently set layering strategy for the from scratch layering.

Returns:

a byte constant as defined in this class or LAYERING_STRATEGY_UNKNOWN if the strategy is unknown.

See Also:

setFromScratchLayeringStrategy(byte)

canLayoutCore

public boolean canLayoutCore(LayoutGraph graph)

Determines whether this layouter can perform the core layout on the given graph.

Specified by:

canLayoutCore in class CanonicMultiStageLayouter

doLayoutCore

public void doLayoutCore(LayoutGraph g)

Performs the actual layout using the currently set mode.

Specified by:

doLayoutCore in class CanonicMultiStageLayouter

See Also:

setLayoutMode(byte), getLayoutMode(), configureCoreLayout(LayoutGraph,y.layout.hierarchic.incremental.HierarchicLayouter), unconfigureCoreLayout(LayoutGraph,y.layout.hierarchic.incremental.HierarchicLayouter)

getMirrorMask

protected int getMirrorMask()

Returns the orientation layouter's mirror mask.

Returns:

The mirror mask.

configureCoreLayout

protected void configureCoreLayout(LayoutGraph graph,
                                   HierarchicLayouter ihl)

Called before the actual layout is performed. Overwrite this to manually reconfigure the instance. If PortCandidateSet.NODE_DP_KEY is registered with the layout graph and there is no HierarchicLayouter.getPortConstraintOptimizer() registered, PCListOptimizer will be temporarily configured with the instance.

Parameters:

graph - the graph to be laid out

ihl - the instance used for the core layout.

unconfigureCoreLayout

protected void unconfigureCoreLayout(LayoutGraph graph,
                                     HierarchicLayouter ihl)

Called after the actual layout is performed. Overwrite this to manually unconfigure the instance. If PortCandidateSet.NODE_DP_KEY is registered with the layout graph and PCListOptimizer was registered with the instance during configureCoreLayout(y.layout.LayoutGraph,y.layout.hierarchic.incremental.HierarchicLayouter) it will be removed by this method.

Parameters:

graph - the graph to be laid out

ihl - the instance used for the core layout.

createIncrementalHintsFactory

public IncrementalHintsFactory createIncrementalHintsFactory()

Returns a IncrementalHintsFactory instance that must be used to obtain marks that can be associated with elements in the graph that will be laid out incrementally.
Use this factory and a DataProvider that is bound to the graph using the INCREMENTAL_HINTS_DPKEY DataProvider key to associate appropriate hints with the elements in the graph that should be laid out incrementally by the algorithm.

Returns:

the factory

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 to specify sequence constraints for the given graph. For these sequence constraints to have any effect, the Sequencer used to determine the in-layer node order (sequence) has to support constraints. Both, DefaultLayerSequencer and the incremental sequencer used internally support sequence constraints.

Note: SequenceConstraintFactory instances have to be disposed after use. Disposing the factory will also remove all constraints previously specified for the factory's associated graph.

Creating a new constraint factory for a graph will render all previously created factories (including any constraints specified) for that graph useless. Therefore a new constraint factory should only be created after previously used factories have been properly disposed.

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 layering:

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

Parameters:

graph -

Returns:

A SequenceConstraintFactory instance for use with the given graph.

See Also:

setFromScratchSequencer(y.layout.hierarchic.incremental.Sequencer), setFixedElementsSequencer(y.layout.hierarchic.incremental.Sequencer)

createLayerConstraintFactory

public LayerConstraintFactory createLayerConstraintFactory(Graph graph)

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

Note: 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 a new constraint factory for a graph will render all previously created factories (including any constraints specified) for that graph useless. Therefore a new constraint factory should only be created after previously used factories have been properly disposed.

Parameters:

graph - the given graph.

Returns:

A LayerConstraintFactory instance for use with the given graph.

getFromScratchLayerer

public Layerer getFromScratchLayerer()

Returns the Layerer instance that is used to obtain the layering for the nodes if the layouter is set to LAYOUT_MODE_FROM_SCRATCH.

Returns:

the layerer for LAYOUT_MODE_FROM_SCRATCH mode.

See Also:

setFromScratchLayerer(Layerer), setLayoutMode(byte)

setFromScratchLayerer

public void setFromScratchLayerer(Layerer layerer)

Sets the Layerer instance that is used to obtain the layering for the nodes if the layouter is set to LAYOUT_MODE_FROM_SCRATCH.

Throws:

NullPointerException - if the argument is null

Parameters:

layerer - the new layerer instance

See Also:

setLayoutMode(byte)

getFromScratchSequencer

public Sequencer getFromScratchSequencer()

Returns the Sequencer instance that is used to calculate the node sequence if the layouter is set to LAYOUT_MODE_FROM_SCRATCH.

Returns:

the sequencer for LAYOUT_MODE_FROM_SCRATCH mode.

See Also:

setFromScratchSequencer(Sequencer), setLayoutMode(byte)

setFromScratchSequencer

public void setFromScratchSequencer(Sequencer sequencer)

Sets the Sequencer instance that is used to calculate the node sequence if the layouter is set to LAYOUT_MODE_FROM_SCRATCH.

Throws:

NullPointerException - if the argument is null

Parameters:

sequencer - the new sequencer instance

See Also:

setFromScratchLayerer(Layerer), setLayoutMode(byte)

getNodePlacer

public NodePlacer getNodePlacer()

Returns the NodePlacer instance that will be used to calculated the final node placement of the layout.

Returns:

the currently set instance

See Also:

setNodePlacer(NodePlacer)

setNodePlacer

public void setNodePlacer(NodePlacer nodePlacer)

Sets the NodePlacer instance that will be used to calculated the final node placement of the layout.

Throws:

NullPointerException - if the argument is null

Parameters:

nodePlacer - the new instance

getFixedElementsLayerer

public Layerer getFixedElementsLayerer()

Returns the Layerer instance that is used to obtain the layering for those nodes that are not marked to be laid out incrementally if the layouter is set to LAYOUT_MODE_INCREMENTAL.

Returns:

the layerer for LAYOUT_MODE_INCREMENTAL mode.

See Also:

setFixedElementsLayerer(Layerer), setLayoutMode(byte)

setFixedElementsLayerer

public void setFixedElementsLayerer(Layerer fixedElementsLayerer)

Sets the Layerer instance that is used to obtain the layering for those nodes that are not marked to be laid out incrementally if the layouter is set to LAYOUT_MODE_INCREMENTAL.

Throws:

NullPointerException - if the argument is null

Parameters:

fixedElementsLayerer - the new layerer instance

See Also:

setLayoutMode(byte)

getFixedElementsSequencer

public Sequencer getFixedElementsSequencer()

Returns the Sequencer instance that is used to calculated the sequence of the nodes that are not marked to be laid out incrementally if the layouter is set to LAYOUT_MODE_INCREMENTAL.

Returns:

the sequencer for LAYOUT_MODE_INCREMENTAL mode.

See Also:

setFixedElementsSequencer(Sequencer), setLayoutMode(byte)

setFixedElementsSequencer

public void setFixedElementsSequencer(Sequencer fixedElementsSequencer)

Sets the Sequencer instance that is used to calculated the sequence of the nodes that are not marked to be laid out incrementally if the layouter is set to LAYOUT_MODE_INCREMENTAL.

Throws:

NullPointerException - if the argument is null

Parameters:

fixedElementsSequencer - the sequencer for LAYOUT_MODE_INCREMENTAL mode.

See Also:

setLayoutMode(byte)

getLayoutMode

public byte getLayoutMode()

Returns the layout mode this layouter is currently in. Depending on the mode the layout algorithm will use different Layerer and Sequencer implementations.
Currently supported modes are:

• LAYOUT_MODE_INCREMENTAL
• LAYOUT_MODE_FROM_SCRATCH

Defaults to LAYOUT_MODE_FROM_SCRATCH.

Returns:

the current mode constant

setLayoutMode

public void setLayoutMode(byte layoutMode)

Sets the layout mode this layouter should use for upcoming layouts. Depending on the mode the layout algorithm will use different Layerer and Sequencer implementations.
Currently valid mode constants are:

• LAYOUT_MODE_INCREMENTAL
• LAYOUT_MODE_FROM_SCRATCH

Throws:

IllegalArgumentException - if the mode is unknown

Parameters:

layoutMode - the new mode constant

createEdgeLayoutDescriptor

protected EdgeLayoutDescriptor createEdgeLayoutDescriptor()

Factory method that creates the default EdgeLayoutDescriptor.

Returns:

a new EdgeLayoutDescriptor (new EdgeLayoutDescriptor())

getEdgeLayoutDescriptor

public EdgeLayoutDescriptor getEdgeLayoutDescriptor()

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

Returns:

the current instance

See Also:

HierarchicLayouter.EDGE_LAYOUT_DESCRIPTOR_DPKEY, createEdgeLayoutDescriptor()

setEdgeLayoutDescriptor

public void setEdgeLayoutDescriptor(EdgeLayoutDescriptor edgeLayoutDescriptor)

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

Throws:

NullPointerException - if the argument is null

Parameters:

edgeLayoutDescriptor - the new descriptor

See Also:

HierarchicLayouter.EDGE_LAYOUT_DESCRIPTOR_DPKEY

createNodeLayoutDescriptor

protected NodeLayoutDescriptor createNodeLayoutDescriptor()

Factory method that creates the default NodeLayoutDescriptor.

Returns:

a new NodeLayoutDescriptor (new NodeLayoutDescriptor())

getNodeLayoutDescriptor

public NodeLayoutDescriptor getNodeLayoutDescriptor()

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

Returns:

the current instance

See Also:

HierarchicLayouter.NODE_LAYOUT_DESCRIPTOR_DPKEY, createNodeLayoutDescriptor()

setNodeLayoutDescriptor

public void setNodeLayoutDescriptor(NodeLayoutDescriptor nodeLayoutDescriptor)

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

Throws:

NullPointerException - if the argument is null

Parameters:

nodeLayoutDescriptor - the new descriptor

See Also:

HierarchicLayouter.NODE_LAYOUT_DESCRIPTOR_DPKEY