HierarchicLayoutData

: ItemCollectionMapping<IEdge,HierarchicLayoutBusDescriptor>

Gets or sets the collection of core nodes used by the BFSLayerer.

Remarks

The core nodes will be placed in the first layer. If there are no core nodes, then nodes with in-degree 0 are considered to be the core nodes.

The BFSLayerer is used when fromScratchLayeringStrategy is set to BFS.

buses

Gets or sets the mapping from edges to their bus descriptor which defines the bus structure they belong to.

Remarks

All edges with the same HierarchicLayoutBusDescriptor adjacent to a specific node (the root) and having the same direction are arranged in a compact, bus-like way. The edgeDirectedness 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 be customized for each bus individually, by using the settings offered by HierarchicLayoutBusDescriptor. It allows to configure the number of bus nodes before and after the common bus segment.

There apply some restrictions for bus structures:

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.
Bus structures can not be nested. That means that if a node is a bus node it can not be a root node of another bus at the same time.
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 AT_SOURCE_PORT and 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 maximumNodesBeforeBus and maximumNodesAfterBus as well as the before/after constraints defined by nodesBeforeBus. 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.

Examples

Buses can be configured by first adding a new HierarchicLayoutBusDescriptor and saving the resulting ItemCollection<TItem>. That one can then be used to define the structure of the bus:

// Retrieve an ItemCollection<IEdge> which defines all edges
// of a bus. This bus will be arranged according to the HierarchicLayoutBusDescriptor
const bus = layoutData.buses.add(new HierarchicLayoutBusDescriptor())
// You can use this ItemCollection<IEdge> as usual, using either one of
// the Source, Items, Mapper, or Delegate properties.
// Here, we simply use the selected edges:
bus.source = graphComponent.selection.selectedEdges

Since adding a new HierarchicLayoutBusDescriptor for a bus returns the ItemCollection<TItem>, configuring buses can also be conveniently chained:

//  bus1Edges, bus2Edges, bus3Edges are of type IEnumerable.<IEdge>
layoutData.buses.add(new HierarchicLayoutBusDescriptor()).source = bus1Edges
layoutData.buses.add(new HierarchicLayoutBusDescriptor()).source = bus2Edges
layoutData.buses.add(new HierarchicLayoutBusDescriptor()).source = bus3Edges

Sample Graphs

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 HierarchicLayoutBusDescriptor, only one edge will be treated as a bus edge.

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

If bus nodes have edges to other bus nodes (from the same or from another bus), then these edges are not considered in the same way during the layering as other edges; in consequence, it can happen that both bus nodes end up in the same final layer and thus the edge becomes a same-layer edge. The same can happen if a group has an edge to a bus node where the bus node is outside said group but the root of the bus is a child of it.

busRootOffsets

: ItemMapping<INode,number>

Gets or sets the mapping from nodes to their layer index relative to the root node of the bus they belong to.

Remarks

An offset value i specified for a bus node is interpreted relative to the root node as follows, assuming that the root node is in layer x.

If the bus is placed in the layers after the root, the bus node will be placed in layer x + i
If the bus is placed in the layers before the root, the bus node will be placed in layer x - i

Examples

When the layer offsets can be readily inferred from the nodes, then the easiest option is usually to use the delegate:

layoutData.busRootOffsets = (node) => node.tag.offsetlayoutData.busRootOffsets = (node: INode): number => node.tag.offset

In case only some nodes need to be mapped to their layer respective offset, it's sometimes easier to use the mapper:

layoutData.busRootOffsets.mapper.set(node1, 0)
layoutData.busRootOffsets.mapper.set(node2, 1)

constraintIncrementalLayererAdditionalEdgeWeights

Gets or sets the mapping from edges to an additional weight used by the ConstraintIncrementalLayerer.

Remarks

The layerer tries to keep edges with higher weights short.

criticalEdgePriorities

Gets or sets a mapping from edges to their priority to be a 'critical' edge.

Remarks

The layout tries to vertically align each node pair that is connected by a critical edge. Critical edges are marked by having a priority greater than 0; edges with a zero or negative priority are not considered critical.

Critical edges highlight different edge paths that are relevant for a user. The layout algorithm 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.

Examples

Critical edges are often determined by some external data source and are often part of a larger path. The following example shows how two different such paths can be made 'critical' with different priorities:

Configuring critical edges via a mapper

// Set two different critical edge paths with different priorities
for (const edge of path1) {
  layoutData.criticalEdgePriorities.mapper.set(edge, 5)
}
// Lower priority for the second path, which then may deviate from a straight line
for (const edge of path2) {
  layoutData.criticalEdgePriorities.mapper.set(edge, 2)
}

Alternatively, a delegate may be used as well, if determining edge criticality is easier when looking at the edge itself:

Configuring critical edges via a delegate

// Assume that the edge's tag holds an instance that has an 'IsCritical' property
layoutData.criticalEdgePriorities = (edge) => (edge.tag.isCritical ? 1 : 0)// Assume that the edge's tag holds an instance that has an 'IsCritical' property
layoutData.criticalEdgePriorities = (edge: IEdge): 0 | 1 =>
  edge.tag.isCritical ? 1 : 0

Sample Graphs

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

Critical edges by default also get crossing costs assigned based on their priorities (see property reduceCriticalEdgeCrossings). Thus, they are favored during the edge crossing minimization phase.

edgeCrossingCosts

Gets or sets the mapping from edges to their crossing cost.

Remarks

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. A crossing with an edge that has a cost of zero is cost-free and such a crossing will therefore not be avoided. The default crossing cost of an edge is 1, which is used for edges which do not have an individual crossing cost.

Examples

When there are only a few edges to customize crossing costs for, the easiest way is usually to use the mapper:

Defining edge crossing costs via a mapper

const layoutData = new HierarchicLayoutData()
// Try harder to prevent crossings with edge1
layoutData.edgeCrossingCosts.mapper.set(edge1, 1.5)
// Crossings with edge2 are not as bad
layoutData.edgeCrossingCosts.mapper.set(edge2, 0.2)

If the crossing cost can readily be computed from the edge itself, the delegate is often the more convenient option:

Defining edge crossing costs via a delegate

// The more labels an edge has, the more important it is to
// prevent crossing with it
layoutData.edgeCrossingCosts = (edge) => 1 + edge.labels.size// The more labels an edge has, the more important it is to
// prevent crossing with it
layoutData.edgeCrossingCosts = (edge: IEdge): number => 1 + edge.labels.size

edgeDirectedness

: ItemMapping<ILabel,PreferredPlacementDescriptor>

Gets or sets the mapping from edges to their directedness.

Remarks

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.

Examples

The easiest option is to define all edges with the same directedness:

Treating all edges as directed

layoutData.edgeDirectedness.constant = 1

Handling only certain edges differently can be done easily by using the mapper property:

Using a mapper to set directedness for certain edges

// edge1 should be considered directed
layoutData.edgeDirectedness.mapper.set(edge1, 1)
// edge2 should be considered directed against the flow
layoutData.edgeDirectedness.mapper.set(edge2, -1)
// All other edges not set in the mapper are treated as undirected

In cases where the directedness for each edge can be determined by looking at the edge itself it's often easier to just set a delegate instead of preparing a mapper:

Using a delegate to determine edge directedness

// Treat edges as directed or undirected based on their style's arrowhead
layoutData.edgeDirectedness = (edge) => {
  const style = edge.style
  // edges with either no arrows on both ends or an arrow on both ends should be considered undirected
  if (
    (style.sourceArrow === null && style.targetArrow === null) ||
    (style.sourceArrow !== null && style.targetArrow !== null)
  ) {
    return 0
  }
  // edges with only a target arrow are directed from source to target
  if (style.targetArrow !== null) {
    return 1
  }
  // edges with only a source arrow are directed from target to source
  if (style.sourceArrow !== null) {
    return -1
  }
  return 0
}// Treat edges as directed or undirected based on their style's arrowhead
layoutData.edgeDirectedness = (edge: IEdge): 0 | 1 | -1 => {
  const style = edge.style as PolylineEdgeStyle
  // edges with either no arrows on both ends or an arrow on both ends should be considered undirected
  if (
    (style.sourceArrow === null && style.targetArrow === null) ||
    (style.sourceArrow !== null && style.targetArrow !== null)
  ) {
    return 0
  }
  // edges with only a target arrow are directed from source to target
  if (style.targetArrow !== null) {
    return 1
  }
  // edges with only a source arrow are directed from target to source
  if (style.sourceArrow !== null) {
    return -1
  }
  return 0
}

