RadialTreeLayoutData<TNode,TEdge,TNodeLabel,TEdgeLabel>

Specifies custom data for the RadialTreeLayout.

Inheritance Hierarchy

LayoutData<TNode,TEdge,TNodeLabel,TEdgeLabel>

RadialTreeLayoutData

Examples

The following example shows how to create a new instance of RadialTreeLayoutData<TNode,TEdge,TNodeLabel,TEdgeLabel> and use it with an RadialTreeLayout:

Creating an instance of RadialTreeLayoutData

const layoutData = new RadialTreeLayoutData()
// Use the node whose label says "Root" as root node for the tree
layoutData.treeRoot = (node: INode): boolean =>
  node.labels.get(0).text === 'Root'
// Place children of nodes with many children interleaved
layoutData.interleavedNodes = (node: INode) =>
  graphComponent.graph.outDegree(node) > 5

graphComponent.graph.applyLayout(new RadialTreeLayout(), layoutData)

In many cases the complete initialization of RadialTreeLayoutData<TNode,TEdge,TNodeLabel,TEdgeLabel> can also be done in a single object initializer:

Using an object initializer for easy creation of RadialTreeLayoutData

const layoutData = new RadialTreeLayoutData({
  // Use the node whose label says "Root" as root node for the tree
  treeRoot: (node: INode): boolean =>
    node.labels.get(0).text === 'Root',
  // Place children of nodes with many children interleaved
  interleavedNodes: (node: INode): boolean =>
    graphComponent.graph.outDegree(node) > 5,
})

graphComponent.graph.applyLayout(new RadialTreeLayout(), layoutData)

Type Parameters

TNode
TEdge
TNodeLabel
TEdgeLabel

Type Details

yFiles module: algorithms

Constructors

RadialTreeLayoutData

()

ParametersOptions Overload

options - Object
A map of options to pass to the method.

interleavedNodes - ItemCollection<TNode>: The collection of nodes whose children should be arranged in an interleaved fashion. This option either sets the value directly or recursively sets properties to the instance of the interleavedNodes property on the created object.
nodeMargins - ItemMapping<TNode,Insets>: The mapping from nodes to their margins. This option either sets the value directly or recursively sets properties to the instance of the nodeMargins property on the created object.
treeRoot - ItemCollection<TNode>: The mapping for marking the node that will be used as root node of the tree. This option either sets the value directly or recursively sets properties to the instance of the treeRoot property on the created object.
edgeLabelPreferredPlacements - ItemMapping<TEdgeLabel,EdgeLabelPreferredPlacement>: The mapping that provides an EdgeLabelPreferredPlacement instance for edge labels. This option either sets the value directly or recursively sets properties to the instance of the edgeLabelPreferredPlacements property on the created object.
childOrder - ChildOrderData<TNode,TEdge>: The ChildOrderData<TNode,TEdge> which specifies how child nodes are to be sorted. This option either sets the value directly or recursively sets properties to the instance of the childOrder property on the created object.
nodeTypes - ItemMapping<TNode,any>: The mapping from nodes to an object defining the node type, which influences the ordering of child nodes such that those with the same type are preferably placed next to each other. This option either sets the value directly or recursively sets properties to the instance of the nodeTypes property on the created object.
nonTreeEdges - ItemCollection<TEdge>: The collection of edges explicitly marked as not belonging to a tree. This option either sets the value directly or recursively sets properties to the instance of the nonTreeEdges property on the created object.
edgeBundleDescriptors - ItemMapping<TEdge,EdgeBundleDescriptor>: The mapping of edges to their EdgeBundleDescriptor. This option either sets the value directly or recursively sets properties to the instance of the edgeBundleDescriptors property on the created object.
ports - BasicPortData<TNode,TEdge,TNodeLabel,TEdgeLabel>: The sub-data that influences the placement of the ports. This option either sets the value directly or recursively sets properties to the instance of the ports property on the created object.

Properties

childOrder

: ChildOrderData<TNode,TEdge>

Gets or sets the ChildOrderData<TNode,TEdge> which specifies how child nodes are to be sorted.

Remarks

If no comparison function is specified for a node, its edges are sorted according to the layout's childOrderingPolicy.

Examples

The ChildOrderData<TNode,TEdge> class provides two primary methods for determining the order of a parent's child nodes: either by directly sorting the child nodes using targetNodeComparators or targetNodeComparables, or by sorting the outgoing edges from the parent node to its child nodes using outEdgeComparators or outEdgeComparables. Setting a comparable value (e.g. a number or a string) for all nodes means that the child nodes of all parents in the graph are ordered using those values.

Using a comparable to order by the height of the child nodes.

// Use the node height as comparable to sort the child nodes by their height
layoutData.childOrder.targetNodeComparables = (child) =>
  child.layout.height

Using a comparison delegate for specific nodes is convenient if the child nodes should be ordered only for particular parent nodes.

