This class arranges graphs in a hierarchic/layered fashion and supports complete re-layout as well as incremental graph layout.
Remarks
Note that class HierarchicLayout offers a facade to this class which is easier to use. Hence, we strongly recommend to not directly use class HierarchicLayoutCore.
Layout Style
The nodes are distributed into layers such that most of the edges point to the main layout direction. The order of the nodes within the layers ensures that the number of edge crossings is as small as possible. There are different edge routing styles available. Edges can be orthogonal, polyline or octilinear.
Hierarchical diagrams are commonly used for the visualization of hierarchical data, since they facilitate the identification of dependencies and relationships among the nodes of the graph. Possible application domains are the following: workflow visualization, call graph visualization, entity-relationship diagrams, biochemical pathways and network management.
Concept
The layout algorithm runs in three main phases:
- Layering – The nodes are distributed into layers by means of layerer. 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 sequencer.
- Drawing – The layout algorithm assigns the final coordinates to all nodes and routes the edges.
Features
In order to customize this layout algorithm, modify the Layerer, Sequencer, PortAllocator, DrawingDistanceCalculator, and NodePlacer instances.
This layout algorithm is able to incrementally add new elements to an existing drawing of a graph. In order to add elements incrementally, register a IDataProvider with the graph using the INCREMENTAL_HINTS_DP_KEY DataProvider key and associate the hints obtained from the IIncrementalHintsFactory with the elements to be added incrementally.
HierarchicLayoutNodeLayoutDescriptor and HierarchicLayoutEdgeLayoutDescriptor 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 IDataProviders registered with NODE_LAYOUT_DESCRIPTOR_DP_KEY or EDGE_LAYOUT_DESCRIPTOR_DP_KEY.
HierarchicLayoutCore supports two approaches to connect edges on a specific side or even an exact location to a node. PortConstraints define a single constraint for the ports of an edge. To realize more complex port restrictions, several PortCandidates or PortCandidateSets can be assigned to edges or nodes. If an edge with registered PortCandidates connects to nodes with PortCandidateSets, the layouter will try to match both collections to find an appropriate port. In case there is no matching port candidate, a PortCandidate specified for the edge is preferred. Since their simultaneous existence at the same node may be ambiguous, it is not recommended to use a combination of PortConstraints and PortCandidates in the same layout.
This algorithm specifies a LabelLayoutTranslator instance as the current labeling and configures it such that the node labels are passed to it by setting translateNodeLabels to true
.
In order to enable integrated edge labeling of this algorithm, make sure LabelLayoutTranslator is registered and edge labels are being translated and written back after the layout.
Moreover, this algorithm supports layer and sequence constraints. These constraints can be specified using a ILayerConstraintFactory and ISequenceConstraintFactory, respectively.
Default Values of Properties
componentLayoutEnabled | false | |
gridSpacing | 0 | There is no grid specified. |
maximumDuration | <code>0x7FFFFFFF</code> | The layout algorithm runs unrestricted. |
Type Details
- yfiles module
- layout-hierarchic
- yfiles-umd modules
- layout-familytree, layout-hierarchic, layout-radial, layout
- Legacy UMD name
- yfiles.hierarchic.HierarchicLayoutCore
See Also
Constructors
Creates a new HierarchicLayoutCore instance with the default settings.
Parameters
A map of options to pass to the method.
- componentLayoutEnabled - boolean
Whether or not the ComponentLayout should be enabled. This option sets the componentLayoutEnabled property on the created object.
- maximumDuration - number
The time limit (in milliseconds) set for the layout algorithm. This option sets the maximumDuration property on the created object.
- layerer - ILayerer
- sequencer - ISequencer
The ISequencer instance responsible for calculating the sequence of nodes within each layer (second phase of the layout algorithm). This option sets the sequencer property on the created object.
- nodePlacer - IHierarchicLayoutNodePlacer
The IHierarchicLayoutNodePlacer instance responsible for the assignment of the x-(sequence) and preliminary y-coordinates of the nodes. This option sets the nodePlacer property on the created object.
- portAllocator - IPortAllocator
The IPortAllocator instance responsible for assigning port coordinates to the adjacent edges of each node. This option sets the portAllocator property on the created object.
- portConstraintOptimizer - IPortConstraintOptimizer
The IPortConstraintOptimizer instance responsible for optimizing the assignment of port constraints to the adjacent edges of each node. This option sets the portConstraintOptimizer property on the created object.
- drawingDistanceCalculator - IDrawingDistanceCalculator
The IDrawingDistanceCalculator instance responsible for determining the minimum distances between elements that belong to the same layer. This option sets the drawingDistanceCalculator property on the created object.
- gridSpacing - number
The equidistant spacing between the horizontal and vertical grid lines. This option sets the gridSpacing property on the created object.
- labeling - ILayoutStage
The ILayoutStage that places the labels of the input graph. This option sets the labeling property on the created object.
- selfLoopRouter - ILayoutStage
The ILayoutStage that routes self-loops. This option sets the selfLoopRouter property on the created object.
- parallelEdgeRouter - ILayoutStage
The ILayoutStage that routes parallel edges. This option sets the parallelEdgeRouter property on the created object.
- componentLayout - ILayoutStage
The ILayoutStage that arranges the connected components of an input graph. This option sets the componentLayout property on the created object.
- subgraphLayout - ILayoutStage
The ILayoutStage that constrains the layout process to a subgraph of the input graph. This option sets the subgraphLayout property on the created object.
- hideGroupsStage - ILayoutStage
The ILayoutStage that hides the group nodes of the input graph. This option sets the hideGroupsStage property on the created object.
- orientationLayout - ILayoutStage
The ILayoutStage that modifies the orientation of a computed layout. This option sets the orientationLayout property on the created object.
- orientationLayoutEnabled - boolean
Whether or not the ILayoutStage that modifies the orientation of the layout is activated. This option sets the orientationLayoutEnabled property on the created object.
- layoutOrientation - LayoutOrientation
The main orientation of the layout. This option sets the layoutOrientation property on the created object.
- selfLoopRouterEnabled - boolean
Whether or not the ILayoutStage used for routing self-loops is activated. This option sets the selfLoopRouterEnabled property on the created object.
- labelingEnabled - boolean
Whether or not the ILayoutStage used for placing the labels of the input graph is activated. This option sets the labelingEnabled property on the created object.
- hideGroupsStageEnabled - boolean
Whether or not the ILayoutStage used for hiding group nodes is activated. This option sets the hideGroupsStageEnabled property on the created object.
- parallelEdgeRouterEnabled - boolean
Whether or not the ILayoutStage used for routing parallel edges is activated. This option sets the parallelEdgeRouterEnabled property on the created object.
- subgraphLayoutEnabled - boolean
Whether or not the ILayoutStage used for constraining the layout process to a subgraph of the input graph is activated. This option sets the subgraphLayoutEnabled property on the created object.
See Also
Properties
Gets or sets the ILayoutStage that arranges the connected components of an input graph.
Default Value
ComponentLayout.See Also
Defined in
Gets or sets whether or not the ComponentLayout should be enabled.
Default Value(Overrides the default value defined in MultiStageLayout)
false
.See Also
Overrides
Factory method called during the initialization of this HierarchicLayoutCore instance that creates a label layouter.
Remarks
true
. Likewise, in order to make use of the integrated edge labeling translateEdgeLabels must be set to true
and also writeBackEdgeLabels must be set to true
(which is the default).Gets or sets the IDrawingDistanceCalculator instance responsible for determining the minimum distances between elements that belong to the same layer.
Remarks
Throws
- Exception({ name: 'ArgumentError' })
- if the specified
is null
See Also
Gets or sets the equidistant spacing between the horizontal and vertical grid lines.
Remarks
Default Value
0
.There is no grid specified.
See Also
Sample Graphs
Gets or sets the ILayoutStage that hides the group nodes of the input graph.
Default Value
HideGroupsStage.See Also
Defined in
Gets or sets whether or not the ILayoutStage used for hiding group nodes is activated.
Remarks
Default Value
true
.The stage responsible for hiding group nodes is activated.
See Also
Defined in
Gets or sets the ILayoutStage that places the labels of the input graph.
Default Value
See Also
Defined in
Gets or sets whether or not the ILayoutStage used for placing the labels of the input graph is activated.
Remarks
Default Value
false
.The stage responsible for label placement is deactivated.
See Also
Defined in
Gets or sets the ILayerer instance responsible for generating the layer assignment (first phase of the layout algorithm).
Remarks
Throws
- Exception({ name: 'ArgumentError' })
- if the specified
is null
See Also
Gets or sets the main orientation of the layout.
Remarks
Default Value
TOP_TO_BOTTOM.Throws
- Exception({ name: 'ArgumentError' })
- if the specified orientation does not match a default layout orientation
See Also
Defined in
Gets or sets the time limit (in milliseconds) set for the layout algorithm.
Remarks
0
.Default Value
<code>0x7FFFFFFF</code>
.The layout algorithm runs unrestricted.
Throws
- Exception({ name: 'ArgumentError' })
- if the maximum duration is negative
Gets or sets the IHierarchicLayoutNodePlacer instance responsible for the assignment of the x-(sequence) and preliminary y-coordinates of the nodes.
Remarks
Throws
- Exception({ name: 'ArgumentError' })
- if the specified
is null
See Also
Gets or sets the ILayoutStage that modifies the orientation of a computed layout.
Default Value
OrientationLayout.See Also
Defined in
Gets or sets whether or not the ILayoutStage that modifies the orientation of the layout is activated.
Remarks
Default Value
true
.The orientation
See Also
Defined in
Gets or sets the ILayoutStage that routes parallel edges.
Default Value
ParallelEdgeRouter.See Also
Defined in
Gets or sets whether or not the ILayoutStage used for routing parallel edges is activated.
Remarks
Default Value
true
.The stage that routes parallel edges is activated.
See Also
Defined in
Gets or sets the IPortAllocator instance responsible for assigning port coordinates to the adjacent edges of each node.
Remarks
Throws
- Exception({ name: 'ArgumentError' })
- if the specified
is null
See Also
Gets or sets the IPortConstraintOptimizer instance responsible for optimizing the assignment of port constraints to the adjacent edges of each node.
Gets or sets the ILayoutStage that routes self-loops.
Default Value
SelfLoopRouter.See Also
Defined in
Gets or sets whether or not the ILayoutStage used for routing self-loops is activated.
Remarks
Default Value
true
.The stage that routes self-loops is activated.
See Also
Defined in
Gets or sets the ISequencer instance responsible for calculating the sequence of nodes within each layer (second phase of the layout algorithm).
Remarks
Throws
- Exception({ name: 'ArgumentError' })
- if the specified
is null
See Also
Gets or sets the ILayoutStage that constrains the layout process to a subgraph of the input graph.
Default Value
SubgraphLayout.See Also
Defined in
Gets or sets whether or not the ILayoutStage used for constraining the layout process to a subgraph of the input graph is activated.
Remarks
Default Value
false
.The stage that constrains the input graph to a subgraph is deactivated.
See Also
Defined in
Methods
Appends the given ILayoutStage to the layout pipeline.
Remarks
Parameters
A map of options to pass to the method.
- stage - ILayoutStage
- the ILayoutStage instance to be added
See Also
Defined in
Calculates a layout for the given graph and applies it directly to the graph.
Remarks
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- the input graph
See Also
Implements
Calculates a hierarchic layout of the given graph.
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- the input graph
Implements
Checks the sizes of the nodes to be non-zero.
Parameters
A map of options to pass to the method.
- g - LayoutGraph
- The graph to check.
Defined in
Factory method that is called lazily upon first usage by drawingDistanceCalculator if the given IDrawingDistanceCalculator instance is null
.
Remarks
Returns
See Also
Factory method called during applyLayoutCore and reates an appropriate IEdgeReverser implementation.
Remarks
Returns
- ↪IEdgeReverser
- an implementation
Factory method that is called during applyLayoutCore and creates a LayoutGroupingSupport instance in case of a grouped graph.
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- the input graph
Returns
- ↪LayoutGroupingSupport
- a LayoutGroupingSupport instance or
null
if the graph is not grouped
Creates an IIncrementalHintsFactory implementation used for obtaining hint objects associated with nodes and edges of the graph prior to the invocation of the layout algorithm.
Remarks
Returns
- ↪IIncrementalHintsFactory
- an IIncrementalHintsFactory instance
See Also
Factory method called during applyLayoutCore and creates an appropriate ILayerer implementation.
Remarks
Returns
Callback method that is called during applyLayoutCore, creates the INodeData and IEdgeData instances and binds them to the elements using the given itemFactory.
Parameters
A map of options to pass to the method.
- g - LayoutGraph
- the input graph
- itemFactory - IItemFactory
- the given IItemFactory instance
Creates a layer constraint factory that allows to create hints that affect the assignment of the nodes to layers.
Remarks
Parameters
A map of options to pass to the method.
- graph - Graph
- the given graph
Returns
- ↪ILayerConstraintFactory
- a ILayerConstraintFactory instance
Factory method called during applyLayoutCore and creates an appropriate ILayers implementation using the given ILayoutDataProvider instance.
Remarks
Parameters
A map of options to pass to the method.
- ldp - ILayoutDataProvider
- the given ILayoutDataProvider instance
Returns
Factory method that is called lazily upon first usage by nodePlacer if the given IHierarchicLayoutNodePlacer instance is null
.
Remarks
Returns
See Also
Factory method that is called lazily upon first usage by portAllocator if the given IPortAllocator instance is null
.
Remarks
Returns
- ↪IPortAllocator
- a IPortAllocator instance
See Also
Factory method that is called lazily upon first usage by portConstraintOptimizer if the given IPortConstraintOptimizer instance is null
.
Remarks
null
. It may be overridden to return a custom IPortConstraintOptimizer instance.Returns
See Also
Creates sequence constraints that affect the sequence of the nodes within each layer.
Remarks
Parameters
A map of options to pass to the method.
- graph - Graph
- the given graph
Returns
Factory method that is called lazily upon first usage by sequencer if the given ISequencer instance is null
.
Remarks
Returns
- ↪ISequencer
- a ISequencer instance
See Also
Factory method called during applyLayoutCore and creates a ISequencer implementation that can sequence subgraphs incrementally.
Remarks
Returns
- ↪ISequencer
- a ISequencer implementation
Deactivates all predefined ILayoutStages so that upon applyLayout only the layout algorithm will be executed.
See Also
Defined in
Provides access to implementation specific properties of the algorithms used.
Remarks
Parameters
A map of options to pass to the method.
- key - Object
- the key to a property
Returns
- ↪any
- the associated property value or
null
See Also
Callback method called during applyLayoutCore and returns a IDataProvider that holds the HierarchicLayoutEdgeLayoutDescriptor information.
Remarks
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- the input graph
Returns
- ↪IDataProvider
- a IDataProvider instance or
null
See Also
Callback method called during applyLayoutCore and returns a IDataProvider that holds the incremental hints information.
Remarks
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- the input graph
Returns
- ↪IDataProvider
- a IDataProvider instance or
null
See Also
Callback method called during applyLayoutCore and returns a IDataProvider that holds the HierarchicLayoutNodeLayoutDescriptor information.
Remarks
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- the input graph
Returns
- ↪IDataProvider
- a IDataProvider instance or
null
See Also
Callback method called during applyLayoutCore and returns a IDataProvider that holds the SwimlaneDescriptor information.
Remarks
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- the input graph
Returns
- ↪IDataProvider
- a IDataProvider instance or
null
See Also
Prepends the given ILayoutStage to the layout pipeline.
Remarks
Parameters
A map of options to pass to the method.
- stage - ILayoutStage
- the ILayoutStage instance to be added
See Also
Defined in
Callback method that publishes the layering information.
Remarks
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- the input graph
- layers - ILayers
- the ILayers implementation that provides the layering information
See Also
Callback method that publishes the sequencing information.
Remarks
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- the input graph
- layers - ILayers
- the ILayers implementation that provides the layering and sequencing information
- ldp - ILayoutDataProvider
- the ILayoutDataProvider implementation which provides access to the INodeData and IEdgeData instances
See Also
Removes the bends which are obviously not necessary.
Remarks
Parameters
A map of options to pass to the method.
- graph - LayoutGraph
- the input graph
- threshold - number
- this method removes a bend, if its horizontal/vertical distance to the closest collinear bend is above this threshold
Removes the given ILayoutStage from the layout pipeline.
Remarks
Parameters
A map of options to pass to the method.
- stage - ILayoutStage
- a ILayoutStage to be removed from the layout pipeline
See Also
Defined in
Provides access to implementation specific properties of the algorithms used.
Remarks
Parameters
A map of options to pass to the method.
See Also
Constants
A data provider key for providing layout information for each edge.
Domain | Edge | |
Values | HierarchicLayoutEdgeLayoutDescriptor | an edge layout descriptor that provides layout information for each edge or null if the default |
See Also
A data provider key for specifying incremental hints.
Remarks
Domain | GraphObject | the nodes and edges of the input graph |
Values | Object | the incremental hint that specifies where the node/edge is incrementally inserted or null if the element is non-incremental |
See Also
A data provider key for internal use only.
Domain | YNode | |
Values | boolean | true if the node should be added incrementally, false otherwise |
A data acceptor key for publishing the layer IDs for all nodes in the graph.
Remarks
Domain | YNode | the nodes of the input graph |
Values | number | the index of the layer inside the |
See Also
A data provider key for providing layout information for each node.
Domain | YNode | |
Values | HierarchicLayoutNodeLayoutDescriptor | a node layout descriptor that provides layout information for each node or null if the default |
See Also
A data acceptor key for publishing the index inside their layer for all nodes in the graph.
Remarks
Domain | YNode | the nodes of the input graph |
Values | number | the index of the node inside the sequence of the according |
See Also
A data provider key for providing information about swimlanes.
Remarks
If this key is present during the layout, the layout algorithm will arrange nodes in swimlanes. The information about the swimlanes is finally written back to the descriptor instances.
Instances can be shared among multiple nodes in the same lane, but don't have to be shared.
Domain | YNode | |
Values | SwimlaneDescriptor | a swimlane layout descriptor that provides information about swimlanes for each node or null if the default |