edgeLabelPreferredPlacement

Gets or sets the mapping that provides a PreferredPlacementDescriptor instance for edge ILabels.

Examples

Depending on how much customization is needed, some ways of setting PreferredPlacementDescriptors are more convenient than others. For example, to set the same descriptor for all labels, you can just use the constant property:

Setting the same PreferredPlacementDescriptor for all labels

layoutData.edgeLabelPreferredPlacement = new PreferredPlacementDescriptor({
  // Place labels along the edge
  angleReference: LabelAngleReferences.RELATIVE_TO_EDGE_FLOW,
  angle: 0,
  // ... on either side
  sideOfEdge: LabelPlacements.LEFT_OF_EDGE | LabelPlacements.RIGHT_OF_EDGE,
  // ... with a bit of distance to the edge
  distanceToEdge: 5
})

If some labels should use custom placement or this has to be configured ahead of time, you can use the mapper instead:

Customizing the placement of certain labels individually via a mapper

// Place label1 orthogonal to the edge anywhere on it
layoutData.edgeLabelPreferredPlacement.mapper.set(
  label1,
  new PreferredPlacementDescriptor({
    placeAlongEdge: LabelPlacements.ANYWHERE,
    angleReference: LabelAngleReferences.RELATIVE_TO_EDGE_FLOW,
    angle: Math.PI / 2
  })
)
// Place label2 near the edge's source on either side of it, and make it parallel to the edge
layoutData.edgeLabelPreferredPlacement.mapper.set(
  label2,
  new PreferredPlacementDescriptor({
    placeAlongEdge: LabelPlacements.AT_SOURCE,
    sideOfEdge: LabelPlacements.RIGHT_OF_EDGE | LabelPlacements.LEFT_OF_EDGE,
    angleReference: LabelAngleReferences.RELATIVE_TO_EDGE_FLOW,
    angle: 0
  })
)

When the preferred placement can be inferred from the label itself, a delegate is usually the easiest choice:

Configuring preferred placement for all labels with a delegate

layoutData.edgeLabelPreferredPlacement = (label) => {
  const customData = label.tag
  return new PreferredPlacementDescriptor({
    angle: 0,
    angleReference: LabelAngleReferences.RELATIVE_TO_EDGE_FLOW,
    // If the tag says to place the label in the center, put it in the center parallel to the edge's path
    // All other labels can be placed anywhere, but on the side of the edge.
    placeAlongEdge: customData.placeInCenter
      ? LabelPlacements.AT_CENTER
      : LabelPlacements.ANYWHERE,
    sideOfEdge: customData.placeInCenter
      ? LabelPlacements.ON_EDGE
      : LabelPlacements.LEFT_OF_EDGE | LabelPlacements.RIGHT_OF_EDGE
  })
}layoutData.edgeLabelPreferredPlacement = (
  label: ILabel
): PreferredPlacementDescriptor => {
  const customData = label.tag
  return new PreferredPlacementDescriptor({
    angle: 0,
    angleReference: LabelAngleReferences.RELATIVE_TO_EDGE_FLOW,
    // If the tag says to place the label in the center, put it in the center parallel to the edge's path
    // All other labels can be placed anywhere, but on the side of the edge.
    placeAlongEdge: customData.placeInCenter
      ? LabelPlacements.AT_CENTER
      : LabelPlacements.ANYWHERE,
    sideOfEdge: customData.placeInCenter
      ? LabelPlacements.ON_EDGE
      : LabelPlacements.LEFT_OF_EDGE | LabelPlacements.RIGHT_OF_EDGE
  })
}

Note that the preferred placement can also be inferred from an arbitrary ILabelModelParameter:

Configuring preferred placement from a label model parameter

layoutData.edgeLabelPreferredPlacement =
  PreferredPlacementDescriptor.fromParameter(
    NinePositionsEdgeLabelModel.CENTER_CENTERED
  )

edgeLayoutDescriptors

: ItemMapping<IEdge,HierarchicLayoutEdgeLayoutDescriptor>

Gets or sets the mapping of edges to their HierarchicLayoutEdgeLayoutDescriptor.

Remarks

If an edge is mapped to null, the default descriptor is used.

Examples

This property allows to change how edges are routed for each edge individually. To just change a few edges that deviate from the default style, using the mapper is probably the best option:

Using a mapper to set different EdgeLayoutDescriptors for different edges

// Ensure larger lengths for the first and last segments of edge1
layoutData.edgeLayoutDescriptors.mapper.set(
  edge1,
  new HierarchicLayoutEdgeLayoutDescriptor({
    minimumFirstSegmentLength: 30,
    minimumLastSegmentLength: 50
  })
)
// Change the routing style to octilinear for edge2
layoutData.edgeLayoutDescriptors.mapper.set(
  edge2,
  new HierarchicLayoutEdgeLayoutDescriptor({
    routingStyle: new HierarchicLayoutRoutingStyle(
      HierarchicLayoutEdgeRoutingStyle.OCTILINEAR
    )
  })
)
// All other edges not set in the mapper use the default EdgeLayoutDescriptor
// set on HierarchicLayout.

If an HierarchicLayoutEdgeLayoutDescriptor is easier to create from every edge itself, using a delegate is often easier:

Using a delegate to set a different EdgeLayoutDescriptor for each edge

// Use a property from a custom business object in the edge's tag as the minimum length
layoutData.edgeLayoutDescriptors = (edge) => {
  const customData = edge.tag
  return new HierarchicLayoutEdgeLayoutDescriptor({
    minimumLength: customData.minimumLength,
    routingStyle: new HierarchicLayoutRoutingStyle(
      customData.shouldUseOctilinearRouting
        ? HierarchicLayoutEdgeRoutingStyle.OCTILINEAR
        : HierarchicLayoutEdgeRoutingStyle.POLYLINE
    )
  })
}

edgeThickness

Gets or sets the mapping from edges to their thickness.

Remarks

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.

Examples

The easiest option is to define the same thickness for all edges:

Specifying a uniform thickness for all edges

layoutData.edgeThickness.constant = 3

Handling only certain edges differently can be done easily by using the mapper property:

Using a mapper to set a custom thickness for certain edges

layoutData.edgeThickness.mapper.set(edge1, 2)
layoutData.edgeThickness.mapper.set(edge2, 5)
// All other edges not set in the mapper have no defined thickness

In cases where the thickness for each edge can be determined by looking at the edge itself it's often easier to just set a delegate instead of preparing a mapper:

Using a delegate to determine edge thickness

// Use the style's pen thickness as edge thickness
layoutData.edgeThickness = (edge) => {
  const style = edge.style
  if (style instanceof PolylineEdgeStyle) {
    return style.stroke.thickness
  }
  return 0
}// Use the style's pen thickness as edge thickness
layoutData.edgeThickness = (edge: IEdge): number => {
  const style = edge.style
  if (style instanceof PolylineEdgeStyle) {
    return style.stroke!.thickness
  }
  return 0
}

Sample Graphs

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

folderNodes

: ItemMapping<INode,NodeHalo>

Gets or sets the collection of folder nodes used for recursive edge styles in incremental mode.

Remarks

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.

Examples

Using the folderNodes property is probably easiest with a delegate that checks for each node whether it's a folder node or not:

Dynamically determine whether a node is a folder node

layoutData.folderNodes = (node) => graph.foldingView.isInFoldingState(node)layoutData.folderNodes = (node) => graph.foldingView!.isInFoldingState(node)

However, the other options are also still there, such as using an IEnumerable<T> via source:

Using a static collection of folder nodes

layoutData.folderNodes = graph.nodes.filter((node) =>
  graph.foldingView.isInFoldingState(node)
)layoutData.folderNodes = graph.nodes.filter((node) =>
  graph.foldingView!.isInFoldingState(node)
)