Ordering child nodes only for a specific parent node and using the child's tag.

layoutData.childOrder.targetNodeComparators = (parent: INode) => {
  if (parent == specificNode) {
    // Define a comparison function only for a specific parent node
    // ... and sort its child nodes based on an order value specified in their tags
    return (child1: INode, child2: INode) =>
      child1.tag.sequenceOrder.compareTo(child2.tag.sequenceOrder)
  }

  // No ordering for the edges around the other nodes
  return null
}

Setting a comparable value (e.g. a number or a string) for all edges means that the outgoing edges of all parents in the graph are ordered using those values.

Using a comparable to order by the label count of the edges.

// Use the label count of the out edges as comparable value to sort them
layoutData.childOrder.outEdgeComparables = (edge) => edge.labels.size

Using a comparison delegate for specific edges is convenient if the outgoing edges should be ordered only for particular nodes.

Ordering edges only for a specific node and using the edge's tag.

layoutData.childOrder.outEdgeComparators = (parent: INode) => {
  if (parent == specificNode) {
    // Define a comparison function only for a specific parent node
    // ... and sort its outgoing edges based on an order value specified in their tags
    return (edge1: IEdge, edge2: IEdge) =>
      edge1.tag.sequenceOrder.compareTo(edge2.tag.sequenceOrder)
  }

  // No ordering for the edges around the other nodes
  return null
}

edgeBundleDescriptors

: ItemMapping<TEdge,EdgeBundleDescriptor>

Gets or sets the mapping of edges to their EdgeBundleDescriptor.

Remarks

This property only has an effect when the treeReductionStage is enabled, which is the default setting.

Bundling together multiple edges means that their common parts are to some degree merged into a bundled part. At the source and target point, the edges are again clearly split.

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

edgeLabelPreferredPlacements

: ItemMapping<TEdgeLabel,EdgeLabelPreferredPlacement>

Gets or sets the mapping that provides an EdgeLabelPreferredPlacement instance for edge labels.

Examples

Depending on how much customization is needed, some ways of setting EdgeLabelPreferredPlacements 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 EdgeLabelPreferredPlacement for all labels

