BalloonLayoutData

Specifies custom data for the BalloonLayout.

Inheritance Hierarchy

BalloonLayoutData

Examples

The following example shows how to create a new instance of BalloonLayoutData and use it with an BalloonLayout:

Creating an instance of BalloonLayoutData

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

graphComponent.graph.applyLayout(new BalloonLayout(), layoutData)const layoutData = new BalloonLayoutData()
// 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 BalloonLayout(), layoutData)

In many cases the complete initialization of BalloonLayoutData can also be done in a single object initializer:

Using an object initializer for easy creation of BalloonLayoutData

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

graphComponent.graph.applyLayout(new BalloonLayout(), layoutData)const layoutData = new BalloonLayoutData({
  // 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 BalloonLayout(), layoutData)

Type Details

yfiles module: view-layout-bridge
yfiles-umd modules: view-layout-bridge
Legacy UMD name: yfiles.tree.BalloonLayoutData

Constructors

BalloonLayoutData

()

Creates a new instance of BalloonLayoutData which helps configuring BalloonLayout.

ParametersOptions Overload

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

interleavedNodes - ItemCollection<INode>: The collection of nodes whose children should be arranged in an interleaved fashion. This option sets the interleavedNodes property on the created object.
nodeHalos - ItemMapping<INode,NodeHalo>: The mapping from nodes to their NodeHalo. This option sets the nodeHalos property on the created object.
abortHandler - AbortHandler: The AbortHandler used during the layout. This option sets the abortHandler property on the created object.
treeRoot - SingleItem<INode>: The mapping for marking the node that will be used as root node of the tree. This option sets the treeRoot property on the created object.
edgeLabelPreferredPlacement - ItemMapping<ILabel,PreferredPlacementDescriptor>: The mapping that provides a PreferredPlacementDescriptor instance for edge ILabels. This option sets the edgeLabelPreferredPlacement property on the created object.
outEdgeComparer - function(IEdge, IEdge):number: The comparison function used to sort the nodes' outgoing edges. This option sets the outEdgeComparer property on the created object.
nodeTypes - ItemMapping<INode,Object>: The mapping from nodes to an object defining the node type, which influences the ordering of child nodes such that those with same type are preferably placed next to each other. This option sets the nodeTypes property on the created object.

Properties

abortHandler

: AbortHandler

Gets or sets the AbortHandler used during the layout.

Remarks

An AbortHandler can be used to gracefully stop or cancel a running layout and offers options for automatically doing so after a predetermined time.

An AbortHandler configured or set here overrides the one on LayoutExecutor.

Examples

The most common use case would be to just configure the AbortHandler here, e.g. to set timeouts for a graceful stop or canceling the running layout:

layoutData.abortHandler.stopDuration = TimeSpan.fromSeconds(10)
layoutData.abortHandler.cancelDuration = TimeSpan.fromSeconds(30)layoutData.abortHandler!.stopDuration = TimeSpan.fromSeconds(10)
layoutData.abortHandler!.cancelDuration = TimeSpan.fromSeconds(30)

If there's already an AbortHandler instance that's pre-configured or will be used in a different place to, e.g., cancel the layout when the user presses a button, you can also set one explicitly:

layoutData.abortHandler = abortHandler

edgeLabelPreferredPlacement

: ItemMapping<ILabel,PreferredPlacementDescriptor>

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
  )

interleavedNodes

: ItemCollection<INode>

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.selectedNodes

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 delegate property:

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

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

Sample Graphs

The custom node selection induced by this collection is only considered if the layout's interleavedMode is set to MARKED_NODES.

nodeHalos

: ItemMapping<INode,NodeHalo>

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))

nodeTypes

: ItemMapping<INode,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 same type are preferably placed next to each other.

Remarks

The BalloonLayout uses the types of nodes to sort the child nodes around their root such that nodes of same type are placed consecutively, where possible. If defined, the comparer 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 sub-trees - this may be especially noticeable in conjunction with the interleaving feature enabled.

Sample Graphs

outEdgeComparer

: function(IEdge, IEdge):number

Gets or sets the comparison function used to sort the nodes' outgoing edges.

Remarks

Setting a comparison function sorts the nodes in the same way as the comparer property on the BalloonLayout itself, with the difference that it is possible to use IEdge instances when defining the comparison.

If no comparison function is specified, the outgoing edges are sorted according to the value of property comparer. If that is not set too, then the edges are sorted according to the layout's childOrderingPolicy.

treeRoot

: SingleItem<INode>

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

Remarks

The custom root node selection induced by this property is only considered if the root node policy is set to SELECTED_ROOT.

Examples

The simplest way to set a custom root node for the layout, if you already have an INode 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 an INode to determine whether it should be the root node or not, it's often most convenient to use the delegate 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.selectedNodes

Sample Graphs

Methods

combineWith

(data: LayoutData…) : LayoutData

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: The LayoutData to combine this instance with.

Returns

↪LayoutData: The combined layout data.

Defined in

LayoutData

BalloonLayoutData

Examples

Type Details

See Also

Constructors

BalloonLayoutData

ParametersOptions Overload

Properties

abortHandler

Remarks

Examples

See Also

edgeLabelPreferredPlacement

Examples

See Also

interleavedNodes

Remarks

Examples

See Also

Sample Graphs

nodeHalos

Remarks

Examples

See Also

nodeTypes

Remarks

See Also

Sample Graphs

outEdgeComparer

Remarks

See Also

treeRoot

Remarks

Examples

See Also

Sample Graphs

Methods

combineWith

Remarks

Parameters

Returns

See Also

Defined in