or explicitly using the items collection to add or remove items, perhaps based on the user collapsing/expanding group nodes:

Adding and removing nodes from the FolderNodes backing collection

// When collapsing a node, mark it as a folder node for layout
graphEditorInputMode.navigationInputMode.addGroupCollapsedListener(
  (sender, args) => layoutData.folderNodes.items.add(args.item)
)
// When expanding the node again, we unmark it again
graphEditorInputMode.navigationInputMode.addGroupExpandedListener(
  (sender, args) => layoutData.folderNodes.items.remove(args.item)
)// When collapsing a node, mark it as a folder node for layout
graphEditorInputMode.navigationInputMode.addGroupCollapsedListener(
  (sender: NavigationInputMode, args: ItemEventArgs<INode>) =>
    layoutData.folderNodes.items.add(args.item)
)
// When expanding the node again, we unmark it again
graphEditorInputMode.navigationInputMode.addGroupExpandedListener(
  (sender: NavigationInputMode, args: ItemEventArgs<INode>) =>
    layoutData.folderNodes.items.remove(args.item)
)

givenLayersLayererIds

: ItemMapping<INode,number>

Gets or set the mapping from nodes to their layer index when using the GivenLayersLayerer.

Remarks

Nodes with the same layer index are in the same layer while the layers are sorted according to their layer indices such that the smallest layer index represents the top layer.

The GivenLayersLayerer is used when fromScratchLayeringStrategy is set to USER_DEFINED.

groupBorderCrossingCosts

: ItemMapping<INode,number>

Gets or sets the mapping from group nodes to the costs for a crossing with the group node border.

Remarks

Like the edgeCrossingCosts, 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.

Examples

When there are only a few group nodes to customize crossing costs for, the easiest way is usually to use the mapper:

Defining group nodes crossing costs via a mapper

// Try harder to prevent crossings with group node1
layoutData.groupBorderCrossingCosts.mapper.set(node1, 7)
// Crossings with group node2 are not as bad
layoutData.groupBorderCrossingCosts.mapper.set(node2, 3)

If the crossing cost can readily be computed from the group node itself, the delegate is often the more convenient option:

Defining group nodes crossing costs via a delegate

// The more labels a group node has, the more important it is to
// prevent crossing with it
layoutData.groupBorderCrossingCosts = (node) => 5 + node.labels.size// The more labels a group node has, the more important it is to
// prevent crossing with it
layoutData.groupBorderCrossingCosts = (node: INode): number =>
  5 + node.labels.size

incrementalHints

: IncrementalHintItemMapping

Gets or sets a mapping from nodes and edges to their incremental hints.

Remarks

Incremental hint specifies if and where nodes and edges are incrementally inserted.

Examples

Elements which should be placed incrementally can be provided as collections:

Creating incremental hints for nodes and edges

// create a HierarchicLayout which rearranges
// only the incremental graph elements
const hl = new HierarchicLayout({ layoutMode: LayoutMode.INCREMENTAL })

// provide additional data to configure the HierarchicLayout
const hlData = new HierarchicLayoutData()
// specify the nodes to rearrange
hlData.incrementalHints.incrementalLayeringNodes = incrementalNodes
// specify the edges to rearrange
hlData.incrementalHints.incrementalSequencingItems =
  ItemCollection.from(incrementalEdges)

graph.applyLayout(hl, hlData)// create a HierarchicLayout which rearranges
// only the incremental graph elements
const hl = new HierarchicLayout({ layoutMode: LayoutMode.INCREMENTAL })

// provide additional data to configure the HierarchicLayout
const hlData = new HierarchicLayoutData()
// specify the nodes to rearrange
hlData.incrementalHints.incrementalLayeringNodes = incrementalNodes
// specify the edges to rearrange
hlData.incrementalHints.incrementalSequencingItems =
  ItemCollection.from<IModelItem>(incrementalEdges)

graph.applyLayout(hl, hlData)

More specific hints can be created using an IIncrementalHintsFactory:

Creating incremental hints for nodes and edges using a factory

// create a HierarchicLayout which rearranges
// only the incremental graph elements
const hl = new HierarchicLayout({ layoutMode: LayoutMode.INCREMENTAL })

// provide additional data to configure the HierarchicLayout
const hlData = new HierarchicLayoutData()

hlData.incrementalHints.contextDelegate = (item, factory) => {
  if (item instanceof INode && incrementalNodes.includes(item)) {
    // create a hint for incremental nodes
    if (graph.isGroupNode(item)) {
      // special hint for groups
      return factory.createIncrementalGroupHint(item)
    }
    if (fixedNodes.includes(item)) {
      // exact layer for the fixedNodes
      return factory.createUseExactLayerCoordinatesHint(item)
    }
    // simple layer hint for all other nodes
    return factory.createLayerIncrementallyHint(item)
  }
  if (item instanceof IEdge && incrementalEdges.includes(item)) {
    // sequence hint for incremental edges
    return factory.createSequenceIncrementallyHint(item)
  }
  // all other items don't get hints
  return null
}

// provide hints

graph.applyLayout(hl, hlData)// create a HierarchicLayout which rearranges
// only the incremental graph elements
const hl = new HierarchicLayout({ layoutMode: LayoutMode.INCREMENTAL })

// provide additional data to configure the HierarchicLayout
const hlData = new HierarchicLayoutData()

hlData.incrementalHints.contextDelegate = (
  item: IModelItem,
  factory: IIncrementalHintsFactory
) => {
  if (item instanceof INode && incrementalNodes.includes(item)) {
    // create a hint for incremental nodes
    if (graph.isGroupNode(item)) {
      // special hint for groups
      return factory.createIncrementalGroupHint(item)
    }
    if (fixedNodes.includes(item)) {
      // exact layer for the fixedNodes
      return factory.createUseExactLayerCoordinatesHint(item)
    }
    // simple layer hint for all other nodes
    return factory.createLayerIncrementallyHint(item)
  }
  if (item instanceof IEdge && incrementalEdges.includes(item)) {
    // sequence hint for incremental edges
    return factory.createSequenceIncrementallyHint(item)
  }
  // all other items don't get hints
  return null
}

// provide hints

graph.applyLayout(hl, hlData)

layerConstraintFactory

: ILayerConstraintFactory

Gets or sets the factory to specify layer constraints.

Remarks

Note that this factory doesn't have to be disposed after the layout calculation.

layerConstraints

: LayerConstraintData

Gets or sets the layout data to specify layer constraints.

Remarks

Layer constraints affect the assignment of nodes to layers. A layer constraint can be specified either explicitly for a given node or by mapping some or all nodes to an IComparable, e.g., a number, with the nodeComparables property.

In the latter case, the comparables are used to create placeBelow constraints between one node and another, if the one precedes the other. These constrains work just like explicitly created constraints. Note that equal values do not result in placeInSameLayer constraints, and no constraints are added for nodes mapped to null..

Examples

One way to map each node to an IComparable is to use the delegate:

Using a delegate to map nodes to objects that can be ordered to define relative layer placements

// Map each node to an IComparable, in this case taken from a custom object stored in the Tag
layoutData.layerConstraints.nodeComparables = (node) => {
  const data = node.tag
  if (data !== null) {
    return data.layerOrder
  }
  // Don't constrain layer placement if the tag doesn't contain our custom object.
  return null
}

If only some nodes should be constrained, the mapper can be used instead:

Using a mapper to map certain nodes to objects that can be ordered to define relative layer placements

// Define layer constraints for a few nodes via a mapper. Nodes that are not
// explicitly mapped don't have constraints on their layer placement.
const mapper = layoutData.layerConstraints.nodeComparables.mapper
// Place both node1 and node2 in the same layer by assigning the same value
mapper.set(node1, 5)
mapper.set(node2, 5)
// Place node3 somewhere above node1 and node2 by assigning a smaller value
mapper.set(node3, 2)
// Place node4 somewhere below node1 and node2 by assigning a larger value
mapper.set(node4, 8)
// The exact values don't matter much they just define an ordering. However, all
// values must have the same type you cannot mix int and string or double, for example.// Define layer constraints for a few nodes via a mapper. Nodes that are not
// explicitly mapped don't have constraints on their layer placement.
const mapper = layoutData.layerConstraints.nodeComparables
  .mapper as IMapper<INode, any>