layoutData.edgeLabelPreferredPlacements = new EdgeLabelPreferredPlacement(
  {
    // Place labels along the edge
    angleReference: LabelAngleReferences.RELATIVE_TO_EDGE_FLOW,
    angle: 0,
    // ... on either side
    edgeSide: LabelEdgeSides.LEFT_OF_EDGE | LabelEdgeSides.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.edgeLabelPreferredPlacements.mapper.set(
  label1,
  new EdgeLabelPreferredPlacement({
    placementAlongEdge: LabelAlongEdgePlacements.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.edgeLabelPreferredPlacements.mapper.set(
  label2,
  new EdgeLabelPreferredPlacement({
    placementAlongEdge: LabelAlongEdgePlacements.AT_SOURCE,
    edgeSide: LabelEdgeSides.RIGHT_OF_EDGE | LabelEdgeSides.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.edgeLabelPreferredPlacements = (
  label: ILabel,
): EdgeLabelPreferredPlacement => {
  const customData = label.tag as CustomData
  return new EdgeLabelPreferredPlacement({
    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.
    placementAlongEdge: customData.placeInCenter
      ? LabelAlongEdgePlacements.AT_CENTER
      : LabelAlongEdgePlacements.ANYWHERE,
    edgeSide: customData.placeInCenter
      ? LabelEdgeSides.ON_EDGE
      : LabelEdgeSides.LEFT_OF_EDGE | LabelEdgeSides.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.edgeLabelPreferredPlacements =
  EdgeLabelPreferredPlacement.fromParameter(
    NinePositionsEdgeLabelModel.CENTER_CENTERED,
  )

interleavedNodes

: ItemCollection<TNode>

Gets or sets the collection of nodes whose children should be arranged in an interleaved fashion.

Remarks

This can be used to place children of nodes with many children in a more compact fashion.

Examples

If you already have a collection or IEnumerable<T> containing the nodes whose children should be drawn interleaved, the easiest way is to set the source:

Configuring the nodes for interleaved child placement via a collection or IEnumerable

// Place children of selected nodes interleaved
layoutData.interleavedNodes = graphComponent.selection.nodes

If only a few nodes should be configured that way that are not yet in a collection, it's usually easier to use items directly:

Configuring interleaved child placement for only certain selected nodes

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

If the criteria for which nodes should have their children placed interleaved are readily apparent from each node, then the best option is usually to use the predicate property:

Using a delegate to configure interleaved child placement for each node individually

// Place children of nodes with many children interleaved
layoutData.interleavedNodes = (node: INode) => graph.outDegree(node) > 5

Sample Graphs

nodeMargins

: ItemMapping<TNode,Insets>

Gets or sets the mapping from nodes to their margins.

Remarks

Node margins allow to reserve space around nodes.

Examples

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

Using constant space around all nodes

layoutData.nodeMargins = new Insets(20)

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

Using a mapper to set margins for certain nodes

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

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

Using a delegate to determine margins for all nodes

// Retrieve the space around the node from its tag property
layoutData.nodeMargins = (node: INode): Insets =>
  new Insets(parseFloat(node.tag))

nodeTypes

: ItemMapping<TNode,any>

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

Remarks

The RadialTreeLayout uses the types of nodes to sort the child nodes around their root such that nodes of the same type are placed consecutively, where possible. If defined, the childOrder is stronger than the node type criterion. However, the node types are considered more important than the childOrderingPolicy. In general, the compactness of the results may be lower due to types, since the algorithm has less freedom in sorting the subtrees - this may be especially noticeable in conjunction with the interleaving feature enabled.

Sample Graphs

nonTreeEdges

: ItemCollection<TEdge>

Gets or sets the collection of edges explicitly marked as not belonging to a tree.

Remarks

This property only has an effect when the treeReductionStage is enabled, which is the default setting.

ports

: BasicPortData<TNode,TEdge,TNodeLabel,TEdgeLabel>

Gets or sets the sub-data that influences the placement of the ports.

Remarks

The port placement can be influenced by specifying EdgePortCandidates for the source and target of an edge, as well as by specifying NodePortCandidates at the nodes.

In addition, it is possible to specify that ports should be grouped at the source or target.

If both EdgePortCandidates and NodePortCandidates are specified, the layout algorithm tries to match them. An edge port candidate matches a node port candidate if

Their matchingIds are equal or one type is null,
They belong to a common side or one side is ANY, and
If both candidates are fixed, they describe the same positions.

The position of a port candidate is defined by offset or the actual offset of the edge endpoint for fixed-from-sketch candidates. When there is no match, the port candidate with the lowest costs specified for the edge is chosen.

The RadialTreeLayout does not natively support port placement constraints. Support is provided through additional pre- and postprocessing by the PortPlacementStage, which is added to the layoutStages and enabled by default.

treeRoot

: ItemCollection<TNode>

Gets or sets the mapping for marking the node that will be used as root node of the tree.

Remarks

If a custom root node is specified here, then the rootSelectionPolicy will be ignored.

If multiple root nodes are provided, the first valid node is used. This can be useful when multiple components of the graph are handled independently, e.g. when using ComponentLayout for a forest graph.

Examples

The simplest way to set a custom root node for the layout, if you already have a TNode for that, would be to use the item to specify it as the root:

Specifying a custom root node directly

layoutData.treeRoot.item = root

In cases where it's easier to look at a TNode to determine whether it should be the root node or not, it's often most convenient to use the predicate property:

Specifying a custom root node via a delegate

// This is equivalent to the declaration above
layoutData.treeRoot = (node) => node === root
// Or use a different way of choosing the root node, e.g. by taking the node whose label
// says 'Root'
layoutData.treeRoot = (node) => node.labels.get(0).text === 'Root'

Sometimes there might also be a collection that usually holds just the single node that should be the root, in which case source can be useful:

Specifying a custom root node from an IEnumerable

// Use the first selected node as the root
// This will be evaluated anew each time the layout is applied
layoutData.treeRoot = graphComponent.selection.nodes

Sample Graphs

Methods

combineWith

(data: LayoutData<TNode,TEdge,TNodeLabel,TEdgeLabel>…) : LayoutData<TNode,TEdge,TNodeLabel,TEdgeLabel>

Combines this instance with the given layout data.

Remarks

This keeps the current instance unmodified and instead returns a new instance that dynamically combines the contents of all involved instances.

Parameters

options - Object
A map of options to pass to the method.

data - LayoutData<TNode,TEdge,TNodeLabel,TEdgeLabel>: The LayoutData<TNode,TEdge,TNodeLabel,TEdgeLabel> to combine this instance with.

Returns

↪LayoutData<TNode,TEdge,TNodeLabel,TEdgeLabel>: The combined layout data.

Defined in

LayoutData

RadialTreeLayoutData<TNode,TEdge,TNodeLabel,TEdgeLabel>

Examples

Type Parameters

Type Details

Constructors

RadialTreeLayoutData

ParametersOptions Overload

Properties

childOrder

Remarks

Examples

See Also

edgeBundleDescriptors

Remarks

See Also

edgeLabelPreferredPlacements

Examples

See Also

interleavedNodes

Remarks

Examples

See Also

Sample Graphs

nodeMargins

Remarks

Examples

See Also

nodeTypes

Remarks

See Also

Sample Graphs

nonTreeEdges

Remarks

See Also

ports

Remarks

treeRoot

Remarks

Examples

See Also

Sample Graphs

Methods

combineWith

Remarks

Parameters

Returns

See Also

Defined in