// Place both node1 and node2 in the same layer by assigning the same value
mapper.set(node1, 5)
mapper.set(node2, 5)
// Place node3 somewhere above node1 and node2 by assigning a smaller value
mapper.set(node3, 2)
// Place node4 somewhere below node1 and node2 by assigning a larger value
mapper.set(node4, 8)
// The exact values don't matter much they just define an ordering. However, all
// values must have the same type you cannot mix int and string or double, for example.

If those mappings have been prepared beforehand, e.g. in a HashMap<TKey,TValue> or IMapper<K,V>, that property on the ItemMapping<TItem,TValue> can also be set:

Setting a prepared mapper or dictionary for relative layer assignment

layoutData.layerConstraints.nodeComparables = layerOrderMapper
// Or create the mapping from a Map, instead:
layoutData.layerConstraints.nodeComparables = layerOrderMap

IComparable is only the most natural option if such an object can be readily produced from a node, or there already exists such a mapping from nodes to something that can be compared. In many cases it can be easier to construct constraints manually with the respective methods on LayerConstraintData:

Defining custom layer constraints

// Place all nodes in sameLayerNodes into the same layer
const firstSameLayerNode = sameLayerNodes.first()
for (const node of sameLayerNodes) {
  layoutData.layerConstraints.placeInSameLayer(firstSameLayerNode, node)
}
// Ensure that node2 is placed two layers below node1
layoutData.layerConstraints.placeBelow(node1, node2, 2)
// Also place another node in the top layer
layoutData.layerConstraints.placeAtTop(nodeAtTop)

Sample Graphs

If there is a fixed layer assignment, for example because the layers are defined by business data, the givenLayersLayererIds should be used instead.

layerIndices

: IMapper<INode,number>

Gets or sets a mapper from nodes to the index of their layer.

Remarks

If this property is set, it can be used after layout to retrieve the layer assignment for each node. If only the layer assignment is needed and not the whole layout, HierarchicLayout can be run with stopAfterLayering set to true. This will skip the remaining stages of the layout and therefore reduce the runtime.

Examples

Retrieving layering information after a layout

const layoutData = new HierarchicLayoutData()
layoutData.layerIndices = new Mapper()
graph.applyLayout(new HierarchicLayout(), layoutData)

for (const node of graph.nodes) {
  console.log(
    `Node ${node} has been placed in layer ${layoutData.layerIndices.get(
      node
    )}`
  )
}

nodeHalos

Gets or sets the mapping from nodes to their NodeHalo.

Remarks

NodeHalos allow to reserve space around nodes.

Examples

The easiest option is to reserve the same space around all nodes, by setting a constant NodeHalo:

Using constant space around all nodes

layoutData.nodeHalos.constant = NodeHalo.create(20)

Handling only certain nodes differently can be done easily by using the mapper property:

Using a mapper to set halos for certain nodes

// node1 only reserves space above and below
layoutData.nodeHalos.mapper.set(node1, NodeHalo.create(20, 0, 0, 10))
// node2 has space all around
layoutData.nodeHalos.mapper.set(node2, NodeHalo.create(25))
// all other nodes don't get extra space

In cases where the NodeHalo for each node can be determined by looking at the node itself it's often easier to just set a delegate instead of preparing a mapper:

Using a delegate to determine halos for all nodes

// Retrieve the space around the node from its Tag property
layoutData.nodeHalos = (node) => NodeHalo.create(parseFloat(node.tag))// Retrieve the space around the node from its Tag property
layoutData.nodeHalos = (node: INode): NodeHalo =>
  NodeHalo.create(parseFloat(node.tag))

nodeLayoutDescriptors

: ItemMapping<INode,HierarchicLayoutNodeLayoutDescriptor>

Gets or sets the mapping of nodes to their HierarchicLayoutNodeLayoutDescriptor

Remarks

If a node is mapped to null, the default descriptor is used.

Examples

This property allows to change how nodes are laid out within their layer for each node individually. To just change a few nodes that deviate from the default handling, using the mapper is probably the best option:

Using a mapper to set different NodeLayoutDescriptors for different nodes

// Don't consider node1's labels at all
layoutData.nodeLayoutDescriptors.mapper.set(
  node1,
  new HierarchicLayoutNodeLayoutDescriptor({
    nodeLabelMode: NodeLabelMode.NEVER
  })
)
// Align node2 at the bottom of its layer
layoutData.nodeLayoutDescriptors.mapper.set(
  node2,
  new HierarchicLayoutNodeLayoutDescriptor({ layerAlignment: 1 })
)
// All other nodes not set in the mapper use the default HierarchicLayoutNodeLayoutDescriptor
// set on HierarchicLayout.

If a HierarchicLayoutNodeLayoutDescriptor is easier to create from every node itself, using a delegate is often easier:

Using a delegate to set a different NodeLayoutDescriptor for each node

// Use a property from a custom business object in the node's tag as the minimum length
layoutData.nodeLayoutDescriptors = (node) => {
  const customData = node.tag
  const descriptor = new HierarchicLayoutNodeLayoutDescriptor({
    minimumDistance: 5,
    nodeLabelMode: NodeLabelMode.CONSIDER_FOR_DRAWING
  })
  switch (customData.alignment) {
    case ItemPlacement.TOP:
      descriptor.layerAlignment = 0
      break
    case ItemPlacement.CENTER:
      descriptor.layerAlignment = 0.5
      break
    case ItemPlacement.BOTTOM:
      descriptor.layerAlignment = 1
      break
  }
  return descriptor
}

nodePortCandidateSets

: ItemMapping<INode,PortCandidateSet>

Gets or sets a mapping from nodes to their PortCandidateSet.

Remarks

If an edge that has port candidates (sourcePortCandidates or targetPortCandidates) connects to a node with a PortCandidateSet, the HierarchicLayout tries to match both collections to find an appropriate port. In case there is no matching port, a port candidate specified for the edge is preferred. For the matching to work properly, the candidates in both collection need to be the same instances.

Examples

The simplest way to define node port candidate sets is to use the same PortCandidateSet for all nodes, if suitable for the use case:

Defining the same port candidates for all nodes

// All nodes get only a candidate for the lower (South) side with capacity 10
const constantPortCandidates = new PortCandidateSet()
constantPortCandidates.add(
  PortCandidate.createCandidate(PortDirections.SOUTH, 10)
)
layoutData.nodePortCandidateSets.constant = constantPortCandidates

The same effect can be achieved with a delegate as well, however, a more useful way to use a delegate would be to decide whether a node should get a port candidate set based on some data at the node, e.g., found in its tag:

Defining port candidate sets with a delegate

// Create a PortCandidateSet with capacity 2 for the upper side (North) and capacity 1 for the lower side (South)
const pcs = new PortCandidateSet()
pcs.add(PortCandidate.createCandidate(PortDirections.NORTH), 2)
pcs.add(PortCandidate.createCandidate(PortDirections.SOUTH), 1)
// Specify the node port candidates for diamond nodes, i.e. for nodes with the string "diamond" in their tag
layoutData.nodePortCandidateSets = (node) =>
  node.tag === 'diamond' ? pcs : null// Create a PortCandidateSet with capacity 2 for the upper side (North) and capacity 1 for the lower side (South)
const pcs = new PortCandidateSet()
pcs.add(PortCandidate.createCandidate(PortDirections.NORTH), 2)
pcs.add(PortCandidate.createCandidate(PortDirections.SOUTH), 1)
// Specify the node port candidates for diamond nodes, i.e. for nodes with the string "diamond" in their tag
layoutData.nodePortCandidateSets = (node) =>
  node.tag === 'diamond' ? pcs : null!

If specific nodes should get a certain PortCandidateSet, it may sometimes be easier to use the mapper to set them:

Defining port candidate sets with a mapper

// Create a PortCandidateSet with capacity 2 for the upper side (North) and capacity 1 for the lower side (South)
const pcs1 = new PortCandidateSet()
pcs1.add(PortCandidate.createCandidate(PortDirections.NORTH), 2)
pcs1.add(PortCandidate.createCandidate(PortDirections.SOUTH), 1)
// Create another set with candidates for the left (West) and right side (East)
const pcs2 = new PortCandidateSet()
pcs2.add(PortCandidate.createCandidate(PortDirections.EAST), 4)
pcs2.add(PortCandidate.createCandidate(PortDirections.WEST), 4)
// Specify the port candidate sets for two specific nodes
layoutData.nodePortCandidateSets.mapper.set(node1, pcs1)
layoutData.nodePortCandidateSets.mapper.set(node2, pcs2)

nodesBeforeBus

Gets or sets the collection of bus nodes that should be placed before the common bus segment.

Remarks

If this collection is not specified, the nodes will be placed in an alternating way.

Examples

When the placement can be readily inferred from the nodes, then the easiest option is usually to use the delegate:

layoutData.nodesBeforeBus = (node) =>
  graphComponent.selection.selectedNodes.isSelected(node)

However, the other options are also still there, such as using an IEnumerable<T> via source:

layoutData.folderNodes = graphComponent.selection.selectedNodes

or explicitly using the items collection to add or remove items:

layoutData.nodesBeforeBus.items.add(node1)
layoutData.nodesBeforeBus.items.add(node2)

nodeTypes

: ItemMapping<INode,any>

Gets or sets the mapping from nodes to an object defining the node type, which influences the ordering of nodes during the sequencing such that nodes of same type are preferably placed next to each other.

Remarks

The node types are 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, PartitionGrid, or sequenceConstraints. The algorithm uses an additional local optimization heuristic to improve the placement with respect to node types and, thus, does not guarantee optimal results. This additional step may significantly increase the required runtime.

Sample Graphs

Node types do not affect the layer assignment.

partitionGridData

: PartitionGridData

Gets or sets the partition grid layout data.

Examples

The following sample shows how to assign nodes to partition grid cells simply via cell indices:

Assigning nodes to partition grid cells via indices

// Create four nodes and place them in grid cells in the following way
// +--+--+--+
// | 1| 2| 3|
// +--+--+--+
//    | 4|
//    +--+

const layoutData = new HierarchicLayoutData()
const gridData = layoutData.partitionGridData

const node1 = graph.createNode()
const node2 = graph.createNode()
const node3 = graph.createNode()
const node4 = graph.createNode()

// Assign the nodes to their rows and columns.
// Note that don't have to create or use PartitionGrid directly in this case.
// Setting the indices is enough.
gridData.rowIndices.mapper.set(node1, 0)
gridData.rowIndices.mapper.set(node2, 0)
gridData.rowIndices.mapper.set(node3, 0)
gridData.rowIndices.mapper.set(node4, 1)
gridData.columnIndices.mapper.set(node1, 0)
gridData.columnIndices.mapper.set(node2, 1)
gridData.columnIndices.mapper.set(node3, 2)
gridData.columnIndices.mapper.set(node4, 1)

graph.applyLayout(new HierarchicLayout(), layoutData)

When used this way there is no need to create a PartitionGrid instance or work with it directly. For more flexibility, e.g. to use cells that span multiple columns or rows, the PartitionGrid can be used as well:

Assigning nodes to partition grid cells via factory methods on the grid

// Create three nodes and place them in grid cells in the following way
// +--+--+
// | 1| 2|
// +--+--+
// |  3  |
// +--+--+

const node1 = graph.createNode(new Rect(0, 0, 50, 50))
const node2 = graph.createNode(new Rect(0, 0, 50, 50))
const node3 = graph.createNode(new Rect(0, 0, 125, 50))

// Create a new PartitionGrid with two rows and two columns
const grid = new PartitionGrid(2, 2)

// Assign the nodes to their cells
const cellIdMapper = new Mapper()
cellIdMapper.set(node1, grid.createCellId(0, 0))
cellIdMapper.set(node2, grid.createCellId(0, 1))
cellIdMapper.set(node3, grid.createRowSpanId(1))

const layoutData = new HierarchicLayoutData({
  partitionGridData: new PartitionGridData({
    grid: grid,
    cellIds: cellIdMapper
  })
})

graph.applyLayout(new HierarchicLayout(), layoutData)// Create three nodes and place them in grid cells in the following way
// +--+--+
// | 1| 2|
// +--+--+
// |  3  |
// +--+--+

const node1 = graph.createNode(new Rect(0, 0, 50, 50))
const node2 = graph.createNode(new Rect(0, 0, 50, 50))
const node3 = graph.createNode(new Rect(0, 0, 125, 50))

// Create a new PartitionGrid with two rows and two columns
const grid = new PartitionGrid(2, 2)

// Assign the nodes to their cells
const cellIdMapper = new Mapper<INode, PartitionCellId>()
cellIdMapper.set(node1, grid.createCellId(0, 0))
cellIdMapper.set(node2, grid.createCellId(0, 1))
cellIdMapper.set(node3, grid.createRowSpanId(1))

const layoutData = new HierarchicLayoutData({
  partitionGridData: new PartitionGridData({
    grid: grid,
    cellIds: cellIdMapper
  })
})

graph.applyLayout(new HierarchicLayout(), layoutData)

reduceCriticalEdgeCrossings

: boolean

Gets or sets whether or not critical edges automatically get crossing costs assigned based on their critical edge priorities.

Remarks

If enabled, an edge gets the critical edge priority plus one as its crossing cost - unless, a higher crossing cost was manually specified. Edges with a priority that is negative or zero get 1 as the crossing cost (which is the default for it). If disabled, the critical edge priorities do not automatically affect the crossing minimization. The user can still provide higher crossing costs manually, of course.

Default Value

The default value is true.

Critical edges automatically get crossing costs based on their priorities

selfLoopCalculatorData

: SelfLoopCalculatorData

Gets or sets the layout data for the SelfLoopCalculator.

sequenceConstraintFactory

: ISequenceConstraintFactory

Gets or sets the factory to specify sequence constraints.

Remarks

Note that this factory doesn't have to be disposed after the layout calculation.

sequenceConstraints

: SequenceConstraintData

Gets or sets the layout data to specify sequence constraints.

Examples

One way to set sequence constraints is by mapping nodes or edges to an IComparable (e.g. a number) which define the order in which those nodes are placed within the same layer. This can be done with the itemComparables property. One way to map each item to such an IComparable is to use the delegate:

Using a delegate to map items to objects that can be ordered to define relative placements within a layer

// Map each item to an IComparable, in this case taken from a custom object stored in the Tag
layoutData.sequenceConstraints.itemComparables = (item) => {
  const data = item.tag
  if (data !== null) {
    return data.sequenceOrder
  }
  // Don't constrain sequencing if the tag doesn't contain our custom object.
  return null
}

If only some nodes should be constrained, the mapper can be used instead:

Using a mapper to map certain items to objects that can be ordered to define relative placements within a layer

// Define sequence constraints for a few nodes via a mapper. Nodes that are not
// explicitly mapped don't have constraints on their placement within the layer.
const mapper = layoutData.sequenceConstraints.itemComparables.mapper
// Place node1 before node2
mapper.set(node1, 1)
mapper.set(node2, 3)
// Place node3 between both of them
mapper.set(node3, 2)
// Place node4 after the others by assigning a larger value
mapper.set(node4, 8)
// The exact values don't matter much they just define an ordering. However, all
// values must have the same type you cannot mix int and string or double, for example.// Define sequence constraints for a few nodes via a mapper. Nodes that are not
// explicitly mapped don't have constraints on their placement within the layer.
const mapper = layoutData.sequenceConstraints.itemComparables
  .mapper as IMapper<INode, any>
// Place node1 before node2
mapper.set(node1, 1)
mapper.set(node2, 3)
// Place node3 between both of them
mapper.set(node3, 2)
// Place node4 after the others by assigning a larger value
mapper.set(node4, 8)
// The exact values don't matter much they just define an ordering. However, all
// values must have the same type you cannot mix int and string or double, for example.

If those mappings have been prepared beforehand, e.g. in a HashMap<TKey,TValue> or IMapper<K,V>, that property on the ItemMapping<TItem,TValue> can also be set:

Setting a prepared mapper or Map for relative placement within a layer

layoutData.sequenceConstraints.itemComparables =
  ItemMapping.from(sequenceMapper)
// Or create the mapping from a Map, instead:
layoutData.sequenceConstraints.itemComparables =
  ItemMapping.from(sequenceMap)layoutData.sequenceConstraints.itemComparables = ItemMapping.from<
  IModelItem,
  IComparable
>(sequenceMapper)
// Or create the mapping from a Map, instead:
layoutData.sequenceConstraints.itemComparables = ItemMapping.from<
  IModelItem,
  IComparable
>(sequenceMap)

Defining custom sequence constraints

// Ensure that node2 is placed after node1
layoutData.sequenceConstraints.placeAfter(node1, node2)
// Also place another node at the very start
layoutData.sequenceConstraints.placeAtHead(firstNodeInLayer)

Sample Graphs

sequenceIndices

: IMapper<INode,number>

Gets or sets a mapper from nodes to the sequence index in their layer.

Remarks

If this property is set, it can be used after layout to retrieve the sequencing for each node. If only the sequencing (and layering) information is needed and not the whole layout, HierarchicLayout can be run with stopAfterSequencing set to true. This will skip the remaining stages of the layout and therefore reduce the runtime.

Examples

Retrieving layering and sequencing information after a layout

const layoutData = new HierarchicLayoutData()
layoutData.layerIndices = new Mapper()
layoutData.sequenceIndices = new Mapper()

graph.applyLayout(new HierarchicLayout(), layoutData)

for (const node of graph.nodes) {
  console.log(
    `Node ${node} has been placed in layer ${layoutData.layerIndices.get(
      node
    )} at position ${layoutData.sequenceIndices.get(node)}`
  )
}

sourceGroupIds

: ItemMapping<IEdge,ICollection<PortCandidate>>

Gets or sets a mapping from edges to an object representing their source edge group.

Remarks

Edges sharing a source group identifier will share a common bus near the source or at a common source node if possible.

The HierarchicLayout is able to group incoming and outgoing edges. Therefore, the source group identifier of the outgoing edges of a node has to match with the target group identifier of the incoming edges.

Examples

One simple way to use source groups is to use the edge's source node as group ID which effectively groups all edges with the same source together:

Grouping all edges on the source side

layoutData.sourceGroupIds = (edge) => edge.sourceNodelayoutData.sourceGroupIds = (edge: IEdge) => edge.sourceNode

Another useful way to use a delegate here would be grouping edges by some commonality, such as the same color:

Grouping edges by color

layoutData.sourceGroupIds = (edge) => {
  const style = edge.style
  if (style instanceof PolylineEdgeStyle) {
    return style.stroke.fill
  }
  return null
}layoutData.sourceGroupIds = (edge: IEdge) => {
  const style = edge.style
  if (style instanceof PolylineEdgeStyle) {
    return style.stroke!.fill
  }
  return null
}

If only certain edges should be grouped it may sometimes be easier to use the mapper to set the group IDs:

Grouping certain edges with a mapper

for (const group of edgeGroups) {
  for (const edge of group) {
    // Use the collection as group ID, since it's common to all edges in it
    layoutData.sourceGroupIds.mapper.set(edge, group)
  }
}

sourcePortCandidates

Gets or sets a mapping from edges to a collection of their source port candidates.

Remarks

Port constraints allow to define where an edge can connect to its source node and allow fine control over port placement.

If all that is needed is to fix the source port in its location or on a node side, port constraints are easier to work with, since they are a slightly simpler concept.

The HierarchicLayout does not support PortCandidates with multiple directions (e.g. EAST or WEST). To model that an edge should connect at one of several sides, define multiple candidates instead, where each candidate has a single direction.

Examples

Source port candidates are effectively a collection of possible port placements with different costs and the layout algorithm is free to choose the candidate that fits best into the overall layout, while also preferring candidates with a lower cost. To set the same candidate list for all edges, it's easiest to use the constant property:

Setting the same set of source port candidates for all edges

layoutData.sourcePortCandidates.constant = new List([
  // Prefer the center position and route the edge downwards if possible (no cost for this candidate)
  PortCandidate.createCandidate(0, 0, PortDirections.SOUTH),
  // Alternatively, use any position at the bottom border of the node, but with a higher cost
  PortCandidate.createCandidate(PortDirections.SOUTH, 1),
  // If that fails, use either the left or the right side
  PortCandidate.createCandidate(PortDirections.WEST, 2),
  PortCandidate.createCandidate(PortDirections.EAST, 2)
])

If certain edges need specific port candidates, it's usually convenient to use the mapper property:

Setting different source port candidates for certain edges

// edge1 should leave the source node preferably on the node side in flow direction,
// but can also use a fixed port location on the left of the node.
layoutData.sourcePortCandidates.mapper.set(
  edge1,
  new List([
    PortCandidate.createCandidate(PortDirections.WITH_THE_FLOW),
    PortCandidate.createCandidate(-0.5, 0.25, PortDirections.WEST, 1)
  ])
)

// edge2 should leave the source node anywhere on the upper side of the node
layoutData.sourcePortCandidates.mapper.set(
  edge2,
  new List([PortCandidate.createCandidate(PortDirections.NORTH)])
)

For cases when the desired configuration of port candidates can be readily created from the edge itself, the delegate is often the most convenient option:

Setting different source port candidates for each edge with a delegate

// Assuming a flowchart, the "yes" edge should leave the decision in flow direction,
// and the "no" edge may leave either left or right of the flow direction.
// This also ensures that the layout still looks natural if the layout uses different orientations.
layoutData.sourcePortCandidates = (edge) => {
  // Only handle decision nodes here
  if (edge.sourceNode.tag instanceof FlowChartDecision) {
    switch (edge.labels.get(0).text) {
      case 'Yes':
        return new List([
          PortCandidate.createCandidate(PortDirections.WITH_THE_FLOW)
        ])
      case 'No':
        return new List([
          PortCandidate.createCandidate(PortDirections.LEFT_IN_FLOW),
          PortCandidate.createCandidate(PortDirections.RIGHT_IN_FLOW)
        ])
    }
  }
  return null
}// Assuming a flowchart, the "yes" edge should leave the decision in flow direction,
// and the "no" edge may leave either left or right of the flow direction.
// This also ensures that the layout still looks natural if the layout uses different orientations.
layoutData.sourcePortCandidates = (
  edge: IEdge
): ICollection<PortCandidate> => {
  // Only handle decision nodes here
  if (edge.sourceNode!.tag instanceof FlowChartDecision) {
    switch (edge.labels.get(0).text) {
      case 'Yes':
        return new List([
          PortCandidate.createCandidate(PortDirections.WITH_THE_FLOW)
        ])
      case 'No':
        return new List([
          PortCandidate.createCandidate(PortDirections.LEFT_IN_FLOW),
          PortCandidate.createCandidate(PortDirections.RIGHT_IN_FLOW)
        ])
    }
  }
  return null!
}

Sample Graphs

sourcePortConstraints

: ItemMapping<IEdge,PortConstraint>

Gets or sets a mapping from edges to their source PortConstraint.

Remarks

Port constraints allow to define where an edge attaches to its source node and can either restrict that to one of the node's sides, or to a fixed port position.

A more general concept which allows finer control over where ports are placed, are port candidates.

Examples

If all edges should exit their source node on the same side, you can simply set a constant constraint for all edges:

Setting the same port constraint for all edges

// All source ports should be on the bottom side
layoutData.sourcePortConstraints.constant = PortConstraint.create(
  PortSide.SOUTH
)

To change the constraints for individual edges, it's usually easiest to use the mapper:

Using a mapper to set different port constraints for certain edges

// edge1 should leave the source node on the left side, while keeping its exact port position (strong port constraint)
layoutData.sourcePortConstraints.mapper.set(
  edge1,
  PortConstraint.create(PortSide.WEST, true)
)
// edge2 should leave the source node downwards, but the port may be placed anywhere along that node border
layoutData.sourcePortConstraints.mapper.set(
  edge2,
  PortConstraint.create(PortSide.SOUTH)
)

If a PortConstraint can readily be created from an edge, using a delegate is often easier:

Using a delegate to set a different port constraint for each edge

// Source ports will be placed on the right side and use a property in the edge's tag
// to determine whether ports will stay fixed at their position.
layoutData.sourcePortConstraints = (edge) =>
  PortConstraint.create(PortSide.EAST, edge.tag.fixPorts)// Source ports will be placed on the right side and use a property in the edge's tag
// to determine whether ports will stay fixed at their position.
layoutData.sourcePortConstraints = (edge: IEdge): PortConstraint =>
  PortConstraint.create(PortSide.EAST, edge.tag.fixPorts)

Sample Graphs

sourcePortGroupIds

: ItemCollectionMapping<INode,HierarchicLayoutSubcomponentDescriptor>

Gets or sets a mapping from edges to an object representing their source port group.

Remarks

All edges with the same port id at a node will share the same port location. However, they will be routed independently and in contrast to source groups will deviate from a common path as soon as possible instead of sharing as much of a common path as possible.

Examples

The simplest way to use source port groups is to use the same object as group ID for all edges. Since grouping is done per node, this has the effect of grouping all edges with the same source node together:

Grouping all edges on the source side

layoutData.sourcePortGroupIds.constant = {}

The same effect can be achieved with a delegate as well, by returning the source node as group ID for each edge. However, a more useful way to use a delegate here would be grouping edges by some commonality, such as the same color:

Grouping edges by color

layoutData.sourcePortGroupIds = (edge) => {
  const style = edge.style
  if (style instanceof PolylineEdgeStyle) {
    return style.stroke.fill
  }
  return null
}layoutData.sourcePortGroupIds = (edge: IEdge) => {
  const style = edge.style
  if (style instanceof PolylineEdgeStyle) {
    return style.stroke!.fill
  }
  return null
}

If only certain edges should be grouped it may sometimes be easier to use the mapper to set the group IDs:

Grouping certain edges with a mapper

for (const group of edgePortGroups) {
  for (const edge of group) {
    // Use the collection as group ID, since it's common to all edges in it
    layoutData.sourcePortGroupIds.mapper.set(edge, group)
  }
}

subcomponents

Gets or sets the mapping of nodes to a subcomponent which is arranged by the layout algorithm defined by property layoutAlgorithm.

Remarks

The nodes forming a subcomponent are arranged by another layout algorithm and that sub-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. Note that subcomponents may not be nested, that is, a subcomponent is not allowed to contain nodes that belong to yet another subcomponent. Nesting of subcomponents results in an exception.

To conveniently define a subcomponent as well as the layout algorithm responsible for it use the add method of this property. It takes the HierarchicLayoutSubcomponentDescriptor as parameter and allows to define the nodes associated to it using the returned ItemCollection<TItem>.

A subcomponent can be connected to nodes of another subcomponent as well as to nodes that are not part of any subcomponent. Edges that model these connections are so-called inter-edges. For inter-edges there apply some smaller restrictions with respect to the supported features (see the documentation of SUBCOMPONENT_DESCRIPTOR_DP_KEY for details).

If all inter-edges of a subcomponent connect to the same external node, that single external so-called connector node is included in the calculation of the component layout when using placement policy AUTOMATIC or ALWAYS_INTEGRATED. In case the result is feasible, this results in a better and more compact integration of the component in the main layout. In that case the sub-layout is fully responsible for the routing of inter-edges (meaning the restrictions below may not apply anymore).

Subcomponents can be defined on grouped graphs with the following restrictions:

All subcomponent nodes must be on the same hierarchy level if the group node itself is not part of the subcomponent.
If a group is assigned to a subcomponent, 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 subcomponent element as incremental or fixed. If the given layout of the subcomponent should be considered, then the from-sketch mode of the used layout algorithm needs to be enabled (if such a mode is supported).

Examples

Subcomponents can be configured by first adding a new HierarchicLayoutSubcomponentDescriptor and saving the resulting ItemCollection<TItem>. That one can then be used to define the subset of nodes which the layout should process:

// Retrieve an ItemCollection<INode> which defines all nodes
// of a subcomponent. This subcomponent will be arranged by an OrganicLayout
const organicSubset = layoutData.subcomponents.add(
  new HierarchicLayoutSubcomponentDescriptor(new OrganicLayout())
)
// You can use this ItemCollection<INode> as usual, using either one of
// the Source, Items, Mapper, or Delegate properties.
// Here, we simply use the selected nodes:
organicSubset.source = graphComponent.selection.selectedNodes

Since adding a new subcomponent returns the ItemCollection<TItem>, configuring subcomponents can also be conveniently chained:

layoutData.subcomponents.add(
  new HierarchicLayoutSubcomponentDescriptor(
    new OrganicLayout(),
    HierarchicLayoutSubcomponentPlacementPolicy.ISOLATED
  )
).source = organicNodes
layoutData.subcomponents.add(
  new HierarchicLayoutSubcomponentDescriptor(new TreeLayout())
).source = treeNodes
layoutData.subcomponents.add(
  new HierarchicLayoutSubcomponentDescriptor(new OrthogonalLayout())
).source = orthogonalNodes

tabularGroupChildComparers

: ItemMapping<INode,system.Comparison<INode>>

Gets or sets the mapping from tabular group nodes to comparison functions used to sort the child nodes of the group.

Remarks

The comparison assigned to a tabular group allows to define a specific order of the child nodes of that tabular group. If there are groups within a tabular group, each of them has to be associated with a comparison if a specific ordering is desired (i.e., the inner groups do not use the comparison associated with the parent group). Otherwise, the algorithm determines a suitable order of the elements within such groups.

Examples

Ordering children by label text for all tabular groups

layoutData.tabularGroupChildComparers.constant = (child1, child2) =>
  child1.labels.get(0).text.localeCompare(child2.labels.get(0).text)layoutData.tabularGroupChildComparers.constant = (
  child1: INode,
  child2: INode
) => child1.labels.get(0).text.localeCompare(child2.labels.get(0).text)

Ordering children of a single tabular group by using custom data

// for the comparison, we assume that child nodes have a custom data tag which holds a column property
layoutData.tabularGroupChildComparers.mapper.set(
  tabularGroupNode1,
  (child1, child2) => child1.tag.column.CompareTo(child2.tag.column)
)// for the comparison, we assume that child nodes have a custom data tag which holds a column property
layoutData.tabularGroupChildComparers.mapper.set(
  tabularGroupNode1,
  (child1: INode, child2: INode) =>
    child1.tag.column.CompareTo(child2.tag.column)
)

tabularGroups

Gets or sets the collection of tabular group nodes whose children are arranged in a tabular fashion.

Remarks

Children of tabular groups are laid out in a compact tabular fashion as shown in the figure below. Groups contained in a tabular group behave like tabular groups as well.

Child nodes are placed next to each other within the same layer with a distance defined by tabularGroupChildDistance, which is zero by default.

There are some setups for which a tabular group may not be tight (i.e., maximally compact):

If edges directly connect to a tabular group (not to its content), then it is not guaranteed that the group becomes maximally compact. Children may be placed a little further apart to fulfill the defined edge-to-edge distance.
The same is true if there are children with self-loops. Such self-loops are always drawn within the tabular group.
In addition, labels of edges connecting two children of the same tabular group may intersect with other edge segments.

Besides, the table groups may not be tight if there are user specified constraints like node halos, node labels that exceed the size of the associated child node, and port constraints connecting to a side orthogonal to the layout orientation.

Examples

Using a delegate to mark all group nodes of the graph as tabular groups

layoutData.tabularGroups.delegate = (node) => graph.isGroupNode(node)

Using a delegate to marks specific groups by looking at custom data tag

// assume that the Tag of a node contains a flag indicating whether a group is a tabular group
layoutData.tabularGroups.delegate = (node) => node.tag.isTabularGroup

Marking two specific nodes as tabular groups

layoutData.tabularGroups.mapper = new Mapper()
layoutData.tabularGroups.mapper.set(tabularGroupNode1, true)
layoutData.tabularGroups.mapper.set(tabularGroupNode2, true)

Using a collection to define the tabular group items

// directly assign a collection of tabular group nodes (e.g. of type List<INode>)
layoutData.tabularGroups.items = tabularGroupNodes

Sample Graphs

To define a specific order of child nodes in a tabular group it is possible to provide a custom comparison via property tabularGroupChildComparers.

Children of tabular groups are never drawn in a stacked style.

If tabular groups are defined, the bend reduction optimization cannot be applied because reduction of bends would cause tabular groups to become less compact.

targetGroupIds

: ItemMapping<IEdge,ICollection<PortCandidate>>

Gets or sets a mapping from edges to an object representing their target edge group.

Remarks

Edges sharing a target group identifier will share a common bus near the target or at a common target node if possible.

The HierarchicLayout is able to group incoming and outgoing edges. Therefore, the target group identifier of the incoming edges of a node has to match with the source group identifier of the outgoing edges.

Examples

One simple way to use source groups is to use the edge's target node as group ID which effectively groups all edges with the same target together:

Grouping all edges on the target side

layoutData.targetGroupIds = (edge) => edge.targetNodelayoutData.targetGroupIds = (edge: IEdge) => edge.targetNode

Another useful way to use a delegate here would be grouping edges by some commonality, such as the same color:

Grouping edges by color

layoutData.targetGroupIds = (edge) => {
  const style = edge.style
  if (style instanceof PolylineEdgeStyle) {
    return style.stroke.fill
  }
  return null
}layoutData.targetGroupIds = (edge: IEdge) => {
  const style = edge.style
  if (style instanceof PolylineEdgeStyle) {
    return style.stroke!.fill
  }
  return null
}

If only certain edges should be grouped it may sometimes be easier to use the mapper to set the group IDs:

Grouping certain edges with a mapper

for (const group of edgeGroups) {
  for (const edge of group) {
    // Use the collection as group ID, since it's common to all edges in it
    layoutData.targetGroupIds.mapper.set(edge, group)
  }
}

targetPortCandidates

Gets or sets a mapping from edges to a collection of their target port candidates.

Remarks

Port constraints allow to define where an edge can connect to its target node and allow fine control over port placement.

If all that is needed is to fix the target port in its location or on a node side, port constraints are easier to work with, since they are a slightly simpler concept.

Examples

Target port candidates are effectively a collection of possible port placements with different costs and the layout algorithm is free to choose the candidate that fits best into the overall layout, while also preferring candidates with a lower cost. To set the same candidate list for all edges, it's easiest to use the constant property:

Setting the same set of target port candidates for all edges

layoutData.targetPortCandidates.constant = new List([
  // Prefer the center position and enter the node from the top if possible (no cost for this candidate)
  PortCandidate.createCandidate(0, 0, PortDirections.NORTH),
  // Alternatively, use any position at the top border of the node, but with a higher cost
  PortCandidate.createCandidate(PortDirections.NORTH, 1),
  // If that fails, use either the left or the right side
  PortCandidate.createCandidate(PortDirections.WEST, 2),
  PortCandidate.createCandidate(PortDirections.EAST, 2)
])

If certain edges need specific port candidates, it's usually convenient to use the mapper property:

Setting different target port candidates for certain edges

// edge1 should enter the target node preferably on the node side in flow direction,
// but can also use a fixed port location on the left of the node.
layoutData.targetPortCandidates.mapper.set(
  edge1,
  new List([
    PortCandidate.createCandidate(PortDirections.WITH_THE_FLOW),
    PortCandidate.createCandidate(-0.5, -0.25, PortDirections.WEST, 1)
  ])
)

// edge2 should enter the target node anywhere on the bottom side of the node
layoutData.targetPortCandidates.mapper.set(
  edge2,
  new List([PortCandidate.createCandidate(PortDirections.SOUTH)])
)

For cases when the desired configuration of port candidates can be readily created from the edge itself, the delegate is often the most convenient option:

Setting different target port candidates for each edge with a delegate

// Assuming a flowchart, edges connecting to a terminal on the target side should enter that node either
// in flow direction (preferred) or from one of the sides.
// This also ensures that the layout still looks natural if the layout uses different orientations.
layoutData.targetPortCandidates = (edge) => {
  // Only handle terminal nodes here
  if (edge.targetNode.tag instanceof FlowChartTerminal) {
    return new List([
      PortCandidate.createCandidate(PortDirections.WITH_THE_FLOW),
      PortCandidate.createCandidate(PortDirections.RIGHT_IN_FLOW, 1),
      PortCandidate.createCandidate(PortDirections.LEFT_IN_FLOW, 1)
    ])
  }
  return null
}// Assuming a flowchart, edges connecting to a terminal on the target side should enter that node either
// in flow direction (preferred) or from one of the sides.
// This also ensures that the layout still looks natural if the layout uses different orientations.
layoutData.targetPortCandidates = (
  edge: IEdge
): ICollection<PortCandidate> => {
  // Only handle terminal nodes here
  if (edge.targetNode!.tag instanceof FlowChartTerminal) {
    return new List([
      PortCandidate.createCandidate(PortDirections.WITH_THE_FLOW),
      PortCandidate.createCandidate(PortDirections.RIGHT_IN_FLOW, 1),
      PortCandidate.createCandidate(PortDirections.LEFT_IN_FLOW, 1)
    ])
  }
  return null!
}

Sample Graphs

targetPortConstraints

: ItemMapping<IEdge,PortConstraint>

Gets or sets a mapping from edges to their target PortConstraint.

Remarks

Port constraints allow to define where an edge attaches to its target node and can either restrict that to one of the node's sides, or to a fixed port position.

A more general concept which allows finer control over where ports are placed, are port candidates.

Examples

If all edges should exit their source node on the same side, you can simply set a constant constraint for all edges:

Setting the same port constraint for all edges

// All target ports should be on the top side
layoutData.targetPortConstraints.constant = PortConstraint.create(
  PortSide.NORTH
)

To change the constraints for individual edges, it's usually easiest to use the mapper:

Using a mapper to set different port constraints for certain edges

// edge1 should enter the target node on the right side, while keeping its exact port position (strong port
// constraint)
layoutData.targetPortConstraints.mapper.set(
  edge1,
  PortConstraint.create(PortSide.EAST, true)
)
// edge2 should enter the target node from the top, but the port may be placed anywhere along that node border
layoutData.targetPortConstraints.mapper.set(
  edge2,
  PortConstraint.create(PortSide.NORTH)
)

If a PortConstraint can readily be created from an edge, using a delegate is often easier:

Using a delegate to set a different port constraint for each edge

// Target ports will be placed on the right side and use a property in the edge's tag
// to determine whether ports will stay fixed at their position.
layoutData.targetPortConstraints = (edge) =>
  PortConstraint.create(PortSide.EAST, edge.tag.fixPorts)// Target ports will be placed on the right side and use a property in the edge's tag
// to determine whether ports will stay fixed at their position.
layoutData.targetPortConstraints = (edge: IEdge): PortConstraint =>
  PortConstraint.create(PortSide.EAST, edge.tag.fixPorts)

Sample Graphs

targetPortGroupIds

Gets or sets a mapping from edges to an object representing their target port group.

Remarks

Examples

The simplest way to use target port groups is to use the same object as group ID for all edges. Since grouping is done per node, this has the effect of grouping all edges with the same target node together:

Grouping all edges on the target side

layoutData.targetPortGroupIds.constant = {}

The same effect can be achieved with a delegate as well, by returning the target node as group ID for each edge. However, a more useful way to use a delegate here would be grouping edges by some commonality, such as the same color:

Grouping edges by color

layoutData.targetPortGroupIds = (edge) => {
  const style = edge.style
  if (style instanceof PolylineEdgeStyle) {
    return style.stroke.fill
  }
  return null
}layoutData.targetPortGroupIds = (edge: IEdge) => {
  const style = edge.style
  if (style instanceof PolylineEdgeStyle) {
    return style.stroke!.fill
  }
  return null
}

If only certain edges should be grouped it may sometimes be easier to use the mapper to set the group IDs:

Grouping certain edges with a mapper

for (const group of edgePortGroups) {
  for (const edge of group) {
    // Use the collection as group ID, since it's common to all edges of it
    layoutData.targetPortGroupIds.mapper.set(edge, group)
  }
}

uniformPortAssignmentGroups